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

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

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

@@ -1,7 +1,7 @@
 {
   "name": "@uniflowed/validator",
-  "version": "0.0.0-alpha.4",
-  "description": "Flow implementation for @uniflowed/validator, part of the Unified Toolchain for Flow.",
+  "version": "0.0.0-alpha.6",
+  "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,
@@ -11,9 +11,24 @@
     "directory": "packages/validator"
   },
   "exports": {
-    ".": "./index.js"
+    ".": "./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": [
-    "index.js"
+    "*.js"
   ]
 }