@uniflowed/validator 0.0.0-alpha.10

package/pipe.js

@@ -0,0 +1,300 @@
+// @flow
+//
+// `@uniflowed/validator/pipe`: a schema with steps after it.
+//
+//   const Handle = pipe(string(), trim(), minLength(3), startsWith("@"));
+//   const Age = pipe(string(), transform(Number), integer(), min(18));
+//
+// A step takes a schema and returns a schema, so a pipeline is a fold and
+// nothing more. `pipe` is variadic because refinement is cumulative in
+// practice — a handle is a string that is trimmed *and* long enough *and*
+// starts with an at-sign — and making that `pipe(pipe(pipe(…)))` is a tax on
+// the only case anybody has.
+//
+// # A pipeline may change the output type
+//
+// `transform` is the reason the type has two parameters. `pipe(string(),
+// transform(Number))` accepts a `string` and produces a `number`, and both
+// halves survive: `InferInput` is `string`, `InferOutput` is `number`. That is
+// what lets `@uniflowed/form` type `defaultValues` as what the controls hold
+// and `onValid` as what the application wanted, from one schema.
+//
+// A step is polymorphic in the input type — `<TInput>(Schema<TFrom, TInput>)
+// => Schema<TTo, TInput>` — which is how the pipeline's input survives every
+// step after the first. It is also why a step is written as a generic arrow
+// rather than a plain one.
+//
+// # Why the overload table
+//
+// Flow cannot fold a type over a variadic argument list, so the relationship
+// "the output of step *n* is the input of step *n+1*" has to be spelled out
+// once per arity. Eight of them, which covers every pipeline this repository
+// or Valibot's own examples contain; a ninth step is a type error, and the fix
+// is to name the first eight and pipe the result. The implementation under the
+// table is arity-agnostic and there is exactly one cast in this package to
+// join the two, marked where it happens.
+//
+// The alternative was the previous signature, `pipe(schema, ...steps:
+// Step<any, any>): Schema<any>`, which type-checked everything and knew
+// nothing: it silently erased the output type of every pipeline in every
+// application, and `uf lint` was right to reject it.
+//
+// # Where a cross-field rule reports
+//
+// [`check`] takes an optional path. A rule that compares two fields lives on
+// the object — it needs both of them — but the message belongs under the
+// control the user has to change:
+//
+//   pipe(
+//     object({ password: string(), confirm: string() }),
+//     check((form) => form.password === form.confirm, "Passwords must match", ["confirm"]),
+//   );
+//
+// Without it the issue arrives with the object's own path and a form has
+// nowhere to put it.
+
+import type { Path } from "./issue.js";
+import { issueUnder } from "./issue.js";
+import type { Constraint, Description, Schema } from "./schema.js";
+import { describe, isAsync, makeAsyncSchema, makeSchema, ok, run, runAsync } from "./schema.js";
+
+/**
+ * One stage of a pipeline.
+ *
+ * Polymorphic in `TInput` so that the type of the pipeline's *input* is
+ * carried through every step rather than being flattened to `mixed` at the
+ * first one.
+ */
+export type Step<TFrom, TTo> = <TInput>(Schema<TFrom, TInput>) => Schema<TTo, TInput>;
+
+/**
+ * `pipe`'s type: one call signature per number of steps.
+ *
+ * Inexact, because an exact object type with call properties cannot be
+ * inhabited by a function.
+ */
+export type Pipe = {
+  <A, AIn>(schema: Schema<A, AIn>): Schema<A, AIn>,
+  <A, AIn, B>(schema: Schema<A, AIn>, a: Step<A, B>): Schema<B, AIn>,
+  <A, AIn, B, C>(schema: Schema<A, AIn>, a: Step<A, B>, b: Step<B, C>): Schema<C, AIn>,
+  <A, AIn, B, C, D>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+  ): Schema<D, AIn>,
+  <A, AIn, B, C, D, E>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+    d: Step<D, E>,
+  ): Schema<E, AIn>,
+  <A, AIn, B, C, D, E, F>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+    d: Step<D, E>,
+    e: Step<E, F>,
+  ): Schema<F, AIn>,
+  <A, AIn, B, C, D, E, F, G>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+    d: Step<D, E>,
+    e: Step<E, F>,
+    f: Step<F, G>,
+  ): Schema<G, AIn>,
+  <A, AIn, B, C, D, E, F, G, H>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+    d: Step<D, E>,
+    e: Step<E, F>,
+    f: Step<F, G>,
+    g: Step<G, H>,
+  ): Schema<H, AIn>,
+  <A, AIn, B, C, D, E, F, G, H, I>(
+    schema: Schema<A, AIn>,
+    a: Step<A, B>,
+    b: Step<B, C>,
+    c: Step<C, D>,
+    d: Step<D, E>,
+    e: Step<E, F>,
+    f: Step<F, G>,
+    g: Step<G, H>,
+    h: Step<H, I>,
+  ): Schema<I, AIn>,
+  ...
+};
+
+function applySteps<TInput>(
+  schema: Schema<mixed, TInput>,
+  ...steps: $ReadOnlyArray<Step<mixed, mixed>>
+): Schema<mixed, TInput> {
+  let piped = schema;
+  for (const step of steps) {
+    piped = step<TInput>(piped);
+  }
+  return piped;
+}
+
+/** Apply steps to a schema, left to right. */
+// $FlowFixMe[incompatible-type] the overload table above is the checked surface.
+export const pipe: Pipe = applySteps as Pipe;
+
+/**
+ * A schema with one more thing that must be true of its output.
+ *
+ * Every named step in `action.js` is a call to this. The `constraint` is what
+ * makes the step visible to `json-schema.js`: a refinement that cannot say
+ * what it refined is invisible to every exporter.
+ */
+export function refine<TOutput, TInput>(
+  schema: Schema<TOutput, TInput>,
+  accepts: (value: TOutput) => boolean,
+  code: string,
+  message: string,
+  constraint: Constraint,
+  at: Path = [],
+): Schema<TOutput, TInput> {
+  const description = (): Description => ({
+    kind: "constrained",
+    inner: describe(schema),
+    constraint,
+  });
+
+  if (isAsync(schema)) {
+    return makeAsyncSchema(async (value, path) => {
+      const result = await runAsync(schema, value, path);
+      if (!result.ok || accepts(result.value)) {
+        return result;
+      }
+      return { ok: false, issues: [issueUnder(code, message, path, at)] };
+    }, description);
+  }
+
+  return makeSchema((value, path) => {
+    const result = run(schema, value, path);
+    if (!result.ok || accepts(result.value)) {
+      return result;
+    }
+    return { ok: false, issues: [issueUnder(code, message, path, at)] };
+  }, description);
+}
+
+/**
+ * An arbitrary predicate, with the message it should report.
+ *
+ * Every other step in the package is a special case of this one. It exists so
+ * that a rule the library did not anticipate — a checksum, a business rule,
+ * one field agreeing with another — is a one-liner rather than a reason to
+ * abandon the schema and hand-roll validation.
+ *
+ * `at` is where the issue lands, relative to the value being checked. See the
+ * module docs for the cross-field case it is there for.
+ */
+export function check<TValue>(
+  accepts: (value: TValue) => boolean,
+  message: string,
+  at: Path = [],
+): Step<TValue, TValue> {
+  return <TInput>(schema: Schema<TValue, TInput>): Schema<TValue, TInput> =>
+    refine(schema, accepts, "check", message, { kind: "opaque", label: message }, at);
+}
+
+/**
+ * A predicate that has to ask something.
+ *
+ * "Is this username taken" is a question with a network on the other end, and
+ * a schema containing one is asynchronous from here up: the object around it,
+ * the array around that, and [`safeParse`] will refuse it and say to use
+ * [`safeParseAsync`].
+ */
+export function checkAsync<TValue>(
+  accepts: (value: TValue) => Promise<boolean>,
+  message: string,
+  at: Path = [],
+): Step<TValue, TValue> {
+  return <TInput>(schema: Schema<TValue, TInput>): Schema<TValue, TInput> =>
+    makeAsyncSchema(
+      async (value, path) => {
+        const result = await runAsync(schema, value, path);
+        if (!result.ok) {
+          return result;
+        }
+        return (await accepts(result.value))
+          ? result
+          : { ok: false, issues: [issueUnder("check", message, path, at)] };
+      },
+      () => ({
+        kind: "constrained",
+        inner: describe(schema),
+        constraint: { kind: "opaque", label: message },
+      }),
+    );
+}
+
+/**
+ * Change the value, and with it the schema's output type.
+ *
+ * Runs after everything before it in the pipeline has accepted, so a transform
+ * never sees a value the steps above rejected — which is why
+ * `pipe(string(), minLength(2), transform((text) => text.length))` is safe to
+ * write in that order and means something different in the other.
+ */
+export function transform<TFrom, TTo>(change: (value: TFrom) => TTo): Step<TFrom, TTo> {
+  return <TInput>(schema: Schema<TFrom, TInput>): Schema<TTo, TInput> => {
+    const description = (): Description => ({ kind: "transformed", inner: describe(schema) });
+    if (isAsync(schema)) {
+      return makeAsyncSchema(async (value, path) => {
+        const result = await runAsync(schema, value, path);
+        return result.ok ? ok(change(result.value)) : result;
+      }, description);
+    }
+    return makeSchema((value, path) => {
+      const result = run(schema, value, path);
+      return result.ok ? ok(change(result.value)) : result;
+    }, description);
+  };
+}
+
+/** A transform that has to wait: a lookup, a hash, a decode off the main path. */
+export function transformAsync<TFrom, TTo>(
+  change: (value: TFrom) => Promise<TTo>,
+): Step<TFrom, TTo> {
+  return <TInput>(schema: Schema<TFrom, TInput>): Schema<TTo, TInput> =>
+    makeAsyncSchema(
+      async (value, path) => {
+        const result = await runAsync(schema, value, path);
+        return result.ok ? ok(await change(result.value)) : result;
+      },
+      () => ({ kind: "transformed", inner: describe(schema) }),
+    );
+}
+
+/**
+ * A name on an otherwise ordinary value.
+ *
+ * It checks nothing at run time and it is not pretending to. The name reaches
+ * the description, so an exported schema can say "this string is a `UserId`";
+ * it does not reach the Flow type, because Flow's opaque types are declared in
+ * a module and cannot be produced by a call. `infer.js` says what to do
+ * instead when the distinction has to be enforced.
+ */
+export function brand<TValue>(name: string): Step<TValue, TValue> {
+  return <TInput>(schema: Schema<TValue, TInput>): Schema<TValue, TInput> => {
+    const description = (): Description => ({
+      kind: "constrained",
+      inner: describe(schema),
+      constraint: { kind: "brand", name },
+    });
+    if (isAsync(schema)) {
+      return makeAsyncSchema((value, path) => runAsync(schema, value, path), description);
+    }
+    return makeSchema((value, path) => run(schema, value, path), description);
+  };
+}

package/plain-object.js

@@ -0,0 +1,105 @@
+// @flow
+//
+// `@uniflowed/validator/plain-object`: reading and writing an object whose
+// keys came from outside.
+//
+// Three functions, and they are separate from every schema that uses them
+// because they are the package's whole answer to one question: what happens
+// when a payload contains a key that means something to JavaScript.
+//
+// `{"__proto__": {"isAdmin": true}}` is valid JSON, and it is what an attacker
+// sends. `out[key] = value` runs the legacy `__proto__` setter rather than
+// adding a property, so the parsed object would come back with a prototype the
+// attacker chose and every `record.isAdmin` downstream would read `true` from
+// a property nobody ever validated. Reading is the mirror image: `input[key]`
+// finds inherited properties, so a shape asking for `constructor` would be
+// handed `Object`.
+//
+// `object.js`, `collection.js`, `union.js` and `issue.js` all build or read an
+// object out of untrusted input, and every one of them goes through here
+// rather than keeping its own copy of the rule. That is the reason this is a
+// module and not three helpers at the top of the object parser: the defence is
+// only a defence if there is exactly one of it.
+
+/** Whether `value` is an object a shape or a record could be read from. */
+export function isPlainObject(value: mixed): boolean {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * `value` as something with string keys.
+ *
+ * The single object boundary in the package. Every caller has already asked
+ * [`isPlainObject`], and every field that leaves a schema went through that
+ * schema first, so the `mixed` values this exposes are narrowed before they
+ * reach an output type.
+ */
+export function plainRecord(value: mixed): { readonly [string]: mixed, ... } {
+  // $FlowFixMe[incompatible-type] guarded by `isPlainObject` at every call.
+  return value as { readonly [string]: mixed, ... };
+}
+
+/**
+ * The own keys of `value`, and nothing inherited.
+ *
+ * `Object.keys` already skips the prototype chain, which is why it is here
+ * rather than `for (const key in value)`.
+ */
+export function ownKeys(value: { readonly [string]: mixed, ... }): $ReadOnlyArray<string> {
+  return Object.keys(value);
+}
+
+/**
+ * Read one key, without falling through to the prototype.
+ *
+ * `record.constructor` is `Object` on every object in the language; a shape
+ * with a `constructor` field would otherwise be handed a function and report
+ * that the payload was fine. It also makes `object(shape)` answer the same way
+ * for `{}` and for a class instance with getters on its prototype, which is
+ * the sort of difference that is discovered in production.
+ *
+ * `Object.hasOwn` on every field read costs about 13% of a field-dense parse,
+ * measured on the workload in `index.js`. That is the price of the paragraph
+ * above and it is being paid deliberately: a payload out of `JSON.parse` has
+ * only own keys, so the check earns nothing there, and it earns everything the
+ * first time somebody hands a schema an object they built themselves.
+ */
+export function ownValue(source: { readonly [string]: mixed, ... }, key: string): mixed {
+  return Object.hasOwn(source, key) ? source[key] : undefined;
+}
+
+/**
+ * Write one parsed field into the object being built.
+ *
+ * `__proto__` is the only key that needs `defineProperty`, and it is worth
+ * knowing why rather than reaching for it on every field. `Object.prototype`
+ * has exactly one accessor on it — `__proto__` — and assignment to a key an
+ * accessor owns runs the setter instead of adding a property. Every other
+ * inherited name (`constructor`, `toString`, `valueOf`) is a *data* property,
+ * and assigning to one of those shadows it with an own property on the
+ * receiver, which is what a parsed field is supposed to be.
+ *
+ * So one string comparison is the whole defence against a hostile payload, and
+ * `defineProperty` is the slow path for the one key that needs it. That is not
+ * a micro-optimisation: `defineProperty` on every field made a thousand-record
+ * parse three times slower than the same parse with an assignment in it — more
+ * than the entire rest of the walk cost — and the measurement is in
+ * `index.js`.
+ *
+ * What this does not defend against is an `Object.prototype` that some other
+ * code has already given a setter to. Nothing in a parser can: a process whose
+ * `Object.prototype` is writable by an attacker has lost, and every read the
+ * consumer makes afterwards goes through the same polluted object.
+ */
+export function put<Value>(out: { [string]: Value, ... }, key: string, value: Value): void {
+  if (key !== "__proto__") {
+    out[key] = value;
+    return;
+  }
+  Object.defineProperty(out, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}

package/primitive.js

@@ -0,0 +1,183 @@
+// @flow
+//
+// `@uniflowed/validator/primitive`: the leaves.
+//
+// A schema that does not contain another schema. Every one of them is the same
+// four lines — test the value, hand it back or say what was wanted — and they
+// are together because that sameness is the whole subject: this is the list of
+// things uf will recognise without being told how.
+//
+// Each is a function rather than a constant so that a project ships only the
+// checks it called. `string` is not a value in a table somewhere that a
+// bundler has to keep because the table is reachable.
+
+import { plainRecord } from "./plain-object.js";
+import type { Description, Schema } from "./schema.js";
+import { fail, makeSchema, ok } from "./schema.js";
+
+const stringly = (): Description => ({ kind: "string" });
+
+export function string(): Schema<string, string> {
+  return makeSchema(
+    (value, path) =>
+      typeof value === "string" ? ok(value) : fail("type", "expected string", path),
+    stringly,
+  );
+}
+
+/**
+ * A finite number.
+ *
+ * `NaN` and the infinities are rejected. They are numbers to `typeof` and
+ * disasters to arithmetic, and a validator that lets `NaN` through has not
+ * validated anything — every comparison downstream silently answers `false`.
+ */
+export function number(): Schema<number, number> {
+  return makeSchema(
+    (value, path) =>
+      typeof value === "number" && Number.isFinite(value)
+        ? ok(value)
+        : fail("type", "expected number", path),
+    () => ({ kind: "number" }),
+  );
+}
+
+/**
+ * A `bigint`.
+ *
+ * Separate from [`number`] because the two do not mix: `1n === 1` is false,
+ * `1n + 1` throws, and `JSON.stringify` refuses. A schema that accepted either
+ * would hand its caller a value whose arithmetic depends on the payload.
+ */
+export function bigint(): Schema<bigint, bigint> {
+  return makeSchema(
+    (value, path) =>
+      typeof value === "bigint" ? ok(value) : fail("type", "expected bigint", path),
+    () => ({ kind: "bigint" }),
+  );
+}
+
+export function boolean(): Schema<boolean, boolean> {
+  return makeSchema(
+    (value, path) =>
+      typeof value === "boolean" ? ok(value) : fail("type", "expected boolean", path),
+    () => ({ kind: "boolean" }),
+  );
+}
+
+/** Anything at all, unexamined. The identity of this package. */
+export function unknown(): Schema<mixed, mixed> {
+  return makeSchema(
+    (value) => ok(value),
+    () => ({ kind: "unknown" }),
+  );
+}
+
+/**
+ * Nothing at all.
+ *
+ * For the branch of a union that must not be reachable, and for a shape whose
+ * field is being removed: `never()` says so at the boundary instead of leaving
+ * a field that quietly still works.
+ */
+export function never(): Schema<empty, empty> {
+  return makeSchema(
+    (value, path) => fail("never", "expected nothing here", path),
+    () => ({ kind: "never" }),
+  );
+}
+
+/** Exactly `null`. Distinct from a missing key, which is [`optional`]. */
+export function null_(): Schema<null, null> {
+  return makeSchema(
+    (value, path) => (value === null ? ok(null) : fail("type", "expected null", path)),
+    () => ({ kind: "null" }),
+  );
+}
+
+/** Exactly `undefined`. */
+export function undefined_(): Schema<void, void> {
+  return makeSchema(
+    (value, path) =>
+      value === undefined ? ok(undefined) : fail("type", "expected undefined", path),
+    () => ({ kind: "undefined" }),
+  );
+}
+
+export function literal<TValue extends string | number | boolean | null>(
+  expected: TValue,
+): Schema<TValue, TValue> {
+  return makeSchema(
+    (value, path) =>
+      value === expected ? ok(expected) : fail("literal", `expected ${String(expected)}`, path),
+    () => ({ kind: "literal", value: expected }),
+  );
+}
+
+/**
+ * One of a fixed list of strings.
+ *
+ * The message names every option, because a rejected enum is almost always a
+ * typo and the fix is in the list the caller could not see.
+ */
+export function enum_<TValue extends string>(
+  values: $ReadOnlyArray<TValue>,
+): Schema<TValue, TValue> {
+  const message = `expected one of ${values.join(", ")}`;
+  return makeSchema(
+    (value, path) => {
+      for (const option of values) {
+        if (value === option) {
+          return ok(option);
+        }
+      }
+      return fail("enum", message, path);
+    },
+    () => ({ kind: "enum", values: values.slice() }),
+  );
+}
+
+/** A `Date` that is a date, rather than the `Invalid Date` a bad string makes. */
+export function date(): Schema<Date, Date> {
+  return makeSchema(
+    (value, path) =>
+      value instanceof Date && Number.isFinite(value.getTime())
+        ? ok(value)
+        : fail("type", "expected Date", path),
+    () => ({ kind: "date" }),
+  );
+}
+
+/** An instance of `ClassValue`, by `instanceof`. */
+export function instance<TValue>(ClassValue: Class<TValue>): Schema<TValue, TValue> {
+  const named = plainRecord(ClassValue).name;
+  const name = typeof named === "string" ? named : "instance";
+  return makeSchema(
+    (value, path) =>
+      value instanceof ClassValue ? ok(value as TValue) : fail("type", `expected ${name}`, path),
+    () => ({ kind: "instance", name }),
+  );
+}
+
+/**
+ * A leaf this package has no name for.
+ *
+ * The escape hatch, and the one place a caller's word is taken for a type:
+ * `accepts` returning true is what makes the value a `TValue`, and nothing
+ * checks that claim. Use it for a value with a shape of its own — a
+ * `Uint8Array`, a branded id from another library — and reach for [`check`]
+ * instead when the value is an ordinary type with a rule attached, because
+ * that keeps the type honest.
+ */
+export function custom<TValue>(
+  accepts: (value: mixed) => boolean,
+  message: string,
+  name: string = "custom",
+): Schema<TValue, TValue> {
+  return makeSchema(
+    (value, path) =>
+      // $FlowFixMe[incompatible-type] `accepts` is the caller's promise, not a proof.
+      accepts(value) ? ok(value as TValue) : fail("custom", message, path),
+    () => ({ kind: "custom", name }),
+  );
+}