devstack 0.1.0

package/vendor/skills/skills/zod/AGENTS.md

@@ -0,0 +1,97 @@
+# Zod
+
+**Version 1.0.0**  
+community  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring codebases. Humans may also find it useful,  
+> but guidance here is optimized for automation and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive schema validation guide for Zod in TypeScript applications, designed for AI agents and LLMs. Contains 43 rules across 8 categories, prioritized by impact from critical (schema definition, parsing) to incremental (performance, bundle optimization). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Schema Definition](references/_sections.md#1-schema-definition) — **CRITICAL**
+   - 1.1 [Apply String Validations at Schema Definition](references/schema-string-validations.md) — CRITICAL (Unvalidated strings allow SQL injection, XSS, and malformed data; validating at schema level catches issues at the boundary)
+   - 1.2 [Avoid Overusing Optional Fields](references/schema-avoid-optional-abuse.md) — CRITICAL (Excessive optional fields create schemas that accept almost anything; forces null checks throughout codebase)
+   - 1.3 [Use Coercion for Form and Query Data](references/schema-coercion-for-form-data.md) — CRITICAL (Form data and query params are always strings; without coercion, z.number() rejects "42" and z.boolean() rejects "true")
+   - 1.4 [Use Enums for Fixed String Values](references/schema-use-enums.md) — CRITICAL (Plain strings accept any value including typos; enums restrict to valid values and enable autocomplete)
+   - 1.5 [Use Primitive Schemas Correctly](references/schema-use-primitives-correctly.md) — CRITICAL (Incorrect primitive selection causes validation to pass on wrong types; using z.any() or z.unknown() loses all type safety)
+   - 1.6 [Use z.unknown() Instead of z.any()](references/schema-use-unknown-not-any.md) — CRITICAL (z.any() bypasses TypeScript's type system entirely; z.unknown() forces type narrowing before use)
+2. [Parsing & Validation](references/_sections.md#2-parsing-&-validation) — **CRITICAL**
+   - 2.1 [Avoid Double Validation](references/parse-avoid-double-validation.md) — HIGH (Parsing the same data twice wastes CPU cycles; in hot paths this adds measurable latency)
+   - 2.2 [Handle All Validation Issues Not Just First](references/parse-handle-all-issues.md) — CRITICAL (Showing only the first error forces users to fix-submit-fix repeatedly; collecting all errors improves UX dramatically)
+   - 2.3 [Never Trust JSON.parse Output](references/parse-never-trust-json.md) — CRITICAL (JSON.parse returns any type; unvalidated JSON allows type confusion attacks and runtime crashes)
+   - 2.4 [Use parseAsync for Async Refinements](references/parse-async-for-async-refinements.md) — CRITICAL (Using parse() with async refinements throws an error; async validation silently fails or crashes the application)
+   - 2.5 [Use safeParse() for User Input](references/parse-use-safeparse.md) — CRITICAL (parse() throws exceptions on invalid data; unhandled exceptions crash servers and expose stack traces to users)
+   - 2.6 [Validate at System Boundaries](references/parse-validate-early.md) — CRITICAL (Validating deep in business logic allows corrupt data to propagate; validating at boundaries catches issues before they spread)
+3. [Type Inference](references/_sections.md#3-type-inference) — **HIGH**
+   - 3.1 [Distinguish z.input from z.infer for Transforms](references/type-input-vs-output.md) — HIGH (Using wrong type with transforms causes TypeScript errors; z.input captures pre-transform shape, z.infer captures post-transform)
+   - 3.2 [Enable TypeScript Strict Mode](references/type-enable-strict-mode.md) — HIGH (Without strict mode, Zod's type inference is unreliable; undefined and null slip through, defeating the purpose of validation)
+   - 3.3 [Export Both Schemas and Inferred Types](references/type-export-schemas-and-types.md) — HIGH (Exporting only schemas forces consumers to derive types themselves; exporting both reduces boilerplate and improves DX)
+   - 3.4 [Use Branded Types for Domain Safety](references/type-branded-types.md) — HIGH (Plain string IDs are interchangeable, allowing userId where orderId is expected; branded types catch these bugs at compile time)
+   - 3.5 [Use z.infer Instead of Manual Types](references/type-use-z-infer.md) — HIGH (Manual type definitions drift from schemas over time; z.infer guarantees types match validation exactly)
+4. [Error Handling](references/_sections.md#4-error-handling) — **HIGH**
+   - 4.1 [Implement Internationalized Error Messages](references/error-i18n.md) — HIGH (Hardcoded English messages exclude non-English users; error maps enable localized messages for global applications)
+   - 4.2 [Provide Custom Error Messages](references/error-custom-messages.md) — HIGH (Default messages like "Expected string, received number" confuse users; custom messages like "Email is required" are actionable)
+   - 4.3 [Return False Instead of Throwing in Refine](references/error-avoid-throwing-in-refine.md) — HIGH (Throwing in refine stops validation early, hiding other errors; returning false allows Zod to collect all issues)
+   - 4.4 [Use flatten() for Form Error Display](references/error-use-flatten.md) — HIGH (Raw ZodError.issues requires manual path parsing; flatten() provides field-keyed errors ready for form display)
+   - 4.5 [Use issue.path for Nested Error Location](references/error-path-for-nested.md) — HIGH (Without path information, users can't identify which nested field failed; path provides exact location in complex objects)
+5. [Object Schemas](references/_sections.md#5-object-schemas) — **MEDIUM-HIGH**
+   - 5.1 [Choose strict() vs strip() for Unknown Keys](references/object-strict-vs-strip.md) — MEDIUM-HIGH (Default passthrough mode leaks unexpected data; strict() catches schema mismatches, strip() silently removes extras)
+   - 5.2 [Distinguish optional() from nullable()](references/object-optional-vs-nullable.md) — MEDIUM-HIGH (Confusing undefined and null semantics causes "property does not exist" vs "property is null" bugs; choose deliberately)
+   - 5.3 [Use Discriminated Unions for Type Narrowing](references/object-discriminated-unions.md) — MEDIUM-HIGH (Regular unions require manual type guards; discriminated unions enable TypeScript's automatic narrowing and Zod's optimized parsing)
+   - 5.4 [Use extend() for Adding Fields](references/object-extend-for-composition.md) — MEDIUM-HIGH (Merging objects manually loses type information; extend() preserves types and allows overriding fields safely)
+   - 5.5 [Use partial() for Update Schemas](references/object-partial-for-updates.md) — MEDIUM-HIGH (Creating separate update schemas duplicates definitions; partial() derives update schema from base, staying in sync)
+   - 5.6 [Use pick() and omit() for Schema Variants](references/object-pick-omit.md) — MEDIUM-HIGH (Copying fields between schemas creates duplication; pick/omit derive variants that stay in sync with base schema)
+6. [Schema Composition](references/_sections.md#6-schema-composition) — **MEDIUM**
+   - 6.1 [Extract Shared Schemas into Reusable Modules](references/compose-shared-schemas.md) — MEDIUM (Duplicating schemas across files leads to inconsistency; shared schemas ensure single source of truth)
+   - 6.2 [Use intersection() for Type Combinations](references/compose-intersection.md) — MEDIUM (Manual field combination loses type relationships; intersection creates proper TypeScript intersection types)
+   - 6.3 [Use pipe() for Multi-Stage Validation](references/compose-pipe.md) — MEDIUM (Chaining transforms loses intermediate type info; pipe() explicitly shows data flow through validation stages)
+   - 6.4 [Use preprocess() for Data Normalization](references/compose-preprocess.md) — MEDIUM (Validating before cleaning data causes false rejections; preprocess() normalizes input before schema validation runs)
+   - 6.5 [Use z.lazy() for Recursive Schemas](references/compose-lazy-recursive.md) — MEDIUM (Recursive types reference themselves before definition; z.lazy() defers evaluation to enable self-referential schemas)
+7. [Refinements & Transforms](references/_sections.md#7-refinements-&-transforms) — **MEDIUM**
+   - 7.1 [Add Path to Refinement Errors](references/refine-add-path.md) — MEDIUM (Errors without path show at object level; adding path highlights the specific field that failed)
+   - 7.2 [Choose refine() vs superRefine() Correctly](references/refine-vs-superrefine.md) — MEDIUM (refine() only reports one error; superRefine() enables multiple issues and custom error codes)
+   - 7.3 [Distinguish transform() from refine() and coerce()](references/refine-transform-coerce.md) — MEDIUM (Using wrong method causes validation to pass with wrong data; each method has distinct purpose)
+   - 7.4 [Use catch() for Fault-Tolerant Parsing](references/refine-catch.md) — MEDIUM (parse() fails on first invalid field; catch() provides fallback values, enabling partial success with degraded data)
+   - 7.5 [Use default() for Optional Fields with Defaults](references/refine-defaults.md) — MEDIUM (Manual default handling spreads logic across codebase; .default() centralizes defaults in schema)
+8. [Performance & Bundle](references/_sections.md#8-performance-&-bundle) — **LOW-MEDIUM**
+   - 8.1 [Avoid Dynamic Schema Creation in Hot Paths](references/perf-avoid-dynamic-creation.md) — LOW-MEDIUM (Zod 4's JIT compilation makes schema creation slower; creating schemas in loops adds ~0.15ms per creation)
+   - 8.2 [Cache Schema Instances](references/perf-cache-schemas.md) — LOW-MEDIUM (Creating schemas on every render/call wastes CPU; module-level or memoized schemas are created once)
+   - 8.3 [Lazy Load Large Schemas](references/perf-lazy-loading.md) — LOW-MEDIUM (Large schemas increase initial bundle and parse time; dynamic imports defer loading until needed)
+   - 8.4 [Optimize Large Array Validation](references/perf-arrays.md) — LOW-MEDIUM (Validating 10,000 items takes ~100ms; early exits, sampling, or batching reduce time for large datasets)
+   - 8.5 [Use Zod Mini for Bundle-Sensitive Applications](references/perf-zod-mini.md) — LOW-MEDIUM (Full Zod is ~17kb gzipped; Zod Mini is ~1.9kb - 85% smaller for frontend-critical bundles)
+
+---
+
+## References
+
+1. [https://zod.dev/](https://zod.dev/)
+2. [https://zod.dev/v4](https://zod.dev/v4)
+3. [https://github.com/colinhacks/zod](https://github.com/colinhacks/zod)
+4. [https://zod.dev/packages/mini](https://zod.dev/packages/mini)
+5. [https://www.totaltypescript.com/tutorials/zod](https://www.totaltypescript.com/tutorials/zod)
+6. [https://zod.dev/error-handling](https://zod.dev/error-handling)
+7. [https://zod.dev/api](https://zod.dev/api)
+
+---
+
+## Source Files
+
+This document was compiled from individual reference files. For detailed editing or extension:
+
+| File                                                            | Description                              |
+| --------------------------------------------------------------- | ---------------------------------------- |
+| [references/\_sections.md](references/_sections.md)             | Category definitions and impact ordering |
+| [assets/templates/\_template.md](assets/templates/_template.md) | Template for creating new rules          |
+| [SKILL.md](SKILL.md)                                            | Quick reference entry point              |
+| [metadata.json](metadata.json)                                  | Version and reference URLs               |

package/vendor/skills/skills/zod/README.md

@@ -0,0 +1,79 @@
+# Zod Best Practices Skill
+
+A comprehensive guide for using Zod effectively in TypeScript applications. This skill provides 42 rules across 8 categories, organized by impact to help AI agents and developers write better validation code.
+
+## Overview
+
+Zod is a TypeScript-first schema declaration and validation library. This skill covers best practices for:
+
+- **Schema Definition**: Choosing correct types, avoiding `z.any()`, proper string validations
+- **Parsing & Validation**: Using `safeParse()`, async validation, error handling
+- **Type Inference**: Leveraging `z.infer`, distinguishing input/output types
+- **Error Handling**: Custom messages, internationalization, form error display
+- **Object Schemas**: strict/strip modes, partial updates, discriminated unions
+- **Schema Composition**: Reusable schemas, intersections, recursive types
+- **Refinements & Transforms**: Custom validation, data transformation
+- **Performance**: Caching, Zod Mini, lazy loading, batch validation
+
+## Usage
+
+### For Claude Code / AI Agents
+
+The skill is automatically loaded when working with Zod code. Reference specific rules:
+
+```
+See rules/parse-use-safeparse.md for safeParse best practices
+```
+
+### For Developers
+
+Read `SKILL.md` for a quick reference, or `AGENTS.md` for the full compiled guide.
+
+## File Structure
+
+```
+zod/
+├── SKILL.md          # Quick reference with rule index
+├── AGENTS.md         # Full compiled guide (all rules)
+├── metadata.json     # Version, categories, references
+├── README.md         # This file
+└── rules/
+    ├── _sections.md  # Category definitions
+    ├── _template.md  # Rule template
+    ├── schema-*.md   # Schema definition rules
+    ├── parse-*.md    # Parsing rules
+    ├── type-*.md     # Type inference rules
+    ├── error-*.md    # Error handling rules
+    ├── object-*.md   # Object schema rules
+    ├── compose-*.md  # Composition rules
+    ├── refine-*.md   # Refinement rules
+    └── perf-*.md     # Performance rules
+```
+
+## Rule Categories
+
+| Priority | Category                 | Rules | Impact      |
+| -------- | ------------------------ | ----- | ----------- |
+| 1        | Schema Definition        | 6     | CRITICAL    |
+| 2        | Parsing & Validation     | 6     | CRITICAL    |
+| 3        | Type Inference           | 5     | HIGH        |
+| 4        | Error Handling           | 5     | HIGH        |
+| 5        | Object Schemas           | 6     | MEDIUM-HIGH |
+| 6        | Schema Composition       | 5     | MEDIUM      |
+| 7        | Refinements & Transforms | 5     | MEDIUM      |
+| 8        | Performance & Bundle     | 5     | LOW-MEDIUM  |
+
+## Key Principles
+
+1. **Type Safety First**: Always use `z.infer`, never duplicate types manually
+2. **Validate at Boundaries**: Parse external data immediately at entry points
+3. **User-Friendly Errors**: Provide custom messages, collect all issues
+4. **Single Source of Truth**: Schema defines validation AND TypeScript types
+5. **Composition Over Duplication**: Use extend, pick, omit, partial
+
+## References
+
+- [Zod Official Documentation](https://zod.dev/)
+- [Zod v4 Release Notes](https://zod.dev/v4)
+- [Zod GitHub](https://github.com/colinhacks/zod)
+- [Zod Mini](https://zod.dev/packages/mini)

package/vendor/skills/skills/zod/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: zod
+description: Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
+---
+
+# Zod Best Practices
+
+Comprehensive schema validation guide for Zod in TypeScript applications. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new Zod schemas
+- Choosing between parse() and safeParse()
+- Implementing type inference with z.infer
+- Handling validation errors for user feedback
+- Composing complex object schemas
+- Using refinements and transforms
+- Optimizing bundle size and validation performance
+- Reviewing Zod code for best practices
+
+## Rule Categories by Priority
+
+| Priority | Category                 | Impact      | Prefix     |
+| -------- | ------------------------ | ----------- | ---------- |
+| 1        | Schema Definition        | CRITICAL    | `schema-`  |
+| 2        | Parsing & Validation     | CRITICAL    | `parse-`   |
+| 3        | Type Inference           | HIGH        | `type-`    |
+| 4        | Error Handling           | HIGH        | `error-`   |
+| 5        | Object Schemas           | MEDIUM-HIGH | `object-`  |
+| 6        | Schema Composition       | MEDIUM      | `compose-` |
+| 7        | Refinements & Transforms | MEDIUM      | `refine-`  |
+| 8        | Performance & Bundle     | LOW-MEDIUM  | `perf-`    |
+
+## Quick Reference
+
+### 1. Schema Definition (CRITICAL)
+
+- `schema-use-primitives-correctly` - Use correct primitive schemas for each type
+- `schema-use-unknown-not-any` - Use z.unknown() instead of z.any() for type safety
+- `schema-avoid-optional-abuse` - Avoid overusing optional fields
+- `schema-string-validations` - Apply string validations at schema definition
+- `schema-use-enums` - Use enums for fixed string values
+- `schema-coercion-for-form-data` - Use coercion for form and query data
+
+### 2. Parsing & Validation (CRITICAL)
+
+- `parse-use-safeparse` - Use safeParse() for user input
+- `parse-async-for-async-refinements` - Use parseAsync for async refinements
+- `parse-handle-all-issues` - Handle all validation issues not just first
+- `parse-validate-early` - Validate at system boundaries
+- `parse-avoid-double-validation` - Avoid validating same data twice
+- `parse-never-trust-json` - Never trust JSON.parse output
+
+### 3. Type Inference (HIGH)
+
+- `type-use-z-infer` - Use z.infer instead of manual types
+- `type-input-vs-output` - Distinguish z.input from z.infer for transforms
+- `type-export-schemas-and-types` - Export both schemas and inferred types
+- `type-branded-types` - Use branded types for domain safety
+- `type-enable-strict-mode` - Enable TypeScript strict mode
+
+### 4. Error Handling (HIGH)
+
+- `error-custom-messages` - Provide custom error messages
+- `error-use-flatten` - Use flatten() for form error display
+- `error-path-for-nested` - Use issue.path for nested error location
+- `error-i18n` - Implement internationalized error messages
+- `error-avoid-throwing-in-refine` - Return false instead of throwing in refine
+
+### 5. Object Schemas (MEDIUM-HIGH)
+
+- `object-strict-vs-strip` - Choose strict() vs strip() for unknown keys
+- `object-partial-for-updates` - Use partial() for update schemas
+- `object-pick-omit` - Use pick() and omit() for schema variants
+- `object-extend-for-composition` - Use extend() for adding fields
+- `object-optional-vs-nullable` - Distinguish optional() from nullable()
+- `object-discriminated-unions` - Use discriminated unions for type narrowing
+
+### 6. Schema Composition (MEDIUM)
+
+- `compose-shared-schemas` - Extract shared schemas into reusable modules
+- `compose-intersection` - Use intersection() for type combinations
+- `compose-lazy-recursive` - Use z.lazy() for recursive schemas
+- `compose-preprocess` - Use preprocess() for data normalization
+- `compose-pipe` - Use pipe() for multi-stage validation
+
+### 7. Refinements & Transforms (MEDIUM)
+
+- `refine-vs-superrefine` - Choose refine() vs superRefine() correctly
+- `refine-transform-coerce` - Distinguish transform() from refine() and coerce()
+- `refine-add-path` - Add path to refinement errors
+- `refine-defaults` - Use default() for optional fields with defaults
+- `refine-catch` - Use catch() for fault-tolerant parsing
+
+### 8. Performance & Bundle (LOW-MEDIUM)
+
+- `perf-cache-schemas` - Cache schema instances
+- `perf-zod-mini` - Use Zod Mini for bundle-sensitive applications
+- `perf-avoid-dynamic-creation` - Avoid dynamic schema creation in hot paths
+- `perf-lazy-loading` - Lazy load large schemas
+- `perf-arrays` - Optimize large array validation
+
+## How to Use
+
+Read individual reference files for detailed explanations and code examples:
+
+- [Section definitions](references/_sections.md) - Category structure and impact levels
+- [Rule template](assets/templates/_template.md) - Template for adding new rules
+- Individual rules: `references/{prefix}-{slug}.md`
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## Related Skills
+
+- For React Hook Form integration, see `react-hook-form` skill
+- For API client generation, see `orval` skill
+
+## Sources
+
+- [Zod Official Documentation](https://zod.dev/)
+- [Zod v4 Release Notes](https://zod.dev/v4)
+- [Zod GitHub Repository](https://github.com/colinhacks/zod)
+- [Zod Mini](https://zod.dev/packages/mini)
+- [Total TypeScript Zod Tutorial](https://www.totaltypescript.com/tutorials/zod)

package/vendor/skills/skills/zod/references/compose-intersection.md

@@ -0,0 +1,143 @@
+---
+title: Use intersection() for Type Combinations
+impact: MEDIUM
+impactDescription: Manual field combination loses type relationships; intersection creates proper TypeScript intersection types
+tags: compose, intersection, and, combination
+---
+
+## Use intersection() for Type Combinations
+
+When you need an object that satisfies multiple schemas simultaneously (like combining a base type with mixins), use `.and()` or `z.intersection()`. This creates proper TypeScript intersection types and validates against all schemas.
+
+**Incorrect (manual combination):**
+
+```typescript
+import { z } from "zod";
+
+const timestampsSchema = z.object({
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+const softDeleteSchema = z.object({
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+});
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+// Manual combination - verbose and error-prone
+const fullUserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+});
+```
+
+**Correct (using intersection):**
+
+```typescript
+import { z } from "zod";
+
+const timestampsSchema = z.object({
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+const softDeleteSchema = z.object({
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+});
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+// Using .and() for intersection
+const fullUserSchema = userSchema.and(timestampsSchema).and(softDeleteSchema);
+
+// Or using z.intersection()
+const fullUserSchema2 = z.intersection(
+  z.intersection(userSchema, timestampsSchema),
+  softDeleteSchema
+);
+
+type FullUser = z.infer<typeof fullUserSchema>;
+// {
+//   id: string;
+//   name: string;
+//   email: string;
+//   createdAt: Date;
+//   updatedAt: Date;
+//   deletedAt: Date | null;
+//   deletedBy: string | null;
+// }
+```
+
+**Creating mixins:**
+
+```typescript
+// Reusable mixins
+const auditable = z.object({
+  createdBy: z.string(),
+  updatedBy: z.string(),
+});
+
+const versioned = z.object({
+  version: z.number().int().positive(),
+});
+
+const tagged = z.object({
+  tags: z.array(z.string()),
+});
+
+// Apply mixins to any schema
+function withAudit<T extends z.ZodRawShape>(schema: z.ZodObject<T>) {
+  return schema.and(auditable).and(timestampsSchema);
+}
+
+function withVersioning<T extends z.ZodRawShape>(schema: z.ZodObject<T>) {
+  return schema.and(versioned);
+}
+
+// Usage
+const documentSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  content: z.string(),
+});
+
+const fullDocumentSchema = withAudit(withVersioning(documentSchema));
+```
+
+**Intersection vs Merge:**
+
+```typescript
+// .merge() - replaces fields from first with second
+const a = z.object({ x: z.string(), y: z.number() });
+const b = z.object({ y: z.string() }); // y is string, not number
+
+a.merge(b); // { x: string, y: string } - b's y wins
+
+// .and() - requires fields to be compatible
+// If both have y with different types, intersection fails at runtime
+a.and(b); // Validation will fail - y can't be both number and string
+```
+
+**When NOT to use this pattern:**
+
+- When schemas have overlapping fields with different types (use merge)
+- When you need to override fields (use extend)
+- Simple cases where extend works fine
+
+Reference: [Zod API - intersection](https://zod.dev/api#intersection)

package/vendor/skills/skills/zod/references/compose-lazy-recursive.md

@@ -0,0 +1,138 @@
+---
+title: Use z.lazy() for Recursive Schemas
+impact: MEDIUM
+impactDescription: Recursive types reference themselves before definition; z.lazy() defers evaluation to enable self-referential schemas
+tags: compose, lazy, recursive, trees
+---
+
+## Use z.lazy() for Recursive Schemas
+
+TypeScript can't infer recursive Zod schema types automatically. Use `z.lazy()` to defer schema evaluation and manually provide the type annotation. This enables tree structures, nested comments, and other self-referential data.
+
+**Incorrect (direct self-reference):**
+
+```typescript
+import { z } from "zod";
+
+// This fails - categorySchema used before it's defined
+const categorySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  children: z.array(categorySchema), // Error: Block-scoped variable used before declaration
+});
+```
+
+**Correct (using z.lazy with type annotation):**
+
+```typescript
+import { z } from "zod";
+
+// Define the type manually
+interface Category {
+  id: string;
+  name: string;
+  children: Category[];
+}
+
+// Use z.lazy() to defer schema reference
+const categorySchema: z.ZodType<Category> = z.object({
+  id: z.string(),
+  name: z.string(),
+  children: z.lazy(() => z.array(categorySchema)),
+});
+
+// Now it works
+const tree = categorySchema.parse({
+  id: "1",
+  name: "Electronics",
+  children: [
+    {
+      id: "2",
+      name: "Phones",
+      children: [
+        { id: "3", name: "iPhones", children: [] },
+        { id: "4", name: "Android", children: [] },
+      ],
+    },
+  ],
+});
+```
+
+**Common recursive patterns:**
+
+```typescript
+// Comments with replies
+interface Comment {
+  id: string;
+  content: string;
+  author: string;
+  replies: Comment[];
+}
+
+const commentSchema: z.ZodType<Comment> = z.object({
+  id: z.string(),
+  content: z.string(),
+  author: z.string(),
+  replies: z.lazy(() => z.array(commentSchema)),
+});
+
+// Binary tree
+interface TreeNode {
+  value: number;
+  left: TreeNode | null;
+  right: TreeNode | null;
+}
+
+const treeNodeSchema: z.ZodType<TreeNode> = z.object({
+  value: z.number(),
+  left: z.lazy(() => treeNodeSchema.nullable()),
+  right: z.lazy(() => treeNodeSchema.nullable()),
+});
+
+// Nested menu structure
+interface MenuItem {
+  label: string;
+  href?: string;
+  children?: MenuItem[];
+}
+
+const menuItemSchema: z.ZodType<MenuItem> = z.object({
+  label: z.string(),
+  href: z.string().url().optional(),
+  children: z.lazy(() => z.array(menuItemSchema)).optional(),
+});
+```
+
+**JSON Schema (any valid JSON):**
+
+```typescript
+type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
+
+const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(jsonValueSchema),
+  ])
+);
+```
+
+**Performance consideration:**
+
+```typescript
+// z.lazy() has minimal overhead - the function is called once
+// and the schema is cached. Safe to use in hot paths.
+
+// If validating many recursive structures, the schema itself
+// is only built once. Validation performance depends on data depth.
+```
+
+**When NOT to use this pattern:**
+
+- Non-recursive schemas (lazy adds unnecessary indirection)
+- When you can flatten the structure instead
+
+Reference: [Zod API - Recursive Types](https://zod.dev/api#recursive-types)