skills/docs/foundation/bitpacker/bitpacker-validation/src/validation/find-array-length-errors.md

findArrayLengthErrors

Purpose

Per-array length-rule detector used by the recursive validateData walker. Given a BitPackerSchema array shape ([schema] for variable-length, [maxLength, schema] for max-bounded), this function checks the corresponding data array against the rule and pushes rows into the validator's error accumulator if the length is out of bounds. Splitting the check out of validateData keeps the main walker's switch ladder readable and lets the array-specific logic evolve independently of the rest of the validator.

The function is hot-path machinery; it accepts the same context shape as validateData (the mutable error/warning arrays + per-call options) and returns void. It does NOT recurse into the array elements — that's the walker's job after the length check passes.

Features

• Detects data.length > maxLength violations for max-bounded arrays
• Detects non-array data against an array schema
• Pushes ValidationReportItem rows with code: "ARRAY_TOO_LONG" or "INVALID_TYPE"
• Honours maxErrors short-circuit
• Path-aware: passes the current path through to the row's path field

Usage: Basic Example

import { findArrayLengthErrors, type ValidationReportItem } from "@suaveplan/bitpacker-validation";

const errors: ValidationReportItem[] = [];
findArrayLengthErrors(
    [10, 255], // schema: max 10 uint8 entries
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], // data: 11 entries
    "items",
    { errors, warnings: [], maxErrors: 10, checkExtraFields: false, strictMode: false }
);
console.log(errors[0].code); // "ARRAY_TOO_LONG"
console.log(errors[0].path); // "items"

Usage: Advanced Example

import {
    findArrayLengthErrors,
    ErrorCodes,
    type ValidationReportItem,
} from "@suaveplan/bitpacker-validation";

const errors: ValidationReportItem[] = [];
findArrayLengthErrors(
    [100, "uuid"],
    "not-an-array",
    "users",
    { errors, warnings: [], maxErrors: 1, checkExtraFields: false, strictMode: false }
);
// errors[0].code === ErrorCodes.INVALID_TYPE
// errors[0].path === "users"

API Reference

findArrayLengthErrors(schema: ArraySchema, data: unknown, path: string, ctx: ValidationContext): void

Checks data against the length rule encoded in schema. If schema = [innerSchema], any array length is valid. If schema = [maxLength, innerSchema], length must be ≤ maxLength. Pushes rows into ctx.errors on violations.

Implementation Notes

• No element-level validation. This function only handles the length rule. Element validation (each item against innerSchema) is the caller's responsibility — typically the recursive validateData walker after this check passes.
• maxLength: 0 is valid. A zero max-length means an empty-array-only schema. Non-empty arrays produce ARRAY_TOO_LONG errors. Consumers wanting "no constraint" use the variable-length form [schema] instead.
• Type errors short-circuit length checks. A non-array data produces a single INVALID_TYPE row and the function returns; it does NOT report a derivative ARRAY_TOO_LONG for a non-array.
• maxErrors is enforced. Once ctx.errors.length >= ctx.maxErrors, the function returns without pushing additional rows.