Skip to content

Remove undefined items

removeUndefinedItems is a built‑in normalization rule that removes undefined entries from arrays.

It produces a cleaner and more predictable sequence of defined values. Because this transformation removes user‑supplied elements, it is considered lossy and runs only in lax mode.

Signature

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

Events

Event code Description
array.without.undefined-items Undefined items were removed from the array.

Design rationale

  • Removes undefined placeholders that commonly arise from sparse arrays, UI inputs, or partially constructed lists.
  • Produces a predictable, fully defined sequence of values for downstream validation and policy layers.
  • Considered lossy because user‑provided undefined entries are removed.
  • Emits a normalization step only when at least one undefined value is removed.
  • Preserves ordering and all meaningful values.

Invoke

removeUndefinedItems runs automatically when:

  • The value is structurally an array.
  • The normalization stage is active.
  • The current mode allows lossy normalization.

Mode behavior:

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

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

Examples

Undefined items removed

const value = [1, undefined, 2, undefined, 3];

const result = removeUndefinedItems(value, "lax", "$");
// → [
//     {
//       path: "$",
//       nextValue: [1, 2, 3],
//       lossy: "lossy",
//       events: [
//         JaneEvent{ kind: "info", code: "array.without.undefined-items", ... }
//       ]
//     }
//   ]

No undefined items — no normalization

const result = removeUndefinedItems([1, 2, 3], "lax", "$");
// → []

Non‑array value

const result = removeUndefinedItems("not an array", "lax", "$");
// → []