skills/docs/foundation/bitpacker/bitpacker-validation/src/validation/validation.md

Validation Top-Level API

(no submodules)

- validator — Stateful validator for a fixed `BitPack…

• validator — Stateful validator for a fixed BitPackerSchema. BitPackerValidator<T> is the right choice when a high-throughput pi…

• validator — Stateful validator for a fixed `BitPack…

• validator — Stateful validator for a fixed BitPackerSchema. BitPackerValidator<T> is the right choice when a high-throughput pi…

• validator — Stateful validator for a fixed `BitPack…

• validator — Stateful validator for a fixed BitPackerSchema. BitPackerValidator<T> is the right choice when a high-throughput pi…

• validator — Stateful validator for a fixed `BitPack…

• validator — Stateful validator for a fixed BitPackerSchema. BitPackerValidator<T> is the right choice when a high-throughput pi…

• validator — Stateful validator for a fixed BitPackerSchema. BitPackerValidator<T> is the right choice when a high-throughput pi…

Purpose

The four free-function entry points that most consumers use to validate data against a BitPackerSchema without constructing a BitPackerValidator instance. validateSchema(schema, data, options?) is the canonical full-form entry; isValid(schema, data) is the boolean-only fast path; getValidationErrors(schema, data) returns just the error list; validateDataReport(schema, data) returns the full ValidationReport shape suitable for forwarding to a downstream consumer.

These functions are stateless and allocate a fresh validator per call. They are the right choice for one-off validation on a request-handler boundary; for long-lived pipelines that validate millions of records against the same schema, construct a BitPackerValidator once and reuse it.

Features

• validateSchema(schema, data, options?) — full-form entry returning ValidationReport; throws if options.throwOnError === true and any error is found
• isValid(schema, data) — boolean-only fast path; equivalent to validateSchema(...).valid but skips the report construction
• getValidationErrors(schema, data) — returns only the error rows from the report
• validateDataReport(schema, data) — returns the full ValidationReport; alias for validateSchema(schema, data, { throwOnError: false })

Usage: Basic Example

import { validateSchema, isValid } from "@suaveplan/bitpacker-validation";

const schema = { x: 255, name: "-32" };
const report = validateSchema(schema, { x: 100, name: "ok" });
if (!report.valid) {
    console.log(report.errors);
}

if (isValid(schema, { x: 100, name: "ok" })) {
    // …safe to pack…
}

Usage: Advanced Example

import {
    validateSchema,
    BitPackerValidationError,
    ErrorCodes,
} from "@suaveplan/bitpacker-validation";

function safePack(schema: unknown, data: unknown) {
    const report = validateSchema(schema, data, {
        throwOnError: true,
        strictMode: true,
        checkExtraFields: true,
        maxErrors: 10,
    });
    return packIt(schema, data);
}

try {
    safePack({ x: 255 }, { x: 300, extra: "bad" });
} catch (err) {
    if (err instanceof BitPackerValidationError) {
        if (err.code === ErrorCodes.OUT_OF_RANGE) {
            // recover with a clamped value
        }
    }
}

API Reference

validateSchema(schema: BitPackerSchema, data: unknown, options?: ValidateSchemaOptions): ValidationReport

Validates data against schema and returns a ValidationReport. If options.throwOnError === true and errors.length > 0, throws BitPackerValidationError with the first error's code and message.

isValid(schema: BitPackerSchema, data: unknown): boolean

Returns true if data matches schema. Cheap boolean check; equivalent in result to validateSchema(schema, data).valid.

getValidationErrors(schema: BitPackerSchema, data: unknown): ValidationReportItem[]

Returns just the error rows. Warnings are excluded.

validateDataReport(schema: BitPackerSchema, data: unknown): ValidationReport

Returns the full report. Alias for validateSchema(schema, data).

Implementation Notes

• Stateless free-function form. Each call constructs a fresh validator; there is no shared state or cache. For high-throughput pipelines, construct a BitPackerValidator once and call validator.validate(data) repeatedly.
• throwOnError only fires on errors, not warnings. Warnings never throw, regardless of strictMode. The strictMode flag promotes warnings to errors before the throw decision; it does not change the throw threshold itself.
• maxErrors is a soft cap. Validation stops collecting after maxErrors errors are found. Subsequent errors in the data are NOT reported. This caps the error-collection cost on heavily-malformed input but means consumers see only the first maxErrors rows.
• No path on free-function errors. The error rows include path for sub-field errors, but a top-level type mismatch (schema = 255, data = "abc") reports path: "" — the empty string. Consumers checking paths must handle the empty case.