@uniflowed/validator 0.0.0-alpha.4 → 0.0.0-alpha.5

package/index.js

@@ -1,783 +1,265 @@
 // @flow
 //
-// `@uniflowed/validator`: schemas as ordinary Flow-typed JavaScript, so they
-// work identically on Node.js, Deno and Bun with no native binding.
+// `@uniflowed/validator`: a schema is a parser, not an assertion.
 //
-// # Why the package is one file
+// ```js
+// const Account = object({
+//   email: pipe(string(), trim(), email()),
+//   age: pipe(string(), transform(Number), integer(), min(18)),
+//   tags: array(pipe(string(), nonEmpty())),
+// });
 //
-// A schema library is one idea, so it is one module, and that module is the
-// entry point. The primitives, the combinators that nest them, the `pipe`
-// steps that refine them, and the two ways to run one are not four subjects
-// that happen to ship together: they are four views of the same closure.
-// `object` calls the same walk `array` does, `pipe` wraps the kernel every
-// primitive returns, and `parse` is `safeParse` plus a throw.
+// const result = safeParse(Account, await request.json());
+// if (!result.ok) {
+//   return respond(422, flatten(result.issues));
+// }
+// createAccount(result.value); // { email: string, age: number, tags: … }
+// ```
 //
-// The shape this replaced was `index.js` re-exporting a sibling that held all
-// of it. That arrangement costs a reader two files to find the first line of
-// code and tells them nothing in exchange — the directory said "there is
-// structure here" where there was one subject and a list. A package with one
-// concept should be a file with that concept in it, and the exports below are
-// named individually so an application still ships only the checks it calls.
+// `result.value.age` is a `number` and nobody wrote that down. The schema is
+// the only description of the account that exists, and both the type the form
+// collects and the type the application uses are read off it — that is the
+// whole promise of this package, and `infer.js` is where it is kept.
 //
-// # Why every schema is one closure
+// Ordinary Flow-typed JavaScript with no native binding, so it behaves
+// identically on Node.js, Deno and Bun, and every builder is a separate named
+// export so an application ships only the checks it calls.
 //
-// A schema is a `parse` function and nothing else. No class, no registry, no
-// interpreter walking a description of a schema at runtime. The engine that
+// # The four decisions everything else follows from
+//
+// **A schema is a closure, plus a description of itself.** No class, no
+// registry, no interpreter walking a description at run time. The engine that
 // validates a `string()` *is* the four-line closure `string()` returned, which
-// a JIT can inline into the object parser that calls it. It is also why the
-// module tree-shakes: a project that never calls `date()` never ships the Date
-// check, because there is no table holding a reference to it.
+// a JIT can inline into the object parser that calls it. The description is a
+// thunk beside it, allocated only when something asks — and it is what makes
+// `toJsonSchema` possible at all, because a closure cannot be read.
+// `schema.js`.
 //
-// # Why the path is a mutable buffer
+// **An issue says where it happened.** `["users", "2", "email"]`, as segments,
+// not a string somebody has to parse back apart. A form binds errors to
+// fields, and a field is a path. `issue.js`.
 //
-// Issues report where they happened — `["users", "2", "email"]` — and the
-// obvious way to carry that is a fresh array per field, `path.concat(key)`.
-// That allocates once per field per parse, on the *successful* path, to
-// produce a value almost every parse throws away. Instead one array is pushed
-// and popped as the walk descends, and only an actual issue copies it. A
-// thousand-row payload that validates cleanly allocates no paths at all.
+// **Every branch of the value is visited.** A bad third row does not hide a
+// bad seventh one; one parse reports both, because the alternative is two
+// round trips for information that was available at once. `collection.js`,
+// `object.js`.
 //
-// # Why parse throws a typed error
+// **Asynchrony is decided when the schema is built, not when it runs.** A
+// schema containing a `checkAsync` is asynchronous from there up, so
+// `safeParse` refuses it with a message instead of returning a promise where
+// its caller expected a result. `schema.js` sets out the alternative and what
+// it would cost every synchronous parse.
 //
-// `parse` raises [`ValidationError`], which carries the structured issues, not
-// just a joined message. A caller writing an HTTP handler needs the field
-// paths to build a response body, and re-parsing them out of a string is not
-// a thing an API should make anyone do.
-
-/** Where an issue happened, as object keys and array indices from the root. */
-type Path = $ReadOnlyArray<string>;
-
-/** The mutable buffer the walk descends with. See the module docs. */
-type PathBuffer = Array<string>;
-
-type SchemaKernel<T> = {|
-  readonly parse: (mixed, PathBuffer) => Result<T>,
-|};
-
-type SchemaCarrier<T> = {|
-  readonly __kind: "Schema",
-  readonly __type: (T) => T,
-  readonly __kernel: SchemaKernel<T>,
-|};
-
-export opaque type Schema<T> = SchemaCarrier<T>;
-
-export type Issue = {|
-  readonly code: string,
-  readonly message: string,
-  readonly path?: Path,
-|};
-
-export type Result<T> =
-  | {| readonly ok: true, readonly value: T |}
-  | {| readonly ok: false, readonly issues: $ReadOnlyArray<Issue> |};
-
-export type Step<TIn, TOut> = (schema: Schema<TIn>) => Schema<TOut>;
-
-export type Shape = { readonly [string]: Schema<mixed>, ... };
-export type Infer<TSchema> = TSchema extends Schema<infer T> ? T : empty;
-
-/**
- * What [`parse`] raises.
- *
- * A real `Error` subclass so it survives `instanceof`, logging and a `catch`
- * that only knows about errors, and it carries `issues` so a caller can build
- * a field-by-field response without parsing the message back apart.
- */
-export class ValidationError extends Error {
-  readonly issues: $ReadOnlyArray<Issue>;
-
-  constructor(issues: $ReadOnlyArray<Issue>) {
-    super(issues.map(describeIssue).join("; "));
-    this.name = "ValidationError";
-    this.issues = issues;
-  }
-}
-
-function describeIssue(entry: Issue): string {
-  const at = entry.path == null || entry.path.length === 0 ? "" : ` at ${entry.path.join(".")}`;
-  return `${entry.message}${at}`;
-}
-
-function makeSchema<T>(kernel: SchemaKernel<T>): Schema<T> {
-  return { __kind: "Schema", __type: (value) => value, __kernel: kernel };
-}
-
-function readKernel<T>(schema: Schema<T>): SchemaKernel<T> {
-  return schema.__kernel;
-}
-
-function issue(code: string, message: string, path: PathBuffer): Issue {
-  return path.length === 0 ? { code, message } : { code, message, path: path.slice() };
-}
-
-function ok<T>(value: T): Result<T> {
-  return { ok: true, value };
-}
-
-function failIssue(code: string, message: string, path: PathBuffer): Result<empty> {
-  return { ok: false, issues: [issue(code, message, path)] };
-}
-
-function mergeIssues(issues: Array<Issue>, result: Result<mixed>): void {
-  match (result) {
-    {ok: false, issues: const nextIssues} => {
-      for (const entry of nextIssues) {
-        issues.push(entry);
-      }
-    }
-    _ => {}
-  }
-}
-
-function parseInternal<T>(schema: Schema<T>, value: mixed, path: PathBuffer): Result<T> {
-  return readKernel(schema).parse(value, path);
-}
-
-/**
- * Parse `value` at one step deeper in the path.
- *
- * The push/pop pair is why the buffer stays balanced even when a nested schema
- * returns early: nothing between them can throw except user code inside a
- * `transform` or a `check`, and a schema that raised has already failed the
- * whole parse.
- */
-function parseAt<T>(schema: Schema<T>, value: mixed, path: PathBuffer, key: string): Result<T> {
-  path.push(key);
-  const result = parseInternal(schema, value, path);
-  path.pop();
-  return result;
-}
-
-function refine<T>(
-  schema: Schema<T>,
-  check: (T) => boolean,
-  code: string,
-  message: string,
-): Schema<T> {
-  return makeSchema({
-    parse: (value, path) => {
-      const result = parseInternal(schema, value, path);
-      if (!result.ok) {
-        return result;
-      }
-      return check(result.value) ? result : failIssue(code, message, path);
-    },
-  });
-}
-
-function isPlainObject(value: mixed): boolean {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
-
-function plainRecord(value: mixed): { readonly [string]: mixed, ... } {
-  // This is the single object boundary in the validator kernel. Every caller checks
-  // `isPlainObject` first, then schemas validate each exported field before exposing T.
-  // $FlowFixMe[incompatible-type]
-  return value as { readonly [string]: mixed, ... };
-}
-
-/**
- * Write a parsed field into the object being built.
- *
- * `out[key] = value` runs a setter when `key` is `__proto__`, so an input
- * carrying that key would change the object's prototype instead of adding a
- * field — and everything downstream would then read attacker-chosen values
- * from a prototype it never inspected. `defineProperty` writes an own
- * property whatever the key is called.
- */
-function put<Value>(out: { [string]: Value, ... }, key: string, value: Value): void {
-  Object.defineProperty(out, key, {
-    value,
-    writable: true,
-    enumerable: true,
-    configurable: true,
-  });
-}
-
-export function string(): Schema<string> {
-  return makeSchema({
-    parse: (value, path) =>
-      typeof value === "string" ? ok(value) : failIssue("type", "expected string", path),
-  });
-}
-
-/**
- * A finite number.
- *
- * `NaN` and the infinities are rejected. They are numbers to `typeof` and
- * disasters to arithmetic, and a validator that lets `NaN` through has not
- * validated anything — every comparison downstream silently answers `false`.
- */
-export function number(): Schema<number> {
-  return makeSchema({
-    parse: (value, path) =>
-      typeof value === "number" && Number.isFinite(value)
-        ? ok(value)
-        : failIssue("type", "expected number", path),
-  });
-}
-
-export function boolean(): Schema<boolean> {
-  return makeSchema({
-    parse: (value, path) =>
-      typeof value === "boolean" ? ok(value) : failIssue("type", "expected boolean", path),
-  });
-}
-
-export function unknown(): Schema<mixed> {
-  return makeSchema({ parse: (value) => ok(value) });
-}
-
-export function literal<T extends string | number | boolean | null>(expected: T): Schema<T> {
-  return makeSchema({
-    parse: (value, path) =>
-      value === expected
-        ? ok(expected)
-        : failIssue("literal", `expected ${String(expected)}`, path),
-  });
-}
-
-export function enum_<T extends string>(values: $ReadOnlyArray<T>): Schema<T> {
-  const message = `expected one of ${values.join(", ")}`;
-  return makeSchema({
-    parse: (value, path) => {
-      for (const option of values) {
-        if (value === option) {
-          return ok(option);
-        }
-      }
-      return failIssue("enum", message, path);
-    },
-  });
-}
-
-export function array<Item>(item: Schema<Item>): Schema<$ReadOnlyArray<Item>> {
-  return makeSchema({
-    parse: (value, path) => {
-      if (!Array.isArray(value)) {
-        return failIssue("type", "expected array", path);
-      }
-      const out: Array<Item> = [];
-      let issues: null | Array<Issue> = null;
-      for (let index = 0; index < value.length; index += 1) {
-        const result = parseAt(item, value[index], path, String(index));
-        if (result.ok) {
-          out.push(result.value);
-        } else {
-          issues = issues ?? [];
-          mergeIssues(issues, result);
-        }
-      }
-      return issues == null ? ok(out) : { ok: false, issues };
-    },
-  });
-}
-
-export function tuple<TItems extends $ReadOnlyArray<Schema<mixed>>>(
-  items: TItems,
-): Schema<$ReadOnlyArray<mixed>> {
-  const arity = items.length;
-  return makeSchema({
-    parse: (value, path) => {
-      if (!Array.isArray(value)) {
-        return failIssue("type", "expected tuple", path);
-      }
-      if (value.length !== arity) {
-        return failIssue("length", `expected ${String(arity)} tuple items`, path);
-      }
-      const out: Array<mixed> = [];
-      let issues: null | Array<Issue> = null;
-      for (let index = 0; index < arity; index += 1) {
-        const result = parseAt(items[index], value[index], path, String(index));
-        if (result.ok) {
-          out.push(result.value);
-        } else {
-          issues = issues ?? [];
-          mergeIssues(issues, result);
-        }
-      }
-      return issues == null ? ok(out) : { ok: false, issues };
-    },
-  });
-}
-
-/**
- * An object whose keys are not known ahead of time.
- *
- * Only own enumerable keys are read, so a payload carrying `__proto__` or
- * `constructor` cannot smuggle an inherited value into the parsed result.
- */
-export function record<Value>(value: Schema<Value>): Schema<{ readonly [string]: Value, ... }> {
-  return makeSchema({
-    parse: (input, path) => {
-      if (!isPlainObject(input)) {
-        return failIssue("type", "expected object", path);
-      }
-      const source = plainRecord(input);
-      const out: { [string]: Value, ... } = {};
-      let issues: null | Array<Issue> = null;
-      for (const key of Object.keys(source)) {
-        const result = parseAt(value, source[key], path, key);
-        if (result.ok) {
-          put(out, key, result.value);
-        } else {
-          issues = issues ?? [];
-          mergeIssues(issues, result);
-        }
-      }
-      // $FlowFixMe[incompatible-type] every retained key went through `value`.
-      return issues == null ? ok(out) : { ok: false, issues };
-    },
-  });
-}
-
-/**
- * The first schema that accepts the value.
- *
- * When none do, every branch's issues are reported, because there is no way to
- * know which branch the author meant. That is also why [`variant`] exists: a
- * discriminated union can know, and its errors say one useful thing instead of
- * every possible thing.
- */
-export function union<T>(schemas: $ReadOnlyArray<Schema<T>>): Schema<T> {
-  return makeSchema({
-    parse: (value, path) => {
-      const issues: Array<Issue> = [];
-      for (const schema of schemas) {
-        const result = parseInternal(schema, value, path);
-        if (result.ok) {
-          return result;
-        }
-        mergeIssues(issues, result);
-      }
-      return { ok: false, issues };
-    },
-  });
-}
-
-/**
- * A union chosen by the value of one key.
- *
- * The discriminant is read first and the matching branch is the only one run,
- * so an invalid `{ kind: "circle", radius: "big" }` reports `expected number
- * at radius` rather than every reason it is not a square, a triangle and a
- * line as well. Unmatched discriminants name the ones that exist.
- */
-export function variant<T>(
-  key: string,
-  branches: { readonly [string]: Schema<T>, ... },
-): Schema<T> {
-  const known = Object.keys(branches);
-  return makeSchema({
-    parse: (value, path) => {
-      if (!isPlainObject(value)) {
-        return failIssue("type", "expected object", path);
-      }
-      const discriminant = plainRecord(value)[key];
-      if (typeof discriminant !== "string" || !Object.hasOwn(branches, discriminant)) {
-        path.push(key);
-        const failed = failIssue("variant", `expected one of ${known.join(", ")}`, path);
-        path.pop();
-        return failed;
-      }
-      return parseInternal(branches[discriminant], value, path);
-    },
-  });
-}
-
-/**
- * Pairs of `[key, schema]`, resolved once when the object schema is built.
- *
- * `for (const key in shape)` on every parse walks the prototype chain and
- * re-reads the same descriptors for the life of the process. The shape cannot
- * change after construction, so the walk belongs at construction.
- */
-function shapeEntries(shape: Shape): $ReadOnlyArray<[string, Schema<mixed>]> {
-  return Object.keys(shape).map((key) => [key, shape[key]]);
-}
-
-function schemaObject<T extends { ... }>(shape: Shape): Schema<T> {
-  const entries = shapeEntries(shape);
-  return makeSchema({
-    parse: (value, path) => {
-      if (!isPlainObject(value)) {
-        return failIssue("type", "expected object", path);
-      }
-      const record = plainRecord(value);
-      const out: { [string]: mixed, ... } = {};
-      let issues: null | Array<Issue> = null;
-      for (const [key, schema] of entries) {
-        const result = parseAt(schema, record[key], path, key);
-        if (result.ok) {
-          put(out, key, result.value);
-        } else {
-          issues = issues ?? [];
-          mergeIssues(issues, result);
-        }
-      }
-      // $FlowFixMe[incompatible-type] shape parsers have constructed every output field.
-      return issues == null ? ok(out as T) : { ok: false, issues };
-    },
-  });
-}
-
-/**
- * An object that rejects keys the shape does not name.
- *
- * `object()` drops unknown keys silently, which is right for a tolerant reader
- * of someone else's payload. `strictObject()` is for the other case — a
- * configuration file, an internal API — where an unrecognised key is almost
- * always a typo the user would rather hear about than have ignored.
- */
-export function strictObject<T extends { ... }>(shape: Shape): Schema<T> {
-  const inner = schemaObject<T>(shape);
-  const allowed = new Set(Object.keys(shape));
-  return makeSchema({
-    parse: (value, path) => {
-      const result = parseInternal(inner, value, path);
-      if (!isPlainObject(value)) {
-        return result;
-      }
-
-      // The unknown-key scan runs whether or not the fields parsed. Returning
-      // early on a field failure meant `{ name: 1, extra: true }` reported the
-      // wrong type of `name` and said nothing about `extra`, so fixing the
-      // first error revealed the second — which is the whole reason this
-      // validator collects issues instead of stopping at one.
-      const issues: Array<Issue> = [];
-      if (!result.ok) {
-        mergeIssues(issues, result);
-      }
-      for (const key of Object.keys(plainRecord(value))) {
-        if (!allowed.has(key)) {
-          path.push(key);
-          issues.push(issue("unknown_key", `unexpected key ${key}`, path));
-          path.pop();
-        }
-      }
-      return issues.length === 0 ? result : { ok: false, issues };
-    },
-  });
-}
-
-export function partial<T extends { ... }>(shape: Shape): Schema<Partial<T>> {
-  const partialShape: { [string]: Schema<mixed>, ... } = {};
-  for (const key of Object.keys(shape)) {
-    partialShape[key] = optional(shape[key]);
-  }
-  return schemaObject<Partial<T>>(partialShape);
-}
-
-export { schemaObject as object };
-
-/**
- * A schema built on first use.
- *
- * The one way to write a recursive type: a comment tree cannot name its own
- * schema in its own initialiser, but it can name a function that returns it.
- * The result is memoised, so recursion costs one closure, not one per node.
- */
-export function lazy<T>(build: () => Schema<T>): Schema<T> {
-  let built: null | Schema<T> = null;
-  return makeSchema({
-    parse: (value, path) => {
-      if (built == null) {
-        built = build();
-      }
-      return parseInternal(built, value, path);
-    },
-  });
-}
-
-export function optional<T>(schema: Schema<T>): Schema<void | T> {
-  return makeSchema({
-    parse: (value, path) =>
-      value === undefined ? ok(undefined) : parseInternal(schema, value, path),
-  });
-}
-
-export function nullable<T>(schema: Schema<T>): Schema<null | T> {
-  return makeSchema({
-    parse: (value, path) => (value === null ? ok(null) : parseInternal(schema, value, path)),
-  });
-}
-
-/**
- * A schema that never fails, substituting `value` when the inner one does.
- *
- * For the boundary where a bad field should not sink the whole payload — a
- * cached response, a user preference — and where the alternative is a
- * `safeParse` and a hand-written `if` at every call site.
- */
-export function fallback<T>(schema: Schema<T>, value: T): Schema<T> {
-  return makeSchema({
-    parse: (input, path) => {
-      const result = parseInternal(schema, input, path);
-      return result.ok ? result : ok(value);
-    },
-  });
-}
-
-/**
- * Apply steps to a schema, left to right.
- *
- * Variadic, because refinement is cumulative in practice — an email is a
- * string that is long enough *and* looks like an address — and forcing
- * `pipe(pipe(pipe(...)))` for that is a tax on the common case.
- */
-export function pipe<A>(schema: Schema<A>, ...steps: $ReadOnlyArray<Step<any, any>>): Schema<any> {
-  let piped: Schema<any> = schema;
-  for (const step of steps) {
-    piped = step(piped);
-  }
-  return piped;
-}
-
-export function transform<A, B>(change: (value: A) => B): Step<A, B> {
-  return (schema) =>
-    makeSchema({
-      parse: (value, path) => {
-        const result = parseInternal(schema, value, path);
-        if (!result.ok) {
-          return result;
-        }
-        return ok(change(result.value));
-      },
-    });
-}
-
-/**
- * An arbitrary predicate, with the message it should report.
- *
- * Every other step in this module is a special case of this one. It exists so
- * that a rule the library did not anticipate — a checksum, a business rule,
- * one field agreeing with another — is a one-liner rather than a reason to
- * abandon the schema and hand-roll validation.
- */
-export function check<T>(predicate: (value: T) => boolean, message: string): Step<T, T> {
-  return (schema) => refine(schema, predicate, "check", message);
-}
-
-/**
- * A nominal marker on an otherwise ordinary value.
- *
- * It does not check anything at runtime, and it is not pretending to: the
- * point is the name in the schema, so that `UserId` and `PostId` read
- * differently at the call site even though both are strings underneath.
- */
-export function brand<T, Name extends string>(name: Name): Step<T, T> {
-  return (schema) => refine(schema, () => true, "brand", `expected brand ${name}`);
-}
-
-export function minLength(value: number): Step<string, string> {
-  return (schema) =>
-    refine(
-      schema,
-      (input) => input.length >= value,
-      "min_length",
-      `expected at least ${String(value)} characters`,
-    );
-}
-
-export function maxLength(value: number): Step<string, string> {
-  return (schema) =>
-    refine(
-      schema,
-      (input) => input.length <= value,
-      "max_length",
-      `expected at most ${String(value)} characters`,
-    );
-}
-
-export function startsWith(value: string): Step<string, string> {
-  return (schema) =>
-    refine(schema, (input) => input.startsWith(value), "starts_with", `expected prefix ${value}`);
-}
-
-export function endsWith(value: string): Step<string, string> {
-  return (schema) =>
-    refine(schema, (input) => input.endsWith(value), "ends_with", `expected suffix ${value}`);
-}
-
-/**
- * A string matching `pattern`.
- *
- * The pattern is tested with `RegExp.prototype.test` against a fresh `lastIndex`
- * every time, because a caller who reaches for `/g` would otherwise get a
- * schema that alternates between accepting and rejecting the same input.
- */
-export function regex(pattern: RegExp, message?: string): Step<string, string> {
-  return (schema) =>
-    refine(
-      schema,
-      (input) => {
-        pattern.lastIndex = 0;
-        return pattern.test(input);
-      },
-      "regex",
-      message ?? `expected a match for ${String(pattern)}`,
-    );
-}
-
-export function trim(): Step<string, string> {
-  return transform((input: string) => input.trim());
-}
-
-export function email(): Step<string, string> {
-  return (schema) =>
-    refine(schema, (input) => /.+@.+\..+/.test(input), "email", "expected email address");
-}
-
-export function min(value: number): Step<number, number> {
-  return (schema) =>
-    refine(schema, (input) => input >= value, "min", `expected at least ${String(value)}`);
-}
-
-export function max(value: number): Step<number, number> {
-  return (schema) =>
-    refine(schema, (input) => input <= value, "max", `expected at most ${String(value)}`);
-}
-
-export function integer(): Step<number, number> {
-  return (schema) => refine(schema, Number.isInteger, "integer", "expected an integer");
-}
-
-export function date(): Schema<Date> {
-  return makeSchema({
-    parse: (value, path) =>
-      value instanceof Date && Number.isFinite(value.getTime())
-        ? ok(value)
-        : failIssue("type", "expected Date", path),
-  });
-}
-
-export function instance<T>(ClassValue: Class<T>): Schema<T> {
-  return makeSchema({
-    parse: (value, path) =>
-      value instanceof ClassValue ? ok(value as T) : failIssue("type", "expected instance", path),
-  });
-}
-
-/** Parse, or raise a [`ValidationError`] carrying every issue found. */
-export function parse<T>(schema: Schema<T>, value: mixed): T {
-  const result = safeParse(schema, value);
-  if (result.ok) {
-    return result.value;
-  }
-  throw new ValidationError(result.issues);
-}
-
-/** Parse into a result, so failure is a value rather than control flow. */
-/**
- * A schema as a standalone function.
- *
- * `safeParse(schema, value)` needs both halves at the call site, which is fine
- * where the schema is in scope and useless where it is not — a boundary that
- * wants to validate what arrives takes a *function*, not a schema and an
- * import of this module. `parser(User)` is that function, and it is why
- * `@uniflowed/fetch` can check a response body without depending on the
- * validator at all.
- */
-export function parser<T>(schema: Schema<T>): (value: mixed) => Result<T> {
-  return (value: mixed) => safeParse(schema, value);
-}
-
-export function safeParse<T>(schema: Schema<T>, value: mixed): Result<T> {
-  return parseInternal(schema, value, []);
-}
-
-/**
- * Validate a value during render.
- *
- * A hook rather than a plain call so the React Compiler memoises it with the
- * rest of the component: re-rendering for an unrelated reason does not re-walk
- * the payload.
- */
-export hook useValidation<T>(schema: Schema<T>, value: mixed): Result<T> {
-  return safeParse(schema, value);
-}
-
-/**
- * Every builder under one name, for callers who prefer `v.string()`.
- *
- * The named exports are the primary surface — they are what tree-shakes — and
- * this is the convenience alias, typed by `typeof` so the two can never drift.
- */
-export const v: {
-  readonly string: typeof string,
-  readonly number: typeof number,
-  readonly boolean: typeof boolean,
-  readonly unknown: typeof unknown,
-  readonly literal: typeof literal,
-  readonly enum: typeof enum_,
-  readonly array: typeof array,
-  readonly tuple: typeof tuple,
-  readonly record: typeof record,
-  readonly union: typeof union,
-  readonly variant: typeof variant,
-  readonly object: typeof schemaObject,
-  readonly strictObject: typeof strictObject,
-  readonly partial: typeof partial,
-  readonly lazy: typeof lazy,
-  readonly optional: typeof optional,
-  readonly nullable: typeof nullable,
-  readonly fallback: typeof fallback,
-  readonly pipe: typeof pipe,
-  readonly transform: typeof transform,
-  readonly check: typeof check,
-  readonly brand: typeof brand,
-  readonly minLength: typeof minLength,
-  readonly maxLength: typeof maxLength,
-  readonly startsWith: typeof startsWith,
-  readonly endsWith: typeof endsWith,
-  readonly regex: typeof regex,
-  readonly trim: typeof trim,
-  readonly email: typeof email,
-  readonly min: typeof min,
-  readonly max: typeof max,
-  readonly integer: typeof integer,
-  readonly date: typeof date,
-  readonly instance: typeof instance,
-  readonly parse: typeof parse,
-  readonly safeParse: typeof safeParse,
-  readonly useValidation: typeof useValidation,
-} = {
-  string,
-  number,
+// # How the package is laid out
+//
+// Fifteen modules beside this one. Nothing is under an `internal/`: each is a
+// reasonable thing to import on purpose, and every one is reachable through a
+// subpath so an application that only needs `parse` and `object` can say so.
+//
+// The leaves, which know nothing about schemas:
+//
+// - `plain-object.js` — reading and writing an object whose keys came from
+//   outside, without touching its prototype. The package's whole answer to
+//   `{"__proto__": …}`, in one place so that it is one answer.
+// - `issue.js` — what a failure is, where it happened, and the error `parse`
+//   throws.
+//
+// The kernel:
+//
+// - `schema.js` — what a schema *is*: the opaque type, the two-function
+//   kernel, the description it carries, and the walk that runs one. Read this
+//   first.
+// - `infer.js` — reading a value's type off its schema. Types only; it
+//   compiles to nothing.
+//
+// The vocabulary, one module per kind of thing a schema can be:
+//
+// - `primitive.js` — the leaves: `string`, `number`, `literal`, `enum_`, and
+//   the rest of what uf will recognise without being told how.
+// - `object.js` — keys known when the schema was written, in the three
+//   flavours that differ only in what happens to an unknown key.
+// - `collection.js` — arrays, tuples, records, maps and sets: containers whose
+//   contents are only known when the value arrives.
+// - `union.js` — several schemas over one value: `union`, the discriminated
+//   `variant` that gives an error worth reading, and `intersect`.
+// - `optional.js` — a value that might not be there, and what to put there
+//   when it is not.
+// - `lazy.js` — a schema that does not exist yet, which is how a comment tree
+//   is spelled.
+//
+// The pipeline:
+//
+// - `pipe.js` — a schema with steps after it, the `Step` type, and the
+//   overload table that carries the output type through a `transform`.
+// - `action.js` — the steps that come ready-made, each with the constraint
+//   that makes it visible to an exporter.
+//
+// The edges:
+//
+// - `parse.js` — the four ways to run a schema, and why there are four.
+// - `json-schema.js` — a schema as a document somebody else can read, and an
+//   honest list of what JSON Schema could not say.
+// - `namespace.js` — `v`, the alias that holds every builder. Separate because
+//   it is the one module that has to import all of them, and an entry point
+//   that did that would make every application carry every check.
+//
+// # Readiness
+//
+// **Implemented and tested.** The schema vocabulary above, including
+// discriminated unions, intersections, recursive schemas, maps and sets;
+// issue paths through every composite; both entry points in both synchronous
+// and asynchronous forms; `InferInput` and `InferOutput` over objects, shapes,
+// tuples, unions, variants and pipelines; a `pipe` that changes the output
+// type with the change surviving into the inferred type; `toJsonSchema` with
+// `$defs` for recursion and a reported list of what it could not express.
+// `tests/library/validator.test.js` covers each of those, including
+// `@uniflowed/form`'s resolver over both a synchronous and an asynchronous
+// schema, and `tests/library/form.test.js` covers that resolver inside a real
+// form.
+//
+// **Experimental.** [`describe`] and the [`Description`] type. The shape is
+// right for `json-schema.js` and it is the shape a code generator should read,
+// but no generator exists yet to prove the second half — see below — so the
+// type may gain cases before it is stable.
+//
+// **Not implemented, deliberately.**
+//
+// - `pick`, `omit` and `required` over a *schema*. These take a shape here or
+//   not at all, and `object.js` says why: a built schema is a closure and a
+//   description, not a reified field list.
+// - A nominal `brand`. `brand("UserId")` is a name in the description and
+//   nothing to the checker, because Flow's opaque types are declared in a
+//   module and cannot be produced by a call. `infer.js` says what to write
+//   instead when the distinction has to be enforced.
+// - Typed field paths. Flow has no template-literal types; an `Issue`'s `path`
+//   is `$ReadOnlyArray<string>` and `@uniflowed/form` makes the same call for
+//   the same reason.
+// - The long tail of format checks — `creditCard`, `emoji`, `mac`, `cuid2`.
+//   `action.js` says why a stale regular expression in a library is worse than
+//   a `check` an application owns.
+// - More than eight `pipe` steps in one call. Flow cannot fold a type over a
+//   variadic list, so the arities are spelled out; a ninth step is a type
+//   error and the fix is to pipe the result of a pipe.
+//
+// **Not implemented, and a gap.** `uf prepare` lists a
+// `GenerateValidatorTypes` step and nothing implements it: no crate reads a
+// schema and writes Flow types or a JSON Schema file to disk. The half that
+// belongs in this package — a description complete enough to generate from —
+// is here and is exercised by `toJsonSchema`. The build-time half is not
+// written, and this package should not grow it: walking a repository's sources
+// is Rust's job under the same rule that puts the formatter and the checker
+// there.
+//
+// # Measured, against Valibot
+//
+// Valibot 1.4.2 from npm, Node 25.8.1, an Apple M2 Max (12 cores, macOS 26.5),
+// best of five timed runs after two warm-up runs, both libraries given the
+// same payload and schemas built out of the same pieces — an object of seven
+// fields with a nested object, an array of strings, and `minLength`,
+// `maxLength`, `integer`, `min` and `max` steps. The two agree on every case
+// the harness runs, which it asserts before it times anything: the same
+// verdict, the same number of issues, the same transformed value.
+//
+// | Workload | uf | Valibot | |
+// | --- | --- | --- | --- |
+// | 1,000-record list, all valid (per record) | **0.49 µs** | 0.65 µs | 1.34x |
+// | 1,000-record list, one field bad in ten | **0.50 µs** | 0.66 µs | 1.34x |
+// | One form object, four fields, one transform | **0.20 µs** | 0.35 µs | 1.73x |
+// | `safeParse(string(), "ada")` | **5.0 ns** | 15.6 ns | 3.1x |
+// | Building the record schema | **0.47 µs** | 6.5 µs | 14x |
+//
+// The harness is not in the repository — it needs Valibot from npm, and this
+// repository installs no dependency it does not ship — so it lives with the
+// change that produced these numbers. It runs as:
+//
+//   UF_PROJECT_ROOT=$PWD node --import ./packages/host/register.js \
+//     bench-validator.js path/to/valibot/dist/index.cjs
+//
+// The construction column is the one to read first: a Valibot schema is a
+// tree of objects with an `~run` method and metadata on each node, and this
+// package's is a closure. That is fourteen times cheaper to build and it is
+// why the leaf parse is three times cheaper to run.
+//
+// The row that was *worse* is worth recording too, because finding it is what
+// made the others true. Writing every parsed field with
+// `Object.defineProperty` — which is how this package used to keep a
+// `__proto__` key out of the prototype — cost more than the entire rest of the
+// walk: the list workload took 298 µs per hundred records instead of 49, and
+// this package was 2.4 times *slower* than Valibot rather than 1.34 times
+// faster. `plain-object.js` has the one-line fix and the argument that it
+// keeps the guarantee intact.
+
+export type { FlatIssues, Issue, Path } from "./issue.js";
+export type { Constraint, Description, Result, Schema } from "./schema.js";
+export type {
+  Infer,
+  InferInput,
+  InferOutput,
+  ItemsInput,
+  ItemsOutput,
+  Options,
+  Shape,
+  ShapeInput,
+  ShapeOutput,
+} from "./infer.js";
+export type { Pipe, Step } from "./pipe.js";
+export type { JsonSchemaExport, JsonSchemaNode, Unrepresentable } from "./json-schema.js";
+
+export { ValidationError, flatten } from "./issue.js";
+export { describe, isAsync } from "./schema.js";
+export {
+  bigint,
   boolean,
-  unknown,
+  custom,
+  date,
+  enum_,
+  instance,
   literal,
-  enum: enum_,
-  array,
-  tuple,
-  record,
-  union,
-  variant,
-  object: schemaObject,
-  strictObject,
-  partial,
-  lazy,
-  optional,
-  nullable,
-  fallback,
-  pipe,
-  transform,
-  check,
-  brand,
-  minLength,
-  maxLength,
-  startsWith,
+  never,
+  null_,
+  number,
+  string,
+  undefined_,
+  unknown,
+} from "./primitive.js";
+export { looseObject, object, partial, strictObject } from "./object.js";
+export { array, map, record, set, tuple } from "./collection.js";
+export { intersect, union, variant } from "./union.js";
+export { fallback, nullable, nullish, optional, withDefault } from "./optional.js";
+export { lazy, lazyAsync } from "./lazy.js";
+export { brand, check, checkAsync, pipe, refine, transform, transformAsync } from "./pipe.js";
+export {
+  email,
   endsWith,
+  includes,
+  integer,
+  isoDate,
+  length,
+  max,
+  maxItems,
+  maxLength,
+  min,
+  minItems,
+  minLength,
+  multipleOf,
+  nonEmpty,
   regex,
+  startsWith,
+  toLowerCase,
+  toUpperCase,
   trim,
-  email,
-  min,
-  max,
-  integer,
-  date,
-  instance,
+  url,
+  uuid,
+} from "./action.js";
+export {
+  is,
   parse,
+  parseAsync,
+  parser,
   safeParse,
+  safeParseAsync,
   useValidation,
-};
+} from "./parse.js";
+export { toJsonSchema } from "./json-schema.js";
+
+export { v } from "./namespace.js";