@structuralists/scaffolding 0.7.0 → 0.9.0

package/src/forms/validations/types.ts

@@ -16,23 +16,87 @@ export type Refinement<Excluded = never> = {
 export type Validator<Input, Excluded = never> =
   ((val: Input) => string | null) & Refinement<Excluded>;
 
-// The constraint for a per-field validation map. Deliberately does NOT demand
-// the `Refinement` marker: a bare `(val) => string | null` is a legal
-// constraint that narrows nothing. Markers on standard-library validators
-// ride along in the *inferred* type of a concrete constraints object and are
-// recovered structurally by `Refine<>`.
+// A single field validator. Deliberately does NOT demand the `Refinement`
+// marker: a bare `(val) => string | null` is a legal constraint that narrows
+// nothing. Markers on standard-library validators ride along in the
+// *inferred* type of a concrete constraints object and are recovered
+// structurally by `Refine<>`.
+export type FieldValidator<F> = (val: F) => string | null;
+
+// What a constraints key may map to — phase 1 of the target grammar (see
+// plan.md): the leaf forms only. A single validator, or an ordered list of
+// validators run first-error-wins (sugar over `allOf` at the constraint
+// site; `allOf` remains for building reusable composite validators). The
+// structural forms (nested `Validations`, list `each`) arrive in phases 2–3.
+export type FieldConstraint<F> =
+  | FieldValidator<F>
+  | readonly FieldValidator<F>[];
+
+// The constraint for a per-field validation map.
 export type Validations<T extends FormValuesObject> = {
-  readonly [K in keyof T]?: (val: T[K]) => string | null;
+  readonly [K in keyof T]?: FieldConstraint<T[K]>;
 };
 
-// Applies each field's validator marker to the form type: the submit-time
-// type. Fields whose validator carries `Refinement<X>` become
-// `Exclude<T[K], X>`; unconstrained fields and bare (marker-less) validators
+// Extracts a validator's refinement marker; bare functions contribute
+// `never`. Distributes over a union-typed validator, yielding the union of
+// the branches' excludes — which is why it must NOT be applied to array
+// members directly (see `SoundExcludedOf`).
+export type ExcludedOf<C> = C extends Refinement<infer Excluded>
+  ? Excluded
+  : never;
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (arg: U) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never;
+
+// What one composed validator (an array member, an `allOf` part) is
+// GUARANTEED to exclude. A member that is itself a *union* of validators
+// (`cond ? v1 : v2`) runs only one branch at runtime, so it may only claim
+// the INTERSECTION of its branches' excludes — what every branch guarantees.
+// Each branch's excludes are boxed in a one-tuple before intersecting so a
+// single validator's own union marker (e.g. notEmpty's
+// `null | undefined | ''`) is not collapsed by the intersection; indexing
+// `[0]` afterwards unboxes (the constrained `infer` keeps the index legal
+// for the checker; inferring the element via `[infer E]` would be wrong —
+// inference from an intersection picks one constituent, not the
+// intersection). A bare-function branch contributes `never`, so a union
+// containing one guarantees nothing — its intersection is `never`.
+type SoundExcludedOf<M> = UnionToIntersection<
+  M extends unknown ? readonly [ExcludedOf<M>] : never
+> extends infer Boxed extends readonly [unknown]
+  ? Boxed[0]
+  : never;
+
+// The excludes earned by a list of validators that ALL run: the union across
+// members, each member contributing only its per-member-sound excludes.
+export type MemberExcludes<C extends readonly unknown[]> = {
+  [I in keyof C]: SoundExcludedOf<C[I]>;
+}[number];
+
+// One field's refinement. `C` is a naked type parameter, so a *union* of
+// constraint types distributes: `RefineField<F, A | B>` is
+// `RefineField<F, A> | RefineField<F, B>`. That distribution is load-bearing
+// for soundness — a conditionally-picked validator (`cond ? v1 : v2`) only
+// runs ONE branch at runtime, so the field may only narrow to the union of
+// the per-branch results, which is exactly what distribution produces. A
+// validator *array* is the opposite regime: every member runs, so the union
+// ACROSS members is earned in a single `Exclude` — but each member's own
+// contribution is per-member sound (`MemberExcludes`): a union-typed member
+// claims only the intersection of its branches' excludes. Branch order
+// matters once the grammar grows structural forms (validator functions are
+// objects) — `Refinement` stays first.
+type RefineField<F, C> = C extends Refinement<infer Excluded>
+  ? Exclude<F, Excluded>
+  : C extends readonly unknown[]
+    ? Exclude<F, MemberExcludes<C>>
+    : F;
+
+// Applies each field's constraint to the form type: the submit-time type.
+// Singles narrow by their marker, arrays by the union of their members'
+// sound excludes; unconstrained fields and bare (marker-less) validators
 // pass through unchanged. Shallow by design — one mapped type, no recursion.
 export type Refine<T extends FormValuesObject, V extends Validations<T>> = {
-  [K in keyof T]: K extends keyof V
-    ? V[K] extends Refinement<infer Excluded>
-      ? Exclude<T[K], Excluded>
-      : T[K]
-    : T[K];
+  [K in keyof T]: K extends keyof V ? RefineField<T[K], V[K]> : T[K];
 };

package/src/forms/validations/walk.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { validateEntry } from './walk';
+
+const pass = () => null;
+const fail = (message: string) => () => message;
+
+describe('validateEntry — single validator', () => {
+  test('a passing validator yields no error', () => {
+    expect(validateEntry(pass, 'anything', ['a'])).toBeNull();
+  });
+
+  test('a failing validator yields its message at the given path', () => {
+    expect(validateEntry(fail('nope'), 'anything', ['a'])).toEqual({
+      path: ['a'],
+      error: 'nope',
+    });
+  });
+
+  test('the validator receives the field value', () => {
+    const spy = mock((val: string) => (val === 'x' ? null : 'expected x'));
+    expect(validateEntry(spy, 'x', ['a'])).toBeNull();
+    expect(spy).toHaveBeenCalledWith('x');
+  });
+});
+
+describe('validateEntry — validator arrays', () => {
+  test('all passing yields no error', () => {
+    expect(validateEntry([pass, pass, pass], 'v', ['a'])).toBeNull();
+  });
+
+  test('validators run in array order and the first error wins', () => {
+    const result = validateEntry(
+      [pass, fail('second'), fail('third')],
+      'v',
+      ['a'],
+    );
+    expect(result).toEqual({ path: ['a'], error: 'second' });
+  });
+
+  test('validators after the first failure are not called', () => {
+    const after = mock(() => 'never reached');
+    validateEntry([fail('boom'), after], 'v', ['a']);
+    expect(after).not.toHaveBeenCalled();
+  });
+
+  test('every validator before the failure sees the value', () => {
+    const first = mock(() => null);
+    const second = mock(() => null);
+    expect(validateEntry([first, second], 42, ['n'])).toBeNull();
+    expect(first).toHaveBeenCalledWith(42);
+    expect(second).toHaveBeenCalledWith(42);
+  });
+
+  test('an empty array passes', () => {
+    expect(validateEntry([], undefined, ['a'])).toBeNull();
+  });
+});
+
+describe('validateEntry — path accumulation', () => {
+  test('the error carries the path it was given, verbatim', () => {
+    // Phase 1 paths are single-key; the signature already speaks PathStep[]
+    // so the phases-2/3 {path, error}[] model needs no walk rewrite.
+    const result = validateEntry(fail('bad date'), undefined, [
+      'drivers',
+      3,
+      'incidents',
+      0,
+      'date',
+    ]);
+    expect(result).toEqual({
+      path: ['drivers', 3, 'incidents', 0, 'date'],
+      error: 'bad date',
+    });
+  });
+});

package/src/forms/validations/walk.ts

@@ -0,0 +1,51 @@
+import type { PathStep } from '../path/types';
+
+// The runtime walk over a constraints object, kept separate from the hook so
+// its semantics are unit-testable without React. Phase 1 grammar is flat —
+// every path has exactly one step — but errors already carry a `PathStep[]`
+// address so the `{path, error}[]` error model of plan phases 2–3 falls out
+// of this structure instead of forcing a second rewrite.
+
+export type ValidationError = {
+  readonly path: readonly PathStep[];
+  readonly error: string;
+};
+
+// The walk's receiving type for one validator. `never` is the one parameter
+// type every field validator is assignable to (contravariance) — the walk
+// cannot correlate a validator's input with its field's value type, so it
+// accepts them all and re-widens at the single call site below.
+type AnyFieldValidator = (val: never) => string | null;
+
+// The walk's view of one entry in a `Validations<T>` object. This type is
+// what lets the compiler police the walk's assumptions: the hook assigns
+// `constraints[key]` to it WITHOUT a cast, so when the grammar grows a form
+// that is neither a function nor an array of them (nested spec, list `each`),
+// that assignment stops compiling and the walk must learn the new form —
+// instead of a stale walk misinterpreting it at runtime.
+export type FlatConstraintEntry =
+  | AnyFieldValidator
+  | readonly AnyFieldValidator[];
+
+// Runs one constraint entry against the field value found at `path`.
+// Semantics for arrays (identical to `allOf`): validators run in array
+// order, first error wins — later validators are not called once one fails.
+// An empty array passes, mirroring its refinement (`Exclude<F, never>`).
+export const validateEntry = (
+  entry: FlatConstraintEntry,
+  value: unknown,
+  path: readonly PathStep[],
+): ValidationError | null => {
+  const validators = typeof entry === 'function' ? [entry] : entry;
+
+  for (const validator of validators) {
+    // Safe: the constraints object was type-checked against the form type
+    // where it was built, so this validator accepts the value at `path`; the
+    // walk just can't see that correlation. Same honest contravariant
+    // widening as `allOf`'s part-call.
+    const error = (validator as (val: unknown) => string | null)(value);
+    if (error != null) return { path, error };
+  }
+
+  return null;
+};

package/src/forms/validators/validators.ts

@@ -1,4 +1,4 @@
-import type { Refinement, Validator } from '../validations/types';
+import type { MemberExcludes, Refinement, Validator } from '../validations/types';
 
 // Standard-library validators. Each one declares its refinement explicitly —
 // `Validator<Input, Excluded>` — even when it narrows nothing (`never`).
@@ -60,8 +60,6 @@ export const min = (
     {} as Refinement,
   );
 
-type ExcludedOf<V> = V extends Refinement<infer Excluded> ? Excluded : never;
-
 // The composed input is the *intersection* of the parts' inputs: a value the
 // composite accepts must be acceptable to every part. Inferring `I` from the
 // union of function types puts it in contravariant position, which is what
@@ -75,13 +73,15 @@ type InputOf<Validators extends readonly ((val: never) => string | null)[]> =
 
 // Composes validators on one field: first error wins. The refinement is the
 // union of the parts' refinements — running all of them earns all of their
-// narrowings. `const Validators` keeps each member's precise type so
-// `ExcludedOf` can extract markers; bare functions contribute `never`.
+// narrowings, with each part contributing only its per-member-sound excludes
+// (`MemberExcludes`: a union-typed part earns just the intersection of its
+// branches). `const Validators` keeps each member's precise type so the
+// markers survive extraction; bare functions contribute `never`.
 export const allOf = <
   const Validators extends readonly ((val: never) => string | null)[],
 >(
   ...validators: Validators
-): Validator<InputOf<Validators>, ExcludedOf<Validators[number]>> =>
+): Validator<InputOf<Validators>, MemberExcludes<Validators>> =>
   Object.assign(
     (val: InputOf<Validators>) => {
       for (const validator of validators) {
@@ -91,5 +91,5 @@ export const allOf = <
       }
       return null;
     },
-    {} as Refinement<ExcludedOf<Validators[number]>>,
+    {} as Refinement<MemberExcludes<Validators>>,
   );