metal-orm 1.0.5 → 1.0.6

package/docs/dml-operations.md

@@ -0,0 +1,156 @@
+# DML Operations
+
+MetalORM provides comprehensive support for Data Manipulation Language (DML) operations including INSERT, UPDATE, and DELETE queries.
+
+## INSERT Operations
+
+The `InsertQueryBuilder` allows you to insert data into your tables with full type safety.
+
+### Basic Insert
+
+```typescript
+import { InsertQueryBuilder } from 'metal-orm';
+
+const query = new InsertQueryBuilder(users)
+  .values({
+    name: 'John Doe',
+    email: 'john@example.com',
+    createdAt: new Date()
+  });
+
+const { sql, params } = query.compile(new MySqlDialect());
+```
+
+### Multi-row Insert
+
+```typescript
+const query = new InsertQueryBuilder(users)
+  .values([
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Smith', email: 'jane@example.com' }
+  ]);
+```
+
+### RETURNING Clause
+
+Some databases support returning inserted data:
+
+```typescript
+const query = new InsertQueryBuilder(users)
+  .values({ name: 'John Doe', email: 'john@example.com' })
+  .returning(users.columns.id, users.columns.name);
+```
+
+## UPDATE Operations
+
+The `UpdateQueryBuilder` provides a fluent API for updating records.
+
+### Basic Update
+
+```typescript
+const query = new UpdateQueryBuilder(users)
+  .set({ name: 'John Updated', email: 'john.updated@example.com' })
+  .where(eq(users.columns.id, 1));
+```
+
+### Conditional Update
+
+```typescript
+const query = new UpdateQueryBuilder(users)
+  .set({ lastLogin: new Date() })
+  .where(and(
+    eq(users.columns.id, 1),
+    isNull(users.columns.deletedAt)
+  ));
+```
+
+### RETURNING Clause
+
+```typescript
+const query = new UpdateQueryBuilder(users)
+  .set({ status: 'active' })
+  .where(eq(users.columns.id, 1))
+  .returning(users.columns.id, users.columns.status);
+```
+
+## DELETE Operations
+
+The `DeleteQueryBuilder` allows you to delete records with safety.
+
+### Basic Delete
+
+```typescript
+const query = new DeleteQueryBuilder(users)
+  .where(eq(users.columns.id, 1));
+```
+
+### Conditional Delete
+
+```typescript
+const query = new DeleteQueryBuilder(users)
+  .where(and(
+    eq(users.columns.status, 'inactive'),
+    lt(users.columns.lastLogin, new Date('2023-01-01'))
+  ));
+```
+
+### RETURNING Clause
+
+```typescript
+const query = new DeleteQueryBuilder(users)
+  .where(eq(users.columns.id, 1))
+  .returning(users.columns.id, users.columns.name);
+```
+
+## Multi-Dialect Support
+
+All DML operations support the same multi-dialect compilation as SELECT queries:
+
+```typescript
+// MySQL
+const mysqlResult = query.compile(new MySqlDialect());
+
+// SQLite
+const sqliteResult = query.compile(new SQLiteDialect());
+
+// SQL Server
+const mssqlResult = query.compile(new MSSQLDialect());
+
+// PostgreSQL
+const postgresResult = query.compile(new PostgresDialect());
+```
+
+## Best Practices
+
+1. **Always use WHERE clauses**: For UPDATE and DELETE operations, always include WHERE clauses to avoid accidental mass updates/deletes.
+
+2. **Use RETURNING for verification**: When supported by your database, use RETURNING clauses to verify what was affected.
+
+3. **Batch operations**: For large datasets, consider batching INSERT operations to avoid parameter limits.
+
+4. **Transaction safety**: Wrap DML operations in transactions when performing multiple related operations.
+
+## Using the Unit of Work (optional)
+
+If you're using `OrmContext`, you don't have to manually build `InsertQueryBuilder` / `UpdateQueryBuilder` / `DeleteQueryBuilder` for every change.
+
+Instead, you can:
+
+1. Load entities via the query builder + `execute(ctx)`.
+2. Modify fields and relations in memory.
+3. Call `ctx.saveChanges()` once.
+
+```ts
+const [user] = await new SelectQueryBuilder(users)
+  .select({ id: users.columns.id, name: users.columns.name })
+  .includeLazy('posts')
+  .where(eq(users.columns.id, 1))
+  .execute(ctx);
+
+user.name = 'Updated Name';
+user.posts.add({ title: 'New from runtime' });
+
+await ctx.saveChanges();
+```
+
+Internally, MetalORM uses the same DML ASTs and dialect compilers described above to generate INSERT, UPDATE, DELETE, and pivot operations.

package/docs/getting-started.md

@@ -1,25 +1,46 @@
 # Getting Started
 
-This guide will help you get started with MetalORM.
+This guide walks you through:
 
-## Installation
+1. Using MetalORM as a **simple query builder**.
+2. Hydrating relations into nested objects.
+3. Taking a first look at the **OrmContext** runtime.
 
-You can install MetalORM using npm, yarn, or pnpm:
+## 1. Installation
 
 ```bash
-# npm
 npm install metal-orm
-
-# yarn
+# or
 yarn add metal-orm
-
-# pnpm
+# or
 pnpm add metal-orm
 ```
 
-## Quick Start
+## 2. Your first query (builder only)
+
+```typescript
+import { defineTable, col, SelectQueryBuilder, eq, MySqlDialect } from 'metal-orm';
+
+const todos = defineTable('todos', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  done: col.boolean().default(false),
+});
+
+const query = new SelectQueryBuilder(todos)
+  .select({
+    id: todos.columns.id,
+    title: todos.columns.title,
+  })
+  .where(eq(todos.columns.done, false));
+
+const dialect = new MySqlDialect();
+const { sql, params } = query.compile(dialect);
+
+// Execute `sql` + `params` with your DB driver.
+```
 
-Here's a complete example to get you started:
+## 3. Adding relations & hydration
 
 ```typescript
 import {
@@ -29,59 +50,50 @@ import {
   SelectQueryBuilder,
   eq,
   count,
+  rowNumber,
   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 posts = defineTable('posts', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  userId: col.int().notNull(),
+  createdAt: col.timestamp().default('CURRENT_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')
-  }
-);
+const users = defineTable('users', {
+  id: col.int().primaryKey(),
+  name: col.varchar(255).notNull(),
+  email: col.varchar(255).unique(),
+}, {
+  posts: hasMany(posts, 'userId'),
+});
 
-// 2. Build your query
+// Build a query with relation & window function
 const builder = new SelectQueryBuilder(users)
   .select({
     id: users.columns.id,
     name: users.columns.name,
     email: users.columns.email,
-    totalPosts: count(posts.columns.id)
+    postCount: count(posts.columns.id),
+    rank: rowNumber(),           // window function helper
   })
   .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)
+  .limit(10)
   .include('posts', {
-    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt]
-  });
+    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt],
+  }); // eager relation for hydration
 
-// 3. Compile to SQL
-const dialect = new MySqlDialect();
 const { sql, params } = builder.compile(dialect);
+const [rows] = await connection.execute(sql, params);
 
-// 4. Execute and hydrate
-const rows = await connection.execute(sql, params);
-const hydrated = hydrateRows(rows, builder.getHydrationPlan());
+// Turn flat rows into nested objects
+const hydrated = hydrateRows(
+  rows as Record<string, unknown>[],
+  builder.getHydrationPlan(),
+);
 
 console.log(hydrated);
 // [
@@ -89,16 +101,71 @@ console.log(hydrated);
 //     id: 1,
 //     name: 'John Doe',
 //     email: 'john@example.com',
-//     totalPosts: 15,
+//     postCount: 15,
+//     rank: 1,
 //     posts: [
-//       {
-//         id: 101,
-//         title: 'Latest Post',
-//         createdAt: '2023-05-15T10:00:00.000Z'
-//       },
-//       // ... more posts
-//     ]
-//   }
-//   // ... more users
+//       { id: 101, title: 'Latest Post', createdAt: '2023-05-15T10:00:00Z' },
+//       // ...
+//     ],
+//   },
+//   // ...
 // ]
 ```
+
+## 4. A taste of the runtime (optional)
+
+When you're ready to let MetalORM manage entities and relations, you can use the OrmContext:
+
+```typescript
+import {
+  OrmContext,
+  MySqlDialect,
+  SelectQueryBuilder,
+  eq,
+} from 'metal-orm';
+
+// 1) Create an OrmContext for this request
+const ctx = new OrmContext({
+  dialect: new MySqlDialect(),
+  db: {
+    async executeSql(sql, params) {
+      const [rows] = await connection.execute(sql, params);
+      // MetalORM expects columns + values; adapt as needed
+      return [{
+        columns: Object.keys(rows[0] ?? {}),
+        values: rows.map(row => Object.values(row)),
+      }];
+    },
+  },
+});
+
+// 2) Load entities with lazy relations
+const [user] = await new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    email: users.columns.email,
+  })
+  .includeLazy('posts')  // HasMany as a lazy collection
+  .includeLazy('roles')  // BelongsToMany as a lazy collection
+  .where(eq(users.columns.id, 1))
+  .execute(ctx);
+
+// user is an Entity<typeof users>
+// scalar props are normal:
+user.name = 'Updated Name';  // marks entity as Dirty
+
+// relations are live collections:
+const postsCollection = await user.posts.load(); // batched lazy load
+const newPost = user.posts.add({ title: 'Hello from ORM mode' });
+
+// Many-to-many via pivot:
+await user.roles.syncByIds([1, 2, 3]);
+
+// 3) Persist the entire graph
+await ctx.saveChanges();
+// INSERT/UPDATE/DELETE + pivot updates happen in a single Unit of Work.
+
+```
+
+See [Runtime & Unit of Work](./runtime.md) for full details on entities and the Unit of Work.

package/docs/hydration.md

@@ -1,8 +1,11 @@
-# Relation Hydration
+# Hydration & Entities
 
-MetalORM can automatically transform flat database rows into nested JavaScript objects, making it easy to work with relational data.
+MetalORM offers two ways to go from SQL rows to richer structures:
 
-## Hydrating Results
+1. **Hydration only** – `hydrateRows(rows, plan)` → nested plain objects.
+2. **Entity runtime** – `builder.execute(ctx)` → entities with lazy relations.
+
+## 1. Hydrating with `hydrateRows`
 
 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.
 
@@ -38,13 +41,75 @@ 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.
-
-For belongs-to-many relationships you can also request pivot columns via the `pivot` option. Pivot columns are hydrated alongside each child row under the `_pivot` key, e.g.:
-
-```typescript
-.include('projects', {
-  columns: ['id', 'name', 'client'],
-  pivot: { columns: ['assigned_at', 'role_id'] }
-})
-```
+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.
+
+## Pivot Column Hydration
+
+For belongs-to-many relationships, you can request pivot columns via the `pivot` option. Pivot columns are hydrated alongside each child row under the `_pivot` key:
+
+```typescript
+.include('projects', {
+  columns: ['id', 'name', 'client'],
+  pivot: { columns: ['assigned_at', 'role_id'] }
+})
+```
+
+This would hydrate to:
+
+```typescript
+{
+  id: 1,
+  name: 'John Doe',
+  projects: [
+    {
+      id: 101,
+      name: 'Project Alpha',
+      client: 'Acme Corp',
+      _pivot: {
+        assigned_at: '2023-01-15T10:00:00.000Z',
+        role_id: 2
+      }
+    }
+  ]
+}
+```
+
+### Advanced Hydration Options
+
+You can also specify which pivot columns to include and customize the hydration:
+
+```typescript
+.include('projects', {
+  columns: ['id', 'name'],
+  pivot: {
+    columns: ['assigned_at', 'role_id'],
+    alias: 'assignment_info' // Custom alias instead of '_pivot'
+  },
+  include: {
+    client: {
+      columns: ['id', 'name']
+    }
+  }
+})
+
+## 2. Entities on top of hydration
+
+When you call `.execute(ctx)` instead of compiling manually:
+
+- MetalORM compiles and executes the query using the dialect in the `OrmContext`.
+- If a `HydrationPlan` exists, it is applied.
+- Each root row is wrapped in an entity proxy:
+  - scalar fields behave like normal properties
+  - relation properties expose `HasManyCollection`, `BelongsToReference`, or `ManyToManyCollection`.
+
+```ts
+const [user] = await new SelectQueryBuilder(users)
+  .select({ id: users.columns.id, name: users.columns.name })
+  .include('posts', { columns: [posts.columns.id, posts.columns.title] }) // eager
+  .includeLazy('roles')                                                   // lazy
+  .execute(ctx);
+
+const eagerPosts = user.posts.getItems();  // hydrated from the join
+const lazyRoles = await user.roles.load(); // resolved on demand
+```
+```

package/docs/index.md

@@ -1,31 +1,36 @@
 # 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.
+MetalORM is a TypeScript-first SQL toolkit that can be used as:
 
-## Philosophy
+1. A **typed query builder** over a real SQL AST.
+2. A **hydration layer** for turning flat rows into nested objects.
+3. An optional **entity runtime** with lazy relations and a Unit of Work.
+
+You can adopt these layers independently, in this order.
 
-MetalORM follows these core principles:
+## Philosophy
 
-- **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
+- **Type Safety First** – rely on TypeScript to catch mistakes early.:contentReference[oaicite:8]{index=8}
+- **SQL Transparency** – inspect the AST and generated SQL at any time.
+- **Composition Over Configuration** – build complex queries from small, pure pieces.
+- **Zero Magic, Opt-in Runtime** – the query builder and ORM runtime are separate layers.
+- **Multi-Dialect** – MySQL, PostgreSQL, SQLite, SQL Server out of the box.:contentReference[oaicite:9]{index=9}
 
 ## 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.
+- Declarative schema definition with relations.
+- Fluent query builder, including CTEs, window functions, subqueries, JSON, CASE.  
+- Relation hydration from flat result sets.
+- Optional entity runtime + Unit of Work.
 
 ## Table of Contents
 
 - [Getting Started](./getting-started.md)
 - [Schema Definition](./schema-definition.md)
 - [Query Builder](./query-builder.md)
+- [DML Operations](./dml-operations.md)
+- [Hydration & Entities](./hydration.md)
+- [Runtime & Unit of Work](./runtime.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

@@ -30,5 +30,30 @@ const mssql = query.compile(new MSSQLDialect());
 - **MySQL**: `MySqlDialect`
 - **SQLite**: `SQLiteDialect`
 - **SQL Server**: `MSSQLDialect`
+- **PostgreSQL**: `PostgresDialect`
 
 Each dialect handles the specific syntax and parameterization of the target database.
+
+### Dialect-Specific Features
+
+```typescript
+// PostgreSQL-specific JSON operations
+const query = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    settings: jsonPath(users.columns.settings, '$.notifications')
+  })
+  .compile(new PostgresDialect());
+
+// SQL Server TOP clause vs LIMIT
+const limitedQuery = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .limit(10);
+
+// MySQL/SQLite/PostgreSQL: SELECT * FROM users LIMIT 10
+// SQL Server: SELECT TOP 10 * FROM users
+```
+
+> **Note**: When using the runtime (`OrmContext`), the same dialects are used to generate INSERT, UPDATE, DELETE, and pivot operations in `saveChanges()`.
+```

package/docs/query-builder.md

@@ -73,3 +73,63 @@ const query = new SelectQueryBuilder(posts)
   .limit(10)
   .offset(20);
 ```
+
+### Window Functions
+
+The query builder supports window functions for advanced analytics:
+
+```typescript
+import { rowNumber, rank } from 'metal-orm';
+
+const query = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    rowNum: rowNumber(),
+    userRank: rank()
+  })
+  .partitionBy(users.columns.department)
+  .orderBy(users.columns.salary, 'DESC');
+```
+
+### CTEs (Common Table Expressions)
+
+You can use CTEs to organize complex queries:
+
+```typescript
+const activeUsers = new SelectQueryBuilder(users)
+  .selectRaw('*')
+  .where(gt(users.columns.lastLogin, new Date('2023-01-01')))
+  .as('active_users');
+
+const query = new SelectQueryBuilder(activeUsers)
+  .with(activeUsers)
+  .selectRaw('*')
+  .where(eq(activeUsers.columns.id, 1));
+```
+
+### Subqueries
+
+Support for subqueries in SELECT and WHERE clauses:
+
+```typescript
+const subquery = new SelectQueryBuilder(posts)
+  .select({ count: count(posts.columns.id) })
+  .where(eq(posts.columns.userId, users.columns.id));
+
+const query = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    postCount: subquery
+  });
+
+## From Builder to Entities
+
+You can keep using the query builder on its own, or plug it into the entity runtime:
+
+- `builder.compile(dialect)` → SQL + params → driver (builder-only usage).
+- `builder.execute(ctx)` → entities tracked by an `OrmContext` (runtime usage).
+
+See [Runtime & Unit of Work](./runtime.md) for how `execute(ctx)` integrates with entities and lazy relations.
+```