chore: test and document coerceUndefinedToNull

README.md

@@ -143,6 +143,7 @@ Decode valid CBOR bytes from a `Uint8Array` (or `Buffer`) and return a JavaScrip
 
 * `allowIndefinite` (boolean, default `true`): when the indefinite length additional information (`31`) is encountered for any type (arrays, maps, strings, bytes) _or_ a "break" is encountered, an error will be thrown.
 * `allowUndefined` (boolean, default `true`): when major 7, minor 23 (`undefined`) is encountered, an error will be thrown. To disallow `undefined` on encode, a custom [type encoder](#type-encoders) for `'undefined'` will need to be supplied.
+* `coerceUndefinedToNull` (boolean, default `false`): when both `allowUndefined` and `coerceUndefinedToNull` are set to `true`, all `undefined` tokens (major `7` minor `23`: `0xf7`) will be coerced to `null` tokens, such that `undefined` is an allowed token but will not appear in decoded values.
 * `allowInfinity` (boolean, default `true`): when an IEEE 754 `Infinity` or `-Infinity` value is encountered when decoding a major 7, an error will be thrown. To disallow `Infinity` and `-Infinity` on encode, a custom [type encoder](#type-encoders) for `'number'` will need to be supplied.
 * `allowNaN` (boolean, default `true`): when an IEEE 754 `NaN` value is encountered when decoding a major 7, an error will be thrown. To disallow `NaN` on encode, a custom [type encoder](#type-encoders) for `'number'` will need to be supplied.
 * `allowBigInt` (boolean, default `true`): when an integer outside of the safe integer range is encountered, an error will be thrown. To disallow `BigInt`s on encode, a custom [type encoder](#type-encoders) for `'bigint'` will need to be supplied.

interface.ts

@@ -33,6 +33,7 @@ export type TagDecoder = (inner: any) => any
 export interface DecodeOptions {
   allowIndefinite?: boolean
   allowUndefined?: boolean
+  coerceUndefinedToNull?: boolean
   allowInfinity?: boolean
   allowNaN?: boolean
   allowBigInt?: boolean

lib/7float.js

@@ -24,10 +24,10 @@ const MINOR_UNDEFINED = 23
  * @returns {Token}
  */
 export function decodeUndefined (_data, _pos, _minor, options) {
-  if (options.coerceUndefinedToNull === true) {
-    return new Token(Type.null, null, 1)
-  } else if (options.allowUndefined === false) {
+  if (options.allowUndefined === false) {
     throw new Error(`${decodeErrPrefix} undefined values are not supported`)
+  } else if (options.coerceUndefinedToNull === true) {
+    return new Token(Type.null, null, 1)
   }
   return new Token(Type.undefined, undefined, 1)
 }

test/test-7float.js

@@ -97,10 +97,19 @@ describe('float', () => {
     })
 
     it('can switch off undefined support', () => {
+      assert.deepStrictEqual(decode(fromHex('f7')), undefined)
+      assert.throws(() => decode(fromHex('f7'), { allowUndefined: false }), /undefined/)
       assert.deepStrictEqual(decode(fromHex('830102f7')), [1, 2, undefined])
       assert.throws(() => decode(fromHex('830102f7'), { allowUndefined: false }), /undefined/)
     })
 
+    it('can coerce undefined to null', () => {
+      assert.deepStrictEqual(decode(fromHex('f7'), { coerceUndefinedToNull: false }), undefined)
+      assert.deepStrictEqual(decode(fromHex('f7'), { coerceUndefinedToNull: true }), null)
+      assert.deepStrictEqual(decode(fromHex('830102f7'), { coerceUndefinedToNull: false }), [1, 2, undefined])
+      assert.deepStrictEqual(decode(fromHex('830102f7'), { coerceUndefinedToNull: true }), [1, 2, null])
+    })
+
     it('can switch off Infinity support', () => {
       assert.deepStrictEqual(decode(fromHex('830102f97c00')), [1, 2, Infinity])
       assert.deepStrictEqual(decode(fromHex('830102f9fc00')), [1, 2, -Infinity])