@uniflowed/validator 0.0.0-alpha.10

package/action.js

@@ -0,0 +1,309 @@
+// @flow
+//
+// `@uniflowed/validator/action`: the steps that come ready-made.
+//
+// Every one of them is a call to `refine` or `transform` with a name, a
+// message and a [`Constraint`] attached, and they are together because that is
+// what they are: a catalogue, in the same sense as `@uniflowed/form`'s
+// `rules.js`. Splitting it by the type each one refines would be splitting by
+// argument rather than by subject, and would leave three modules that each say
+// "this is a `check` with a better error message".
+//
+// The constraint is the part that is not decoration. `minLength(3)` records
+// `{ kind: "minLength", value: 3 }`, which is what lets `json-schema.js` emit
+// `"minLength": 3` rather than shrugging; a hand-written `check((text) =>
+// text.length >= 3, …)` does the same thing at run time and exports as
+// nothing, because a predicate has no spelling in any export format.
+//
+// # Messages
+//
+// Each carries a default that says what was wanted rather than what was found
+// — "expected at least 3 characters" — because the value is already in the
+// caller's hands and the expectation is the half it is missing. Where a
+// message wants to be user-facing prose, `check(predicate, "Pick a longer
+// name")` is the way to say it; these are for the boundary, not the label.
+//
+// # What is deliberately absent
+//
+// No `creditCard`, `emoji`, `mac`, `imei`, `cuid2` or the rest of the long
+// tail. Each is a regular expression with a maintenance schedule attached —
+// Unicode adds emoji, card issuers add prefixes — and a validator that ships a
+// stale one is worse than an application that writes `check` with a rule it
+// owns. The ones here are either structural (`length`, `min`) or defined by a
+// specification that does not move under them (`uuid`, `isoDate`).
+
+import type { Step } from "./pipe.js";
+import { refine, transform } from "./pipe.js";
+import type { Schema } from "./schema.js";
+
+/** At least `value` characters. */
+export function minLength(value: number): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.length >= value,
+      "min_length",
+      `expected at least ${String(value)} characters`,
+      { kind: "minLength", value },
+    );
+}
+
+/** At most `value` characters. */
+export function maxLength(value: number): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.length <= value,
+      "max_length",
+      `expected at most ${String(value)} characters`,
+      { kind: "maxLength", value },
+    );
+}
+
+/** Exactly `value` characters. */
+export function length(value: number): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.length === value,
+      "length",
+      `expected exactly ${String(value)} characters`,
+      { kind: "length", value },
+    );
+}
+
+/**
+ * At least one character.
+ *
+ * Separate from `minLength(1)` because it is the check a form makes on every
+ * required text field, and `nonEmpty()` says why at the call site.
+ */
+export function nonEmpty(): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(schema, (input: string) => input.length > 0, "non_empty", "expected a value", {
+      kind: "minLength",
+      value: 1,
+    });
+}
+
+export function startsWith(value: string): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.startsWith(value),
+      "starts_with",
+      `expected prefix ${value}`,
+      { kind: "pattern", source: `^${escapeRegExp(value)}` },
+    );
+}
+
+export function endsWith(value: string): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.endsWith(value),
+      "ends_with",
+      `expected suffix ${value}`,
+      { kind: "pattern", source: `${escapeRegExp(value)}$` },
+    );
+}
+
+export function includes(value: string): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => input.includes(value),
+      "includes",
+      `expected ${value} somewhere in the value`,
+      { kind: "pattern", source: escapeRegExp(value) },
+    );
+}
+
+/** `value` with every regular-expression metacharacter made literal. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * A string matching `pattern`.
+ *
+ * The pattern is tested against a reset `lastIndex` every time, because a
+ * caller who reaches for `/g` would otherwise get a schema that alternates
+ * between accepting and rejecting the same input.
+ */
+export function regex(pattern: RegExp, message?: string): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => {
+        pattern.lastIndex = 0;
+        return pattern.test(input);
+      },
+      "regex",
+      message ?? `expected a match for ${String(pattern)}`,
+      { kind: "pattern", source: pattern.source },
+    );
+}
+
+/**
+ * Something shaped like an email address.
+ *
+ * Deliberately loose. The grammar in RFC 5322 accepts addresses no mail server
+ * will route and the regular expressions that implement it are famous for
+ * rejecting real ones; the only test that proves an address exists is sending
+ * something to it. This rejects the typos — a missing at-sign, a missing dot —
+ * and gets out of the way.
+ */
+export function email(): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input),
+      "email",
+      "expected email address",
+      { kind: "format", name: "email" },
+    );
+}
+
+/** A URL the platform's own parser accepts, so the parse is the check. */
+export function url(): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => {
+        try {
+          return new URL(input) != null;
+        } catch {
+          return false;
+        }
+      },
+      "url",
+      "expected a URL",
+      { kind: "format", name: "uri" },
+    );
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/** A UUID with a version and a variant, as RFC 9562 defines them. */
+export function uuid(): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(schema, (input: string) => UUID.test(input), "uuid", "expected a UUID", {
+      kind: "format",
+      name: "uuid",
+    });
+}
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * A calendar date as `YYYY-MM-DD`.
+ *
+ * The shape is not enough: `2026-02-30` matches the pattern and is not a day.
+ * The value is round-tripped through `Date` and compared back, which rejects
+ * every month that is shorter than the payload thought.
+ */
+export function isoDate(): Step<string, string> {
+  return <TInput>(schema: Schema<string, TInput>): Schema<string, TInput> =>
+    refine(
+      schema,
+      (input: string) => {
+        const parts = ISO_DATE.exec(input);
+        if (parts == null) {
+          return false;
+        }
+        const when = new Date(`${input}T00:00:00Z`);
+        return Number.isFinite(when.getTime()) && when.toISOString().slice(0, 10) === input;
+      },
+      "iso_date",
+      "expected a date as YYYY-MM-DD",
+      { kind: "format", name: "date" },
+    );
+}
+
+/** Whitespace off both ends, before whatever comes next in the pipeline. */
+export function trim(): Step<string, string> {
+  return transform((input: string) => input.trim());
+}
+
+export function toLowerCase(): Step<string, string> {
+  return transform((input: string) => input.toLowerCase());
+}
+
+export function toUpperCase(): Step<string, string> {
+  return transform((input: string) => input.toUpperCase());
+}
+
+/** At least `value`. */
+export function min(value: number): Step<number, number> {
+  return <TInput>(schema: Schema<number, TInput>): Schema<number, TInput> =>
+    refine(schema, (input: number) => input >= value, "min", `expected at least ${String(value)}`, {
+      kind: "min",
+      value,
+    });
+}
+
+/** At most `value`. */
+export function max(value: number): Step<number, number> {
+  return <TInput>(schema: Schema<number, TInput>): Schema<number, TInput> =>
+    refine(schema, (input: number) => input <= value, "max", `expected at most ${String(value)}`, {
+      kind: "max",
+      value,
+    });
+}
+
+export function integer(): Step<number, number> {
+  return <TInput>(schema: Schema<number, TInput>): Schema<number, TInput> =>
+    refine(schema, (input: number) => Number.isInteger(input), "integer", "expected an integer", {
+      kind: "integer",
+    });
+}
+
+/**
+ * A multiple of `value`.
+ *
+ * The remainder is compared with a tolerance rather than against zero, because
+ * `0.3 % 0.1` is `0.09999999999999998` and a step of `0.1` on a price field is
+ * the reason anybody asks for this.
+ */
+export function multipleOf(value: number): Step<number, number> {
+  return <TInput>(schema: Schema<number, TInput>): Schema<number, TInput> =>
+    refine(
+      schema,
+      (input: number) => {
+        const remainder = Math.abs(input % value);
+        return remainder < 1e-9 || Math.abs(remainder - Math.abs(value)) < 1e-9;
+      },
+      "multiple_of",
+      `expected a multiple of ${String(value)}`,
+      { kind: "multipleOf", value },
+    );
+}
+
+/** At least `value` items. Arrays, where `minLength` is for strings. */
+export function minItems<TItem>(value: number): Step<$ReadOnlyArray<TItem>, $ReadOnlyArray<TItem>> {
+  return <TInput>(
+    schema: Schema<$ReadOnlyArray<TItem>, TInput>,
+  ): Schema<$ReadOnlyArray<TItem>, TInput> =>
+    refine(
+      schema,
+      (input: $ReadOnlyArray<TItem>) => input.length >= value,
+      "min_items",
+      `expected at least ${String(value)} items`,
+      { kind: "minItems", value },
+    );
+}
+
+/** At most `value` items. */
+export function maxItems<TItem>(value: number): Step<$ReadOnlyArray<TItem>, $ReadOnlyArray<TItem>> {
+  return <TInput>(
+    schema: Schema<$ReadOnlyArray<TItem>, TInput>,
+  ): Schema<$ReadOnlyArray<TItem>, TInput> =>
+    refine(
+      schema,
+      (input: $ReadOnlyArray<TItem>) => input.length <= value,
+      "max_items",
+      `expected at most ${String(value)} items`,
+      { kind: "maxItems", value },
+    );
+}

package/collection.js

@@ -0,0 +1,338 @@
+// @flow
+//
+// `@uniflowed/validator/collection`: containers whose contents are only known
+// when the value arrives.
+//
+// `object.js` names its keys when the schema is written. These five do not:
+// an array has as many items as the payload has, a record has whatever keys it
+// was sent, a map and a set have whatever they were built with. So the walk is
+// the same in all five — visit every child, keep the ones that parsed, collect
+// the issues from the ones that did not, and report all of them — and the only
+// thing that differs is what the container is called and how the result is
+// rebuilt. `tuple` is here rather than beside `object` for the same reason: its
+// positions are its keys.
+//
+// # Every child is visited, including the ones after a failure
+//
+// A parse stops at the first bad field in most libraries. This one does not,
+// because "row 3 is wrong" followed by "row 7 is wrong" on the next attempt is
+// two round trips for information that was available at once — and for a form
+// bound to an array of rows it is two renders where one would do.
+//
+// # Where an issue lands
+//
+// An array or tuple item is its index, as a decimal string: `["items", "2"]`.
+// A record value is its key. A set element is its position in iteration order,
+// which is insertion order.
+//
+// A map is the one that needs two segments. An entry can fail because its key
+// was wrong or because its value was, and `["3", "key"]` against `["3",
+// "value"]` says which — where a single index would have left the caller
+// guessing at exactly the moment it needed to know.
+//
+// # What crosses a wire, and what does not
+//
+// `map` and `set` do not survive `JSON.stringify`, and `json-schema.js`
+// reports them as unrepresentable rather than pretending. They are here
+// because not every boundary is JSON: a value coming out of `structuredClone`,
+// out of IndexedDB, or from another module in the same process is a real value
+// with a real shape, and a validator that could only describe JSON would be a
+// JSON validator.
+
+import type { ItemsInput, ItemsOutput, Options } from "./infer.js";
+import type { 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,
+  runUnder,
+} from "./schema.js";
+
+/** Every item of an array, each parsed by `item`. */
+export function array<TOutput, TInput>(
+  item: Schema<TOutput, TInput>,
+): Schema<$ReadOnlyArray<TOutput>, $ReadOnlyArray<TInput>> {
+  const description = (): Description => ({ kind: "array", item: describe(item) });
+
+  if (isAsync(item)) {
+    return makeAsyncSchema(async (value, path) => {
+      if (!Array.isArray(value)) {
+        return fail("type", "expected array", path);
+      }
+      const collected = await collectAsync(
+        value.map((entry, index) => ({ keys: [String(index)], schema: item, value: entry })),
+        path,
+      );
+      if (!collected.ok) {
+        return { ok: false, issues: collected.issues };
+      }
+      // $FlowFixMe[incompatible-type] every element came out of `item`.
+      return ok(collected.values as $ReadOnlyArray<TOutput>);
+    }, description);
+  }
+
+  return makeSchema((value, path) => {
+    if (!Array.isArray(value)) {
+      return fail("type", "expected array", path);
+    }
+    const out: Array<TOutput> = [];
+    let issues: null | Array<Issue> = null;
+    for (let index = 0; index < value.length; index += 1) {
+      const result = runAt(item, value[index], path, String(index));
+      if (result.ok) {
+        out.push(result.value);
+      } else {
+        issues = issues ?? [];
+        mergeIssues(issues, result);
+      }
+    }
+    return issues == null ? ok(out) : { ok: false, issues };
+  }, description);
+}
+
+/**
+ * A fixed number of positions, each with a schema of its own.
+ *
+ * The arity is part of the type: a payload with one item too many is rejected
+ * rather than truncated, because a tuple whose length varied would be an array
+ * with extra steps.
+ */
+export function tuple<TItems extends Options>(
+  items: TItems,
+): Schema<ItemsOutput<TItems>, ItemsInput<TItems>> {
+  const arity = items.length;
+  const message = `expected ${String(arity)} tuple items`;
+  const description = (): Description => ({
+    kind: "tuple",
+    items: items.map((item) => describe(item)),
+  });
+
+  if (items.some((item) => isAsync(item))) {
+    return makeAsyncSchema(async (value, path) => {
+      if (!Array.isArray(value)) {
+        return fail("type", "expected tuple", path);
+      }
+      if (value.length !== arity) {
+        return fail("length", message, path);
+      }
+      const collected = await collectAsync(
+        items.map((item, index) => ({ keys: [String(index)], schema: item, value: value[index] })),
+        path,
+      );
+      if (!collected.ok) {
+        return { ok: false, issues: collected.issues };
+      }
+      // $FlowFixMe[incompatible-type] position by position, each item's own schema built it.
+      return ok(collected.values as ItemsOutput<TItems>);
+    }, description);
+  }
+
+  return makeSchema((value, path) => {
+    if (!Array.isArray(value)) {
+      return fail("type", "expected tuple", path);
+    }
+    if (value.length !== arity) {
+      return fail("length", message, path);
+    }
+    const out: Array<mixed> = [];
+    let issues: null | Array<Issue> = null;
+    for (let index = 0; index < arity; index += 1) {
+      const result = runAt(items[index], value[index], path, String(index));
+      if (result.ok) {
+        out.push(result.value);
+      } else {
+        issues = issues ?? [];
+        mergeIssues(issues, result);
+      }
+    }
+    // $FlowFixMe[incompatible-type] position by position, each item's own schema built it.
+    return issues == null ? ok(out as ItemsOutput<TItems>) : { ok: false, issues };
+  }, description);
+}
+
+/**
+ * An object whose keys are not known ahead of time.
+ *
+ * Only own enumerable keys are read, so a payload carrying `__proto__` or
+ * `constructor` cannot smuggle an inherited value into the parsed result.
+ */
+export function record<TOutput, TInput>(
+  value: Schema<TOutput, TInput>,
+): Schema<{ readonly [string]: TOutput, ... }, { readonly [string]: TInput, ... }> {
+  const description = (): Description => ({ kind: "record", value: describe(value) });
+
+  if (isAsync(value)) {
+    return makeAsyncSchema(async (input, path) => {
+      if (!isPlainObject(input)) {
+        return fail("type", "expected object", path);
+      }
+      const source = plainRecord(input);
+      const keys = ownKeys(source);
+      const collected = await collectAsync(
+        keys.map((key) => ({ keys: [key], schema: value, value: ownValue(source, key) })),
+        path,
+      );
+      if (!collected.ok) {
+        return { ok: false, issues: collected.issues };
+      }
+      const out: { [string]: TOutput, ... } = {};
+      keys.forEach((key, index) => {
+        // $FlowFixMe[incompatible-type] every value came out of `value`.
+        put(out, key, collected.values[index] as TOutput);
+      });
+      return ok(out);
+    }, description);
+  }
+
+  return makeSchema((input, path) => {
+    if (!isPlainObject(input)) {
+      return fail("type", "expected object", path);
+    }
+    const source = plainRecord(input);
+    const out: { [string]: TOutput, ... } = {};
+    let issues: null | Array<Issue> = null;
+    for (const key of ownKeys(source)) {
+      const result = runAt(value, ownValue(source, key), path, key);
+      if (result.ok) {
+        put(out, key, result.value);
+      } else {
+        issues = issues ?? [];
+        mergeIssues(issues, result);
+      }
+    }
+    return issues == null ? ok(out) : { ok: false, issues };
+  }, description);
+}
+
+/**
+ * A `Map`, with a schema for its keys and one for its values.
+ *
+ * Rebuilt rather than checked in place, because a `key` schema may be a `pipe`
+ * that changes the key — and a map re-keyed in place would collide with itself
+ * halfway through.
+ */
+export function map<TKey, TKeyInput, TValue, TValueInput>(
+  key: Schema<TKey, TKeyInput>,
+  value: Schema<TValue, TValueInput>,
+): Schema<$ReadOnlyMap<TKey, TValue>, $ReadOnlyMap<TKeyInput, TValueInput>> {
+  const description = (): Description => ({
+    kind: "map",
+    key: describe(key),
+    value: describe(value),
+  });
+
+  if (isAsync(key) || isAsync(value)) {
+    return makeAsyncSchema(async (input, path) => {
+      if (!(input instanceof Map)) {
+        return fail("type", "expected Map", path);
+      }
+      const entries = Array.from(input.entries());
+      const collected = await collectAsync(
+        entries.flatMap(([entryKey, entryValue], index) => [
+          { keys: [String(index), "key"], schema: key, value: entryKey },
+          { keys: [String(index), "value"], schema: value, value: entryValue },
+        ]),
+        path,
+      );
+      if (!collected.ok) {
+        return { ok: false, issues: collected.issues };
+      }
+      const out = new Map<TKey, TValue>();
+      for (let index = 0; index < entries.length; index += 1) {
+        // $FlowFixMe[incompatible-type] the jobs were pushed key-then-value, in order.
+        out.set(collected.values[index * 2] as TKey, collected.values[index * 2 + 1] as TValue);
+      }
+      return ok(out);
+    }, description);
+  }
+
+  return makeSchema((input, path) => {
+    if (!(input instanceof Map)) {
+      return fail("type", "expected Map", path);
+    }
+    const out = new Map<TKey, TValue>();
+    let issues: null | Array<Issue> = null;
+    let index = 0;
+    for (const [entryKey, entryValue] of input.entries()) {
+      const at = String(index);
+      const parsedKey = runUnder(key, entryKey, path, [at, "key"]);
+      const parsedValue = runUnder(value, entryValue, path, [at, "value"]);
+      if (parsedKey.ok && parsedValue.ok) {
+        out.set(parsedKey.value, parsedValue.value);
+      } else {
+        issues = issues ?? [];
+        mergeIssues(issues, parsedKey);
+        mergeIssues(issues, parsedValue);
+      }
+      index += 1;
+    }
+    return issues == null ? ok(out) : { ok: false, issues };
+  }, description);
+}
+
+/**
+ * A `Set`, every member parsed by `item`.
+ *
+ * A `pipe` on `item` can make two distinct inputs equal — `trim()` over
+ * `"a"` and `"a "` — and the rebuilt set then has one member where the input
+ * had two. That is what a set is for, and it is worth knowing before it
+ * surprises somebody counting rows.
+ */
+export function set<TOutput, TInput>(
+  item: Schema<TOutput, TInput>,
+): Schema<$ReadOnlySet<TOutput>, $ReadOnlySet<TInput>> {
+  const description = (): Description => ({ kind: "set", item: describe(item) });
+
+  if (isAsync(item)) {
+    return makeAsyncSchema(async (value, path) => {
+      if (!(value instanceof Set)) {
+        return fail("type", "expected Set", path);
+      }
+      const collected = await collectAsync(
+        Array.from(value).map((member, index) => ({
+          keys: [String(index)],
+          schema: item,
+          value: member,
+        })),
+        path,
+      );
+      if (!collected.ok) {
+        return { ok: false, issues: collected.issues };
+      }
+      const out = new Set<TOutput>();
+      for (const member of collected.values) {
+        // $FlowFixMe[incompatible-type] every member came out of `item`.
+        out.add(member as TOutput);
+      }
+      return ok(out);
+    }, description);
+  }
+
+  return makeSchema((value, path) => {
+    if (!(value instanceof Set)) {
+      return fail("type", "expected Set", path);
+    }
+    const out = new Set<TOutput>();
+    let issues: null | Array<Issue> = null;
+    let index = 0;
+    for (const member of value) {
+      const result = runAt(item, member, path, String(index));
+      if (result.ok) {
+        out.add(result.value);
+      } else {
+        issues = issues ?? [];
+        mergeIssues(issues, result);
+      }
+      index += 1;
+    }
+    return issues == null ? ok(out) : { ok: false, issues };
+  }, description);
+}