@uniflowed/validator 0.0.0-alpha.10

package/object.js

@@ -0,0 +1,241 @@
+// @flow
+//
+// `@uniflowed/validator/object`: an object whose keys are known when the
+// schema is written.
+//
+// Three of them, and the only difference is what happens to a key the shape
+// does not name:
+//
+// - [`object`] drops it. The right default for reading somebody else's
+//   payload, where a new field appearing upstream is not your emergency.
+// - [`strictObject`] rejects it. The right answer for a configuration file or
+//   an internal API, where an unrecognised key is almost always a typo the
+//   user would rather hear about than have ignored.
+// - [`looseObject`] keeps it. For a boundary that has to forward what it did
+//   not understand — a webhook that is re-signed, a document that round-trips
+//   through a form and must come back whole.
+//
+// One walk serves all three, because "which keys does the shape name" is the
+// same question in each and only the fourth line of the answer differs.
+//
+// # Why these take a shape and not a schema
+//
+// `partial({ name: string(), age: number() })`, not `partial(User)`. A schema
+// here is a closure and a description, not a reified list of fields, so there
+// is nothing on a built schema for `partial` to take apart — and adding one
+// would mean every object schema carried its shape for the benefit of the
+// callers that reshape it. Naming the shape once and passing it to both is the
+// same amount of typing and keeps the built schema the size of its job:
+//
+//   const account = { name: string(), age: number() };
+//   const Account = object(account);
+//   const Draft = partial(account);
+//
+// Valibot's `pick`, `omit` and `required` are absent for the same reason, and
+// because over a shape they are object literal manipulation the language
+// already has: `object({ name: account.name })` is `pick`.
+//
+// # Reading and writing
+//
+// Every read of an untrusted key goes through `plain-object.js`, and so does
+// every write. `object.js` never touches `source[key]` or `out[key] = …`
+// directly, and the reason is written down there.
+
+import type { Shape, ShapeInput, ShapeOutput } from "./infer.js";
+import type { Issue, PathBuffer } from "./issue.js";
+import { issue } from "./issue.js";
+import { isPlainObject, ownKeys, ownValue, plainRecord, put } from "./plain-object.js";
+import type { Description, Result, Schema } from "./schema.js";
+import {
+  collectAsync,
+  describe,
+  fail,
+  isAsync,
+  makeAsyncSchema,
+  makeSchema,
+  mergeIssues,
+  ok,
+  runAt,
+} from "./schema.js";
+import { optional } from "./optional.js";
+
+/** What an object schema does with a key its shape does not name. */
+type UnknownKeys = "strip" | "reject" | "keep";
+
+/**
+ * Pairs of `[key, schema]`, resolved once when the schema is built.
+ *
+ * `Object.keys(shape)` on every parse 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, mixed>]> {
+  return Object.keys(shape).map((key) => [key, shape[key]]);
+}
+
+/** Issues for every own key the shape does not name. Empty unless rejecting. */
+function unknownKeyIssues(
+  source: { readonly [string]: mixed, ... },
+  named: Set<string>,
+  path: PathBuffer,
+): Array<Issue> {
+  const issues: Array<Issue> = [];
+  for (const key of ownKeys(source)) {
+    if (!named.has(key)) {
+      path.push(key);
+      issues.push(issue("unknown_key", `unexpected key ${key}`, path));
+      path.pop();
+    }
+  }
+  return issues;
+}
+
+/** Copy every own key the shape does not name into the output, unchecked. */
+function keepUnknownKeys(
+  source: { readonly [string]: mixed, ... },
+  named: Set<string>,
+  out: { [string]: mixed, ... },
+): void {
+  for (const key of ownKeys(source)) {
+    if (!named.has(key)) {
+      put(out, key, ownValue(source, key));
+    }
+  }
+}
+
+/**
+ * The one object parser.
+ *
+ * `TOutput` and `TInput` are supplied by the three exported spellings; nothing
+ * at run time depends on them, which is why one implementation can serve an
+ * exact result, a `Partial` one and an inexact one alike.
+ */
+function buildObject<TOutput, TInput>(
+  shape: Shape,
+  unknownKeys: UnknownKeys,
+): Schema<TOutput, TInput> {
+  const entries = shapeEntries(shape);
+  const named = new Set(entries.map(([key]) => key));
+  const description = (): Description => ({
+    kind: "object",
+    entries: entries.map(([key, schema]) => [key, describe(schema)]),
+    unknownKeys,
+  });
+
+  function assemble(
+    source: { readonly [string]: mixed, ... },
+    out: { [string]: mixed, ... },
+    found: Array<Issue>,
+    path: PathBuffer,
+  ): Result<TOutput> {
+    const issues =
+      unknownKeys === "reject" ? found.concat(unknownKeyIssues(source, named, path)) : found;
+    if (issues.length > 0) {
+      return { ok: false, issues };
+    }
+    if (unknownKeys === "keep") {
+      keepUnknownKeys(source, named, out);
+    }
+    // $FlowFixMe[incompatible-type] every retained key was produced by the shape.
+    return ok(out as TOutput);
+  }
+
+  if (entries.some(([, schema]) => isAsync(schema))) {
+    return makeAsyncSchema(async (value, path) => {
+      if (!isPlainObject(value)) {
+        return fail("type", "expected object", path);
+      }
+      const source = plainRecord(value);
+      const collected = await collectAsync(
+        entries.map(([key, schema]) => ({ keys: [key], schema, value: ownValue(source, key) })),
+        path,
+      );
+      const out: { [string]: mixed, ... } = {};
+      const found: Array<Issue> = [];
+      match (collected) {
+        {ok: true, values: const values} => {
+          entries.forEach(([key], index) => {
+            put(out, key, values[index]);
+          });
+        }
+        {ok: false, issues: const collectedIssues} => {
+          for (const entry of collectedIssues) {
+            found.push(entry);
+          }
+        }
+      }
+      return assemble(source, out, found, path);
+    }, description);
+  }
+
+  return makeSchema((value, path) => {
+    if (!isPlainObject(value)) {
+      return fail("type", "expected object", path);
+    }
+    const source = plainRecord(value);
+    const out: { [string]: mixed, ... } = {};
+    const found: Array<Issue> = [];
+    for (const [key, schema] of entries) {
+      const result = runAt(schema, ownValue(source, key), path, key);
+      if (result.ok) {
+        put(out, key, result.value);
+      } else {
+        mergeIssues(found, result);
+      }
+    }
+    return assemble(source, out, found, path);
+  }, description);
+}
+
+/** An object with exactly the shape's keys; anything else is dropped. */
+export function object<TShape extends Shape>(
+  shape: TShape,
+): Schema<ShapeOutput<TShape>, ShapeInput<TShape>> {
+  return buildObject(shape, "strip");
+}
+
+/**
+ * An object that rejects keys the shape does not name.
+ *
+ * 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.
+ */
+export function strictObject<TShape extends Shape>(
+  shape: TShape,
+): Schema<ShapeOutput<TShape>, ShapeInput<TShape>> {
+  return buildObject(shape, "reject");
+}
+
+/**
+ * An object that keeps the keys the shape does not name.
+ *
+ * The extra keys are in the parsed value and not in its type: they are
+ * `mixed`, because nothing validated them. The result type is inexact, which
+ * is Flow saying exactly that.
+ */
+export function looseObject<TShape extends Shape>(
+  shape: TShape,
+): Schema<{ ...ShapeOutput<TShape>, ... }, { ...ShapeInput<TShape>, ... }> {
+  return buildObject(shape, "keep");
+}
+
+/**
+ * Every field of `shape`, each allowed to be missing.
+ *
+ * A key that was absent is present in the result holding `undefined`, rather
+ * than absent from it. One shape for the parsed value means a consumer reads
+ * `draft.name` without asking whether the key exists, and `Partial` says the
+ * same thing to the checker.
+ */
+export function partial<TShape extends Shape>(
+  shape: TShape,
+): Schema<Partial<ShapeOutput<TShape>>, Partial<ShapeInput<TShape>>> {
+  const partialShape: { [string]: Schema<mixed, mixed>, ... } = {};
+  for (const key of Object.keys(shape)) {
+    put(partialShape, key, optional(shape[key]));
+  }
+  return buildObject(partialShape, "strip");
+}

package/optional.js

@@ -0,0 +1,132 @@
+// @flow
+//
+// `@uniflowed/validator/optional`: a value that might not be there.
+//
+// Four wrappers and one rule each, and they are together because the question
+// they answer is one question — what counts as "not there", and what should
+// the parse produce when it happens.
+//
+//   optional(string())          // undefined is fine, and stays undefined
+//   nullable(string())          // null is fine, and stays null
+//   nullish(string())           // either is fine
+//   withDefault(string(), "")   // undefined becomes ""
+//   fallback(number(), 8080)    // *anything* that fails becomes 8080
+//
+// `undefined` and `null` are kept apart on purpose. A missing key and a key
+// explicitly set to null mean different things in every wire format uf reads —
+// a PATCH body, a GraphQL response, a form that cleared a field — and a
+// validator that folded them together would hand the application a value it
+// could no longer tell apart. `nullish` is there for the boundary that really
+// does not care.
+//
+// # Where the input type stops matching the output type
+//
+// [`withDefault`] and [`fallback`] are the two schemas whose `InferInput` is
+// genuinely wider than their `InferOutput`: a default's input may be missing
+// and its output never is, and a fallback accepts literally anything. That is
+// not a quirk of the typing, it is what those two are for, and it is the case
+// `InferInput` exists to describe.
+
+import type { Description, Result, Schema } from "./schema.js";
+import { describe, isAsync, makeAsyncSchema, makeSchema, ok, run, runAsync } from "./schema.js";
+
+/**
+ * Build a wrapper that answers for some inputs itself and delegates the rest.
+ *
+ * `shortcut` returns a result to use as-is, or null to mean "ask the inner
+ * schema". Every wrapper in this module is that shape, and writing it once is
+ * also what keeps the asynchronous variants from being four more copies of the
+ * same three lines.
+ */
+function wrap<TOutput, TInput>(
+  inner: Schema<TOutput, mixed>,
+  shortcut: (value: mixed) => null | Result<TOutput>,
+  description: () => Description,
+): Schema<TOutput, TInput> {
+  if (isAsync(inner)) {
+    return makeAsyncSchema((value, path) => {
+      const answered = shortcut(value);
+      return answered == null ? runAsync(inner, value, path) : Promise.resolve(answered);
+    }, description);
+  }
+  return makeSchema((value, path) => {
+    const answered = shortcut(value);
+    return answered == null ? run(inner, value, path) : answered;
+  }, description);
+}
+
+/** `undefined` passes through; anything else goes to `schema`. */
+export function optional<TOutput, TInput>(
+  schema: Schema<TOutput, TInput>,
+): Schema<void | TOutput, void | TInput> {
+  return wrap(
+    schema,
+    (value) => (value === undefined ? ok(undefined) : null),
+    () => ({ kind: "optional", inner: describe(schema) }),
+  );
+}
+
+/** `null` passes through; anything else goes to `schema`. */
+export function nullable<TOutput, TInput>(
+  schema: Schema<TOutput, TInput>,
+): Schema<null | TOutput, null | TInput> {
+  return wrap(
+    schema,
+    (value) => (value === null ? ok(null) : null),
+    () => ({ kind: "nullable", inner: describe(schema) }),
+  );
+}
+
+/** Either `null` or `undefined` passes through, unchanged. */
+export function nullish<TOutput, TInput>(
+  schema: Schema<TOutput, TInput>,
+): Schema<null | void | TOutput, null | void | TInput> {
+  return wrap(
+    schema,
+    (value) => (value == null ? ok(value === null ? null : undefined) : null),
+    () => ({ kind: "nullish", inner: describe(schema) }),
+  );
+}
+
+/**
+ * `undefined` becomes `value`; anything else goes to `schema`.
+ *
+ * The default is not validated. It is a value the program wrote, in the
+ * program's own types, and running it back through the parser would only be a
+ * chance for the two to disagree.
+ */
+export function withDefault<TOutput, TInput>(
+  schema: Schema<TOutput, TInput>,
+  value: TOutput,
+): Schema<TOutput, void | TInput> {
+  return wrap(
+    schema,
+    (input) => (input === undefined ? ok(value) : null),
+    () => ({ kind: "default", inner: describe(schema) }),
+  );
+}
+
+/**
+ * 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. Its input type is
+ * `mixed`, because that is the truth: it accepts everything.
+ */
+export function fallback<TOutput>(
+  schema: Schema<TOutput, mixed>,
+  value: TOutput,
+): Schema<TOutput, mixed> {
+  const description = (): Description => ({ kind: "fallback", inner: describe(schema) });
+  if (isAsync(schema)) {
+    return makeAsyncSchema(async (input, path) => {
+      const result = await runAsync(schema, input, path);
+      return result.ok ? result : ok(value);
+    }, description);
+  }
+  return makeSchema((input, path) => {
+    const result = run(schema, input, path);
+    return result.ok ? result : ok(value);
+  }, description);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@uniflowed/validator",
+  "version": "0.0.0-alpha.10",
+  "description": "Schemas that parse rather than assert: typed inference, issue paths and JSON Schema export, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/validator"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./action": "./action.js",
+    "./collection": "./collection.js",
+    "./infer": "./infer.js",
+    "./issue": "./issue.js",
+    "./json-schema": "./json-schema.js",
+    "./lazy": "./lazy.js",
+    "./namespace": "./namespace.js",
+    "./object": "./object.js",
+    "./optional": "./optional.js",
+    "./parse": "./parse.js",
+    "./pipe": "./pipe.js",
+    "./plain-object": "./plain-object.js",
+    "./primitive": "./primitive.js",
+    "./schema": "./schema.js",
+    "./union": "./union.js"
+  },
+  "files": [
+    "*.js"
+  ]
+}

package/parse.js

@@ -0,0 +1,116 @@
+// @flow
+//
+// `@uniflowed/validator/parse`: the four ways to run a schema.
+//
+//   safeParse(User, body)        // a Result: failure is a value
+//   parse(User, body)            // the value, or a thrown ValidationError
+//   await safeParseAsync(…)      // the same, for a schema that has to wait
+//   await parseAsync(…)
+//
+// Two axes, and both of them are a real choice rather than a style.
+//
+// # Throwing or not
+//
+// A boundary that already has a failure path — an HTTP handler building a 422,
+// a form collecting field errors — wants [`safeParse`], because a `throw` there
+// is a control-flow detour to reach a value it was going to inspect anyway.
+// Code with no failure path — a configuration file the process cannot start
+// without, a fixture in a test — wants [`parse`], because the alternative is an
+// `if (!result.ok) throw` at every call site.
+//
+// [`parse`] raises [`ValidationError`], which carries the structured issues
+// rather than only a joined message. 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 anybody do.
+//
+// # Waiting or not
+//
+// A schema is asynchronous, or it is not, and it knew which when it was built
+// — `schema.js` says why. So the synchronous entry points do not return a
+// promise sometimes: given a schema with a `checkAsync` in it they throw an
+// `Error` naming the asynchronous pair, which is a programmer's mistake
+// reported as one. It is not a [`ValidationError`], because nothing was
+// invalid.
+//
+// The asynchronous entry points accept both kinds. A schema with nothing to
+// wait for resolves on the first microtask, so a caller that does not know
+// which it has — a generic resolver, a request handler taking a schema from a
+// route table — can always use them.
+
+import type { Result, Schema } from "./schema.js";
+import { runAsync, run } from "./schema.js";
+import { ValidationError } from "./issue.js";
+
+/** Parse into a result, so failure is a value rather than control flow. */
+export function safeParse<TOutput>(schema: Schema<TOutput, mixed>, value: mixed): Result<TOutput> {
+  return run(schema, value, []);
+}
+
+/** Parse, or raise a [`ValidationError`] carrying every issue found. */
+export function parse<TOutput>(schema: Schema<TOutput, mixed>, value: mixed): TOutput {
+  const result = safeParse(schema, value);
+  if (result.ok) {
+    return result.value;
+  }
+  throw new ValidationError(result.issues);
+}
+
+/** [`safeParse`], for a schema with something to wait for. */
+export function safeParseAsync<TOutput>(
+  schema: Schema<TOutput, mixed>,
+  value: mixed,
+): Promise<Result<TOutput>> {
+  return runAsync(schema, value, []);
+}
+
+/** [`parse`], for a schema with something to wait for. */
+export async function parseAsync<TOutput>(
+  schema: Schema<TOutput, mixed>,
+  value: mixed,
+): Promise<TOutput> {
+  const result = await safeParseAsync(schema, value);
+  if (result.ok) {
+    return result.value;
+  }
+  throw new ValidationError(result.issues);
+}
+
+/**
+ * Whether `value` would parse.
+ *
+ * A `boolean` and not a type guard. Flow's `value is T` needs the predicate to
+ * be provable from the function's body, and here the proof is a closure the
+ * checker cannot see through; a guard would be a claim rather than a check.
+ * Narrow with [`safeParse`] and read `result.value`, which is the same
+ * information with the value attached.
+ */
+export function is(schema: Schema<mixed, mixed>, value: mixed): boolean {
+  return safeParse(schema, value).ok;
+}
+
+/**
+ * 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 package. `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<TOutput>(schema: Schema<TOutput, mixed>): (value: mixed) => Result<TOutput> {
+  return (value: mixed) => safeParse(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. It is here rather than in a module of its own because it is
+ * [`safeParse`] at a render boundary and not a second idea — and because
+ * nothing in this package imports React to provide it.
+ */
+export hook useValidation<TOutput>(schema: Schema<TOutput, mixed>, value: mixed): Result<TOutput> {
+  return safeParse(schema, value);
+}