first commit

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

@@ -0,0 +1,102 @@
+# 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.