@dataset.sh/typelang/README.md

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

# 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

### CLI Usage

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

### Programmatic API

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

### Basic Types

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

### Generic Types

```typescript
// 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

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

### Nested Objects

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

### Metadata and Attributes

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

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

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

### Complete Example

```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<K,V>` | `Record<K,V>` | `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](https://github.com/dataset-sh)

## Contributing

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

## Related Projects

- [typelang-py](https://github.com/dataset-sh/typelang-py) - Python implementation of Typelang