Typelang

A TypeScript-flavored schema definition language for cross-platform type generation.

Features

- 🚀 TypeScript-like syntax - Familiar and easy to learn
- 🎯 Multiple targets - Generate TypeScript, Python (dataclass/Pydantic), and JSON Schema
- 🔧 CLI and API - Use as a command-line tool or programmatic library
- 📝 Rich metadata - Support for JSDoc comments and custom attributes
- 🔄 Generic types - Full support for generic type parameters
- ⚡ Fast and reliable - Built with TypeScript for performance and type safety

Installation

``bash
npm install @dataset.sh/typelang


or

pnpm add @dataset.sh/typelang

or

yarn add @dataset.sh/typelang
`

Quick Start

$3

`bash


Generate TypeScript types

npx typelang schema.tl -o types.ts

Generate Python Pydantic models

npx typelang schema.tl -t py-pydantic -o models.py

Generate JSON Schema

npx typelang schema.tl -t jsonschema -o schema.json

Output to stdout

npx typelang schema.tl -t ts
`

$3

`typescript
import { compile } from '@dataset.sh/typelang'

const source =
type User = {
id: string
name: string
email?: string
age: int
}

const result = compile(source, {
targets: ['typescript', 'python-pydantic']
})

console.log(result.typescript) // TypeScript output
console.log(result.pythonPydantic) // Python Pydantic output
`

Schema Language

$3

`typescript
type User = {
// Primitive types
id: string
age: int
score: float
active: bool

// Optional fields
email?: string
phone?: string

// Arrays
tags: string[]
scores: float[]

// Maps/Dictionaries
metadata: Dict
settings: Dict
}
`

$3

`typescript
// Generic type parameters
type Container = {
value: T
timestamp: string
}

type Result = {
success: bool
data?: T
error?: E
}

// Using generic types
type UserContainer = Container
`

$3

`typescript
// String literal unions (enums)
type Status = "draft" | "published" | "archived"

// Mixed unions
type StringOrNumber = string | int

// Complex unions
type Response =
| { success: true, data: User }
| { success: false, error: string }
`

$3

`typescript
type Address = {
street: string
city: string
country: string
}

type User = {
name: string
address: Address // Nested type reference

// Inline nested object
contact: {
email: string
phone?: string
}
}
`

$3

`typescript
/* User model for the application /
@table("users")
@index(["email", "username"])
type User = {
/* Unique identifier /
@primary
@generated("uuid")
id: string

/* User's email address /
@unique
@validate("email")
email: string

/* User's display name /
@minLength(3)
@maxLength(50)
name: string
}
`

CLI Options

`
Usage: npx typelang source.tl -o output-file -t [target]

Options:
-o, --output Output file path (optional, defaults to stdout)
-t, --target Target format (default: ts)
Available targets:
ts TypeScript
py-dataclass Python with dataclasses
py-pydantic Python with Pydantic
jsonschema JSON Schema
ir Intermediate Representation (JSON)
-h, --help Show help message
`

API Reference

$3

Compiles Typelang source code to multiple target formats.

`typescript
interface CompileOptions {
targets?: Array<'typescript' | 'python-dataclass' | 'python-pydantic' | 'jsonschema'>
}

interface CompileResult {
typescript?: string
pythonDataclass?: string
pythonPydantic?: string
jsonSchema?: string
ir?: any // Intermediate representation
errors: string[]
}
`

$3

`typescript
import { compile } from '@dataset.sh/typelang'
import { writeFileSync } from 'fs'

const schema =
/* Product in our catalog /
@table("products")
type Product = {
/* Unique product ID /
@primary
id: string

/* Product display name /
name: string

/* Price in cents /
price: int

/* Available stock /
stock: int

/* Product categories /
categories: string[]

/* Product status /
status: "draft" | "published" | "out-of-stock"
}

/* Customer order /
type Order = {
id: string
customerId: string
products: Product[]
total: float
status: "pending" | "paid" | "shipped" | "delivered"
createdAt: string
}

// Compile to all targets
const result = compile(schema, {
targets: ['typescript', 'python-pydantic', 'jsonschema']
})

// Check for errors
if (result.errors.length > 0) {
console.error('Compilation errors:', result.errors)
process.exit(1)
}

// Write outputs
writeFileSync('types.ts', result.typescript!)
writeFileSync('models.py', result.pythonPydantic!)
writeFileSync('schema.json', result.jsonSchema!)
`

Built-in Types

| Typelang | TypeScript | Python | JSON Schema |
|----------|------------|---------|-------------|
| string | string | str | "type": "string" |
| int | number | int | "type": "integer" |
| float | number | float | "type": "number" |
| bool | boolean | bool | "type": "boolean" |
| any | any | Any | {} |
| T[] | T[] | List[T] | "type": "array" |
| Dict | Record | Dict[K,V] | "type": "object" |
| T? | T \| undefined | Optional[T] | not required |

Development

`bash


Install dependencies

pnpm install

Build the project

pnpm build

Run tests

pnpm test

Run tests in watch mode

pnpm test:watch

Type check

pnpm typecheck
``

License

MIT © dataset.sh

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

- typelang-py - Python implementation of Typelang