metal-orm 1.0.1 → 1.0.2

package/.github/workflows/publish-metal-orm.yml

@@ -0,0 +1,38 @@
+name: Publish metal-orm to npm
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  id-token: write    # OIDC for Trusted Publishing
+  packages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Test
+        run: npm test
+        continue-on-error: true  # ou remove se quiser quebrar se falhar
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish (Trusted Publishing)
+        run: npm publish --provenance --access public

package/README.md

@@ -8,152 +8,17 @@
 
 MetalORM keeps SQL generation deterministic (CTEs, aggregates, window functions, EXISTS/subqueries) while letting you introspect the AST or reuse builders inside larger queries. It's designed for developers who want the power of raw SQL with the convenience of a modern ORM.
 
-## Philosophy
+## Documentation
 
-MetalORM follows these core principles:
-
-- **Type Safety First**: Leverage TypeScript to catch errors at compile time
-- **SQL Transparency**: Generate predictable, readable SQL that you can inspect
-- **Composition Over Configuration**: Build complex queries by composing simple parts
-- **Zero Magic**: Explicit operations with clear AST representation
-- **Multi-Dialect Support**: Write once, compile to MySQL, SQLite, or SQL Server
+For detailed information and API reference, please visit our [full documentation](docs/index.md).
 
 ## Features
 
-### Declarative Schema Definition
-Define your database structure in TypeScript with full type inference:
-
-```typescript
-const users = defineTable(
-  'users',
-  {
-    id: col.int().primaryKey(),
-    name: col.varchar(255).notNull(),
-    email: col.varchar(255).unique(),
-    createdAt: col.timestamp().default('CURRENT_TIMESTAMP')
-  },
-  {
-    posts: hasMany(posts, 'userId'),
-    profile: hasOne(profiles, 'userId')
-  }
-);
-```
-
-### Rich Query Building
-```typescript
-// Simple queries
-const simpleQuery = new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .where(eq(users.columns.id, 1))
-  .limit(1);
-
-// Complex joins with relations
-const complexQuery = new SelectQueryBuilder(users)
-  .select({
-    userId: users.columns.id,
-    userName: users.columns.name,
-    postCount: count(posts.columns.id),
-  })
-  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
-  .where(and(
-    like(users.columns.name, '%John%'),
-    gt(posts.columns.createdAt, new Date('2023-01-01'))
-  ))
-  .groupBy(users.columns.id)
-  .having(gt(count(posts.columns.id), 5))
-  .orderBy(count(posts.columns.id), 'DESC');
-```
-
-### Advanced SQL Features
-```typescript
-// CTEs (Common Table Expressions)
-const since = new Date();
-since.setDate(since.getDate() - 30);
-
-const activeUsers = new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .where(gt(users.columns.lastLogin, since))
-  .as('active_users');
-
-const query = new SelectQueryBuilder(activeUsers)
-  .with(activeUsers)
-  .selectRaw('*')
-  .where(eq(activeUsers.columns.id, 1));
-
-// Window Functions
-const rankedPosts = new SelectQueryBuilder(posts)
-  .select({
-    id: posts.columns.id,
-    title: posts.columns.title,
-    rank: windowFunction('RANK', [], [posts.columns.userId], [
-      { column: posts.columns.createdAt, direction: 'DESC' }
-    ])
-  });
-
-// Subqueries and EXISTS
-const usersWithPosts = new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .where(exists(
-    new SelectQueryBuilder(posts)
-      .selectRaw('1')
-      .where(eq(posts.columns.userId, users.columns.id))
-  ));
-```
-
-### Relation Hydration
-Automatically transform flat database rows into nested JavaScript objects:
-
-```typescript
-const builder = new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .include('posts', {
-    columns: ['id', 'title', 'content'],
-    include: {
-      comments: {
-        columns: ['id', 'content', 'createdAt']
-      }
-    }
-  });
-
-const { sql, params } = builder.compile(new MySqlDialect());
-const rows = await db.execute(sql, params);
-
-// Automatically hydrates to:
-// {
-//   id: 1,
-//   name: 'John',
-//   posts: [
-//     {
-//       id: 1,
-//       title: 'First Post',
-//       comments: [...]
-//     }
-//   ]
-// }
-const hydrated = hydrateRows(rows, builder.getHydrationPlan());
-```
-
-### Multi-Dialect Support
-Compile the same query to different SQL dialects:
-
-```typescript
-const query = new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .where(eq(users.columns.id, 1))
-  .limit(10);
-
-// MySQL
-const mysql = query.compile(new MySqlDialect());
-// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
-
-// SQLite
-const sqlite = query.compile(new SQLiteDialect());
-// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
-
-// SQL Server
-const mssql = query.compile(new MSSQLDialect());
-// SQL: SELECT TOP 10 * FROM users WHERE id = @p1
-```
+- **Declarative Schema Definition**: Define your database structure in TypeScript with full type inference.
+- **Rich Query Building**: A fluent API to build simple and complex queries.
+- **Advanced SQL Features**: Support for CTEs, window functions, subqueries, and more.
+- **Relation Hydration**: Automatically transform flat database rows into nested JavaScript objects.
+- **Multi-Dialect Support**: Compile the same query to different SQL dialects.
 
 ## Installation
 
@@ -168,382 +33,61 @@ yarn add metal-orm
 pnpm add metal-orm
 ```
 
-## Quick Start
+## Database Drivers
+
+MetalORM compiles SQL; it does not bundle a database driver. Install one that matches your database, compile your query with the matching dialect, and hand the SQL + parameters to the driver.
+
+| Dialect | Driver | Install |
+| --- | --- | --- |
+| MySQL / MariaDB | `mysql2` | `npm install mysql2` |
+| SQLite | `sqlite3` | `npm install sqlite3` |
+| SQL Server | `tedious` | `npm install tedious` |
 
-Here's a complete example to get you started:
+After installing the driver, pick the matching dialect implementation before compiling the query (`MySqlDialect`, `SQLiteDialect`, `MSSQLDialect`), and execute the resulting SQL string with the driver of your choice.
+
+## Quick Start
 
 ```typescript
+import mysql from 'mysql2/promise';
 import {
   defineTable,
   col,
-  hasMany,
   SelectQueryBuilder,
   eq,
-  count,
   hydrateRows,
-  MySqlDialect
+  MySqlDialect,
 } from 'metal-orm';
 
-// 1. Define your schema
-const posts = defineTable(
-  'posts',
-  {
-    id: col.int().primaryKey(),
-    title: col.varchar(255).notNull(),
-    content: col.text(),
-    userId: col.int().notNull(),
-    createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
-    updatedAt: col.timestamp()
-  }
-);
+const users = defineTable('users', {
+  id: col.int().primaryKey(),
+  name: col.varchar(255).notNull(),
+});
 
-const users = defineTable(
-  'users',
-  {
-    id: col.int().primaryKey(),
-    name: col.varchar(255).notNull(),
-    email: col.varchar(255).unique(),
-    createdAt: col.timestamp().default('CURRENT_TIMESTAMP')
-  },
-  {
-    posts: hasMany(posts, 'userId')
-  }
-);
+const connection = await mysql.createConnection({
+  host: 'localhost',
+  user: 'root',
+  database: 'test',
+});
 
-// 2. Build your query
 const builder = new SelectQueryBuilder(users)
   .select({
     id: users.columns.id,
     name: users.columns.name,
-    email: users.columns.email,
-    totalPosts: count(posts.columns.id)
   })
-  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
-  .groupBy(users.columns.id, users.columns.name, users.columns.email)
-  .orderBy(count(posts.columns.id), 'DESC')
-  .limit(20)
-  .include('posts', {
-    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt]
-  });
+  .where(eq(users.columns.id, 1));
 
-// 3. Compile to SQL
 const dialect = new MySqlDialect();
 const { sql, params } = builder.compile(dialect);
-
-// 4. Execute and hydrate
-const rows = await connection.execute(sql, params);
-const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+const [rows] = await connection.execute(sql, params);
+const hydrated = hydrateRows(rows as Record<string, unknown>[], builder.getHydrationPlan());
 
 console.log(hydrated);
-// [
-//   {
-//     id: 1,
-//     name: 'John Doe',
-//     email: 'john@example.com',
-//     totalPosts: 15,
-//     posts: [
-//       {
-//         id: 101,
-//         title: 'Latest Post',
-//         createdAt: '2023-05-15T10:00:00.000Z'
-//       },
-//       // ... more posts
-//     ]
-//   }
-//   // ... more users
-// ]
-```
-
-## Advanced Expression Helpers
-
-### JSON filters and comparisons
-```typescript
-const userData = defineTable('user_data', {
-  id: col.int().primaryKey(),
-  userId: col.int().notNull(),
-  preferences: col.json().notNull()
-});
-
-const jsonQuery = new SelectQueryBuilder(userData)
-  .select({
-    id: userData.columns.id,
-    userId: userData.columns.userId,
-    theme: jsonPath(userData.columns.preferences, '$.theme')
-  })
-  .where(and(
-    eq(jsonPath(userData.columns.preferences, '$.theme'), 'dark'),
-    inList(userData.columns.userId, [1, 2, 3])
-  ));
-```
-
-### CASE expressions and window helpers
-```typescript
-const tieredUsers = new SelectQueryBuilder(users)
-  .select({
-    id: users.columns.id,
-    tier: caseWhen([
-      { when: gt(count(posts.columns.id), 10), then: 'power user' }
-    ], 'regular')
-  })
-  .groupBy(users.columns.id);
-
-const rankedPosts = new SelectQueryBuilder(posts)
-  .select({
-    id: posts.columns.id,
-    createdAt: posts.columns.createdAt,
-    rank: windowFunction('RANK', [], [posts.columns.userId], [
-      { column: posts.columns.createdAt, direction: 'DESC' }
-    ])
-  });
-```
-
-## Performance Considerations
-
-### Query Optimization
-- **Use `.select()` explicitly** instead of `select('*')` to only fetch needed columns
-- **Leverage CTEs** for complex queries to improve readability and sometimes performance
-- **Use indexes** on frequently queried columns and join conditions
-- **Reuse compiled hydration plans** when transforming rows to avoid repeating row reconstruction
-
-### Caching Strategies
-```typescript
-// Implement query result caching
-const cache = new Map<string, any>();
-
-async function getUserWithPosts(userId: number) {
-  const cacheKey = `user:${userId}:with-posts`;
-
-  if (cache.has(cacheKey)) {
-    return cache.get(cacheKey);
-  }
-
-  const builder = new SelectQueryBuilder(users)
-    .selectRaw('*')
-    .where(eq(users.columns.id, userId))
-    .include('posts');
-
-  const { sql, params } = builder.compile(dialect);
-  const rows = await db.execute(sql, params);
-  const result = hydrateRows(rows, builder.getHydrationPlan());
-
-  cache.set(cacheKey, result);
-  return result;
-}
 ```
 
-## Comparison with Other ORMs
-
-| Feature                | MetalORM               | TypeORM          | Prisma            | Knex            |
-|------------------------|------------------------|------------------|-------------------|------------------|
-| Type Safety            | ✅ Full TypeScript     | ✅ Good           | ✅ Excellent       | ❌ Limited         |
-| SQL Generation         | ✅ Deterministic       | ❌ ORM-style      | ✅ Good            | ✅ Good           |
-| AST Inspection         | ✅ Full access         | ❌ No             | ❌ No              | ❌ No             |
-| Multi-Dialect          | ✅ MySQL/SQLite/MSSQL | ✅ Many           | ✅ Many            | ✅ Many           |
-| Relation Hydration     | ✅ Automatic           | ✅ Manual         | ✅ Automatic       | ❌ Manual          |
-| Query Builder          | ✅ Rich                | ✅ Good           | ❌ Limited         | ✅ Good           |
-| Learning Curve         | ⚠️ Moderate           | ⚠️ Moderate      | ✅ Low            | ⚠️ Moderate      |
-| Bundle Size            | ✅ Small               | ⚠️ Medium         | ⚠️ Medium         | ✅ Small           |
-
-## Migration Guide
-
-### From Knex
-```typescript
-// Before (Knex)
-const users = await knex('users')
-  .select('users.*', knex.raw('COUNT(posts.id) as post_count'))
-  .leftJoin('posts', 'users.id', 'posts.user_id')
-  .groupBy('users.id')
-  .orderBy('post_count', 'desc');
-
-// After (MetalORM)
-const users = defineTable('users', { /* ... */ });
-const posts = defineTable('posts', { /* ... */ });
-
-const result = await new SelectQueryBuilder(users)
-  .select({
-    ...allUserColumns,
-    postCount: count(posts.columns.id)
-  })
-  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
-  .groupBy(users.columns.id)
-  .orderBy(count(posts.columns.id), 'DESC')
-  .compile(dialect);
-```
-
-### From TypeORM
-```typescript
-// Before (TypeORM)
-const users = await userRepository
-  .createQueryBuilder('user')
-  .leftJoinAndSelect('user.posts', 'post')
-  .where('user.name LIKE :name', { name: '%John%' })
-  .orderBy('user.createdAt', 'DESC')
-  .getMany();
-
-// After (MetalORM)
-const result = await new SelectQueryBuilder(users)
-  .selectRaw('*')
-  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
-  .where(like(users.columns.name, '%John%'))
-  .orderBy(users.columns.createdAt, 'DESC')
-  .include('posts')
-  .compile(dialect);
-```
-
-## Project Structure
-
-```
-metal-orm/
-├── src/
-│   ├── schema/          # Table/column/relation definitions
-│   ├── builder/         # Query builder and managers
-│   ├── ast/             # AST nodes and expression builders
-│   ├── dialect/         # SQL dialect implementations
-│   ├── runtime/         # Hydration and utility functions
-│   ├── codegen/         # Code generation helpers
-│   └── playground/      # Interactive playground
-├── tests/               # Test suites
-├── dist/                # Compiled output
-└── playground/          # Vite-based playground app
-```
-
-## API Documentation
-
-### Core Classes
-- `SelectQueryBuilder` - Main query builder class
-- `MySqlDialect` / `SQLiteDialect` / `MSSQLDialect` - SQL dialect compilers
-- `HydrationManager` - Handles relation hydration logic
-
-### Key Functions
-- `defineTable()` - Define database tables
-- `col.*()` - Column type definitions
-- `hasMany()` / `belongsTo()` - Relation definitions
-- `eq()`, `and()`, `or()`, etc. - Expression builders
-- `hydrateRows()` - Transform flat rows to nested objects
-
-### Utility Functions
-- `count()`, `sum()`, `avg()` - Aggregate functions
-- `like()`, `between()`, `inList()`, `notInList()` - Comparison operators
-- `jsonPath()` - JSON extraction
-- `caseWhen()`, `exists()`, `notExists()` - Conditional and subquery helpers
-- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `windowFunction()` - Window function helpers
-
-## Project Commands
-
-```bash
-# Build the project
-npm run build
-
-# Type checking
-npm run check
-
-# Run tests
-npm run test
-
-# Interactive test UI
-npm run test:ui
-
-# Launch playground
-npm run playground
-
-# Clean build
-npm run clean
-```
-
-## Development Setup
-
-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/celsowm/metal-orm.git
-   cd metal-orm
-   ```
-
-2. **Install dependencies:**
-   ```bash
-   npm install
-   ```
-
-3. **Run the playground:**
-   ```bash
-   npm run playground
-   ```
-   This launches a Vite-based UI where you can experiment with queries.
-
-4. **Run tests:**
-   ```bash
-   npm test
-   ```
-
 ## Contributing
 
-We welcome contributions! Here's how you can help:
-
-### Getting Started
-1. Fork the repository
-2. Clone your fork and install dependencies
-3. Run `npm run playground` to see MetalORM in action
-
-### Development Workflow
-1. **Write tests first** - Add test cases in the `tests/` directory
-2. **Implement features** - Follow existing code patterns
-3. **Update documentation** - Keep docs in sync with changes
-4. **Run all checks** - Ensure tests pass and formatting is correct
-
-### Code Guidelines
-- Follow existing TypeScript patterns and conventions
-- Keep functions small and focused
-- Add JSDoc comments for public APIs
-- Write comprehensive tests for new features
-- Maintain 100% type coverage
-
-### Pull Request Process
-1. Create a feature branch from `main`
-2. Implement your changes with tests
-3. Update documentation as needed
-4. Ensure all tests pass (`npm test`)
-5. Submit PR with clear description of changes
-
-### Documentation Standards
-- Update `ROADMAP.md` for major feature plans
-- Add `SOLID_*.md` files for architectural decisions
-- Keep API documentation in sync with code changes
-- Add examples for new features
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
 
 ## License
 
-MetalORM is [MIT licensed](https://github.com/celsowm/metal-orm/blob/main/LICENSE).
-
-## Support
-
-- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/celsowm/metal-orm/issues)
-- **Discussions**: Join the conversation on [GitHub Discussions](https://github.com/celsowm/metal-orm/discussions)
-- **Contributing**: See the [Contributing](#contributing) section above
-
-## Roadmap
-
-Check out our [ROADMAP.md](ROADMAP.md) for upcoming features and long-term vision.
-
-## Examples
-
-See the [playground scenarios](playground/src/data/scenarios/) for comprehensive examples covering:
-- Basic CRUD operations
-- Complex joins and relations
-- Aggregations and window functions
-- CTEs and subqueries
-- JSON operations
-- And much more!
-
-## Who's Using MetalORM?
-
-MetalORM is used in production by various projects. If you're using MetalORM, consider adding your project to this list!
-
-## Acknowledgements
-
-Special thanks to all contributors and the open-source community for their support and feedback.
-
----
-
-**Star this repo if you find it useful!** ⭐
-
-[GitHub Repository](https://github.com/celsowm/metal-orm) |
-[npm package](https://www.npmjs.com/package/metal-orm)
+MetalORM is [MIT licensed](LICENSE).

package/docs/advanced-features.md

@@ -0,0 +1,85 @@
+# Advanced Features
+
+MetalORM supports a wide range of advanced SQL features to handle complex scenarios.
+
+## Common Table Expressions (CTEs)
+
+CTEs help organize complex queries. You can define a CTE using a `SelectQueryBuilder` and reference it in the main query.
+
+```typescript
+const since = new Date();
+since.setDate(since.getDate() - 30);
+
+const activeUsers = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(gt(users.columns.lastLogin, since))
+  .as('active_users');
+
+const query = new SelectQueryBuilder(activeUsers)
+  .with(activeUsers)
+  .selectRaw('*')
+  .where(eq(activeUsers.columns.id, 1));
+```
+
+## Window Functions
+
+MetalORM provides helpers for window functions like `RANK()`, `ROW_NUMBER()`, etc.
+
+```typescript
+const rankedPosts = new SelectQueryBuilder(posts)
+  .select({
+    id: posts.columns.id,
+    title: posts.columns.title,
+    rank: windowFunction('RANK', [], [posts.columns.userId], [
+      { column: posts.columns.createdAt, direction: 'DESC' }
+    ])
+  });
+```
+
+## Subqueries and EXISTS
+
+You can use subqueries and `EXISTS` to perform complex checks.
+
+```typescript
+const usersWithPosts = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(exists(
+    new SelectQueryBuilder(posts)
+      .selectRaw('1')
+      .where(eq(posts.columns.userId, users.columns.id))
+  ));
+```
+
+## JSON Operations
+
+MetalORM provides helpers for working with JSON data.
+
+```typescript
+const userData = defineTable('user_data', {
+  id: col.int().primaryKey(),
+  userId: col.int().notNull(),
+  preferences: col.json().notNull()
+});
+
+const jsonQuery = new SelectQueryBuilder(userData)
+  .select({
+    id: userData.columns.id,
+    theme: jsonPath(userData.columns.preferences, '$.theme')
+  })
+  .where(eq(jsonPath(userData.columns.preferences, '$.theme'), 'dark'));
+```
+
+## CASE Expressions
+
+You can use `caseWhen()` to create `CASE` expressions for conditional logic.
+
+```typescript
+const tieredUsers = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    tier: caseWhen([
+      { when: gt(count(posts.columns.id), 10), then: 'power user' }
+    ], 'regular')
+  })
+  .groupBy(users.columns.id);
+```

package/docs/api-reference.md

@@ -0,0 +1,22 @@
+# API Reference
+
+This section provides a reference for the core classes, key functions, and utility functions in MetalORM.
+
+### Core Classes
+- `SelectQueryBuilder` - Main query builder class
+- `MySqlDialect` / `SQLiteDialect` / `MSSQLDialect` - SQL dialect compilers
+- `HydrationManager` - Handles relation hydration logic
+
+### Key Functions
+- `defineTable()` - Define database tables
+- `col.*()` - Column type definitions
+- `hasMany()` / `belongsTo()` - Relation definitions
+- `eq()`, `and()`, `or()`, etc. - Expression builders
+- `hydrateRows()` - Transform flat rows to nested objects
+
+### Utility Functions
+- `count()`, `sum()`, `avg()` - Aggregate functions
+- `like()`, `between()`, `inList()`, `notInList()` - Comparison operators
+- `jsonPath()` - JSON extraction
+- `caseWhen()`, `exists()`, `notExists()` - Conditional and subquery helpers
+- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `windowFunction()` - Window function helpers

package/docs/getting-started.md

@@ -0,0 +1,104 @@
+# Getting Started
+
+This guide will help you get started with MetalORM.
+
+## Installation
+
+You can install MetalORM using npm, yarn, or pnpm:
+
+```bash
+# npm
+npm install metal-orm
+
+# yarn
+yarn add metal-orm
+
+# pnpm
+pnpm add metal-orm
+```
+
+## Quick Start
+
+Here's a complete example to get you started:
+
+```typescript
+import {
+  defineTable,
+  col,
+  hasMany,
+  SelectQueryBuilder,
+  eq,
+  count,
+  hydrateRows,
+  MySqlDialect
+} from 'metal-orm';
+
+// 1. Define your schema
+const posts = defineTable(
+  'posts',
+  {
+    id: col.int().primaryKey(),
+    title: col.varchar(255).notNull(),
+    content: col.text(),
+    userId: col.int().notNull(),
+    createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
+    updatedAt: col.timestamp()
+  }
+);
+
+const users = defineTable(
+  'users',
+  {
+    id: col.int().primaryKey(),
+    name: col.varchar(255).notNull(),
+    email: col.varchar(255).unique(),
+    createdAt: col.timestamp().default('CURRENT_TIMESTAMP')
+  },
+  {
+    posts: hasMany(posts, 'userId')
+  }
+);
+
+// 2. Build your query
+const builder = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    email: users.columns.email,
+    totalPosts: count(posts.columns.id)
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
+  .groupBy(users.columns.id, users.columns.name, users.columns.email)
+  .orderBy(count(posts.columns.id), 'DESC')
+  .limit(20)
+  .include('posts', {
+    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt]
+  });
+
+// 3. Compile to SQL
+const dialect = new MySqlDialect();
+const { sql, params } = builder.compile(dialect);
+
+// 4. Execute and hydrate
+const rows = await connection.execute(sql, params);
+const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+
+console.log(hydrated);
+// [
+//   {
+//     id: 1,
+//     name: 'John Doe',
+//     email: 'john@example.com',
+//     totalPosts: 15,
+//     posts: [
+//       {
+//         id: 101,
+//         title: 'Latest Post',
+//         createdAt: '2023-05-15T10:00:00.000Z'
+//       },
+//       // ... more posts
+//     ]
+//   }
+//   // ... more users
+// ]
+```

package/docs/hydration.md

@@ -0,0 +1,41 @@
+# Relation Hydration
+
+MetalORM can automatically transform flat database rows into nested JavaScript objects, making it easy to work with relational data.
+
+## Hydrating Results
+
+The `hydrateRows()` function takes an array of database rows and a hydration plan to produce nested objects. The hydration plan is generated by the `SelectQueryBuilder` when you use the `include()` method.
+
+```typescript
+const builder = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .include('posts', {
+    columns: ['id', 'title', 'content'],
+    include: {
+      comments: {
+        columns: ['id', 'content', 'createdAt']
+      }
+    }
+  });
+
+const { sql, params } = builder.compile(new MySqlDialect());
+const rows = await db.execute(sql, params);
+
+// Automatically hydrates to:
+// {
+//   id: 1,
+//   name: 'John',
+//   posts: [
+//     {
+//       id: 1,
+//       title: 'First Post',
+//       comments: [...]
+//     }
+//   ]
+// }
+const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+```
+
+## How it Works
+
+The `SelectQueryBuilder` analyzes the `include()` configuration and generates a `HydrationPlan`. This plan contains the necessary information to map the flat rows to a nested structure, including relation details and column aliases. The `hydrateRows()` function then uses this plan to efficiently process the result set.

package/docs/index.md

@@ -0,0 +1,31 @@
+# Introduction to MetalORM
+
+MetalORM is a TypeScript-first SQL query builder designed for developers who want the power of raw SQL with the convenience of a modern ORM. It keeps SQL generation deterministic (CTEs, aggregates, window functions, EXISTS/subqueries) while letting you introspect the AST or reuse builders inside larger queries.
+
+## Philosophy
+
+MetalORM follows these core principles:
+
+- **Type Safety First**: Leverage TypeScript to catch errors at compile time
+- **SQL Transparency**: Generate predictable, readable SQL that you can inspect
+- **Composition Over Configuration**: Build complex queries by composing simple parts
+- **Zero Magic**: Explicit operations with clear AST representation
+- **Multi-Dialect Support**: Write once, compile to MySQL, SQLite, or SQL Server
+
+## Features
+
+- **Declarative Schema Definition**: Define your database structure in TypeScript with full type inference.
+- **Rich Query Building**: A fluent API to build simple and complex queries.
+- **Advanced SQL Features**: Support for CTEs, window functions, subqueries, and more.
+- **Relation Hydration**: Automatically transform flat database rows into nested JavaScript objects.
+- **Multi-Dialect Support**: Compile the same query to different SQL dialects.
+
+## Table of Contents
+
+- [Getting Started](./getting-started.md)
+- [Schema Definition](./schema-definition.md)
+- [Query Builder](./query-builder.md)
+- [Advanced Features](./advanced-features.md)
+- [Hydration](./hydration.md)
+- [Multi-Dialect Support](./multi-dialect-support.md)
+- [API Reference](./api-reference.md)

package/docs/multi-dialect-support.md

@@ -0,0 +1,34 @@
+# Multi-Dialect Support
+
+MetalORM is designed to be database-agnostic. You can write your queries once and compile them to different SQL dialects.
+
+## Compiling Queries
+
+The `compile()` method on the `SelectQueryBuilder` takes a dialect instance and returns the compiled SQL and parameters.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(eq(users.columns.id, 1))
+  .limit(10);
+
+// MySQL
+const mysql = query.compile(new MySqlDialect());
+// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
+
+// SQLite
+const sqlite = query.compile(new SQLiteDialect());
+// SQL: SELECT * FROM users WHERE id = ? LIMIT ?
+
+// SQL Server
+const mssql = query.compile(new MSSQLDialect());
+// SQL: SELECT TOP 10 * FROM users WHERE id = @p1
+```
+
+## Supported Dialects
+
+- **MySQL**: `MySqlDialect`
+- **SQLite**: `SQLiteDialect`
+- **SQL Server**: `MSSQLDialect`
+
+Each dialect handles the specific syntax and parameterization of the target database.

package/docs/query-builder.md

@@ -0,0 +1,75 @@
+# Query Builder
+
+MetalORM's query builder provides a fluent and expressive API for constructing SQL queries.
+
+## Selecting Data
+
+The `SelectQueryBuilder` is the main entry point for building `SELECT` queries.
+
+### Basic Selections
+
+You can select all columns using `selectRaw('*')` or specify columns using `select()`:
+
+```typescript
+// Select all columns
+const query = new SelectQueryBuilder(users).selectRaw('*');
+
+// Select specific columns
+const query = new SelectQueryBuilder(users).select({
+  id: users.columns.id,
+  name: users.columns.name,
+});
+```
+
+### Joins
+
+You can join tables using `leftJoin`, `innerJoin`, `rightJoin`, etc.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .select({
+    userId: users.columns.id,
+    postTitle: posts.columns.title,
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id));
+```
+
+### Filtering
+
+You can filter results using the `where()` method with expression helpers:
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(and(
+    like(users.columns.name, '%John%'),
+    gt(users.columns.createdAt, new Date('2023-01-01'))
+  ));
+```
+
+### Aggregation
+
+You can use aggregate functions like `count()`, `sum()`, `avg()`, etc., and group the results.
+
+```typescript
+const query = new SelectQueryBuilder(users)
+  .select({
+    userId: users.columns.id,
+    postCount: count(posts.columns.id),
+  })
+  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
+  .groupBy(users.columns.id)
+  .having(gt(count(posts.columns.id), 5));
+```
+
+### Ordering and Pagination
+
+You can order the results using `orderBy()` and paginate using `limit()` and `offset()`.
+
+```typescript
+const query = new SelectQueryBuilder(posts)
+  .selectRaw('*')
+  .orderBy(posts.columns.createdAt, 'DESC')
+  .limit(10)
+  .offset(20);
+```

package/docs/schema-definition.md

@@ -0,0 +1,61 @@
+# Schema Definition
+
+MetalORM allows you to define your database schema in TypeScript, providing full type inference and a single source of truth for your data structures.
+
+## Defining Tables
+
+You can define a table using the `defineTable` function. It takes the table name, a columns object, and an optional relations object.
+
+```typescript
+import { defineTable, col } from 'metal-orm';
+
+const users = defineTable('users', {
+  id: col.int().primaryKey(),
+  name: col.varchar(255).notNull(),
+  email: col.varchar(255).unique(),
+  createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
+});
+```
+
+## Column Types
+
+MetalORM provides a variety of column types through the `col` object:
+
+- `col.int()`: Integer
+- `col.varchar(length)`: Variable-length string
+- `col.text()`: Text
+- `col.timestamp()`: Timestamp
+- `col.json()`: JSON
+- ...and more.
+
+You can also chain modifiers to define column constraints:
+
+- `.primaryKey()`: Marks the column as a primary key.
+- `.notNull()`: Adds a `NOT NULL` constraint.
+- `.unique()`: Adds a `UNIQUE` constraint.
+- `.default(value)`: Sets a default value.
+
+## Relations
+
+You can define relations between tables using `hasMany` and `belongsTo`:
+
+```typescript
+import { defineTable, col, hasMany } from 'metal-orm';
+
+const posts = defineTable('posts', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  userId: col.int().notNull(),
+});
+
+const users = defineTable(
+  'users',
+  {
+    id: col.int().primaryKey(),
+    name: col.varchar(255).notNull(),
+  },
+  {
+    posts: hasMany(posts, 'userId'),
+  }
+);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "exports": {
     ".": {

package/src/constants/sql.ts

@@ -51,7 +51,8 @@ export type OrderDirection = (typeof ORDER_DIRECTIONS)[keyof typeof ORDER_DIRECT
 export const SUPPORTED_DIALECTS = {
   MYSQL: 'mysql',
   SQLITE: 'sqlite',
-  MSSQL: 'mssql'
+  MSSQL: 'mssql',
+  POSTGRES: 'postgres'
 } as const;
 
 export type DialectName = (typeof SUPPORTED_DIALECTS)[keyof typeof SUPPORTED_DIALECTS];

package/src/dialect/postgres/index.ts

@@ -0,0 +1,81 @@
+import { CompilerContext, Dialect } from '../abstract';
+import { SelectQueryNode } from '../../ast/query';
+import { JsonPathNode } from '../../ast/expression';
+
+export class PostgresDialect extends Dialect {
+  public constructor() {
+    super();
+  }
+
+  quoteIdentifier(id: string): string {
+    return `"${id}"`;
+  }
+
+  protected compileJsonPath(node: JsonPathNode): string {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    // Postgres uses col->>'path' for text extraction
+    return `${col}->>'${node.path}'`;
+  }
+
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = ast.columns.map(c => {
+      let expr = '';
+      if (c.type === 'Function') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'Column') {
+        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
+      } else if (c.type === 'ScalarSubquery') {
+        expr = this.compileOperand(c, ctx);
+      } else if (c.type === 'WindowFunction') {
+        expr = this.compileOperand(c, ctx);
+      }
+
+      if (c.alias) {
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = `${this.quoteIdentifier(ast.from.name)}`;
+
+    const joins = ast.joins.map(j => {
+      const table = this.quoteIdentifier(j.table.name);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+
+    const groupBy = ast.groupBy && ast.groupBy.length > 0
+      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
+      : '';
+
+    const having = ast.having
+      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
+      : '';
+
+    const orderBy = ast.orderBy && ast.orderBy.length > 0
+      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
+      : '';
+
+    const limit = ast.limit ? ` LIMIT ${ast.limit}` : '';
+    const offset = ast.offset ? ` OFFSET ${ast.offset}` : '';
+
+    const ctes = ast.ctes && ast.ctes.length > 0
+      ? (() => {
+        const hasRecursive = ast.ctes.some(cte => cte.recursive);
+        const prefix = hasRecursive ? 'WITH RECURSIVE ' : 'WITH ';
+        const cteDefs = ast.ctes.map(cte => {
+          const name = this.quoteIdentifier(cte.name);
+          const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
+          const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
+          return `${name}${cols} AS (${query})`;
+        }).join(', ');
+        return prefix + cteDefs + ' ';
+      })()
+      : '';
+
+    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy}${limit}${offset};`;
+  }
+}

package/tests/postgres.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { SelectQueryBuilder } from '../src/builder/select';
+import { PostgresDialect } from '../src/dialect/postgres';
+import { Users } from '../src/playground/features/playground/data/schema';
+import { jsonPath, eq } from '../src/ast/expression';
+
+describe('PostgresDialect', () => {
+  it('should compile a simple select', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*');
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users";');
+  });
+
+  it('should compile a select with a where clause', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*').where(eq(Users.columns.id, 1));
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users" WHERE "users"."id" = ?;');
+    expect(compiled.params).toEqual([1]);
+  });
+
+  it('should compile a select with a json path', () => {
+    const query = new SelectQueryBuilder(Users).selectRaw('*').where(eq(jsonPath(Users.columns.settings, '$.first'), 'John'));
+    const dialect = new PostgresDialect();
+    const compiled = query.compile(dialect);
+    expect(compiled.sql).toBe('SELECT "users"."*" FROM "users" WHERE "users"."settings"->>\'$.first\' = ?;');
+    expect(compiled.params).toEqual(['John']);
+  });
+});

package/tests/window-function.test.ts

@@ -3,6 +3,7 @@ import { SelectQueryBuilder } from '../src/builder/select';
 import { SqliteDialect } from '../src/dialect/sqlite';
 import { MySqlDialect } from '../src/dialect/mysql';
 import { SqlServerDialect } from '../src/dialect/mssql';
+import { PostgresDialect } from '../src/dialect/postgres';
 import { TableDef } from '../src/schema/table';
 import { rowNumber, rank, denseRank, lag, lead, ntile, firstValue, lastValue, windowFunction } from '../src/ast/expression';
 
@@ -14,6 +15,7 @@ describe('Window Function Support', () => {
     const sqlite = new SqliteDialect();
     const mysql = new MySqlDialect();
     const mssql = new SqlServerDialect();
+    const postgres = new PostgresDialect();
 
     it('should generate ROW_NUMBER() window function', () => {
         const users = table('users');
@@ -28,10 +30,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "users"."id" AS "id", "users"."name" AS "name", ROW_NUMBER() OVER () AS "row_num" FROM "users";';
         const expectedMysql = 'SELECT `users`.`id` AS `id`, `users`.`name` AS `name`, ROW_NUMBER() OVER () AS `row_num` FROM `users`;';
         const expectedMssql = 'SELECT [users].[id] AS [id], [users].[name] AS [name], ROW_NUMBER() OVER () AS [row_num] FROM [users];';
+        const expectedPostgres = 'SELECT "users"."id" AS "id", "users"."name" AS "name", ROW_NUMBER() OVER () AS "row_num" FROM "users";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate RANK() with PARTITION BY and ORDER BY', () => {
@@ -48,10 +52,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "orders"."id" AS "id", "orders"."customer_id" AS "customer_id", "orders"."amount" AS "amount", RANK() OVER (PARTITION BY "orders"."customer_id" ORDER BY "orders"."amount" DESC) AS "rank" FROM "orders";';
         const expectedMysql = 'SELECT `orders`.`id` AS `id`, `orders`.`customer_id` AS `customer_id`, `orders`.`amount` AS `amount`, RANK() OVER (PARTITION BY `orders`.`customer_id` ORDER BY `orders`.`amount` DESC) AS `rank` FROM `orders`;';
         const expectedMssql = 'SELECT [orders].[id] AS [id], [orders].[customer_id] AS [customer_id], [orders].[amount] AS [amount], RANK() OVER (PARTITION BY [orders].[customer_id] ORDER BY [orders].[amount] DESC) AS [rank] FROM [orders];';
+        const expectedPostgres = 'SELECT "orders"."id" AS "id", "orders"."customer_id" AS "customer_id", "orders"."amount" AS "amount", RANK() OVER (PARTITION BY "orders"."customer_id" ORDER BY "orders"."amount" DESC) AS "rank" FROM "orders";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate LAG function with offset and default value', () => {
@@ -67,10 +73,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LAG("sales"."amount", ?, ?) OVER () AS "prev_amount" FROM "sales";';
         const expectedMysql = 'SELECT `sales`.`date` AS `date`, `sales`.`amount` AS `amount`, LAG(`sales`.`amount`, ?, ?) OVER () AS `prev_amount` FROM `sales`;';
         const expectedMssql = 'SELECT [sales].[date] AS [date], [sales].[amount] AS [amount], LAG([sales].[amount], @p1, @p2) OVER () AS [prev_amount] FROM [sales];';
+        const expectedPostgres = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LAG("sales"."amount", ?, ?) OVER () AS "prev_amount" FROM "sales";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate LEAD function', () => {
@@ -86,10 +94,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LEAD("sales"."amount", ?) OVER () AS "next_amount" FROM "sales";';
         const expectedMysql = 'SELECT `sales`.`date` AS `date`, `sales`.`amount` AS `amount`, LEAD(`sales`.`amount`, ?) OVER () AS `next_amount` FROM `sales`;';
         const expectedMssql = 'SELECT [sales].[date] AS [date], [sales].[amount] AS [amount], LEAD([sales].[amount], @p1) OVER () AS [next_amount] FROM [sales];';
+        const expectedPostgres = 'SELECT "sales"."date" AS "date", "sales"."amount" AS "amount", LEAD("sales"."amount", ?) OVER () AS "next_amount" FROM "sales";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate window function with both PARTITION BY and ORDER BY', () => {
@@ -107,10 +117,12 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."department" AS "department", "employees"."salary" AS "salary", ROW_NUMBER() OVER (PARTITION BY "employees"."department" ORDER BY "employees"."salary" DESC) AS "dept_rank" FROM "employees";';
         const expectedMysql = 'SELECT `employees`.`id` AS `id`, `employees`.`name` AS `name`, `employees`.`department` AS `department`, `employees`.`salary` AS `salary`, ROW_NUMBER() OVER (PARTITION BY `employees`.`department` ORDER BY `employees`.`salary` DESC) AS `dept_rank` FROM `employees`;';
         const expectedMssql = 'SELECT [employees].[id] AS [id], [employees].[name] AS [name], [employees].[department] AS [department], [employees].[salary] AS [salary], ROW_NUMBER() OVER (PARTITION BY [employees].[department] ORDER BY [employees].[salary] DESC) AS [dept_rank] FROM [employees];';
+        const expectedPostgres = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."department" AS "department", "employees"."salary" AS "salary", ROW_NUMBER() OVER (PARTITION BY "employees"."department" ORDER BY "employees"."salary" DESC) AS "dept_rank" FROM "employees";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 
     it('should generate multiple window functions in one query', () => {
@@ -129,9 +141,11 @@ describe('Window Function Support', () => {
         const expectedSqlite = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."salary" AS "salary", ROW_NUMBER() OVER () AS "row_num", RANK() OVER () AS "rank", DENSE_RANK() OVER () AS "dense_rank" FROM "employees";';
         const expectedMysql = 'SELECT `employees`.`id` AS `id`, `employees`.`name` AS `name`, `employees`.`salary` AS `salary`, ROW_NUMBER() OVER () AS `row_num`, RANK() OVER () AS `rank`, DENSE_RANK() OVER () AS `dense_rank` FROM `employees`;';
         const expectedMssql = 'SELECT [employees].[id] AS [id], [employees].[name] AS [name], [employees].[salary] AS [salary], ROW_NUMBER() OVER () AS [row_num], RANK() OVER () AS [rank], DENSE_RANK() OVER () AS [dense_rank] FROM [employees];';
+        const expectedPostgres = 'SELECT "employees"."id" AS "id", "employees"."name" AS "name", "employees"."salary" AS "salary", ROW_NUMBER() OVER () AS "row_num", RANK() OVER () AS "rank", DENSE_RANK() OVER () AS "dense_rank" FROM "employees";';
 
         expect(query.toSql(sqlite)).toBe(expectedSqlite);
         expect(query.toSql(mysql)).toBe(expectedMysql);
         expect(query.toSql(mssql)).toBe(expectedMssql);
+        expect(query.toSql(postgres)).toBe(expectedPostgres);
     });
 });