feat: add recursive and mutually recursive schemas

library/src/index.ts

@@ -19,6 +19,8 @@ export type {
   DefaultValue,
   ErrorMessage,
   FailureDataset,
+  GenericConstraintError,
+  Generics,
   GenericIssue,
   GenericMetadata,
   GenericSchema,

library/src/methods/flatten/flatten.test-d.ts

@@ -4,7 +4,11 @@ import type {
   NumberIssue,
   NumberSchema,
   ObjectSchema,
+  RecursiveSchema,
+  StringIssue,
+  StringSchema,
 } from '../../schemas/index.ts';
+import type { Ref } from '../../schemas/recursive/_recursive.ts';
 import type { ArrayPathItem, ObjectPathItem } from '../../types/index.ts';
 import { flatten } from './flatten.ts';
 
@@ -46,6 +50,43 @@ describe('flatten', () => {
       lang: undefined,
     },
   ];
+  const recursiveIssues: [StringIssue] = [
+    {
+      kind: 'schema',
+      type: 'string',
+      input: 123,
+      expected: 'string',
+      received: '123',
+      message: 'Invalid type: Expected string but received 123',
+      path: [
+        {
+          type: 'object',
+          origin: 'value',
+          input: { subcategories: [{ name: 123 }] },
+          key: 'subcategories',
+          value: [{ name: 123 }],
+        } satisfies ObjectPathItem,
+        {
+          type: 'array',
+          origin: 'value',
+          input: [{ name: 123 }],
+          key: 0,
+          value: { name: 123 },
+        } satisfies ArrayPathItem,
+        {
+          type: 'object',
+          origin: 'value',
+          input: { name: 123 },
+          key: 'name',
+          value: 123,
+        } satisfies ObjectPathItem,
+      ],
+      abortEarly: undefined,
+      abortPipeEarly: undefined,
+      issues: undefined,
+      lang: undefined,
+    },
+  ];
 
   test('should return generic flat errors', () => {
     expectTypeOf(flatten(issues)).toEqualTypeOf<{
@@ -81,6 +122,34 @@ describe('flatten', () => {
     }>();
   });
 
+  test('should return recursive flat errors', () => {
+    type Schema = RecursiveSchema<
+      ObjectSchema<
+        {
+          name: StringSchema<undefined>;
+          subcategories: ArraySchema<Ref, undefined>;
+        },
+        undefined
+      >
+    >;
+
+    expectTypeOf(flatten<Schema>(recursiveIssues)).toEqualTypeOf<{
+      readonly root?: [string, ...string[]];
+      readonly nested?: Readonly<
+        Partial<
+          Record<
+            | 'name'
+            | 'subcategories'
+            | `subcategories.${number}`
+            | `subcategories.${number}.${string}`,
+            [string, ...string[]]
+          >
+        >
+      >;
+      readonly other?: [string, ...string[]];
+    }>();
+  });
+
   test('should accept readonly list of errors', () => {
     const readonlyIssues = issues as Readonly<typeof issues>;
     expectTypeOf(flatten(readonlyIssues)).toEqualTypeOf<{

library/src/schemas/index.ts

@@ -30,6 +30,8 @@ export * from './objectWithRest/index.ts';
 export * from './optional/index.ts';
 export * from './picklist/index.ts';
 export * from './promise/index.ts';
+export * from './recursive/index.ts';
+export * from './mutualRecursive/index.ts';
 export * from './record/index.ts';
 export * from './set/index.ts';
 export * from './strictObject/index.ts';

library/src/schemas/mutualRecursive/_mutualRecursive.ts

@@ -0,0 +1,226 @@
+import type {
+  BaseIssue,
+  GenericSchema,
+  GenericSchemaAsync,
+  InferInput,
+  InferIssue,
+  InferOutput,
+} from '../../types/index.ts';
+import {
+  checkRecursiveReferences,
+  createRecursiveSchema,
+  createRef,
+  type RecursiveMarker,
+  type RecursiveOwner,
+  type RecursiveReferences,
+  type Ref,
+  type RefAsync,
+  type ResolveRecursiveInput,
+  type ResolveRecursiveIssue,
+  type ResolveRecursiveOutput,
+} from '../recursive/_recursive.ts';
+import type { MutualRecursiveSchema } from './mutualRecursive.ts';
+import type { MutualRecursiveSchemaAsync } from './mutualRecursiveAsync.ts';
+
+/**
+ * Factory for named synchronous recursive references.
+ */
+export type RefFactory = <const TName extends string = never>(
+  name: TName
+) => Ref<TName>;
+
+/**
+ * Factory for named async recursive references.
+ */
+export type RefFactoryAsync = <const TName extends string = never>(
+  name: TName
+) => RefAsync<TName>;
+
+/**
+ * Creates a factory for named synchronous recursive references.
+ *
+ * @param owner The owner of the references.
+ *
+ * @returns A named reference factory.
+ *
+ * @internal
+ */
+export function createRefFactory(
+  owner: RecursiveOwner & { readonly async: false }
+): RefFactory;
+
+/**
+ * Creates a factory for named async recursive references.
+ *
+ * @param owner The owner of the references.
+ *
+ * @returns A named async reference factory.
+ *
+ * @internal
+ */
+export function createRefFactory(
+  owner: RecursiveOwner & { readonly async: true }
+): RefFactoryAsync;
+export function createRefFactory(owner: RecursiveOwner) {
+  return <const TName extends string = never>(name: TName) =>
+    createRef(owner, name);
+}
+
+type SyncOrAsyncSchema = GenericSchema | GenericSchemaAsync;
+type Entries = Record<string, SyncOrAsyncSchema>;
+
+/**
+ * Mutual recursive construction options.
+ *
+ * @internal
+ */
+export type MutualConstruction = {
+  readonly reference: RecursiveOwner['reference'];
+} & (
+  | {
+      readonly type: 'mutualRecursive';
+      readonly async: false;
+      readonly build: (ref: RefFactory) => Record<string, GenericSchema>;
+    }
+  | {
+      readonly type: 'mutualRecursiveAsync';
+      readonly async: true;
+      readonly build: (ref: RefFactoryAsync) => Entries;
+    }
+);
+
+/**
+ * Creates the entries for a mutually recursive schema group.
+ *
+ * @param owner The recursive owner and construction options.
+ * @param setEntries The function that installs the entries.
+ *
+ * @returns A map of recursive schemas.
+ *
+ * @internal
+ */
+export function createMutualRecursive(
+  owner: MutualConstruction & RecursiveOwner,
+  setEntries: (entries: Entries) => void
+): Record<string, Entries[string]> {
+  // @ts-expect-error TS can't correlate the owner's sync/async build callback with its matching reference factory.
+  const entries = owner.build(createRefFactory(owner));
+  setEntries(entries);
+  const seen = new Set<object>();
+  const schemas: Record<PropertyKey, Entries[string]> = Object.create(null);
+  for (const key of Reflect.ownKeys(entries)) {
+    const entry = (entries as Record<PropertyKey, Entries[string]>)[key];
+    checkRecursiveReferences(entry, owner, seen);
+    schemas[key] = createRecursiveSchema<
+      Entries[string] & { readonly wrapped: Entries[string] }
+    >(entry, owner, owner.type, owner.reference);
+  }
+  return schemas;
+}
+
+type EntryInputs<TEntries extends Entries> = {
+  [TKey in keyof TEntries as `${TKey & (string | number)}`]: InferInput<
+    TEntries[TKey]
+  >;
+};
+type EntryOutputs<TEntries extends Entries> = {
+  [TKey in keyof TEntries as `${TKey & (string | number)}`]: InferOutput<
+    TEntries[TKey]
+  >;
+};
+
+type EntryIssues<TEntries extends Entries> = {
+  [TKey in keyof TEntries as `${TKey & (string | number)}`]: InferIssue<
+    TEntries[TKey]
+  >;
+};
+
+type ReferenceNames<TReference> =
+  TReference extends RecursiveMarker<infer TName> ? TName : never;
+
+type UnmatchedReferences<TEntries extends Entries> = Exclude<
+  ReferenceNames<
+    RecursiveReferences<EntryInputs<TEntries> | EntryOutputs<TEntries>>
+  >,
+  keyof EntryInputs<TEntries>
+>;
+
+interface Error<TReason extends string> {
+  readonly reason: TReason;
+  readonly impossible: never;
+}
+
+/**
+ * Rejects references to names absent from the entries.
+ *
+ * @internal
+ */
+export type CheckReferences<TEntries extends Entries> = [
+  UnmatchedReferences<TEntries>,
+] extends [never]
+  ? unknown
+  : Error<`Unmatched recursive reference: '${Extract<UnmatchedReferences<TEntries>, string>}'`>;
+
+/**
+ * Resolved mutual recursive schema interface.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- A named interface defers recursive type resolution.
+export interface ResolvedRecursiveSchema<
+  TWrapped extends GenericSchema,
+  TInputRoot,
+  TOutputRoot,
+  TIssue extends BaseIssue<unknown>,
+  TIssueRoot = TIssue,
+> extends MutualRecursiveSchema<
+    TWrapped,
+    ResolveRecursiveInput<InferInput<TWrapped>, TInputRoot>,
+    ResolveRecursiveOutput<InferOutput<TWrapped>, TOutputRoot>,
+    ResolveRecursiveIssue<TIssue, TIssueRoot>
+  > {}
+
+/**
+ * Resolved mutual recursive schema async interface.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- A named interface defers recursive type resolution.
+export interface ResolvedRecursiveSchemaAsync<
+  TWrapped extends Entries[string],
+  TInputRoot,
+  TOutputRoot,
+  TIssue extends BaseIssue<unknown>,
+  TIssueRoot = TIssue,
+> extends MutualRecursiveSchemaAsync<
+    TWrapped,
+    ResolveRecursiveInput<InferInput<TWrapped>, TInputRoot>,
+    ResolveRecursiveOutput<InferOutput<TWrapped>, TOutputRoot>,
+    ResolveRecursiveIssue<TIssue, TIssueRoot>
+  > {}
+
+/**
+ * Resolves each synchronous entry against the complete entries map.
+ *
+ * @internal
+ */
+export type RecursiveSchemas<TEntries extends Record<string, GenericSchema>> = {
+  [TName in keyof TEntries]: ResolvedRecursiveSchema<
+    TEntries[TName],
+    EntryInputs<TEntries>,
+    EntryOutputs<TEntries>,
+    InferIssue<TEntries[keyof TEntries]>,
+    EntryIssues<TEntries>
+  >;
+};
+
+/**
+ * Resolves each async entry against the complete entries map.
+ *
+ * @internal
+ */
+export type RecursiveSchemasAsync<TEntries extends Entries> = {
+  [TName in keyof TEntries]: ResolvedRecursiveSchemaAsync<
+    TEntries[TName],
+    EntryInputs<TEntries>,
+    EntryOutputs<TEntries>,
+    InferIssue<TEntries[keyof TEntries]>,
+    EntryIssues<TEntries>
+  >;
+};

library/src/schemas/mutualRecursive/index.ts

@@ -0,0 +1,14 @@
+export {
+  mutualRecursive,
+  type MutualRecursiveSchema,
+} from './mutualRecursive.ts';
+export type {
+  RefFactory,
+  RefFactoryAsync,
+  ResolvedRecursiveSchema as ResolvedMutualRecursiveSchema,
+  ResolvedRecursiveSchemaAsync as ResolvedMutualRecursiveSchemaAsync,
+} from './_mutualRecursive.ts';
+export {
+  mutualRecursiveAsync,
+  type MutualRecursiveSchemaAsync,
+} from './mutualRecursiveAsync.ts';