TypeScript type generation from document schema
npm install @palantir/pack.document-schema.type-genTypeScript type generation from document schema definitions. This package provides CLI tools and programmatic APIs for generating TypeScript types and Zod schemas from document schema definitions in both IR (Intermediate Representation) and YAML migration steps formats.
``
Usage: document-schema-type-gen [options] [command]
Document schema type generation CLI
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
ir IR (Intermediate Representation) based generation commands
schema Commands for working with TypeScript schema definitions
steps Commands dealing with migration steps and type generation
help [command] display help for command
`
#### Steps Commands
Generate types and schemas from YAML migration steps:
`bashGenerate TypeScript types from YAML migration steps
type-gen steps types -i
#### IR Commands
Generate schemas from Intermediate Representation format:
`bash
Generate Zod schemas from IR format
type-gen ir zod -s -r -o
`$3
#### Generating TypeScript Types from YAML
Given a directory with YAML migration step files:
`yaml
001-initial.yaml
- local-fragment:
position:
x: double
y: double- add-records:
Node:
docs: "A node in the graph"
extends: [position]
fields:
label: optional
edges: list
- add-union:
NodeType:
standard: Node
special: SpecialNode
`Run:
`bash
type-gen steps types -i ./schemas -o ./generated/types.ts
`This generates TypeScript interfaces for all defined records and unions.
#### Converting YAML to IR Format
`bash
type-gen steps ir \
-i ./schema.yaml \
-o ./schema-ir.json \
-n "MySchema" \
-d "Application document schema" \
-v "2.0"
`#### Generating Zod Schemas
From YAML:
`bash
type-gen steps zod -i ./schema.yaml -o ./generated/zod-schemas.ts
`From IR:
`bash
type-gen ir zod -s ./schema.json -r ./records.json -o ./generated/zod-schemas.ts
`Programmatic API
All CLI commands and their handlers are exported for composition in other tools and libraries.
$3
Register commands in your own CLI:
`typescript
import {
registerIrCommands,
registerStepsCommands,
} from "@palantir/pack.document-schema.type-gen";
import { Command } from "commander";const program = new Command();
// Register IR-based commands
registerIrCommands(program);
// Register steps-based commands
registerStepsCommands(program);
program.parse();
`$3
Use command handlers directly in your code:
`typescript
import {
convertSchemaToIr,
convertStepsToIr,
generateTypesFromSchema,
generateZodFromSchema,
generateZodSchemasFromIr,
} from "@palantir/pack.document-schema.type-gen";// Generate TypeScript types from a schema object
const schema = {/ your schema definition /};
const typesCode = generateTypesFromSchema(schema);
// Generate Zod schemas from migration steps
const zodCode = generateZodFromSchema(schema);
// Convert migration steps to IR format
const irSchema = convertStepsToIr(steps, metadata);
// Generate Zod from IR
const zodFromIr = await generateZodSchemasFromIr(irSchema);
`$3
The package exports several utility functions for schema processing:
`typescript
import {
convertRecordDefToIr,
convertSchemaToIr,
convertTypeToFieldTypeUnion,
generateZodFromStepsSchema,
type SchemaMetadata,
} from "@palantir/pack.document-schema.type-gen";// Convert PACK types to field type unions
const fieldType = convertTypeToFieldTypeUnion(type);
// Convert record definitions to IR format
const irRecord = convertRecordDefToIr(recordDef);
// Generate Zod schemas from steps with custom metadata
const metadata: SchemaMetadata = {
name: "MySchema",
description: "Custom schema",
version: "1.0.0",
};
const zodSchemas = generateZodFromStepsSchema(steps, metadata);
`$3
`typescript
import { cli } from "@palantir/pack.document-schema.type-gen";// Use the built-in CLI with custom arguments
cli(process.argv);
// Or build your own CLI using the exported handlers
import { stepsGenTypesHandler } from "@palantir/pack.document-schema.type-gen";
import { Command } from "commander";
const program = new Command();
program
.command("generate-types")
.requiredOption("-i, --input ", "Input folder")
.requiredOption("-o, --output ", "Output file")
.action(stepsGenTypesHandler);
program.parse();
`Supported Field Types
The type generator supports the following field types in YAML:
- Basic types:
string, double, boolean
- Collections: array, list, set
- Optional types: optional
- References to other defined records
- Nested structures via record extensionMigration Steps Format
The YAML migration steps support these operations:
-
local-fragment: Define reusable field groups
- add-records: Add new record types with fields
- add-union: Define discriminated unions
- modify-records`: Modify existing record definitions