🧠 TypeScript SQL Typing Library

🧪 This is a research project exploring the limits of compile-time type inference in TypeScript for SQL parsing, ORM generation, and ERD visualization. It is not yet production-ready.

This library provides a zero-runtime, fully type-safe SQL parser and ORM utility written entirely in TypeScript. It enables:

• ✅ Parse CREATE TABLE statements at compile time
• ✅ Infer a complete DatabaseSchema from SQL
• ✅ Perform raw SQL queries (sql<"SELECT ...">) with full type inference
• ✅ Use a lightweight in-memory ORM with autocompletion and validation
• ⚠️ MySQL adapter support (mysql2/promise) is partially implemented — insert/select supported, but schema sync and query builder incomplete
• ⚠️ Generate MermaidJS ER diagrams from schema types — currently unstable

---

✨ How It Works

• Type-Level SQL Parsing: CREATE TABLE strings are parsed into types using TypeScript's conditional and template literal types — no runtime involved.
• Smart Type Mapping: SQL column types like INT, TEXT, and BOOLEAN are mapped to TypeScript types (number, string, boolean).
• ORM Interface: A simple API (.insert(), .select().where(), .select().all()) is generated based on your schema — with autocompletion and compile-time validation.
• Multi-Adapter Support: Includes an in-memory adapter for testing and a partial MySQL adapter for real databases.
• Mermaid ER Diagrams: Compile-time schema types can be transformed into Mermaid-compatible entity-relationship diagrams — currently experimental.

---

📦 Usage

1. Define Tables

const usersSql = `CREATE TABLE users (
  id INT,
  name TEXT,
  email TEXT
)` as const;

const postsSql = `CREATE TABLE posts (
  id INT,
  title TEXT,
  published BOOLEAN,
  author_id INT REFERENCES users(id)
)` as const;

2. Generate Schema

type Tables = [TableDef<typeof usersSql>, TableDef<typeof postsSql>];
type DatabaseSchema = ToSchema<Tables>;

3. Use the ORM

await db.users.insert({ id: 1, name: 'Max', email: '[email protected]' });

const result = await db.users.select('id', 'name').where({ id: 1 });
const allResults = await db.users.select().all();

4. MySQL Integration

const adapter = createMySqlAdapter({
  host: 'localhost',
  user: 'root',
  password: 'root',
  database: 'test',
});
const db = createOrm<DatabaseSchema>(adapter);

5. Type-safe SELECT (Static)

const result = sql<'SELECT id, name FROM users'>();
// Type: { id: number; name: string }

6. Generate ER Diagram (Mermaid)

⚠️ Not fully functional yet!

type ERD = MermaidER<DatabaseSchema>;

Output example:

erDiagram
  users {
    INT id
    TEXT name
    TEXT email
  }
  posts {
    INT id
    TEXT title
    BOOLEAN published
    INT author_id
  }
  users ||--o{ posts : "author_id"

Loading

---

🧩 Future Ideas

• JOIN, UPDATE, DELETE parsing
• Type-safe query builders
• SQLite schema dump integration
• JSON schema export
• Editor integration (autocomplete + highlighting)

---

🧙 Inspiration

Inspired by Drizzle ORM, Kysely, and the power of TypeScript template type inference.

---

License

MIT, see MIT