Skip to content

Array is deep

arrayIsDeep is a built‑in scan rule that detects arrays nested beyond a safe structural depth.

It walks the first‑element chain of the array to estimate nesting. When the observed depth exceeds the configured threshold (20), the rule emits a warn‑level array.is.deep scan event containing the measured and allowed depth. If the value is not an array or does not exceed the threshold, no events are emitted.

Signature

export const arrayIsDeep: ScanRule (raw: unknown, path: FieldPath) => JaneEvent[]

Events

Event code Description
array.is.deep Array nesting depth exceeded the safe threshold.

Design rationale

  • Detects excessively nested arrays that may indicate malformed or adversarial input.
  • Uses a first‑element descent to estimate structural depth without full traversal.
  • Emits a warning when the observed depth exceeds the conservative limit (20).
  • Prevents downstream stages from operating on deeply nested structures that may cause performance degradation or stack pressure.
  • Provides depth metadata ({ depth, maxDepth }) for policy decisions and analysis.
  • Performs no mutation or restructuring of the input.

Invoke

arrayIsDeep runs automatically whenever the scan stage is enabled.

Activation methods:

  • Enable scan explicitly: jane.value(input).scan().
  • Use a mode that enables scan:
  • strict() enables scan by default.
  • moderate() and lax() do not enable scan unless .scan() is called.
  • Enable scan with policy: jane.value(input).withPolicy({ mode: 'strict' }).

If scan is not enabled or the structural type is not an array, arrayIsDeep does not run and no depth detection occurs.

Examples

Deep array detected

const value = [[[[[[1]]]]]]; // depth > 20 in real cases
const result = arrayIsDeep(value, "$");
// → [ JaneEvent{ kind: "warn", code: "array.is.deep", ... } ]

Shallow array

const result = arrayIsDeep([1, [2]], "$");
// → []

Non‑array value

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