feat: add null-preserving intOrNull/floatOrNull/transformOrNull/magneticVariationOrNull (#57)

An NMEA 0183 null field (IEC 61162-1 §7.2.3.4) signals "sensor working,
value not available" and must not be conflated with a legitimate zero.
The existing int/float/transform/magneticVariation collapse both into
the same numeric 0, which surfaces as real bugs downstream — e.g.
SignalK/nmea0183-signalk#192 where an empty RMC magnetic-variation
field reports as 0° instead of null, causing a 13° course error for
one reporter.

Add four null-preserving variants that return null for empty /
whitespace / null / undefined / non-numeric input, and a genuine 0 for
"0". Existing functions are unchanged for back-compat.

Author: msallin

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.1.0
+
+### Non-breaking additions
+
+- **`intOrNull(n)` / `floatOrNull(n)`** — null-preserving variants of
+  `int` / `float`. Return `null` for empty / whitespace / `null` /
+  `undefined` / non-numeric input, instead of silently coercing to `0`.
+  `intOrNull('0')` still returns `0`, so legitimate zero measurements
+  stay distinguishable from "not available".
+- **`transformOrNull(value, from, to)`** — null-short-circuiting unit
+  conversion. Identical to `transform` for real input; returns `null`
+  when `value` doesn't parse. Unsupported unit pairs still throw.
+- **`magneticVariationOrNull(degrees, pole)`** — null-preserving
+  magnetic variation. Returns `null` when degrees or pole is missing or
+  unparseable (including lowercase / unknown pole letters), rather than
+  throwing or returning `0`.
+
+Motivation: IEC 61162-1 §7.2.3.4 defines a null NMEA field as "sensor
+working, value not available" — distinct from a legitimate zero. Legacy
+`int` / `float` collapse both into `0`, which has caused bugs like
+SignalK/nmea0183-signalk#192 (magnetic variation reported as 0° from an
+empty RMC field, causing a 13° error in one reporter's case). Use the
+`*OrNull` family when passing through to Signal K, which maps `null` in
+a delta value onto the same semantic.
+
+Existing `int` / `float` / `transform` / `magneticVariation` are
+unchanged for back-compat.
+
 ## 1.0.0
 
 First stable release. The package is now authored in TypeScript with strict

README.md

@@ -162,6 +162,31 @@ doesn't parse. Accepts `unknown` so `int(null)`, `int(undefined)`,
 Same idea for `parseFloat`. Accepts numbers or numeric strings. Returns
 `0.0` on parse failure.
 
+#### `intOrNull(n) => number | null` / `floatOrNull(n) => number | null`
+
+Null-preserving variants of `int` / `float`. An NMEA 0183 null field
+(IEC 61162-1 §7.2.3.4) signals "sensor working, value not available"
+and must not be confused with a legitimate zero. `intOrNull('')`,
+`intOrNull(null)`, `intOrNull('abc')` all return `null`; `intOrNull('0')`
+returns `0`. Prefer these over `int`/`float` when the caller wants to
+pass the not-available semantic through to Signal K (which treats `null`
+the same way).
+
+#### `transformOrNull(value, from, to) => number | null`
+
+Null-short-circuiting unit conversion. Identical to `transform` for real
+input; returns `null` when `value` is empty / `null` / `undefined` /
+non-numeric. Unsupported unit pairs still throw — the null short-circuit
+runs first, so a missing field with an unknown unit pair is still
+`null`, not an error.
+
+#### `magneticVariationOrNull(degrees, pole) => number | null`
+
+Null-preserving magnetic variation. Returns `null` when degrees or pole
+is missing or unparseable (including unknown / lowercase pole letters),
+rather than throwing or silently returning `0`. `0` with a valid pole
+returns `0`, not `null`.
+
 #### `zero(n) => string`
 
 Width-2 left-pad for integer date/time components. `zero(2) === '02'`,

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/nmea0183-utilities",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Various utilities for transforming NMEA0183 units into SI units for use in SK.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.json

@@ -345,6 +345,74 @@ export function float(n: unknown): number {
   return Number.isNaN(parsed) ? 0.0 : parsed
 }
 
+// Null-preserving numeric parsers. An NMEA 0183 null field (IEC 61162-1
+// §7.2.3.4) signals "sensor working, value not available" and must not be
+// conflated with a legitimate zero. `int`/`float` above coerce to 0 for
+// back-compat; prefer these when the caller wants to preserve the
+// not-available semantic end-to-end.
+//
+//   intOrNull('')    -> null
+//   intOrNull('42')  -> 42
+//   intOrNull('abc') -> null
+export function intOrNull(n: unknown): number | null {
+  const parsed = parseInt(n as string, 10)
+  return Number.isNaN(parsed) ? null : parsed
+}
+
+export function floatOrNull(n: unknown): number | null {
+  const parsed = parseFloat(n as string)
+  return Number.isNaN(parsed) ? null : parsed
+}
+
+// Null-short-circuiting unit conversion. Lets callers write
+//   transformOrNull(parts[8], 'deg', 'rad')
+// for an optional NMEA field without a surrounding emptiness check.
+// Unsupported conversion pairs still throw (same contract as `transform`).
+export function transformOrNull(
+  value: unknown,
+  inputFormat: UnitFormat,
+  outputFormat: UnitFormat
+): number | null {
+  const numeric = floatOrNull(value)
+  if (numeric === null) {
+    return null
+  }
+  if (inputFormat === outputFormat) {
+    return numeric
+  }
+  const converter = CONVERSIONS[inputFormat + ':' + outputFormat]
+  if (!converter) {
+    throw new Error(
+      'unsupported conversion: ' + inputFormat + ' -> ' + outputFormat
+    )
+  }
+  return converter(numeric)
+}
+
+// Null-preserving magnetic variation. Returns null when either the
+// degrees field or the pole letter is missing or unparseable, rather
+// than throwing or (via the old `float` path) silently returning 0.
+// Valid pole letters still enforce the `Pole` contract; an unknown
+// pole given alongside numeric degrees is treated as "not available"
+// rather than fatal, matching how callers already treat the whole
+// field as optional when the direction indicator is empty.
+export function magneticVariationOrNull(
+  degrees: unknown,
+  pole: unknown
+): number | null {
+  const deg = floatOrNull(degrees)
+  if (deg === null) {
+    return null
+  }
+  if (pole === 'N' || pole === 'E') {
+    return deg
+  }
+  if (pole === 'S' || pole === 'W') {
+    return -deg
+  }
+  return null
+}
+
 // Default export aggregate so ESM consumers using
 // `import utils from '@signalk/nmea0183-utilities'` get the same bag
 // that `const utils = require(...)` returns in CJS.
@@ -360,5 +428,9 @@ export default {
   isValidPosition,
   zero,
   int,
-  float
+  float,
+  intOrNull,
+  floatOrNull,
+  transformOrNull,
+  magneticVariationOrNull
 }

src/index.ts

@@ -18,6 +18,12 @@ describe('default export', function () {
     expect(utils.zero).to.equal(named.zero)
     expect(utils.int).to.equal(named.int)
     expect(utils.float).to.equal(named.float)
+    expect(utils.intOrNull).to.equal(named.intOrNull)
+    expect(utils.floatOrNull).to.equal(named.floatOrNull)
+    expect(utils.transformOrNull).to.equal(named.transformOrNull)
+    expect(utils.magneticVariationOrNull).to.equal(
+      named.magneticVariationOrNull
+    )
     done()
   })