Skip to content

Empty to undefined

emptyToUndefined is a built‑in normalization rule that converts empty strings ("") into undefined.

This removes text fields that contain no meaningful content while preserving all non‑empty string values. If the value is not a string, or the string is not empty, no normalization step is emitted.

Signature

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

Events

Event code Description
string.now.undefined Empty string was converted to undefined.

Design rationale

  • Eliminates empty text fields that carry no semantic value.
  • Preserves all non‑empty strings and all non‑string values.
  • Addresses common UI and form‑handling patterns where empty strings are used as placeholders or default values.
  • Emits a normalization step only when the input is exactly an empty string.
  • Classified as lossy normalization — the original empty string is discarded.
  • Produces cleaner, more meaningful data for downstream validators, scanners, and policy layers.

Invoke

emptyToUndefined runs automatically when:

  • The value is structurally a string.
  • 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

Empty string converted to undefined

const value = "";

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

Non‑empty string — no normalization

const result = emptyToUndefined("hello", "lax", "$");
// → []

Non‑string value

const result = emptyToUndefined(42, "lax", "$");
// → []