@structuralists/scaffolding 0.4.1 → 0.5.0

package/src/forms/useFormState/useFormState.test-d.ts

@@ -0,0 +1,209 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { useFormState } from './useFormState';
+import { allOf, matches, min, minLength, notEmpty } from '../validators/validators';
+import type { Refine, Validations } from '../validations/types';
+import type { Path, ValueAt } from '../path/types';
+
+// These tests exercise the headline feature end-to-end at the hook boundary:
+// the type `onSubmit` receives must be the *refined* form type. The two
+// call-site shapes under test:
+//   1. inline constraints — no ceremony at all; the hook's `const V` type
+//      parameter preserves each validator's Refinement marker
+//   2. pre-built constraints — `as const satisfies Validations<T>` outside
+//      the call
+
+describe('useFormState onSubmit narrowing — inline constraints', () => {
+  it('narrows a refined field and passes others through, with no call-site ceremony', () => {
+    useFormState({
+      initialValues: {
+        a: undefined as string | undefined,
+        b: 0,
+        c: null as string | null,
+      },
+      constraints: {
+        a: notEmpty('a'),
+        c: notEmpty('c'),
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          a: string;
+          b: number;
+          c: string;
+        }>();
+      },
+    });
+  });
+
+  it('bare inline validator functions narrow nothing', () => {
+    useFormState({
+      initialValues: { a: undefined as string | undefined },
+      constraints: {
+        a: (val) => (val ? null : 'required'),
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{ a: string | undefined }>();
+      },
+    });
+  });
+
+  it('without constraints, onSubmit receives the unrefined form type', () => {
+    useFormState({
+      initialValues: { a: undefined as string | undefined, b: 0 },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          a: string | undefined;
+          b: number;
+        }>();
+      },
+    });
+  });
+
+  it('rejects constraints for keys not in the form type', () => {
+    useFormState({
+      initialValues: { a: '' },
+      constraints: {
+        // @ts-expect-error 'nope' is not a field of the form
+        nope: notEmpty('nope'),
+      },
+    });
+  });
+
+  it('rejects a validator whose input is incompatible with the field', () => {
+    useFormState({
+      initialValues: { a: 0 },
+      constraints: {
+        // @ts-expect-error minLength validates strings, `a` is a number
+        a: minLength('a', 3),
+      },
+    });
+  });
+});
+
+describe('useFormState onSubmit narrowing — pre-built constraints', () => {
+  type FormType = {
+    email: string | undefined;
+    nickname: string | undefined;
+  };
+
+  it('preserves refinements from an `as const satisfies` constraints object', () => {
+    const constraints = {
+      email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+    } as const satisfies Validations<FormType>;
+
+    useFormState({
+      initialValues: { email: undefined, nickname: undefined } as FormType,
+      constraints,
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          email: string;
+          nickname: string | undefined;
+        }>();
+      },
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The recursion probe. Prior explorations of this design narrowed fine on
+// trivial examples but hit TS recursion limits on realistic form state. This
+// form type is deliberately chunky — ~30 leaf fields, 3 levels of object
+// nesting, lists of objects with nested objects inside. If the machinery
+// scales, this file typechecks; if it regresses, tsc fails here first.
+// ---------------------------------------------------------------------------
+
+type UsAddress = {
+  line1: string | undefined;
+  line2: string | undefined;
+  city: string | undefined;
+  state: string | undefined;
+  postalCode: string | undefined;
+};
+
+type InsuranceQuoteForm = {
+  firstName: string | undefined;
+  lastName: string | undefined;
+  email: string | undefined;
+  phone: string | undefined;
+  dateOfBirth: string | undefined;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress;
+  employer: string | null;
+  jobTitle: string | null;
+  yearsEmployed: number | null;
+  annualIncomeUsd: number | null;
+  coverageType: string | undefined;
+  deductibleUsd: number | undefined;
+  startDate: string | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    licenseNumber: string | undefined;
+    licenseState: string | undefined;
+    incidents: Array<{
+      date: string | undefined;
+      kind: string | undefined;
+      claimAmountUsd: number | null;
+    }>;
+  }>;
+  vehicles: Array<{
+    vin: string | undefined;
+    year: number | undefined;
+    make: string | undefined;
+    model: string | undefined;
+    primaryDriverName: string | undefined;
+    garagingAddress: UsAddress;
+  }>;
+  discountCodes: string[];
+  referralSource: string | null;
+  notes: string | undefined;
+};
+
+describe('useFormState narrowing at realistic scale', () => {
+  it('narrows constrained fields on a ~30-field, 3-level-deep form', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        firstName: notEmpty('firstName'),
+        lastName: notEmpty('lastName'),
+        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+        dateOfBirth: notEmpty('dateOfBirth'),
+        yearsEmployed: min('yearsEmployed', 0),
+        annualIncomeUsd: min('annualIncomeUsd', 0),
+        coverageType: notEmpty('coverageType'),
+        startDate: notEmpty('startDate'),
+        referralSource: notEmpty('referralSource'),
+        notes: minLength('notes', 10),
+      },
+      onSubmit: (values) => {
+        // Refined: notEmpty strips null/undefined/'' from the union.
+        expectTypeOf(values.firstName).toEqualTypeOf<string>();
+        expectTypeOf(values.email).toEqualTypeOf<string>();
+        expectTypeOf(values.referralSource).toEqualTypeOf<string>();
+        // Constrained but non-refining validators leave the type alone.
+        expectTypeOf(values.phone).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.annualIncomeUsd).toEqualTypeOf<number | null>();
+        expectTypeOf(values.notes).toEqualTypeOf<string | undefined>();
+        // Unconstrained fields — including all nested structure — untouched.
+        expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
+        expectTypeOf(values.drivers).toEqualTypeOf<
+          InsuranceQuoteForm['drivers']
+        >();
+        expectTypeOf(values.vehicles[0].garagingAddress).toEqualTypeOf<UsAddress>();
+      },
+    });
+  });
+
+  it('Path<T> still expands on the realistic form type', () => {
+    // Path is the most recursion-prone type in forms/ — its union grows with
+    // every key at every depth. Probe it with deep representative paths
+    // rather than equality on the (huge) full union.
+    type P = Path<InsuranceQuoteForm>;
+    expectTypeOf<['homeAddress', 'city']>().toMatchTypeOf<P>();
+    expectTypeOf<['drivers', number, 'incidents', number, 'claimAmountUsd']>().toMatchTypeOf<P>();
+    expectTypeOf<['vehicles', number, 'garagingAddress', 'postalCode']>().toMatchTypeOf<P>();
+
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['drivers', number, 'incidents', number, 'claimAmountUsd']>
+    >().toEqualTypeOf<number | null>();
+  });
+});

package/src/forms/useFormState/useFormState.test.tsx

@@ -0,0 +1,134 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormState } from './useFormState';
+import { allOf, matches, notEmpty } from '../validators/validators';
+
+type SignupForm = {
+  email: string | undefined;
+  nickname: string | undefined;
+};
+
+const initialValues: SignupForm = { email: undefined, nickname: undefined };
+
+describe('useFormState', () => {
+  test('exposes initial values', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.values).toEqual(initialValues);
+  });
+
+  test('onValueChanges accepts a replacement object', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: 'will' });
+    });
+    expect(result.current.values.email).toBe('a@b.co');
+  });
+
+  test('onValueChanges accepts an updater function', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, nickname: 'will' }));
+    });
+    expect(result.current.values).toEqual({ email: undefined, nickname: 'will' });
+  });
+
+  test('errors are derived live from the current values', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    expect(result.current.isValid).toBe(false);
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    expect(result.current.errors.email).toBeUndefined();
+    expect(result.current.isValid).toBe(true);
+  });
+
+  test('fields without constraints never produce errors', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.nickname).toBeUndefined();
+  });
+
+  test('a form without constraints is always valid', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.isValid).toBe(true);
+    expect(result.current.errors).toEqual({});
+  });
+
+  test('submit on an invalid form marks the attempt and skips onSubmit', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+    expect(result.current.submitAttempted).toBe(false);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  test('submit on a valid form calls onSubmit with the current values', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: {
+          email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: undefined });
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'a@b.co',
+      nickname: undefined,
+    });
+  });
+
+  test('a failed submit followed by a fix allows the next submit through', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+});

package/src/forms/useFormState/useFormState.ts

@@ -1,14 +1,50 @@
 import { useState } from 'react';
-import type { FormHelpers, FormValuesObject } from './types';
+import type { FormErrors, FormHelpers, FormValuesObject } from './types';
+import type { Refine, Validations } from '../validations/types';
 
-type Args<T extends FormValuesObject> = {
+// `const V` freezes the inferred type of an inline `constraints` object —
+// each validator's precise type and Refinement marker survive without any
+// `as const` at the call site. Constraint objects built outside the call
+// still need `as const satisfies Validations<T>` (see src/forms/CLAUDE.md).
+type Args<T extends FormValuesObject, V extends Validations<T>> = {
   initialValues: T;
+  constraints?: V;
+  onSubmit?: (values: Refine<T, V>) => void;
 };
 
-export const useFormState = <T extends FormValuesObject>(args: Args<T>): FormHelpers<T> => {
-  const { initialValues } = args;
+export const useFormState = <
+  T extends FormValuesObject,
+  const V extends Validations<T> = Validations<T>,
+>(
+  args: Args<T, V>,
+): FormHelpers<T> => {
+  const { initialValues, constraints, onSubmit } = args;
 
   const [values, onValueChanges] = useState<T>(initialValues);
+  const [submitAttempted, setSubmitAttempted] = useState(false);
 
-  return { values, onValueChanges };
+  const errors: FormErrors<T> = {};
+  if (constraints) {
+    for (const key of Object.keys(constraints) as (keyof T & string)[]) {
+      // Field type and validator input are correlated per key, but TS can't
+      // track that through the union of keys — widen the input to unknown.
+      const validator = constraints[key] as
+        | ((val: unknown) => string | null)
+        | undefined;
+      const error = validator?.(values[key]);
+      if (error != null) errors[key] = error;
+    }
+  }
+
+  const isValid = Object.keys(errors).length === 0;
+
+  const submit = () => {
+    setSubmitAttempted(true);
+    if (!isValid) return;
+    // Every constrained field's validator just passed at runtime — exactly
+    // the guarantee Refine<T, V> encodes.
+    onSubmit?.(values as Refine<T, V>);
+  };
+
+  return { values, onValueChanges, errors, isValid, submitAttempted, submit };
 };

package/src/forms/validations/perField.ts

@@ -0,0 +1,11 @@
+// Aggregation entry point for building a `Validations<T>`-shaped constraints
+// object. Runtime identity; the value is in the type: the `const` type
+// parameter freezes each validator's precise type (including `Refinement`
+// markers) instead of letting function types widen. Callers still apply
+// `as const satisfies Validations<FormType>` to shape-check against their
+// form type without losing that precision — see src/forms/CLAUDE.md.
+export const perField = <
+  const V extends Record<string, (val: never) => string | null>,
+>(
+  validations: V,
+): V => validations;

package/src/forms/validations/types.test-d.ts

@@ -1,5 +1,7 @@
 import { describe, it, expectTypeOf } from 'vitest';
-import type { Refinement, Validator } from './types';
+import { perField } from './perField';
+import { allOf, matches, minLength, notEmpty } from '../validators/validators';
+import type { Refine, Refinement, Validations, Validator } from './types';
 
 describe('Validator<Input, Excluded>', () => {
   it('preserves the input type as the call parameter', () => {
@@ -24,3 +26,74 @@ describe('Validator<Input, Excluded>', () => {
     expectTypeOf<Extracted>().toBeNever();
   });
 });
+
+type FormType = {
+  a: string | undefined;
+  b: number;
+  c: string | null;
+};
+
+describe('Refine<T, V>', () => {
+  it('narrows fields whose validator carries a refinement', () => {
+    const constraints = {
+      a: notEmpty('a'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string | null;
+    }>();
+  });
+
+  it('preserves precision through perField without as const', () => {
+    const constraints = perField({
+      a: notEmpty('a'),
+      c: notEmpty('c'),
+    }) satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string;
+    }>();
+  });
+
+  it('bare validator functions narrow nothing', () => {
+    const constraints = {
+      a: (val: string | undefined) => (val ? null : 'required'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('a constraints object widened by annotation refines nothing', () => {
+    // Annotating with `: Validations<FormType>` (instead of `satisfies`)
+    // widens every validator to a bare function — markers are lost. This is
+    // the failure mode the `as const satisfies` / const-generic patterns exist
+    // to prevent.
+    const constraints: Validations<FormType> = { a: notEmpty('a') };
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('allOf carries the union of its parts’ refinements', () => {
+    const constraints = {
+      a: allOf(notEmpty('a'), minLength('a', 3), matches('a', /^\S+$/, 'no spaces')),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('an empty constraints object leaves the form type unchanged', () => {
+    const constraints = {} as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+});

package/src/forms/validations/types.ts

@@ -1,3 +1,5 @@
+import type { FormValuesObject } from '../useFormState/types';
+
 // Phantom marker carried by validators. The runtime value of `__excludes`
 // is meaningless and never read — only its declared type matters. Required
 // (not optional) so validators can't accidentally drop the marker, and so
@@ -13,3 +15,24 @@ export type Refinement<Excluded = never> = {
 // validates at runtime; it just doesn't shrink the field's submit type).
 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<>`.
+export type Validations<T extends FormValuesObject> = {
+  readonly [K in keyof T]?: (val: T[K]) => string | null;
+};
+
+// 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
+// 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];
+};

package/src/forms/validators/validators.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from 'bun:test';
+import { allOf, matches, min, minLength, notEmpty } from './validators';
+
+describe('notEmpty', () => {
+  const validator = notEmpty('email');
+
+  test('rejects null, undefined, and the empty string', () => {
+    expect(validator(null)).toBe("'email' cannot be empty");
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('')).toBe("'email' cannot be empty");
+  });
+
+  test('passes any other value', () => {
+    expect(validator('a@b.co')).toBeNull();
+    expect(validator(0)).toBeNull();
+    expect(validator(' ')).toBeNull();
+  });
+});
+
+describe('minLength', () => {
+  const validator = minLength('nickname', 3);
+
+  test('rejects strings shorter than the minimum', () => {
+    expect(validator('ab')).toBe("'nickname' must be at least 3 characters");
+  });
+
+  test('passes strings at or above the minimum', () => {
+    expect(validator('abc')).toBeNull();
+    expect(validator('abcd')).toBeNull();
+  });
+
+  test('passes nullish and empty values — requiredness is notEmpty’s job', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('matches', () => {
+  const validator = matches('email', /@/, 'a valid email');
+
+  test('rejects values that fail the pattern', () => {
+    expect(validator('not-an-email')).toBe("'email' must be a valid email");
+  });
+
+  test('passes values matching the pattern', () => {
+    expect(validator('a@b.co')).toBeNull();
+  });
+
+  test('passes nullish and empty values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('min', () => {
+  const validator = min('age', 18);
+
+  test('rejects numbers below the minimum', () => {
+    expect(validator(17)).toBe("'age' must be at least 18");
+  });
+
+  test('passes numbers at or above the minimum', () => {
+    expect(validator(18)).toBeNull();
+    expect(validator(99)).toBeNull();
+  });
+
+  test('passes nullish values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+  });
+});
+
+describe('allOf', () => {
+  const validator = allOf(
+    notEmpty('email'),
+    minLength('email', 6),
+    matches('email', /@/, 'a valid email'),
+  );
+
+  test('returns the first failing part’s error', () => {
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('a@b')).toBe("'email' must be at least 6 characters");
+    expect(validator('abcdefg')).toBe("'email' must be a valid email");
+  });
+
+  test('passes when every part passes', () => {
+    expect(validator('a@b.com')).toBeNull();
+  });
+
+  test('accepts bare validator functions alongside marked ones', () => {
+    const noAdmin = (val: string | null | undefined) =>
+      val === 'admin' ? 'reserved' : null;
+    const composed = allOf(notEmpty('name'), noAdmin);
+    expect(composed('admin')).toBe('reserved');
+    expect(composed('will')).toBeNull();
+  });
+});