@azure-net/node-kit 0.0.0-stage → 0.1.0

package/VALIDATION.md

@@ -0,0 +1,866 @@
+# Validation API
+
+This reference describes the current `src/validation` implementation and its
+runtime and TypeScript tests. Validation is framework-independent, synchronous
+or asynchronous, and noncoercive. It checks caller-owned data; it is not a parser
+that creates a transformed output.
+
+## Imports and public exports
+
+```ts
+import {
+  Validator,
+  createValidator,
+  createRules,
+  rules,
+  ValidationResult,
+  ValidationError,
+  validationMessagesEn,
+  validationMessagesRu,
+  validationMessagesI18n,
+} from "@azure-net/node-kit/validation";
+```
+
+The package root is intentionally not exported. Catalog-only entry
+points are `@azure-net/node-kit/validation/messages`,
+`@azure-net/node-kit/validation/messages/en` (`validationMessagesEn`), and
+`@azure-net/node-kit/validation/messages/ru` (`validationMessagesRu`).
+
+Public types exported by the validation entry point:
+
+| Group                 | Types                                                                                                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Rules                 | `RuleOptions`, `RuleFailure`, `RuleResult`, `RuleContext`, `SyncValidationRule`, `AsyncValidationRule`, `ValidationRule`, `BuiltinRule`, `FieldRule`, `ValidationRules`, `AnyRule`, `TypedRules` |
+| Messages              | `ValidationPath`, `ValidationParams`, `MessageContext`, `ValidationMessage`, `ValidationMessages`, `ValidationLocales`                                                                           |
+| Results/configuration | `ValidationIssue`, `ValidationErrors`, `ValidatorOptions`, `ValidatorCreateOptions`, `ValidationOptions`, `ValidationArguments`                                                                  |
+| String options        | `LengthOptions`, `UuidOptions`, `UrlOptions`, `NanoidOptions`, `JwtOptions`, `MacOptions`, `HashOptions`, `HashAlgorithm`, `IsoTimeOptions`, `IsoDateTimeOptions`                                |
+| Value options         | `ValueRangeOptions`, `ValueClockOptions`, `ValueFileOptions`                                                                                                                                     |
+
+Use the merged `rules` object, not internal modules. There is no public
+`/validation/rules` package subpath. `testRule`, `descriptor`, the engine functions,
+and individual internal rule-group objects are not public entry-point exports.
+`AnyRule` is the exported erased representation; prefer the typed callback types.
+
+## Define a validator
+
+Every field has an **array of rules**, not a fluent chain. Define a no-argument
+subclass and call its static methods; do not instantiate it to validate input.
+
+```ts
+import {
+  Validator,
+  rules as r,
+  type ValidationRules,
+} from "@azure-net/node-kit/validation";
+
+interface Registration {
+  email: string;
+  password: string;
+  confirmation: string;
+  nickname?: string | null;
+}
+
+class RegistrationValidator extends Validator<Registration> {
+  protected rules(): ValidationRules<Registration> {
+    return {
+      email: [r.string(), r.email()],
+      password: [r.string(), r.minLength(12)],
+      confirmation: [r.string(), r.sameAs("password")],
+      nickname: [r.nullish(), r.string(), r.maxLength(40)],
+    };
+  }
+}
+
+const input: unknown = {
+  email: "ada@example.com",
+  password: "a-long-password",
+  confirmation: "a-long-password",
+};
+const data: Registration = RegistrationValidator.validateAndThrow(input);
+```
+
+`ValidationRules<T, TRoot = T, TContext = unknown>` requires entries for every
+model key, including optional properties. Structural rule output types must fit
+the declared field type. A TypeScript `?` does not add runtime optional behavior;
+use `optional()` or `nullish()` explicitly. There is no schema-to-model inference
+API replacing the declared `T`, and `unknown()` does not prove a narrower model.
+
+Schema field keys must be strings or numbers, not symbols. `ValidationRules`
+rejects symbol-keyed fields at compile time. At runtime, a symbol-keyed subclass
+definition throws `TypeError` when its schema is first built; `object()` and both
+`intersection()` shapes reject own symbol keys at construction. Numeric object
+keys become string property paths. This restriction is on schema keys, not values:
+`symbol()` still validates a symbol value in a supported field.
+
+Each visited field must have a structural rule such as `string()`, `number()`,
+`object()`, or `unknown()`. A list containing only `email()`, `minLength()`, a
+callback, or no rules throws `TypeError` for a non-skipped value. Markers alone
+do not guard non-nullish values. `optional()`, `nullable()`, and `nullish()` skip
+all other rules for their accepted nullish values, regardless of array order.
+Thus `[optional(), required(), string()]` still permits `undefined`.
+
+## Four static methods
+
+All methods accept `input: unknown`, not an already trusted `T`.
+
+| Method                                     | Return                         | Invalid data                      |
+| ------------------------------------------ | ------------------------------ | --------------------------------- |
+| `V.validate(input, options?)`              | `ValidationResult<T>`          | Failed result                     |
+| `V.validateAndThrow(input, options?)`      | `T`                            | Throws `ValidationError<T>`       |
+| `V.validateAsync(input, options?)`         | `Promise<ValidationResult<T>>` | Resolves to failed result         |
+| `V.validateAndThrowAsync(input, options?)` | `Promise<T>`                   | Rejects with `ValidationError<T>` |
+
+`ValidationOptions<C>` contains `locale?: string`, `context?: C`, and
+`signal?: AbortSignal`. With a concrete dependency type `C` on `Validator<T, C>`,
+the call requires an options object with `context: C`; locale alone is not enough.
+With the default `unknown` context, options are optional. Context is typed, not
+runtime-validated by the library.
+
+`result.isValid` is a boolean, not a discriminated-union type guard:
+`result.data` remains `T | undefined` in TypeScript even after checking it.
+The throwing APIs provide a direct `T` on success.
+
+Unexpected exceptions from callbacks, message functions, locale providers, or
+dependencies propagate unchanged. They are not validation issues. Cancellation
+propagates the signal's abort reason, not `ValidationError`.
+
+## Configured base classes
+
+```ts
+import {
+  Validator,
+  validationMessagesRu,
+  validationMessagesI18n,
+} from "@azure-net/node-kit/validation";
+
+const RussianValidator = new Validator.create({
+  messages: validationMessagesRu,
+  defaultLocale: "ru",
+});
+
+// Supply this function from application-owned request storage.
+declare function currentRequestLocale(): string | undefined;
+const LocalizedValidator = new Validator.create({
+  messages: validationMessagesI18n,
+  defaultLocale: "en",
+  fallbackLocale: "en",
+  getLocale: () => currentRequestLocale(),
+});
+
+// Extend RussianValidator<Model> or LocalizedValidator<Model, Dependencies>.
+```
+
+`Validator.create(options)`, `new Validator.create(options)`, and
+`createValidator(options)` all return a configured **base class**, not a validator
+instance or a schema. Configuration and copied catalogs are frozen. A flat
+`messages` catalog applies to every locale. A locale-to-catalog `messages` map
+selects translations by locale. Do not mix flat entries and nested catalogs.
+Explicit `locales` takes precedence over locale-keyed `messages` when both are
+supplied. The class exposes `static readonly configuration: ValidatorOptions`.
+
+| Option           | Default                | Meaning                                                                                        |
+| ---------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `messages`       | None                   | Flat overrides, or locale-keyed catalogs in `ValidatorCreateOptions`                           |
+| `locales`        | Built-in `en`/`ru` map | Explicit locale-keyed catalogs                                                                 |
+| `defaultLocale`  | `"en"`                 | Locale when neither call nor provider supplies one                                             |
+| `fallbackLocale` | `"en"`                 | Fallback catalog lookup                                                                        |
+| `getLocale`      | None                   | Synchronous `() => string \| undefined`, evaluated per validation                              |
+| `unknownKeys`    | `"reject"`             | Object unknown-key policy; `"allow"` preserves keys                                            |
+| `cascade`        | `"stop"`               | Stop after first failed check per field; `"continue"` collects more built-in constraint issues |
+| `maxNodes`       | `10000`                | Traversal budget; configured integer range `1..10000`                                          |
+| `maxDepth`       | `64`                   | Traversal depth; configured integer range `1..64`                                              |
+| `maxIssues`      | `100`                  | Diagnostic count; configured integer range `1..10000`                                          |
+
+Factories reject invalid limits with `RangeError`. Root depth starts at zero and
+counts as a node. Nested values, keys, lazy/validator expansions, and union
+alternatives consume traversal work; union branches share the node budget.
+Depth/node exhaustion is invalid (`validation.depth` / `validation.nodes`, or a
+containing union failure). Reaching `maxIssues` truncates diagnostics without an
+extra truncation issue. These are traversal/diagnostic limits, not input-byte,
+CPU-time, regex, network-timeout, or custom-callback allocation limits.
+
+## Execution, ownership, and safety
+
+1. The engine prepares structure across the input before user callbacks. Nullish
+   markers skip their accepted values first. For unskipped null/undefined values,
+   explicit `required()`, `notNull()`, and `notEmpty()` predicates run before type
+   guards so their presence messages are retained. Otherwise, structural guards
+   run before value constraints irrespective of their positions in a list.
+2. A structural failure in the main traversal suppresses **all** user callbacks,
+   including callbacks on otherwise valid siblings. Rejected union alternatives
+   are isolated; a valid alternative can still succeed.
+3. Built-in constraints run before callbacks on a field. Child jobs precede parent
+   callbacks. A failed field or descendant suppresses that field's callbacks.
+4. The default cascade stops on the first failed check per field. `"continue"`
+   allows further built-in constraints, but does not make callbacks run after a
+   failure. An unrelated value-constraint failure need not suppress valid siblings.
+5. Async rules and attempted union branches are awaited sequentially, not in
+   parallel. An ordinary `union()` discards failed branch diagnostics on success;
+   failure reports a single union issue rather than a public branch-error tree.
+   `discriminatedUnion()` instead validates its selected branch directly and
+   retains precise nested issue paths and messages from that branch.
+
+The nullish presence precheck stops at the first failed presence predicate in
+rule-array order, even with `cascade: "continue"`. That failure marks preparation
+as structurally invalid and suppresses user callbacks across the validation.
+If all applicable presence checks pass, normal type checking proceeds;
+`notNull()` alone accepts undefined, so a following `string()` can still reject it.
+Presence predicates do not replace the requirement for a structural rule.
+
+For example, `[string(), required({ message: "Name is required" })]` reports
+`"Name is required"` for null or a missing value, but a `string` type error for
+the non-nullish value `42`. Empty strings are non-nullish: they undergo normal
+type checking first, then constraints such as `notEmpty()`. An accepting
+`optional()`, `nullable()`, or `nullish()` marker still bypasses presence checks.
+
+Sync methods throw `TypeError` if an executed rule returns a promise or thenable.
+Use async methods for schemas that may perform async work. Detecting a promise
+cannot undo a callback or side effect that already started. The sync engine
+observes rejection to avoid an unhandled rejection, but cannot cancel that work.
+Similarly, later union attempts cannot undo earlier attempts' side effects.
+
+Signals are checked before traversal/jobs and after awaited results. Forward
+`signal` to dependencies for cooperative cancellation; validation does not race
+or forcibly interrupt a pending promise, synchronous computation, or external I/O.
+
+The library does not mutate, trim, normalize, coerce, strip, default, or clone
+validated input. Successful `data` is the **same reference** as input. Caller-owned
+objects remain unfrozen and mutable, so neither callers nor callbacks should
+mutate input in-flight, especially across awaits. Diagnostics are snapshots, not
+the successful data. Copy data yourself before validation if isolation is needed.
+
+Object fields and array indices are read through own property descriptors.
+Accessors encountered during structural traversal are rejected with
+`object.accessor` without invoking their getters/setters. Inherited values cannot
+satisfy declared fields; sparse array holes are treated as `undefined`.
+Unknown own enumerable string keys reject with `object.unknownKeys` by default;
+`object(shape, { unknownKeys: "allow" })` overrides the global policy locally.
+Allowed keys are not stripped or recursively checked. Symbol and non-enumerable
+unknown keys are not part of this enumeration. `record()` validates own enumerable
+string keys. Object validation is not restricted to plain-object prototypes, but
+rejects arrays, Dates, Maps, Sets, RegExps, ArrayBuffers, and buffer views.
+
+These protections are not a sandbox for arbitrary executable objects: `unknown()`
+does not traverse contents, custom callbacks can access anything, proxies can
+execute traps, and rules such as `uniqueBy()` read selected properties. Use
+ordinary data objects from a trusted parsing boundary. Traversed cycles reject;
+shared acyclic references are allowed.
+
+`rules()` is called once per subclass, on a new no-argument instance, and its
+shape/rule arrays are cached. Lazy resolvers and child definitions are also cached.
+Do not capture a request, tenant, current user, locale, or request-specific service
+inside `rules()` or a lazy resolver. Read per-call dependencies from `context`,
+per-call data from `root`/`data`, and locale through `getLocale` or call options.
+
+## Custom rules and typed dependencies
+
+Public callback signatures (all imported from the validation entry point):
+
+```ts
+type SyncValidationRule<
+  TValue,
+  TData = unknown,
+  TRoot = TData,
+  TContext = unknown,
+> = (context: RuleContext<TValue, TData, TRoot, TContext>) => RuleResult;
+type AsyncValidationRule<
+  TValue,
+  TData = unknown,
+  TRoot = TData,
+  TContext = unknown,
+> = (
+  context: RuleContext<TValue, TData, TRoot, TContext>,
+) => PromiseLike<RuleResult>;
+type ValidationRule<
+  TValue,
+  TData = unknown,
+  TRoot = TData,
+  TContext = unknown,
+> = (
+  context: RuleContext<TValue, TData, TRoot, TContext>,
+) => RuleResult | PromiseLike<RuleResult>;
+```
+
+`RuleContext` has readonly `value`, `data` (immediate parent object/collection),
+`root` (current validator root), `context` (dependencies), `path` (absolute
+`readonly (string | number)[]`), and `signal: AbortSignal | undefined`.
+Readonly context properties do not deep-freeze their referenced objects.
+
+`RuleResult` is `boolean | RuleFailure | readonly RuleFailure[]`:
+
+| Return                                               | Meaning                            |
+| ---------------------------------------------------- | ---------------------------------- |
+| `true` or `[]`                                       | Success                            |
+| `false`                                              | Failure with code `custom.invalid` |
+| `{ message, code, messageKey, label, params, path }` | One failure; all members optional  |
+| Array of failure objects                             | Multiple issues                    |
+
+`RuleFailure` extends `RuleOptions` with `params?: Readonly<Record<string, unknown>>`
+and `path?: ValidationPath`. Failure paths are **relative to the current field**,
+not absolute. Omit the path for the field itself. Return a failure object for an
+expected rejection; throw for an operational failure. Strings, `undefined`, and
+arrays of booleans are not valid results.
+
+```ts
+import {
+  Validator,
+  rules as r,
+  type AsyncValidationRule,
+  type ValidationRules,
+} from "@azure-net/node-kit/validation";
+
+interface Account {
+  email: string;
+}
+interface Dependencies {
+  emailExists(email: string, signal?: AbortSignal): Promise<boolean>;
+}
+
+export const unusedEmail: AsyncValidationRule<
+  string,
+  Account,
+  Account,
+  Dependencies
+> = async ({ value, context, signal }) =>
+  (await context.emailExists(value, signal))
+    ? { code: "email.taken", message: "Email is already registered." }
+    : true;
+
+class AccountValidator extends Validator<Account, Dependencies> {
+  protected rules(): ValidationRules<Account, Account, Dependencies> {
+    return { email: [r.string(), r.email(), unusedEmail] };
+  }
+}
+
+declare const input: unknown;
+declare const dependencies: Dependencies;
+const account: Account = await AccountValidator.validateAndThrowAsync(input, {
+  context: dependencies,
+});
+```
+
+### Typed nested rules
+
+`createRules<T, C>()` returns `TypedRules<T, C>`, a frozen facade over `rules`.
+Its `object`, `array`, `record`, `map`, `set`, and `tuple` helpers preserve the root
+`T` and dependency `C` types inside nested callbacks, while `data` is the immediate
+container. The bound `object()` inference overload uses the leading built-in
+descriptor in each field's rule array to infer the field type, then contextually
+types subsequent callbacks without letting them widen that inferred model.
+For example, `[r.string(), callback]` infers a string value and the corresponding
+typed parent object. A second overload accepts `ValidationRules<V, T, C>`;
+explicit nested generics remain available for pretyped shapes or when inference
+is insufficient. Leading descriptors matter for this inference overload, not
+for changing runtime rule execution order.
+
+```ts
+import {
+  createRules,
+  type ValidationRules,
+} from "@azure-net/node-kit/validation";
+
+interface Order {
+  tenant: string;
+  rows: { sku: string }[];
+}
+interface Services {
+  accepts(tenant: string, sku: string): boolean;
+}
+const r = createRules<Order, Services>();
+
+const orderRules: ValidationRules<Order, Order, Services> = {
+  tenant: [r.string()],
+  rows: [
+    r.array<Order["rows"][number]>([
+      r.object({
+        sku: [
+          r.string(),
+          ({ value, data, root, context }) =>
+            data.sku === value && context.accepts(root.tenant, value),
+        ],
+      }),
+    ]),
+  ],
+};
+```
+
+For raw helpers, supply their root/context generics explicitly if needed, for
+example `rules.object<Child, Root, Dependencies>(shape)`. Unbound nested helpers
+default unknown root/context types. The facade does not rebind `union`,
+`discriminatedUnion`, `intersection`, `lazy`, or `when`; those retain their own
+generic signatures.
+
+`createRules<T, C>().sameAs(key)` and `.notSameAs(key)` restrict keys to string keys
+of `T`. They still compare the **immediate sibling** at runtime, never the root or
+a dotted path. For nested sibling names, use `createRules<Child>()` for comparison
+descriptors or raw `rules.sameAs("childKey")`; a root-bound facade does not
+automatically change its allowed comparison keys when entering a nested object.
+
+### Child-validator boundary
+
+`rules.validator(ChildValidator)` reuses the child's cached schema. Inside it,
+`root` is the child value, even under arrays or multiple nested validator boundaries.
+Paths remain absolute in the outer input; dependency context and signal remain
+the outer call's. A callback beside `validator(...)` in the outer field's array
+still sees the outer root. Ordinary `object()` and `lazy()` do not reset root.
+
+Child composition reuses the definition, not the child's static validation method.
+The child's configured `unknownKeys` policy applies throughout its subtree,
+defaulting to `"reject"` even when the parent allows unknown keys. Thus a child
+configured with `"allow"` permits unknown keys within its subtree even under a
+rejecting parent. Explicit nested `object(..., { unknownKeys })` options override
+the subtree policy locally; a further `validator(...)` boundary establishes that
+child's own policy. Siblings outside the child subtree retain the parent's policy.
+
+All other configuration, including localization, cascade, and shared traversal/
+issue budgets, remains inherited from the outer validation call; child defaults
+for those settings are not independently applied. Descriptors now carry dependency
+and root types as `BuiltinRule<TValue, TContext, TRoot>`. Child descriptors preserve
+their dependency contract, so typed parent rule maps must supply a compatible
+context, including through structural wrappers. Dependencies are still supplied
+by the caller and are not runtime-validated.
+
+## Messages and locale resolution
+
+`RuleOptions` is `{ message?, messageKey?, code?, label? }`. Messages are strings
+or `(context: MessageContext) => string`. `MessageContext` exposes `code`,
+`messageKey`, `params`, `path`, `locale`, and `label`.
+
+Locale precedence, resolved once per validation:
+
+1. Call option `locale`.
+2. Configured `getLocale()` result.
+3. Configured `defaultLocale`.
+4. `"en"`.
+
+An explicit locale bypasses `getLocale`. Locale lookup uses exact keys; there is
+no language negotiation or automatic `ru-RU` to `ru` conversion. The application
+should resolve supported language tags before calling validation.
+
+For each issue, lookup uses `messageKey ?? originalCode`, in this order:
+
+1. Rule/failure `message`.
+2. Flat configured `messages[key]`.
+3. Configured selected-locale catalog (or built-in locale map when none configured).
+4. Built-in selected-locale catalog.
+5. Configured fallback-locale catalog (or built-in fallback map when none configured).
+6. Built-in English catalog.
+7. Literal `"Invalid value"`.
+
+The requested locale remains in `MessageContext.locale` even when fallback text
+is used. Built-in catalogs currently cover `en` and `ru`, not arbitrary languages.
+Do not assume every possible descriptor code has a translation: for example,
+current exact-tuple-length failures use `array.length`, and absent entries follow
+the fallback chain. Add application catalog entries for custom codes.
+
+For a built-in rule, `code` overrides the emitted issue code without changing its
+default lookup key; use `messageKey` to select a different translation. A custom
+failure's `code` is its base lookup code unless `messageKey` is supplied. Failure
+options override descriptor options; failure params merge over descriptor params.
+
+After a string or function message is obtained, `{label}` uses the explicit label
+or the last path segment (`"value"` at root). Other `{word}` placeholders use own
+params and `String(...)`; missing placeholders remain unchanged. This is simple
+interpolation, not ICU formatting, escaping, pluralization, or HTML sanitization.
+Never include secrets in messages or params.
+
+## Results and HTTP errors
+
+`ValidationResult<T>` exposes readonly `isValid`, `data`, and `issues`.
+Each `ValidationIssue` contains `path`, `code`, rendered `message`, and `params`.
+Failed results discard input (`data === undefined`); successful results retain it
+by reference. The public constructor is `new ValidationResult(data, issues)`;
+no issues means success, even if the supplied data is `undefined`.
+
+`errors: ValidationErrors<T>` is a lazily built, cached, frozen tree:
+
+- `messages` stores issues at that exact node, including root/form errors.
+- `fields` stores string path segments, including literal dots and brackets.
+- `items` stores numeric path segments, filling preceding unaffected indices with
+  explicit `null` placeholders, not sparse holes. It is not padded to input length.
+- Parent messages are retained alongside child `fields`/`items`; they are never
+  replaced by descendant errors. This does not imply every parent rule executes
+  after a child has failed.
+
+For issues at root, `rows`, and `rows[2].name`, a possible serialized tree is:
+
+```json
+{
+  "messages": ["Form is invalid"],
+  "fields": {
+    "rows": {
+      "messages": ["Rows need review"],
+      "items": [
+        null,
+        null,
+        {
+          "messages": [],
+          "fields": { "name": { "messages": ["Name is required"] } }
+        }
+      ]
+    }
+  }
+}
+```
+
+Separate namespaces allow input fields named `messages`, `fields`, `items`, or
+`__proto__`. String `"0"` is a field; numeric `0` is an item.
+`formErrors` returns root messages. `toFieldErrors()` returns a frozen flat record
+of RFC 6901 JSON Pointer keys to message arrays: `~` becomes `~0`, `/` becomes
+`~1`, and root errors are omitted. Numeric and string zero share a flat pointer;
+use the tree when that distinction matters.
+
+Issues, paths, and metadata are detached frozen snapshots. Metadata is converted
+to JSON-safe data: bigints become decimal strings, valid Dates ISO strings,
+RegExps `/source/flags`, invalid Dates/nonfinite numbers `null`, and cycles
+`"[Circular]"`. Accessors, functions, symbols, undefined, and proxies are omitted
+(or `null` in arrays); getters and `toJSON` are not invoked during snapshotting.
+Snapshots are bounded: depth 32, container width 1000, per-result 10000 entries
+and 100000 characters, individual text up to 4096 characters. Truncation uses
+`"[Truncated]"` and sometimes a `$snapshot` marker; oversized keys are omitted.
+These limits do not sanitize rendered message text.
+
+Public result construction also caps issues at 10000, path depth at 128, numeric
+indices at `0..10000`, tree nodes at 100000, and aggregate array slots at 100000.
+Invalid paths or excessive allocations throw rather than producing an unsafe
+tree. Custom relative paths are subject to these bounds too.
+
+`ValidationError<T>` extends `Error`, requires a failed result, and exposes
+`result`, `issues`, and `errors`. Its default message is `"Validation failed"`;
+`new ValidationError(result, message)` overrides it. `toJSON()` includes only
+`name`, `message`, `issues`, and `errors`, not input or stack. Application-supplied
+diagnostic text/params can still expose data, so avoid sensitive values.
+
+```ts
+import { ValidationError } from "@azure-net/node-kit/validation";
+import { ResponseBuilder } from "@azure-net/node-kit/delivery/http";
+
+function validationResponse(error: unknown): Response {
+  if (!(error instanceof ValidationError)) throw error;
+  return ResponseBuilder.UnprocessableEntity(null, {
+    message: "Validation failed",
+    code: "VALIDATION_FAILED",
+    errors: error.errors,
+  }).toResponse();
+}
+```
+
+There is no automatic HTTP mapping. `UnprocessableEntity(data?, options?)` fixes
+status 422; without a code override its code is `UNPROCESSABLE_ENTITY`. Pass
+`error.issues` instead if the client needs codes, params, and paths. The response's
+top-level message is independent of localized field messages.
+
+### Hono integration (conceptual)
+
+Hono is **not a dependency** of this package. In a Hono application, install the
+application's context-storage middleware before routes, then provide a
+`getLocale` closure that reads the current request's resolved locale from that
+storage. Read storage when validation starts, not while constructing the schema.
+Use the application's supported-locale selection policy; do not treat the raw
+`Accept-Language` header as a catalog key.
+
+At a route boundary, parse the body into `unknown`, pass explicit typed services
+as `context`, and await `validateAndThrowAsync`. Catch `ValidationError` in the
+application error boundary and build a 422 envelope as above; operational errors
+must follow a different error path. A Hono handler can return the native
+`response.toResponse()` or `c.json(response.toJSON(), response.status)`. `toJSON()`
+returns an object; do not JSON-stringify it before passing it to `c.json`.
+Alternatively pass `locale` explicitly and bypass context storage altogether.
+The toolkit creates no Hono adapter, global locale, or request storage itself.
+
+## Complete built-in rule catalog
+
+Below, `o?` means optional `RuleOptions` unless a more specific exported option
+type is stated. Factories return immutable descriptors except `when`, `some`, and
+`every`, which return callbacks. Constraints need an accompanying structural
+guard even if they independently reject wrong types. Invalid factory arguments
+generally throw `TypeError` or `RangeError`, not a failed validation result.
+
+### Structural scalars and presence
+
+| Rule                                            | Semantics                                                                                            |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `string(o?)`                                    | Primitive strings, including empty strings; structural guard                                         |
+| `number(o?)`, `finite(o?)`                      | Finite primitive numbers, excluding NaN/infinities; structural guards                                |
+| `bigint(o?)`, `boolean(o?)`, `symbol(o?)`       | Exact primitive type; structural guards                                                              |
+| `date(o?)`                                      | Valid `Date` instance, not a timestamp/string; structural guard                                      |
+| `null(o?)`, `undefined(o?)`, `nan(o?)`          | Exactly null, undefined, or numeric NaN; structural guards                                           |
+| `unknown(o?)`                                   | Accept any value without traversing it; structural guard                                             |
+| `never(o?)`                                     | Reject every value; structural guard                                                                 |
+| `instanceOf(constructor, o?)`                   | `instanceof` check against the supplied constructor; structural guard                                |
+| `literal(expected, o?)`                         | `Object.is` equality to string, finite number, bigint, boolean, or null; structural guard            |
+| `enum(values, o?)`                              | Nonempty literal array, or string/number enum object; exact `Object.is` membership; structural guard |
+| `enumName(enumObject, o?)`                      | String member names, excluding numeric reverse mappings; structural guard                            |
+| `optional()`                                    | Skip undefined/missing values                                                                        |
+| `nullable()`                                    | Skip null values only                                                                                |
+| `nullish()`                                     | Skip undefined/missing and null values                                                               |
+| `required(o?)`                                  | Reject null and undefined; accepts empty string, zero, and false; constraint                         |
+| `notNull(o?)`                                   | Reject null only (undefined passes); constraint                                                      |
+| `empty(o?)`, `notEmpty(o?)`                     | Empty/nonempty constraint, not a type guard                                                          |
+| `equal(expected, o?)`, `notEqual(expected, o?)` | Deep strict equality/inequality via Node `isDeepStrictEqual`                                         |
+
+Enum objects exclude TypeScript numeric reverse mappings. Arrays can include
+bigint, boolean, and null; enum objects accept string/finite-number values only.
+No conversion of enum names or numeric strings occurs. Erased `const enum`s
+cannot supply a runtime object. `literal` distinguishes `-0` and `0`.
+
+Empty means nullish, a string whose `trim()` is empty, an empty array/Map/Set/Blob,
+or a plain/null-prototype object with no own keys (including symbol keys).
+Whitespace is examined, not removed. Zero, false, `[undefined]`, and
+`{ value: undefined }` are nonempty.
+
+### Numbers, ranges, and decimals
+
+| Rule                                                          | Semantics                                                                                               |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `int32(o?)`                                                   | Structural number guard, integer `-2147483648..2147483647`                                              |
+| `uint32(o?)`                                                  | Structural number guard, integer `0..4294967295`                                                        |
+| `float32(o?)`                                                 | Structural finite-number guard, absolute value at most `3.4028234663852886e38`; range only, no rounding |
+| `int64(o?)`                                                   | Structural bigint guard, `-(2n ** 63n)..2n ** 63n - 1n`                                                 |
+| `uint64(o?)`                                                  | Structural bigint guard, `0n..2n ** 64n - 1n`                                                           |
+| `integer(o?)`                                                 | Integer finite number or any bigint; constraint                                                         |
+| `safeInteger(o?)`                                             | Number/bigint within JS safe-integer bounds; constraint                                                 |
+| `positive(o?)`, `negative(o?)`                                | Finite number/bigint strictly above/below zero                                                          |
+| `nonNegative(o?)`, `nonPositive(o?)`                          | Finite number/bigint including zero                                                                     |
+| `min(bound, o?)`, `max(bound, o?)`                            | Inclusive by default; `ValueRangeOptions.inclusive: false` excludes bound                               |
+| `lessThan(bound, o?)`, `greaterThan(bound, o?)`               | Exclusive by default; `inclusive: true` includes bound                                                  |
+| `lessThanOrEqual(bound, o?)`, `greaterThanOrEqual(bound, o?)` | Always inclusive; ordinary `RuleOptions`                                                                |
+| `between(min, max, o?)`                                       | Same-type ordered bounds; both inclusive by default                                                     |
+| `multipleOf(divisor, o?)`                                     | Same-type finite number/bigint, nonzero divisor; exact decimal-number divisibility or bigint remainder  |
+| `decimal(places?, o?)`                                        | Finite number or decimal-notation string, optionally bounded fractional places                          |
+| `precisionScale(precision, scale, o?)`                        | At most `precision - scale` integer and `scale` fractional digits                                       |
+
+Bounds accept finite numbers, bigints, or valid Dates, but input must have the
+same kind as the bound. Date targets are snapshotted as timestamps. Reversed or
+mixed-kind `between` bounds throw. `between` endpoint settings
+`minInclusive`/`maxInclusive` override `inclusive`; these endpoint settings do not
+change single-bound checks.
+
+`float32` is not an exact `Math.fround` representability test: it accepts `0.1`
+and tiny finite doubles within range. 64-bit integer rules require bigint, not
+JS numbers. `multipleOf(0.1)` accepts `0.3` but rejects `0.1 + 0.2`; it compares
+shortest round-trip decimal number representations without epsilon tolerance.
+
+Decimal checks accept signed decimal/exponent notation, including `.5` and `1.`,
+but no whitespace, hex, separators, bigint, NaN, or infinity. Strings retain exact
+digits; number inputs use their decimal representation. Trailing fractional zeros
+do not consume scale. Input notation is limited to 4096 characters, and exponent
+handling avoids exponent-sized allocations. `places`, precision, and scale are
+nonnegative safe integers; precision must be positive and scale cannot exceed it.
+These checks never convert the original string into a number. Pair with `string()`
+for decimal strings or an explicit number/string union to accept both.
+
+### Dates and files
+
+| Rule                                      | Semantics                                                                                      |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `before(target, o?)`, `after(target, o?)` | Strict comparison to a valid Date                                                              |
+| `same(target, o?)`                        | Same Date instant in milliseconds, not calendar-day equality                                   |
+| `isPast(o?)`, `isFuture(o?)`              | Strict comparison to a per-check clock; `ValueClockOptions`                                    |
+| `file(o?)`                                | Structural real-File metadata validation; returns `BuiltinRule<File>`; `ValueFileOptions`      |
+| `blob(o?)`                                | Structural Blob/File metadata validation; returns `BuiltinRule<Blob>`; same `ValueFileOptions` |
+
+Date constraints require Date input; pair with `date()`. Relative-date options
+accept `clock?: () => Date | number`; default reads `Date.now()` for each check.
+An invalid clock result throws. Target Dates are snapshotted at rule construction.
+
+`file()` requires a genuine File instance, rejecting plain Blobs even if they
+have an added `name` property. Its `BuiltinRule<File>` output supports File-typed
+DTO fields. `blob()` accepts genuine Blob or File instances and returns
+`BuiltinRule<Blob>`; use it when a filename is not required. Both use the
+`node:buffer` classes, reject file-shaped objects and forged prototype-only
+instances, and validate metadata without converting or cloning the value.
+
+```ts
+import type { Blob, File } from "node:buffer";
+import { rules, type ValidationRules } from "@azure-net/node-kit/validation";
+
+interface Upload {
+  attachment: File;
+  content: Blob;
+}
+const uploadRules: ValidationRules<Upload> = {
+  attachment: [rules.file({ maxSize: 5_000_000, extensions: ["pdf"] })],
+  content: [rules.blob({ maxSize: 5_000_000 })],
+};
+```
+
+Both rules share `ValueFileOptions`. `minSize`/`maxSize` are inclusive byte sizes.
+`mimeTypes` contains exact
+types or subtype wildcards such as `image/*`, matched case-insensitively against
+the declared MIME essence while ignoring parameters such as charset.
+`extensions` contains case-insensitive suffixes with or without a leading dot;
+checking extensions requires a real File and uses its native name, including
+when configured on `blob()`. Adding a name to a Blob does not satisfy this check.
+Size bounds must be ordered nonnegative safe integers. Both rules are synchronous:
+**no bytes are read,
+no MIME signature/content inspection is performed**, and metadata is not proof
+of safe content. Apply actual content/security checks separately.
+
+### Strings, lengths, and patterns
+
+| Rule                                                               | Semantics                                                          |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `length(n, o?)`, `minLength(n, o?)`, `maxLength(n, o?)`            | Exact/min/max size; `LengthOptions`                                |
+| `matches(regex, o?)`                                               | RegExp test, not necessarily a full-string match                   |
+| `includes(text, o?)`, `startsWith(text, o?)`, `endsWith(text, o?)` | Case-sensitive substring/prefix/suffix checks                      |
+| `lowercase(o?)`, `uppercase(o?)`                                   | Value equals its JS lower/upper-case conversion; no transformation |
+
+Lengths count Unicode code points by default, or UTF-16 units with
+`{ unit: "codeUnits" }`; neither counts grapheme clusters. Arrays count elements,
+Maps/Sets entries. Length bounds are nonnegative safe integers. Format/string
+constraints should normally be paired with `string()`.
+
+`matches` and URL filter patterns are copied with flags and reset internally;
+they do not mutate caller `lastIndex`. Supply anchors if full matching is wanted.
+Regex state-safety does not imply ReDoS safety: caller patterns must be trusted,
+and JavaScript RegExp execution has no timeout here.
+
+### String formats and scope
+
+All entries below are nonstructural string constraints; add `string()`.
+Unless noted, options are ordinary `RuleOptions`. These are format checks, not
+existence, ownership, authenticity, allocation, or reachability checks.
+
+| Rule                                   | Accepted format and limitations                                                                                                                              |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `email(o?)`                            | ASCII dot-atom local part up to 64 characters, dotted DNS domain, total up to 254; not all RFC 5322 mailboxes, no quoted local parts or deliverability check |
+| `uuid(o?)`                             | RFC 9562 versions 1-8; `UuidOptions.version` restricts version; unrestricted also accepts Nil/Max UUIDs; case-insensitive                                    |
+| `guid(o?)`                             | Hyphenated `8-4-4-4-12` hex shape without UUID version/variant constraints                                                                                   |
+| `url(o?)`                              | Absolute WHATWG URL, including non-HTTP schemes; `UrlOptions.protocol`/`hostname` RegExp filters                                                             |
+| `httpUrl(o?)`                          | HTTP/HTTPS with explicit `://` and hostname; same URL filters; localhost/IPs can pass                                                                        |
+| `hostname(o?)`                         | ASCII DNS labels up to 63 characters, total name up to 253 excluding optional root dot; use punycode for IDNs                                                |
+| `e164(o?)`                             | `+` followed by 2-15 digits with nonzero first digit; not allocation/reachability verification                                                               |
+| `emoji(o?)`                            | Common Unicode-property-based emoji sequences, flags, keycaps, modifiers, and joins; not a versioned RGI membership test                                     |
+| `base64(o?)`                           | Canonical padded RFC 4648 Base64; empty allowed                                                                                                              |
+| `base64url(o?)`                        | Canonical unpadded RFC 4648 URL alphabet; empty allowed                                                                                                      |
+| `hex(o?)`                              | Case-insensitive hex digits, including empty/odd-length strings; no `0x` prefix                                                                              |
+| `jwt(o?)`                              | Three nonempty canonical base64url segments; UTF-8 JSON object header/payload; syntax only; `JwtOptions.algorithm` optionally requires exact header `alg`    |
+| `nanoid(o?)`                           | URL alphabet letters/digits/underscore/hyphen, length 21 by default; positive safe-integer `NanoidOptions.length`                                            |
+| `cuid(o?)`                             | Canonical CUID v1 shape: `c` plus 24 lowercase alphanumerics                                                                                                 |
+| `cuid2(o?)`                            | Lowercase leading letter followed by zero or more lowercase alphanumerics; no fixed length                                                                   |
+| `ulid(o?)`                             | 26 case-insensitive Crockford-base32 characters, first digit `0..7`                                                                                          |
+| `xid(o?)`                              | 20 case-insensitive base32hex characters `0-9a-v`; no padding-bit/provenance check                                                                           |
+| `ksuid(o?)`                            | 27 base62 characters; no decoded 160-bit range or timestamp check                                                                                            |
+| `ip(o?)`, `ipv4(o?)`, `ipv6(o?)`       | Node `net.isIP` address parsing; IPv6 zone identifiers rejected                                                                                              |
+| `cidr(o?)`, `cidrv4(o?)`, `cidrv6(o?)` | Address/prefix notation, decimal prefix `0..32` or `0..128` without redundant leading zeros; host bits may be nonzero                                        |
+| `mac(o?)`                              | Six hex byte pairs; `MacOptions.delimiter` is `":"` (default), `"-"`, or `""`; case-insensitive                                                              |
+| `creditCard(o?)`                       | 12-19 digits with optional single space/hyphen between digits and Luhn checksum; all-zero rejected; no issuer/account verification                           |
+| `iban(o?)`                             | Uppercase electronic IBAN shape, 15-34 characters, check digits 02-98 and MOD-97; no country-specific length/BBAN/bank registry validation                   |
+| `currencyCode(o?)`                     | Uppercase currency codes in host `Intl.supportedValuesOf("currency")`; ICU-dependent, not a live ISO registry                                                |
+| `hash(algorithm, o?)`                  | Exact digest length for `md5`, `sha1`, `sha256`, `sha384`, `sha512`; `HashOptions.encoding` is `hex` (default), `base64`, or `base64url`; no content hashing |
+| `isoDate(o?)`                          | Gregorian `YYYY-MM-DD`, actual month/leap-day validation, including astronomical year 0000                                                                   |
+| `isoTime(o?)`                          | Local `HH:mm[:ss[.fraction]]`; `IsoTimeOptions.precision` controls seconds/fraction; no leap seconds or 24:00                                                |
+| `isoDateTime(o?)`                      | Date plus uppercase `T`, UTC `Z` by default; `IsoDateTimeOptions.offset`/`local` opt into offsets/local form                                                 |
+| `isoDuration(o?)`                      | ISO 8601-1 subset: weeks alone, or ordered Y/M/D plus H/M/S; fractions only on seconds with dot/comma; no negative or mixed-week form                        |
+
+URL checks reject whitespace, controls, and backslashes before parsing, but do
+not constitute an SSRF or safe-navigation policy. URL filters see parsed protocol
+without `:` and parsed hostname; the input itself is not rewritten.
+
+JWT checks reject `alg: "none"`, require a nonempty string algorithm, allow an
+absent `typ` or case-insensitive `JWT`, and reject `b64: false`. **No JWT signature
+verification, claim validation, expiration check, or algorithm-security policy
+is performed.** Use a verification library before trusting claims.
+
+ISO time precision defaults to `null`: optional seconds/fractions for local time,
+but seconds are required for zoned date-times. Precision `-1` requires minutes
+only; `0` requires seconds without fraction; a positive safe integer requires
+exactly that many fractional digits. `offset: true` permits `+/-HH:mm` through
+23:59; `local: true` permits a zone-less form. These validate notation, not convert
+to Date or resolve a time zone. ISO durations are not converted to elapsed time.
+
+Implementation sources are the local [StringRules.ts](src/validation/rules/StringRules.ts)
+and [format tests](tests/validation-strings.test.mjs): independent algorithms and
+fixed patterns, Node `net.isIP`, WHATWG `URL`, Buffer encoding round trips, and host
+Unicode/ICU data. The source records a format-scope review against Zod 4.6.7's
+`src/v4/core/{regexes,schemas}.ts` (MIT, Colin McDonnell and contributors); that
+is provenance for the review, not a claim of dependency or exact equivalence.
+Standards named above describe the implemented scope, not blanket certification.
+
+### Structures and collections
+
+| Rule                                      | Signature/semantics                                                                                                                |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `object(shape, o?)`                       | Typed field-to-rule-array shape; options also accept local `unknownKeys`                                                           |
+| `array(itemRules, o?)`                    | Validate every element; empty array valid unless constrained                                                                       |
+| `tuple(ruleLists, o?)`                    | Positional rule arrays, exact length; no rest-element factory option                                                               |
+| `record(valueRules, o?, keyRules?)`       | Own enumerable string-key dictionary; optional key checks share each entry's path                                                  |
+| `map(keyRules, valueRules, o?)`           | Actual Map; paths `[entryIndex, "key"]` and `[entryIndex, "value"]`                                                                |
+| `set(itemRules, o?)`                      | Actual Set; numeric paths by iteration order                                                                                       |
+| `union(alternatives, o?)`                 | At least two rule-array alternatives; first successful branch wins                                                                 |
+| `discriminatedUnion(key, variants, o?)`   | Nonempty string-keyed map of rule arrays; own data-property tag selects branch; selected-branch errors retain precise nested paths |
+| `intersection(leftShape, rightShape, o?)` | Merge two object rule maps; shared fields must satisfy both rule lists independently; not arbitrary schema intersection            |
+| `validator(ChildValidator, o?)`           | Reuse child definition with child root boundary                                                                                    |
+| `lazy(() => ruleArray, o?)`               | Resolve once, cache rules; supports recursive definitions                                                                          |
+
+The discriminator may be a string, number, or boolean, matched by `String(tag)`
+against own variant keys. Missing/inherited/accessor/unknown tags produce a generic
+`type.union` issue at the union field; getters are not invoked. Once a variant is
+selected, its failures are reported directly: for a field `payload` with a selected
+object branch containing `name`, a bad name reports at `["payload", "name"]`,
+not just `["payload"]`. Ordinary `union()` still reports a generic union-field
+failure when no alternative succeeds. Include a structural guard within each branch. A lazy resolver
+must return valid rule arrays, not request-dependent data or a promise.
+
+### Collection constraints, comparisons, and conditions
+
+| Rule                            | Semantics                                                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `unique(o?)`                    | Array elements unique by Set/SameValueZero semantics; objects compared by identity                |
+| `uniqueBy<T>(key: keyof T, o?)` | Array values at own selected property unique by Set semantics; absent properties select undefined |
+| `contains(expected, o?)`        | At least one array element deep-strict-equal to expected                                          |
+| `some<T>(predicate, o?)`        | Callback using array `.some`; predicate `(value: T, index: number) => boolean`                    |
+| `every<T>(predicate, o?)`       | Callback using array `.every`; same predicate type; empty array succeeds                          |
+| `sameAs(key, o?)`               | Current value `Object.is`-equal to an own sibling property                                        |
+| `notSameAs(key, o?)`            | Current value not `Object.is`-equal to an own sibling property                                    |
+| `when(condition, checks)`       | Conditional value checks/callbacks; no separate options argument                                  |
+
+`sameAs`/`notSameAs` both fail when the sibling is absent. They are not deep
+equality: two distinct equal-looking objects differ, NaN equals itself, and
+`+0` differs from `-0`. Use `equal`/`notEqual` for deep comparison to a configured
+value or a custom callback for root-dependent comparisons.
+
+`when<T, D = unknown, R = D, C = unknown>` takes a synchronous
+`(context: RuleContext<T, D, R, C>) => boolean` and an array of
+`FieldRule<T, D, R, C>`. A false condition succeeds without checks. A true condition
+runs them sequentially and stops at the first failure, independently of the outer
+cascade. It may return a promise if a contained callback does. Structural rules,
+markers, objects, unions, and other nested descriptors inside `when` throw at
+construction; put structure outside the condition. `some`/`every` predicates are
+synchronous; async predicates are not awaited. All three are user callbacks for
+the engine's callback-suppression rules.
+
+## Differences from Zod and deliberate non-goals
+
+This is not a claim of total Zod parity. It is a model-first validator with arrays
+of descriptors/callbacks and static class methods, not a fluent schema builder.
+It offers no transforms, defaults, coercion, codecs, preprocessing pipeline,
+schema-driven output cloning, or JSON Schema builder/exporter. Unknown keys reject
+by default, and allowing them preserves them. Structural guards must be explicit;
+format constraints alone are not structural schemas.
+
+Length defaults to code points, not UTF-16 units. `multipleOf` uses exact decimal
+representation rather than epsilon acceptance. `float32` is range-only; 64-bit
+integers require bigint. Decimal strings stay strings. Date rules require Dates,
+while ISO rules validate strings. Ordinary union errors are compact, selected
+discriminated-union errors preserve nested paths, intersection merges object
+shapes only, and typed callbacks run after structural preparation rather
+than in arbitrary array order. Format catalogs have the explicit limits above;
+similar names do not guarantee interchangeable acceptance sets or error shapes.
+
+## Source and test map
+
+- [Public types](src/validation/Types.ts), [Validator](src/validation/Validator.ts),
+  [engine](src/validation/Engine.ts), and [results](src/validation/Result.ts).
+- [Rule exports and typed facade](src/validation/rules/index.ts),
+  [value rules](src/validation/rules/ValueRules.ts),
+  [structure rules](src/validation/rules/StructureRules.ts), and
+  [custom rules](src/validation/rules/CustomRules.ts).
+- [Message exports](src/validation/messages/index.ts) and
+  [HTTP response builder](src/delivery/http/ResponseBuilder.ts).
+- [Engine tests](tests/validation-engine.test.mjs),
+  [presence-order tests](tests/validation-presence.test.mjs),
+  [type tests](tests/validation.types.ts), [result tests](tests/validation-result.test.mjs),
+  [value tests](tests/validation-values.test.mjs), and
+  [string-format tests](tests/validation-strings.test.mjs).