Flatten one level¶

flattenOneLevel is a built‑in normalization rule that flattens nested arrays by exactly one level, preserving item order.

It simplifies shallow, unintended nesting patterns that often arise from UI frameworks, spread operations, or partial constructions. Because this transformation removes structural boundaries, it is considered lossy and runs only in lax mode.

Signature¶

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

Events¶

Event code	Description
`array.now.flattened`	Nested arrays were flattened one level.

Design rationale¶

Eliminates shallow, unintended nesting while preserving the order of all items.
Targets arrays produced by UI components, spread operations, or partial merges where nested arrays appear unintentionally.
Performs a single‑level flatten — never recursive — ensuring predictable, bounded behavior.
Considered lossy because structural grouping information is removed.
Emits a normalization step only when at least one nested array is flattened.

Invoke¶

flattenOneLevel 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¶

Nested arrays flattened¶

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

const result = flattenOneLevel(value, "lax", "$");
// → [
//     {
//       path: "$",
//       nextValue: [1, 2, 3, 4],
//       lossy: "lossy",
//       events: [
//         JaneEvent{ kind: "info", code: "array.now.flattened", ... }
//       ]
//     }
//   ]

No nested arrays — no normalization¶

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

Non‑array value¶

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