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

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 };
+}

package/json-schema.js

@@ -0,0 +1,307 @@
+// @flow
+//
+// `@uniflowed/validator/json-schema`: a schema as a document somebody else can
+// read.
+//
+//   const { schema, unrepresentable } = toJsonSchema(Account);
+//   // { $schema: "…/2020-12/schema", type: "object", properties: { … } }
+//
+// The roadmap calls this "schema exports", and it is the reason `schema.js`
+// makes every schema carry a [`Description`] beside its parse function. A
+// closure cannot be read: a schema that was *only* the four lines that check a
+// value can be run and can never be published, documented, handed to an
+// OpenAPI generator, or turned into types for a consumer written in another
+// language. The description is the readable half, and this module is the first
+// consumer of it.
+//
+// # What "unrepresentable" means, and why it is a return value
+//
+// JSON Schema describes JSON. `map`, `set`, `bigint`, `date`, `instance` and
+// `custom` describe values that JSON does not have, and `check` describes a
+// predicate no declarative format can express. A converter has three options
+// for those: throw, lie, or say so. Throwing makes one `Date` field fatal for a
+// document that is otherwise fine. Lying — emitting `{}` and moving on — is
+// what makes an exported schema quietly weaker than the one the application
+// runs.
+//
+// So this says so. The node becomes `{}`, which accepts anything and is
+// therefore *never wrong*, only imprecise, and the place it happened is
+// reported in `unrepresentable` with the path to it. A caller that wants the
+// strict behaviour asserts the list is empty; a caller documenting an API that
+// happens to have one `Date` in it gets its document.
+//
+// # The exported document describes the input, not the output
+//
+// `pipe(string(), transform(Number))` exports as `{ "type": "string" }`. That
+// is the whole point of a JSON Schema: it validates what arrives on the wire,
+// and what arrives is the input. `InferOutput` is for the code on this side of
+// the boundary; the document is for the code on the other side, which has
+// never heard of the transform.
+//
+// The consequence is easy to get wrong, and this module got it wrong first: a
+// step *after* a transform constrains the output, not the input.
+// `pipe(string(), transform(Number), min(18))` must not export as `{ "type":
+// "string", "minimum": 18 }`, which would ask a consumer to compare a string
+// against a number. It exports as `{ "type": "string" }`, and `min after a
+// transform` is reported as unrepresentable — because the schema does reject
+// `"5"` and the document does not, and that is exactly what the list is for.
+//
+// `fallback` follows the same rule to its conclusion: a fallback accepts every
+// value, so it exports as `{}`. Nothing is lost that JSON Schema could have
+// held.
+//
+// # Recursion
+//
+// A `lazy` schema is a cycle, and the description of one is a thunk rather
+// than a value for exactly that reason. Each `lazy` carries an identity, and
+// the walk keeps a table from that identity to a name under `$defs`: the first
+// visit converts the body, and every visit after it emits a `$ref`. A comment
+// tree comes out as one definition and a reference to it, which is what JSON
+// Schema is for.
+//
+// # What this is not, yet
+//
+// `uf prepare` lists a `GenerateValidatorTypes` step, and there is no code
+// behind it — no crate reads a schema and writes a `.js.flow`. This module is
+// the half that can exist without one: a description a generator would read,
+// and a converter proving the description is complete enough to build
+// something from. When that step is implemented it should consume
+// [`describe`], not re-derive a shape from the source.
+
+import type { Path } from "./issue.js";
+import { put } from "./plain-object.js";
+import type { Constraint, Description, Schema } from "./schema.js";
+import { describe } from "./schema.js";
+
+/** One node of a JSON Schema document. */
+export type JsonSchemaNode = { readonly [string]: mixed, ... };
+
+/** Somewhere the document is less precise than the schema it came from. */
+export type Unrepresentable = {|
+  readonly path: Path,
+  readonly kind: string,
+|};
+
+/** A JSON Schema document, and everything JSON Schema could not say. */
+export type JsonSchemaExport = {|
+  readonly schema: JsonSchemaNode,
+  readonly unrepresentable: $ReadOnlyArray<Unrepresentable>,
+|};
+
+const DIALECT = "https://json-schema.org/draft/2020-12/schema";
+
+/** `left` with `right`'s keywords on top, written prototype-safely. */
+function merge(left: JsonSchemaNode, right: JsonSchemaNode): JsonSchemaNode {
+  const out: { [string]: mixed, ... } = {};
+  for (const key of Object.keys(left)) {
+    put(out, key, left[key]);
+  }
+  for (const key of Object.keys(right)) {
+    put(out, key, right[key]);
+  }
+  return out;
+}
+
+/**
+ * Whether a field may be absent.
+ *
+ * `optional`, `nullish` and a default all mean the key can be missing, and any
+ * of them may be wrapped in the steps of a pipeline — `pipe(optional(string()),
+ * …)` is an `optional` under a `constrained` — so the wrappers are unwrapped
+ * before the question is asked. `nullable` is not here: `null` is a value, and
+ * a key holding it is present.
+ */
+function mayBeAbsent(description: Description): boolean {
+  return match (description) {
+    {kind: "optional", inner: _} => true,
+    {kind: "nullish", inner: _} => true,
+    {kind: "default", inner: _} => true,
+    {kind: "fallback", inner: _} => true,
+    {kind: "constrained", inner: const inner, constraint: _} => mayBeAbsent(inner),
+    {kind: "transformed", inner: const inner} => mayBeAbsent(inner),
+    _ => false,
+  };
+}
+
+/**
+ * Whether a description is of a value some step already changed.
+ *
+ * Only the spine of pipeline wrappers is followed. A transform *inside* an
+ * object's field does not make the object transformed: the field's own node is
+ * where that is handled.
+ */
+function describesTransformedValue(description: Description): boolean {
+  return match (description) {
+    {kind: "transformed", inner: _} => true,
+    {kind: "constrained", inner: const inner, constraint: _} => describesTransformedValue(inner),
+    _ => false,
+  };
+}
+
+/** What to call a constraint in the `unrepresentable` list. */
+function labelFor(constraint: Constraint): string {
+  return constraint.kind === "opaque" ? `check ${constraint.label}` : constraint.kind;
+}
+
+/** The JSON Schema keywords one `pipe` step contributes, if any. */
+function keywordsFor(constraint: Constraint): JsonSchemaNode {
+  return match (constraint) {
+    {kind: "minLength", value: const value} => { minLength: value },
+    {kind: "maxLength", value: const value} => { maxLength: value },
+    {kind: "length", value: const value} => { minLength: value, maxLength: value },
+    {kind: "minItems", value: const value} => { minItems: value },
+    {kind: "maxItems", value: const value} => { maxItems: value },
+    {kind: "min", value: const value} => { minimum: value },
+    {kind: "max", value: const value} => { maximum: value },
+    {kind: "integer"} => { type: "integer" },
+    {kind: "multipleOf", value: const value} => { multipleOf: value },
+    {kind: "pattern", source: const source} => { pattern: source },
+    {kind: "format", name: const name} => { format: name },
+    {kind: "brand", name: const name} => { title: name },
+    {kind: "opaque", label: _} => {},
+  };
+}
+
+/**
+ * Convert `schema` to a JSON Schema document.
+ *
+ * The walk keeps three pieces of state — the definitions a recursive schema
+ * needs, the names already given out, and the places JSON Schema could not
+ * say what the schema meant — which is why it is a closure over a converter
+ * rather than a free function.
+ */
+export function toJsonSchema(schema: Schema<mixed, mixed>): JsonSchemaExport {
+  const definitions: { [string]: JsonSchemaNode, ... } = {};
+  const names = new Map<symbol, string>();
+  const unrepresentable: Array<Unrepresentable> = [];
+
+  function unsupported(kind: string, path: Path): JsonSchemaNode {
+    unrepresentable.push({ path: path.slice(), kind });
+    return {};
+  }
+
+  function object(
+    entries: $ReadOnlyArray<[string, Description]>,
+    unknownKeys: "strip" | "reject" | "keep",
+    path: Path,
+  ): JsonSchemaNode {
+    const properties: { [string]: JsonSchemaNode, ... } = {};
+    const required: Array<string> = [];
+    for (const [key, inner] of entries) {
+      put(properties, key, convert(inner, path.concat(key)));
+      if (!mayBeAbsent(inner)) {
+        required.push(key);
+      }
+    }
+    const base = { type: "object", properties, required };
+    return unknownKeys === "reject" ? merge(base, { additionalProperties: false }) : base;
+  }
+
+  function recursive(id: symbol, inner: () => Description, path: Path): JsonSchemaNode {
+    const already = names.get(id);
+    if (already != null) {
+      return { $ref: `#/$defs/${already}` };
+    }
+    const name = `definition${String(names.size)}`;
+    names.set(id, name);
+    put(definitions, name, convert(inner(), path));
+    return { $ref: `#/$defs/${name}` };
+  }
+
+  function convert(description: Description, path: Path): JsonSchemaNode {
+    return match (description) {
+      {kind: "unknown"} => {},
+      {kind: "never"} => { not: {} },
+      {kind: "string"} => { type: "string" },
+      {kind: "number"} => { type: "number" },
+      {kind: "boolean"} => { type: "boolean" },
+      {kind: "null"} => { type: "null" },
+      {kind: "bigint"} => unsupported("bigint", path),
+      {kind: "undefined"} => unsupported("undefined", path),
+      {kind: "date"} => unsupported("date", path),
+      {kind: "instance", name: const name} => unsupported(`instance ${name}`, path),
+      {kind: "custom", name: const name} => unsupported(`custom ${name}`, path),
+      {kind: "map", key: _, value: _} => unsupported("map", path),
+      {kind: "set", item: _} => unsupported("set", path),
+      {kind: "literal", value: const value} => { const: value },
+      {kind: "enum", values: const values} => { enum: values.slice() },
+      {kind: "array", item: const item} =>
+        {
+          type: "array",
+          items: convert(item, path.concat("*")),
+        },
+      {kind: "tuple", items: const items} =>
+        {
+          type: "array",
+          prefixItems: items.map((item, index) => convert(item, path.concat(String(index)))),
+          minItems: items.length,
+          maxItems: items.length,
+        },
+      {kind: "record", value: const value} =>
+        {
+          type: "object",
+          additionalProperties: convert(value, path.concat("*")),
+        },
+      {kind: "object", entries: const entries, unknownKeys: const unknownKeys} =>
+        object(entries, unknownKeys, path),
+      {kind: "union", options: const options} =>
+        {
+          anyOf: options.map((option) => convert(option, path)),
+        },
+      {kind: "variant", key: _, branches: const branches} =>
+        {
+          oneOf: branches.map(([, branch]) => convert(branch, path)),
+        },
+      {kind: "intersect", parts: const parts} =>
+        {
+          allOf: parts.map((part) => convert(part, path)),
+        },
+      {kind: "optional", inner: const inner} => convert(inner, path),
+      {kind: "default", inner: const inner} => convert(inner, path),
+      {kind: "nullable", inner: const inner} =>
+        {
+          anyOf: [convert(inner, path), { type: "null" }],
+        },
+      {kind: "nullish", inner: const inner} =>
+        {
+          anyOf: [convert(inner, path), { type: "null" }],
+        },
+      {kind: "fallback", inner: _} => {},
+      {kind: "transformed", inner: const inner} => convert(inner, path),
+      {kind: "lazy", id: const id, inner: const inner} => recursive(id, inner, path),
+      {kind: "constrained", inner: const inner, constraint: const constraint} =>
+        constrained(inner, constraint, path),
+    };
+  }
+
+  /**
+   * A pipeline step's keywords on top of what it refined.
+   *
+   * Two of them contribute nothing. A `check`'s predicate is a closure, and a
+   * step that sits above a `transform` is about the output rather than the
+   * input this document describes. Both leave the node alone and add a line
+   * saying the document is looser than the schema at that path.
+   */
+  function constrained(inner: Description, constraint: Constraint, path: Path): JsonSchemaNode {
+    const node = convert(inner, path);
+    if (describesTransformedValue(inner)) {
+      unrepresentable.push({
+        path: path.slice(),
+        kind: `${labelFor(constraint)} after a transform`,
+      });
+      return node;
+    }
+    if (constraint.kind === "opaque") {
+      unrepresentable.push({ path: path.slice(), kind: labelFor(constraint) });
+      return node;
+    }
+    return merge(node, keywordsFor(constraint));
+  }
+
+  const root = convert(describe(schema), []);
+  const document =
+    Object.keys(definitions).length === 0
+      ? merge({ $schema: DIALECT }, root)
+      : merge(merge({ $schema: DIALECT }, root), { $defs: definitions });
+  return { schema: document, unrepresentable };
+}

package/lazy.js

@@ -0,0 +1,93 @@
+// @flow
+//
+// `@uniflowed/validator/lazy`: a schema that does not exist yet.
+//
+// A comment has replies, and a reply is a comment. There is no order in which
+// to write that down, because the initialiser of `Comment` would have to name
+// `Comment`, and at that moment it is still `undefined`. So the schema is
+// wrapped in a function, and the function is not called until the first parse:
+//
+//   type Comment = {| text: string, replies: $ReadOnlyArray<Comment> |};
+//
+//   const Comment: Schema<Comment> = lazy(() =>
+//     object({ text: string(), replies: array(Comment) }),
+//   );
+//
+// The annotation is the other half, and it is not optional. Flow will infer
+// the type of almost every schema in this package, but it will not solve a
+// type that mentions itself; the `Schema<Comment>` on the binding is where the
+// cycle is cut, and `infer.js` says so among the other limits.
+//
+// # Why the result is memoised
+//
+// Without it, every node of the tree calls `build()` and gets a fresh object
+// graph — a thousand-comment thread would construct a thousand schemas, none
+// of which is reused, on a parse that should have allocated nothing. With it,
+// recursion costs one closure for the whole schema.
+//
+// # Why there are two of these
+//
+// Everything else in the package works out whether it is asynchronous when it
+// is built: `object` asks its fields, `array` asks its item. A lazy schema
+// cannot ask, because the thing it would ask does not exist yet, and building
+// it to find out is the infinite loop the laziness was there to avoid.
+//
+// So the answer is declared instead of discovered. [`lazy`] is synchronous and
+// [`lazyAsync`] is not, and a recursive schema with a `checkAsync` anywhere
+// inside it must use the second — otherwise the objects and arrays above it
+// build their synchronous halves, and the first `await` that never happens
+// surfaces as a thrown "use safeParseAsync" from the middle of a parse rather
+// than as a type the caller could have seen.
+
+import type { Description, Schema } from "./schema.js";
+import { describe, makeAsyncSchema, makeSchema, run, runAsync } from "./schema.js";
+
+/** Build once, then hand back the same schema for the life of the process. */
+function memoise<TOutput, TInput>(
+  build: () => Schema<TOutput, TInput>,
+): () => Schema<TOutput, TInput> {
+  let built: null | Schema<TOutput, TInput> = null;
+  return () => {
+    const already = built;
+    if (already != null) {
+      return already;
+    }
+    const made = build();
+    built = made;
+    return made;
+  };
+}
+
+/**
+ * A synchronous schema built on first use.
+ *
+ * `id` is what a converter keys its definitions on: `json-schema.js` sees the
+ * same symbol every time it walks back around the cycle, which is how a
+ * recursive schema becomes a `$ref` rather than a stack overflow.
+ */
+export function lazy<TOutput, TInput = mixed>(
+  build: () => Schema<TOutput, TInput>,
+): Schema<TOutput, TInput> {
+  const resolve = memoise(build);
+  const id = Symbol("lazy");
+  const description = (): Description => ({
+    kind: "lazy",
+    id,
+    inner: () => describe(resolve()),
+  });
+  return makeSchema((value, path) => run(resolve(), value, path), description);
+}
+
+/** A recursive schema with an asynchronous step somewhere inside it. */
+export function lazyAsync<TOutput, TInput = mixed>(
+  build: () => Schema<TOutput, TInput>,
+): Schema<TOutput, TInput> {
+  const resolve = memoise(build);
+  const id = Symbol("lazyAsync");
+  const description = (): Description => ({
+    kind: "lazy",
+    id,
+    inner: () => describe(resolve()),
+  });
+  return makeAsyncSchema((value, path) => runAsync(resolve(), value, path), description);
+}