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

npm install @dataset.sh/typelang
# or
pnpm add @dataset.sh/typelang
# or
yarn add @dataset.sh/typelang

Quick Start

CLI Usage

# 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

Programmatic API

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

Basic Types

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<string, any>
  settings: Dict<string, bool>
}

Generic Types

// Generic type parameters
type Container<T> = {
  value: T
  timestamp: string
}

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

// Using generic types
type UserContainer = Container<User>

Union Types

// 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 }

Nested Objects

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
  }
}

Metadata and Attributes

/** 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

compile(source: string, options?: CompileOptions): CompileResult

Compiles Typelang source code to multiple target formats.

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[]
}

Complete Example

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<K,V> | Record<K,V> | Dict[K,V] | "type": "object" | | T? | T \| undefined | Optional[T] | not required |

Development

# 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