Skip to content

NaN to undefined

nanToUndefined is a built‑in normalization rule that converts NaN into undefined.

This removes invalid numeric states that cannot be compared, serialized, or validated reliably. If the value is not a number, or the number is not NaN, no normalization step is emitted.

Signature

export const nanToUndefined: NormalizationRule<unknown>
(value: unknown, mode: NormalizationMode, path: FieldPath) => NormalizationStep[]

Events

Event code Description
number.now.undefined Invalid numeric value was converted.

Design rationale

  • Eliminates the only JavaScript numeric value that is not equal to itself and cannot be meaningfully compared.
  • Prevents NaN from leaking into validators, scanners, or policy layers where numeric comparisons are required.
  • Treats NaN as semantically equivalent to "no usable numeric value".
  • Emits a normalization step only when the input is NaN.
  • Classified as lossy normalization — the original value is discarded.
  • Addresses values originating from parsing failures, arithmetic errors, or external APIs that surface NaN.

Invoke

nanToUndefined runs automatically when:

  • The value is structurally a number.
  • The normalization stage is active.
  • The current mode allows lossy normalization.

Mode behavior:

  • strict: Rule does not run (lossy).
  • moderate: Rule does not run (lossy).
  • lax: Rule runs.

Normalization cannot be invoked manually. It is always applied automatically based on structural type and mode.

Examples

NaN converted to undefined

const value = Number("not a number"); // → NaN

const result = nanToUndefined(value, "lax", "$");
// → [
//     {
//       path: "$",
//       nextValue: undefined,
//       lossy: "lossy",
//       events: [
//         JaneEvent{ kind: "info", code: "number.now.undefined", ... }
//       ]
//     }
//   ]

Valid number — no normalization

const result = nanToUndefined(123, "lax", "$");
// → []

Non‑number value

const result = nanToUndefined("NaN", "lax", "$");
// → []