docs: recursive types

Author: johannes-lindgren

packages/pure-parse/.vitepress/config.ts

@@ -90,6 +90,7 @@ export default defineConfig({
           },
           { text: 'Transformations', link: '/guide/transformations' },
           { text: 'Custom Parsers', link: '/guide/customizing' },
+          { text: 'Recursion', link: '/guide/recursion' },
           { text: 'Formatting', link: '/guide/formatting' },
           { text: 'JSON', link: '/guide/json' },
           { text: 'Performance', link: '/guide/performance' },

packages/pure-parse/docs/guide/recursion.md

@@ -0,0 +1,80 @@
+# Recursion
+
+To define a self-referential validation function, use the [lazy](../api/common/lazy.md) function. This is useful for validating recursive data structures like trees.
+
+For example:
+
+::: code-group
+
+```ts [Parser]
+import { lazy, type Parser, object, parseString, optional } from 'pure-parse'
+
+type Person = {
+  name: string
+  father?: Person
+  mother?: Person
+}
+
+const parsePerson: Parser<Person> = lazy(() =>
+  object({
+    name: parseString,
+    father: optional(parsePerson),
+    mother: optional(parsePerson),
+  }),
+)
+```
+
+```ts [Guard]
+import {
+  lazy,
+  type Guard,
+  objectGuard,
+  parseString,
+  optionalGuard,
+} from 'pure-parse'
+
+type Person = {
+  name: string
+  father?: Person
+  mother?: Person
+}
+
+const isPerson: Guard<Person> = lazy(() =>
+  objectGuard({
+    name: parseString,
+    father: optionalGuard(parsePerson),
+    mother: optionalGuard(parsePerson),
+  }),
+)
+```
+
+:::
+
+> [!NOTE]
+> You must use explicit type annotations for recursive types. Type inferrence is not available in this case.
+
+There are two tricks to note here:
+
+1. The `lazy` function ensures that the code works at runtime. Without `lazy`, `parsePerson` would not be defined on the `father` and `mother` properties, leading to a runtime error.
+   > TS2448: Block-scoped variable \* used before its declaration.
+   ```ts
+   const parsePerson: Parser<Person> = object({
+     name: parseString,
+     // TS2448: Block-scoped variable parsePerson used before its declaration.
+     father: optional(parsePerson),
+     // TS2448: Block-scoped variable parsePerson used before its declaration.
+     mother: optional(parsePerson),
+   })
+   ```
+2. The explicit type annotation is due to TypeScript's inability to infer cyclical types:
+   > TS7022: \* implicitly has type any because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
+   ```ts
+   // TS7022 parsePerson implicitly has type any because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
+   const parsePerson = lazy(() =>
+     object({
+       name: parseString,
+       father: optional(parsePerson),
+       mother: optional(parsePerson),
+     }),
+   )
+   ```

packages/pure-parse/src/common/lazy.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, test, vi } from 'vitest'
 import { lazy } from './lazy'
 import { Equals } from '../internals'
+import { object, optional, Parser, parseString, success } from '../parsers'
 
 describe('lazy', () => {
   it('only constructs the function once (memoization)', () => {
@@ -26,4 +27,132 @@ describe('lazy', () => {
     const fn3 = lazy(() => (base: number, exp: number) => base ** exp)
     const t3: Equals<typeof fn3, (base: number, exp: number) => number> = true
   })
+  it('supports direct recursive parsers', () => {
+    type Person = {
+      name: string
+      mother?: Person
+      father?: Person
+    }
+    const parsePerson: Parser<Person> = lazy(() =>
+      object({
+        name: parseString,
+        mother: optional(parsePerson),
+        father: optional(parsePerson),
+      }),
+    )
+
+    // Test that it works in runtime, even though it is the types that matter
+    const person1: Person = {
+      name: 'Johannes',
+    }
+    expect(parsePerson(person1)).toEqual(success(person1))
+
+    const person2: Person = {
+      name: 'Bob',
+      mother: {
+        name: 'Alice',
+      },
+      father: {
+        name: 'Evan',
+      },
+    }
+    expect(parsePerson(person2)).toEqual(success(person2))
+
+    const person3: Person = {
+      name: 'Charlie',
+      mother: {
+        name: 'Diana',
+        mother: {
+          name: 'Diana',
+        },
+        father: {
+          name: 'Evan',
+        },
+      },
+      father: {
+        name: 'Johan',
+        mother: {
+          name: 'Alice',
+        },
+        father: {
+          name: 'Frank',
+        },
+      },
+    }
+    expect(parsePerson(person3)).toEqual(success(person3))
+
+    // Failure cases
+    const person4 = {
+      name: 'A',
+      mother: {
+        name: 'B',
+        father: {}, // Missing required field 'name'
+      },
+    }
+    expect(parsePerson(person4)).toEqual(
+      expect.objectContaining({
+        tag: 'failure',
+      }),
+    )
+  })
+  it('supports indirect recursive parsers', () => {
+    type Family = {
+      mother: Person
+      father: Person
+    }
+    type Person = {
+      family?: Family
+    }
+    const parsePerson: Parser<Person> = lazy(() =>
+      object({
+        family: optional(parseFamily),
+      }),
+    )
+    const parseFamily: Parser<Family> = lazy(() =>
+      object({
+        mother: parsePerson,
+        father: parsePerson,
+      }),
+    )
+
+    // Test that it works in runtime, even though it is the types that matter
+    const person1: Person = {}
+    expect(parsePerson(person1)).toEqual(success(person1))
+
+    const person2: Person = {
+      family: {
+        mother: {},
+        father: {},
+      },
+    }
+    expect(parsePerson(person2)).toEqual(success(person2))
+
+    const person3: Person = {
+      family: {
+        mother: {
+          family: {
+            mother: {},
+            father: {},
+          },
+        },
+        father: {
+          family: {
+            mother: {},
+            father: {},
+          },
+        },
+      },
+    }
+    expect(parsePerson(person3)).toEqual(success(person3))
+
+    // Failure cases
+    const person4 = {
+      family: {},
+    }
+    expect(parsePerson(person4)).toEqual(
+      expect.objectContaining({
+        tag: 'failure',
+      }),
+    )
+  })
 })

packages/pure-parse/src/common/lazy.ts

@@ -1,3 +1,28 @@
+/**
+ * Creates a lazy-loaded function that initializes the function only when it is called for the first time.
+ * With `lazy`, you can create recursive parsers without running into circular dependencies.
+ * Also useful to lazily initialize just-in-time compuliled parsers and guards.
+ * @example
+ * Create recursive parsers with `lazy`.
+ * Note that you must use explicit type annotations:
+ * ```ts
+ * import { lazy, type Parser, object, parseString, optional } from 'pure-parse'
+ *
+ * type Person = {
+ *   name: string
+ *   father?: Person
+ *   mother?: Person
+ * }
+ * const parsePerson: Parser<Person> = lazy(() =>
+ *   object({
+ *     name: parseString,
+ *     father: optional(parsePerson),
+ *     mother: optional(parsePerson),
+ *   }),
+ * )
+ * ```
+ * @param constructFn
+ */
 export const lazy = <T extends (...args: never[]) => unknown>(
   constructFn: () => T,
 ): T => {