zod-to-x

Imported from rroumenov/zod-to-x (AGENTS.md). Install upstream with npx skills add rroumenov/zod-to-x. Copyright stays with the author.

zod-to-x — Agent Instructions

Overview

npm package that transpiles Zod schema-based data models into typed code for multiple languages (TypeScript, Python/Pydantic, C++11/C++17, Dart/json_serializable) and data formats (Protobuf v3, JSON Schema). Uses a layered modeling architecture inspired by Clean Architecture (DDD).

Quick Reference

npm install              # Always first — Zod version depends on branch
npm run build            # Clean build: rm dist → tsc → tsc-alias
npm run build:debug      # Dev build with sourcemaps (tsconfig.dev.json)
npm test                 # Delete err-* files → vitest --run
npm run test:cpp         # Native C++ compilation tests
npm run test:py          # Native Python tests (needs venv activated)
npm run test:all         # C++ + Python native tests
npm run test:dart        # Native Dart tests (dart + build_runner required)
npm run test:go          # Native Go tests (Go toolchain required)
npm run format:check     # Prettier check

Critical rule: Always run npm run build before npm test. Tests import from dist/.

Architecture

3-Phase Pipeline

Zod Schema → Zod2Ast.build() → AST Nodes → Zod2X.transpile() → string output

1. Zod Schema — User defines data models with Zod + .zod2x("TypeName") metadata
2. AST — Zod2Ast.build() converts schemas into language-agnostic AST nodes
3. Transpile — Concrete Zod2X<T> subclass renders AST into target language code

Key directories

Transpiler Structure

Every transpiler has at minimum:

• options.ts — Language-specific options extending IZodToXOpt (base: header, indent, includeComments, useImports)
• runner.ts — Class extending Zod2X<T> implementing ~25 abstract methods

Optional: libs.ts — Import/include definitions (Python, C++ use this).

Abstract Methods to Implement (grouped)

Conventions

Naming

• Files: snake_case.ts
• Classes: PascalCase with prefixes (AST for AST types, Zod2 for transpilers)
• Properties: camelCase in code; output follows target language conventions
• Tests: kebab-expected/ folders, *.test.ts files

Zod Extensions

• .zod2x("TypeName") — assigns output type name to a schema. In layered modeling its optional
• .zod2x(zodEnum) — on ZodLiteral, links to parent enum (for discriminated unions)
• createGenericType("T") — creates a generic type placeholder using z.promise(z.literal("T")) marker
• useGenericType(obj, { slot: concreteType }) — instantiates a generic object

Metadata

Metadata lives in zodInstance._zod2x with fields: typeName, parentEnum, layer, aliasOf, parentLayer, genericTypes, isGenericChild.

ZodHelpers

Uses _def.typeName strings (not instanceof) for Bun compatibility.

Branches

• main / dev — Zod 4
• main_v1 / dev_v1 — Zod 3

Test Patterns

Individual Transpiler Tests

Each test/test_zod2<lang>/ contains:

• <lang>_supported_schemas.ts — all supported Zod types wrapped in a single object
• <lang>_supported_schemas.layered.ts — same types via layered modeling
• zod2<lang>.test.ts — vitest suite comparing output vs expected strings/files
• class-expected/ and/or struct-expected/ (or interface-expected/) — expected output files

Issue Tests

Each issue in test/test_issues/no_id/N/ contains:

• case_N.ts — schema definition reproducing the bug
• case_N.test-suite.ts — calls createGenericTestSuite(), exports runCaseNSuite
• struct-expected/ and class-expected/ — expected output files per language

The facade test_noid_issues.test.ts imports and calls all runCaseNSuite().

Cross-language coverage rule: Every issue test MUST include expected output files for ALL supported transpilers where the bug or its fix applies. Currently: TypeScript (.expected_typescript.ts), Python (.expected_python.py), C++ (.expected_cpp.h), Dart (.expected_dart.dart), Go (.expected_go.go). If a bug is in src/core/ (AST or base transpiler), it likely affects all languages. If a bug is in a specific transpiler, check whether other transpilers have the same problem.

Test Utilities

• testOutput(output, expected, errPath?) — trims, compares, writes err-* on failure
• createGenericTestSuite(name, model, transpiler, basePath) — generates struct + class test pair
• getSchemas() — factory returning fresh Zod schemas (avoids metadata pollution)

Skills & Prompts

See .github/skills/ for detailed guidance on:

• Adding a new transpiler
• Adding an issue test
• Debugging transpilation
• Understanding the AST system
• Layered modeling
• Test patterns

See .github/prompts/ for reusable task prompts.

Cross-Transpiler Impact Analysis

When investigating or fixing a bug:

1. Determine the scope: Is the fix in src/core/ (affects all languages) or src/transpilers/<lang>/ (language-specific)?
2. Core fixes propagate: A change in ast_node.ts, transpiler.ts, or zod_helpers.ts can affect TypeScript, Python, AND C++ output. Test all.
3. Transpiler-specific fixes may repeat: If a transpiler has a bug in transpileStruct() or _transpileMember(), check if the equivalent method in other transpilers has the same flaw. Patterns like checkExtendedTypeInclusion are implemented independently in each runner.
4. New language = backfill issue tests: When adding a new transpiler, review ALL existing issue test cases and add expected output files for the new language where the bug scenario applies.

Common Pitfalls

1. Forgetting to build — npm run build before npm test, always
2. Metadata pollution — Use getSchemas() factory in tests; never share schema instances
3. z.lazy() vs plain — z.discriminatedUnion and z.intersection need plain ZodObject, use useGenericType(obj, types, true) with skipLazy=true
4. Cross-layer references — The @Layer decorator clones schemas for cross-layer refs, setting aliasOf + parentLayer
5. Decorator singleton — Each decorated class is cached on constructor.instance; don't instantiate twice
6. err- files* — Generated on test failure, gitignored, cleaned by npm test
7. Single-language issue tests — Never test only one language. If a bug can manifest in multiple transpilers, cover all of them.

Dart Transpiler Notes

The Dart transpiler (src/transpilers/dart/) emits json_annotation + json_serializable code.

Key Dart-specific behaviors

• @JsonSerializable(genericArgumentFactories: true) is emitted for generic classes; their fromJson takes extra fromJsonT function parameters.
• @JsonKey(fromJson: fn, toJson: fn) is emitted for class-typed fields to prevent json_serializable from following typedef chains to transitively-imported types.
• instanceType string check (not instanceof) is used to detect ASTObject vs ASTEnum for cross-file references, because cross-file refs are ASTDefinition nodes.
• Cross-file generic typedefs (e.g. AdminUserEntity = GenericUserEntity<AdminUserMetadata>) are detected in the transpile() pre-scan: top-level nodes with parentFile + description (base type name) + non-empty templatesTranslation populate _typedefToExtendedType so runAfter() generates 2-arg factory helpers.
• Discriminated unions emit an abstract sealed class with a dispatcher function. Typedef aliases of disc unions delegate to the entity-level dispatcher via _discriminatedUnionDelegateFromJson.
• Dart test package lives at test/test_zod2dart/dart_test_pkg/. The test_dart.sh script copies files, runs dart run build_runner build, then dart analyze lib/.
• Regenerate expected files with npx vite-node test_dev/generate_dart_expected.ts after any runner change.