Skip to content

Remove null items

removeNullItems is a built‑in normalization rule that removes null entries from arrays.

It eliminates structurally empty items while preserving the order and meaning of all defined values. Because this transformation removes user‑supplied elements, it is considered lossy and runs only in lax mode.

Signature

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

Events

Event code Description
array.without.null-items Null items were removed from the array.

Design rationale

  • Removes null placeholders that commonly arise from UI inputs, partial constructions, or sparse data sources.
  • Preserves all meaningful values and maintains original ordering.
  • Considered lossy because user‑provided null entries are removed.
  • Emits a normalization step only when at least one null value is removed.
  • Produces cleaner, more predictable arrays for downstream validation and policy.

Invoke

removeNullItems 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

Null items removed

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

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

No null items — no normalization

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

Non‑array value

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