@uniflowed/validator 0.0.0-alpha.10

package/index.js

@@ -0,0 +1,265 @@
+// @flow
+//
+// `@uniflowed/validator`: a schema is a parser, not an assertion.
+//
+// ```js
+// const Account = object({
+//   email: pipe(string(), trim(), email()),
+//   age: pipe(string(), transform(Number), integer(), min(18)),
+//   tags: array(pipe(string(), nonEmpty())),
+// });
+//
+// const result = safeParse(Account, await request.json());
+// if (!result.ok) {
+//   return respond(422, flatten(result.issues));
+// }
+// createAccount(result.value); // { email: string, age: number, tags: … }
+// ```
+//
+// `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.
+//
+// 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.
+//
+// # 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. 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`.
+//
+// **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`.
+//
+// **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`.
+//
+// **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.
+//
+// # 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,
+  custom,
+  date,
+  enum_,
+  instance,
+  literal,
+  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,
+  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";

package/infer.js

@@ -0,0 +1,107 @@
+// @flow
+//
+// `@uniflowed/validator/infer`: reading a value's type off its schema.
+//
+// This module compiles to nothing. Every name in it is a type, and the reason
+// they are here rather than beside the parsers is that they are the answer to
+// a question the parsers do not ask: given a schema, what is the type of the
+// thing it produces, and what is the type of the thing you may hand it?
+//
+//   const Account = object({
+//     email: pipe(string(), email()),
+//     age: pipe(string(), transform(Number), min(18)),
+//   });
+//
+//   type Raw = InferInput<typeof Account>;   // {| email: string, age: string |}
+//   type Account = InferOutput<typeof Account>; // {| email: string, age: number |}
+//
+// Neither type was written down. That is the point: a schema is the single
+// source of truth, and a hand-written `type Account` beside it is a second
+// truth that will disagree with the first on a Tuesday.
+//
+// # What Flow can do here
+//
+// More than this package used to assume. Conditional types with `infer` are
+// what read a parameter back out of `Schema<Out, In>`; mapped types are what
+// turn a shape — an object whose values are schemas — into an object whose
+// values are those schemas' outputs, key by key, without naming the keys.
+// `object`, `partial`, `looseObject`, `tuple`, `union`, `variant` and `record`
+// all infer, so none of them takes an explicit type argument any more, and a
+// field added to a shape appears in the inferred type with nothing else
+// edited.
+//
+// The inferred object types are **exact**. `InferOutput<typeof Account>` does
+// not accept an extra property, which matches what `object()` does at run time
+// — it drops keys the shape does not name — and is why `looseObject` has a
+// separate spelling with `...` in its result.
+//
+// # What it cannot
+//
+// **Paths are not typed.** An `Issue`'s `path` is `$ReadOnlyArray<string>`.
+// Flow has no template-literal types, so there is no way to say "one of the
+// paths that exist in this schema", and a `SchemaPath<S>` alias that was
+// really `string` would be a type that looks like it checks something and does
+// not. `@uniflowed/form` makes the same call for the same reason.
+//
+// **Branded outputs are not nominal.** `pipe(string(), brand("UserId"))` is
+// `Schema<string, string>`. Flow's opaque types are per module and cannot be
+// generated from a call, so the brand is a label in the description — real for
+// `json-schema.js`, and honest about being nothing to the checker. A project
+// that wants `UserId` to be a distinct type should declare
+// `opaque type UserId = string` in the module that owns it and annotate there.
+//
+// **`InferInput` describes shape, not provenance.** It says a valid input to
+// `pipe(string(), transform(Number))` is a `string`. It cannot say that the
+// string has to parse as a number, because that is what the parse is for.
+//
+// **A recursive schema still needs one annotation.** `lazy(() => …)` builds a
+// type that mentions itself, and Flow will not solve for that on its own; the
+// type argument on `lazy` is where the cycle is cut. `lazy.js` has the
+// example.
+
+import type { Schema } from "./schema.js";
+
+/** The type a schema produces. The one every consumer wants. */
+export type InferOutput<TSchema> = TSchema extends Schema<infer TValue, infer TSource>
+  ? TValue
+  : empty;
+
+/**
+ * The type a valid input to a schema has.
+ *
+ * Equal to [`InferOutput`] until a `transform` is in the pipeline. Where they
+ * differ, this is the one a form's `defaultValues` wants and the other is the
+ * one its `onValid` receives.
+ */
+export type InferInput<TSchema> = TSchema extends Schema<infer TValue, infer TSource>
+  ? TSource
+  : empty;
+
+/** The older name for [`InferOutput`], kept so existing annotations compile. */
+export type Infer<TSchema> = InferOutput<TSchema>;
+
+/** An object whose values are schemas: what `object` and `variant` take. */
+export type Shape = { readonly [string]: Schema<mixed, mixed>, ... };
+
+/** A list of schemas: what `union` and `tuple` take. */
+export type Options = $ReadOnlyArray<Schema<mixed, mixed>>;
+
+/** The object a shape produces, key by key. */
+export type ShapeOutput<TShape extends Shape> = {
+  [Key in keyof TShape]: InferOutput<TShape[Key]>,
+};
+
+/** The object a shape accepts, key by key. */
+export type ShapeInput<TShape extends Shape> = {
+  [Key in keyof TShape]: InferInput<TShape[Key]>,
+};
+
+/** The tuple a list of schemas produces, position by position. */
+export type ItemsOutput<TItems extends Options> = {
+  [Index in keyof TItems]: InferOutput<TItems[Index]>,
+};
+
+/** The tuple a list of schemas accepts, position by position. */
+export type ItemsInput<TItems extends Options> = {
+  [Index in keyof TItems]: InferInput<TItems[Index]>,
+};

package/issue.js

@@ -0,0 +1,129 @@
+// @flow
+//
+// `@uniflowed/validator/issue`: what a failure is, and where it happened.
+//
+// A validator that answers "no" has told the caller nothing. A form needs to
+// put a message under one input, an HTTP handler needs to name the field in
+// its 422 body, and a log needs to say which row of a thousand was wrong. All
+// three want the same thing: the path from the root of the value to the place
+// that failed, as data.
+//
+// So an issue is `{ code, message, path }` — `["users", "2", "email"]`, not
+// `"users[2].email"`. Segments compose without a grammar: joining them with a
+// dot is one line at the boundary that wants a string, and splitting a string
+// back into segments is a parser nobody should have to write. Array indices
+// are their decimal spelling, because a path is a path whether the container
+// was an object or an array, and a consumer that has to branch on the segment
+// type gains nothing from the distinction.
+//
+// # Why this is separate from the schemas
+//
+// Because nothing here knows what a schema is. `issue.js` is a leaf: it is
+// imported by the kernel, by every combinator that reports a failure, and by
+// `@uniflowed/form`, and it imports one thing itself. Keeping it that way is
+// what lets a consumer translate issues — into field errors, into a response
+// body — without resolving the schema engine at all.
+
+import { put } from "./plain-object.js";
+
+/** Where an issue happened, as object keys and array indices from the root. */
+export type Path = $ReadOnlyArray<string>;
+
+/**
+ * The mutable buffer the synchronous walk descends with.
+ *
+ * `schema.js` explains why one array is pushed and popped rather than a fresh
+ * array being allocated per field. The type is separate from [`Path`] so that
+ * the distinction between "the buffer, which is being mutated right now" and
+ * "a path, which is a value" is visible in every signature.
+ */
+export type PathBuffer = Array<string>;
+
+/**
+ * One reason a value was rejected.
+ *
+ * `code` is for programs — `"type"`, `"min_length"`, `"unknown_key"` — and is
+ * stable across message changes, so a caller can tell "this is not an email
+ * address" from "we need an email address" without matching on prose.
+ *
+ * `path` is absent rather than empty when the issue is about the whole value,
+ * because the overwhelmingly common case is a successful parse and an object
+ * with one fewer field is one fewer allocation on the path that matters.
+ */
+export type Issue = {|
+  readonly code: string,
+  readonly message: string,
+  readonly path?: Path,
+|};
+
+/**
+ * An issue at wherever the walk currently is.
+ *
+ * The `slice` is the only copy of a path the package makes, and it happens
+ * exactly when a value was going to be rejected anyway.
+ */
+export function issue(code: string, message: string, path: Path): Issue {
+  return path.length === 0 ? { code, message } : { code, message, path: path.slice() };
+}
+
+/** An issue at `path` with `keys` appended: a cross-field rule's landing spot. */
+export function issueUnder(code: string, message: string, path: Path, keys: Path): Issue {
+  const at = path.concat(keys);
+  return at.length === 0 ? { code, message } : { code, message, path: at };
+}
+
+function describeIssue(entry: Issue): string {
+  const at = entry.path == null || entry.path.length === 0 ? "" : ` at ${entry.path.join(".")}`;
+  return `${entry.message}${at}`;
+}
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Issues grouped the way a form renders them.
+ *
+ * `root` is everything that was about the value as a whole; `nested` is keyed
+ * by the dotted path, which is the same string `@uniflowed/form`'s `register`
+ * was given. Written through [`put`] because a payload's own `__proto__` key
+ * reaches this function as a path segment.
+ */
+export type FlatIssues = {|
+  readonly root: $ReadOnlyArray<string>,
+  readonly nested: { readonly [string]: $ReadOnlyArray<string>, ... },
+|};
+
+/** Group `issues` by their path, for a caller that renders per field. */
+export function flatten(issues: $ReadOnlyArray<Issue>): FlatIssues {
+  const root: Array<string> = [];
+  const nested: { [string]: Array<string>, ... } = {};
+  for (const entry of issues) {
+    const path = entry.path;
+    if (path == null || path.length === 0) {
+      root.push(entry.message);
+      continue;
+    }
+    const key = path.join(".");
+    const already = Object.hasOwn(nested, key) ? nested[key] : null;
+    if (already == null) {
+      put(nested, key, [entry.message]);
+    } else {
+      already.push(entry.message);
+    }
+  }
+  return { root, nested };
+}