# Validation Top-Level API

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - validator — Stateful validator for a fixed `BitPack…
- [validator](./validator.md) — 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](./validator.md) — 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](./validator.md) — 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](./validator.md) — Stateful validator for a fixed `BitPackerSchema`. `BitPackerValidator<T>` is the right choice when a high-throughput pi…
- [validator](./validator.md) — 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

```ts
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

```ts
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.