synclangs 0.2.0
Write types once, use everywhere
Requires Python: >=3.10
Keywords: types, codegen, typescript, python, schema

# SyncLangs

> One centralized types file -> Multiple languages across all your codebases.

[![PyPI version](https://img.shields.io/pypi/v/synclangs.svg)](https://pypi.org/project/synclangs/)
[![Python versions](https://img.shields.io/pypi/pyversions/synclangs.svg)](https://pypi.org/project/synclangs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/HarjjotSinghh/synclangs/actions/workflows/test.yml/badge.svg)](https://github.com/HarjjotSinghh/synclangs/actions/workflows/test.yml)

SyncLangs is a developer tool that enables you to maintain a single source of truth for your type definitions. Define your structures once in a universal schema language (`.syln`) and automatically synchronize them as native, idiomatic types across Python, TypeScript, and multiple projects or packages simultaneously.

## Why SyncLangs?

Modern full-stack applications often use different languages for frontend (TypeScript) and backend (Python). This creates type duplication, drift risk, and maintenance burden.

**SyncLangs solves this by:**

- **No more type drift** - Define types once, generate native code for each language
- **Zero config start** - Works immediately with sensible defaults
- **Fast watch mode** - Regenerates in under 200ms on file save
- **Readable syntax** - Human-readable `.syln` files, no verbose boilerplate

## Quick Start

### Installation

```bash
pip install synclangs
# or
pipx install synclangs
```

### Initialize a Project

```bash
syln init
```

This creates:
- `syln.config.json` - Configuration file
- `shared/example.syln` - Example schema

### Define Your Types

Create `shared/user.syln`:

```
## Represents a user in the system
type User {
  ## Unique identifier
  id: string

  ## User's email address
  email: string

  ## Display name (optional)
  name: string?

  ## Account active status
  isActive: bool

  ## User tags
  tags: list<string>

  ## Arbitrary metadata
  metadata: map<string, any>
}
```

### Generate Code

```bash
syln generate
```

**TypeScript Output (`user.types.ts`):**

```typescript
// Auto-generated by SyncLangs - DO NOT EDIT

export interface User {
  /** Unique identifier */
  id: string;
  /** User's email address */
  email: string;
  /** Display name (optional) */
  name?: string;
  /** Account active status */
  isActive: boolean;
  /** User tags */
  tags: string[];
  /** Arbitrary metadata */
  metadata: Record<string, any>;
}
```

**Python Output (`user_types.py`):**

```python
# Auto-generated by SyncLangs - DO NOT EDIT

from dataclasses import dataclass
from typing import Any, Optional

@dataclass
class User:
    """Represents a user in the system"""
    id: str
    """Unique identifier"""
    email: str
    """User's email address"""
    is_active: bool
    """Account active status"""
    tags: list[str]
    """User tags"""
    metadata: dict[str, Any]
    """Arbitrary metadata"""
    name: Optional[str] = None
    """Display name (optional)"""
```

### Watch Mode

```bash
syln watch
```

Changes to `.syln` files automatically regenerate output in under 200ms.

## CLI Reference

| Command | Description |
|---------|-------------|
| `syln init` | Initialize a new project with config and example |
| `syln generate` | Generate code from .syln files |
| `syln check` | Validate schemas without generating |
| `syln watch` | Watch mode with auto-regeneration |
| `syln version` | Show version |

### Common Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--config` | `-c` | Config file path (default: `./syln.config.json`) |
| `--input` | `-i` | Input directory (default: `./shared`) |
| `--out-ts` | | TypeScript output directory |
| `--out-py` | | Python output directory |
| `--verbose` | `-v` | Verbose logging |
| `--dry-run` | | Show what would be generated |

## Syntax Reference

### Primitives

| SyncLangs | Python | TypeScript |
|-----------|--------|------------|
| `string` | `str` | `string` |
| `int` | `int` | `number` |
| `float` | `float` | `number` |
| `bool` | `bool` | `boolean` |
| `any` | `Any` | `any` |

### Generics

| SyncLangs | Python | TypeScript |
|-----------|--------|------------|
| `list<T>` | `list[T]` | `T[]` |
| `map<K, V>` | `dict[K, V]` | `Record<K, V>` |

### Nullable Types

```
type Example {
  required: string      # Required field
  optional: string?     # Optional field (nullable)
}
```

### Imports

```
import { User, Address } from "./user.syln"

type Order {
  user: User
  shippingAddress: Address
}
```

### Comments

```
# Regular comment (ignored in output)

## Doc comment (generates docstrings/JSDoc)
type User {
  ## The user's unique identifier
  id: string
}
```

## Configuration

Create `syln.config.json` in your project root:

```json
{
  "$schema": "https://synclangs.com/schema/v1.json",
  "version": "1.0",
  "input": "./shared",
  "outputs": {
    "typescript": {
      "enabled": true,
      "outDir": "./generated/ts",
      "fileExtension": ".types.ts"
    },
    "python": {
      "enabled": true,
      "outDir": "./generated/py",
      "fileExtension": "_types.py",
      "useDataclasses": true
    }
  },
  "options": {
    "watchDebounceMs": 100,
    "caseConversion": {
      "fields": {
        "python": "snake_case",
        "typescript": "camelCase"
      }
    },
    "generateIndex": true
  }
}
```

## Error Messages

SyncLangs provides helpful error messages with file locations and suggestions:

```
Error: SY002 - Invalid type reference
  --> shared/user.syln:15:12
   |
15 |   role: Roles
   |         ^^^^^ Type 'Roles' not found. Did you mean 'Role'?
   |
Help: Import 'Roles' or define it in this file.
```

## Documentation

- [Getting Started](https://docs.synclangs.com/getting-started)
- [Syntax Reference](https://docs.synclangs.com/syntax)
- [Configuration](https://docs.synclangs.com/configuration)
- [CLI Reference](https://docs.synclangs.com/cli)

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

## License

MIT - see [LICENSE](LICENSE)

---

Made with care by [Harjot Singh Rana](https://github.com/HarjjotSinghh)