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

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

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