Skip to content

Remove null keys

removeNullKeys is a built‑in normalization rule that removes object keys whose values are null.

This strips explicitly empty fields while preserving all defined, meaningful data.

If the value is not a plain object, or no keys contain null, no normalization step is emitted.

Signature

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

Events

Event code Description
object.without.null-keys null

Design rationale

  • Removes only keys whose values are exactly null.
  • Preserves all non‑null values, including undefined, empty strings, empty arrays, and empty objects (handled by other rules).
  • Eliminates explicit "empty" placeholders commonly produced by form libraries, UI frameworks, or API responses.
  • Emits a normalization step only when at least one null key is removed.
  • Classified as lossy normalization — the original null values are discarded.
  • Produces cleaner, more semantically meaningful object shapes for downstream validators, scanners, and policy layers.

Invoke

removeNullKeys runs automatically when:

  • The value is structurally a plain object (not an array).
  • 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

Null keys removed

const value = {
  name: "Alice",
  age: null,
  meta: null
};

const result = removeNullKeys(value, "lax", "$");
// → [
//     {
//       path: "$",
//       nextValue: { name: "Alice" },
//       lossy: "lossy",
//       events: [
//         JaneEvent{ kind: "info", code: "object.without.null-keys", ... }
//       ]
//     }
//   ]

No null values — no normalization

const result = removeNullKeys({ a: 1, b: null }, "strict", "$");
// → []

Non‑object value

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