@uniflowed/validator 0.0.0-alpha.10

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

package/namespace.js

@@ -0,0 +1,229 @@
+// @flow
+//
+// `@uniflowed/validator/namespace`: every builder under one name.
+//
+//   import { v } from "@uniflowed/validator";
+//   const Account = v.object({ email: v.pipe(v.string(), v.email()) });
+//
+// The named exports are the primary surface. This is the convenience alias,
+// for the many schemas that mention a dozen builders and would otherwise open
+// with a dozen-line import, and for readers coming from Valibot who already
+// write `v.` in front of everything.
+//
+// # Why it is a module of its own
+//
+// Because it is the one module that has to import all of them, and a package
+// whose entry point did that would make every application carry every check.
+// Here it is reached through a single named re-export from `index.js`, which a
+// bundler drops when nothing reads `v`; a project that imports
+// `@uniflowed/validator/primitive` directly never resolves this file at all.
+//
+// # Why it is typed with `typeof`
+//
+// So the two surfaces cannot drift. Each field's type is the exported
+// function's own, which means adding a builder and forgetting to list it here
+// is a missing property rather than a silently different signature, and
+// renaming one is an error at this file rather than a surprise at a call site.
+
+import {
+  email,
+  endsWith,
+  includes,
+  integer,
+  isoDate,
+  length,
+  max,
+  maxItems,
+  maxLength,
+  min,
+  minItems,
+  minLength,
+  multipleOf,
+  nonEmpty,
+  regex,
+  startsWith,
+  toLowerCase,
+  toUpperCase,
+  trim,
+  url,
+  uuid,
+} from "./action.js";
+import { array, map, record, set, tuple } from "./collection.js";
+import { flatten } from "./issue.js";
+import { toJsonSchema } from "./json-schema.js";
+import { lazy, lazyAsync } from "./lazy.js";
+import { looseObject, object, partial, strictObject } from "./object.js";
+import { fallback, nullable, nullish, optional, withDefault } from "./optional.js";
+import {
+  is,
+  parse,
+  parseAsync,
+  parser,
+  safeParse,
+  safeParseAsync,
+  useValidation,
+} from "./parse.js";
+import { brand, check, checkAsync, pipe, refine, transform, transformAsync } from "./pipe.js";
+import {
+  bigint,
+  boolean,
+  custom,
+  date,
+  enum_,
+  instance,
+  literal,
+  never,
+  null_,
+  number,
+  string,
+  undefined_,
+  unknown,
+} from "./primitive.js";
+import { describe, isAsync } from "./schema.js";
+import { intersect, union, variant } from "./union.js";
+
+export const v: {
+  readonly string: typeof string,
+  readonly number: typeof number,
+  readonly bigint: typeof bigint,
+  readonly boolean: typeof boolean,
+  readonly unknown: typeof unknown,
+  readonly never: typeof never,
+  readonly null: typeof null_,
+  readonly undefined: typeof undefined_,
+  readonly literal: typeof literal,
+  readonly enum: typeof enum_,
+  readonly date: typeof date,
+  readonly instance: typeof instance,
+  readonly custom: typeof custom,
+  readonly object: typeof object,
+  readonly strictObject: typeof strictObject,
+  readonly looseObject: typeof looseObject,
+  readonly partial: typeof partial,
+  readonly array: typeof array,
+  readonly tuple: typeof tuple,
+  readonly record: typeof record,
+  readonly map: typeof map,
+  readonly set: typeof set,
+  readonly union: typeof union,
+  readonly variant: typeof variant,
+  readonly intersect: typeof intersect,
+  readonly optional: typeof optional,
+  readonly nullable: typeof nullable,
+  readonly nullish: typeof nullish,
+  readonly withDefault: typeof withDefault,
+  readonly fallback: typeof fallback,
+  readonly lazy: typeof lazy,
+  readonly lazyAsync: typeof lazyAsync,
+  readonly pipe: typeof pipe,
+  readonly check: typeof check,
+  readonly checkAsync: typeof checkAsync,
+  readonly transform: typeof transform,
+  readonly transformAsync: typeof transformAsync,
+  readonly brand: typeof brand,
+  readonly refine: typeof refine,
+  readonly minLength: typeof minLength,
+  readonly maxLength: typeof maxLength,
+  readonly length: typeof length,
+  readonly nonEmpty: typeof nonEmpty,
+  readonly startsWith: typeof startsWith,
+  readonly endsWith: typeof endsWith,
+  readonly includes: typeof includes,
+  readonly regex: typeof regex,
+  readonly email: typeof email,
+  readonly url: typeof url,
+  readonly uuid: typeof uuid,
+  readonly isoDate: typeof isoDate,
+  readonly trim: typeof trim,
+  readonly toLowerCase: typeof toLowerCase,
+  readonly toUpperCase: typeof toUpperCase,
+  readonly min: typeof min,
+  readonly max: typeof max,
+  readonly integer: typeof integer,
+  readonly multipleOf: typeof multipleOf,
+  readonly minItems: typeof minItems,
+  readonly maxItems: typeof maxItems,
+  readonly parse: typeof parse,
+  readonly safeParse: typeof safeParse,
+  readonly parseAsync: typeof parseAsync,
+  readonly safeParseAsync: typeof safeParseAsync,
+  readonly is: typeof is,
+  readonly parser: typeof parser,
+  readonly useValidation: typeof useValidation,
+  readonly describe: typeof describe,
+  readonly isAsync: typeof isAsync,
+  readonly flatten: typeof flatten,
+  readonly toJsonSchema: typeof toJsonSchema,
+} = {
+  string,
+  number,
+  bigint,
+  boolean,
+  unknown,
+  never,
+  null: null_,
+  undefined: undefined_,
+  literal,
+  enum: enum_,
+  date,
+  instance,
+  custom,
+  object,
+  strictObject,
+  looseObject,
+  partial,
+  array,
+  tuple,
+  record,
+  map,
+  set,
+  union,
+  variant,
+  intersect,
+  optional,
+  nullable,
+  nullish,
+  withDefault,
+  fallback,
+  lazy,
+  lazyAsync,
+  pipe,
+  check,
+  checkAsync,
+  transform,
+  transformAsync,
+  brand,
+  refine,
+  minLength,
+  maxLength,
+  length,
+  nonEmpty,
+  startsWith,
+  endsWith,
+  includes,
+  regex,
+  email,
+  url,
+  uuid,
+  isoDate,
+  trim,
+  toLowerCase,
+  toUpperCase,
+  min,
+  max,
+  integer,
+  multipleOf,
+  minItems,
+  maxItems,
+  parse,
+  safeParse,
+  parseAsync,
+  safeParseAsync,
+  is,
+  parser,
+  useValidation,
+  describe,
+  isAsync,
+  flatten,
+  toJsonSchema,
+};