Skip to content

Compact sparse array

compactSparseArray is a built‑in normalization rule that removes sparse array holes while preserving all defined elements.

It produces a dense array without altering semantic content. If the array contains no holes, no normalization step is emitted.

Signature

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

Events

Event code Description
array.now.compacted Sparse array holes were removed.

Design rationale

  • Removes only structural holes, never defined values.
  • Produces a dense array suitable for downstream validators, scanners, and policy layers.
  • Targets arrays originating from UI frameworks, spread operations, or partial constructions where holes appear unintentionally.
  • Emits a normalization step only when the compacted array differs from the original.
  • Guarantees lossless normalization — no user data is removed or transformed.

Invoke

compactSparseArray runs automatically when:

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

Mode behavior:

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

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

Examples

Sparse array compacted

const value = [1, , 3]; // hole at index 1

const result = compactSparseArray(value, "strict", "$");
// → [
//     {
//       path: "$",
//       nextValue: [1, 3],
//       lossy: "lossless",
//       events: [
//         JaneEvent{ kind: "info", code: "array.now.compacted", ... }
//       ]
//     }
//   ]

No holes — no normalization

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

Non‑array value

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