metal-orm 1.0.5 → 1.0.7

package/README.md

@@ -1,113 +1,299 @@
-# MetalORM
-
-[![npm version](https://img.shields.io/npm/v/metal-orm.svg)](https://www.npmjs.com/package/metal-orm)
-[![license](https://img.shields.io/npm/l/metal-orm.svg)](https://github.com/celsowm/metal-orm/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%23007ACC.svg)](https://www.typescriptlang.org/)
-
-**A TypeScript-first SQL query builder with schema-driven AST, hydrated relations, and multi-dialect compilation.**
-
-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.
-
-## Documentation
-
-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.
-- **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
-
-```bash
-# npm
-npm install metal-orm
-
-# yarn
-yarn add metal-orm
-
-# pnpm
-pnpm add metal-orm
-```
-
-## 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` |
-
-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,
-  SelectQueryBuilder,
-  eq,
-  hydrateRows,
-  MySqlDialect,
-} from 'metal-orm';
-
-const users = defineTable('users', {
-  id: col.int().primaryKey(),
-  name: col.varchar(255).notNull(),
-});
-
-const connection = await mysql.createConnection({
-  host: 'localhost',
-  user: 'root',
-  database: 'test',
-});
-
-const builder = new SelectQueryBuilder(users)
-  .select({
-    id: users.columns.id,
-    name: users.columns.name,
-  })
-  .where(eq(users.columns.id, 1));
-
-const dialect = new MySqlDialect();
-const { sql, params } = builder.compile(dialect);
-const [rows] = await connection.execute(sql, params);
-const hydrated = hydrateRows(rows as Record<string, unknown>[], builder.getHydrationPlan());
-
-console.log(hydrated);
-```
-
-## Helper idea
-
-If you find yourself compiling/executing the same way across your app, wrap the compiler + driver interaction in a tiny helper instead of repeating it:
-
-```typescript
-async function runMetalQuery<T>(
-  builder: SelectQueryBuilder<T>,
-  connection: mysql.Connection,
-  dialect = new MySqlDialect()
-) {
-  const { sql, params } = builder.compile(dialect);
-  const [rows] = await connection.execute(sql, params);
-  return hydrateRows(rows as Record<string, unknown>[], builder.getHydrationPlan());
-}
-
-const results = await runMetalQuery(builder, connection);
-```
-
-This keeps the ORM-focused pieces in one place while letting you reuse any pooling/transaction strategy the driver provides.
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
-
-## License
-
-MetalORM is [MIT licensed](LICENSE).
+# MetalORM
+
+[![npm version](https://img.shields.io/npm/v/metal-orm.svg)](https://www.npmjs.com/package/metal-orm)
+[![license](https://img.shields.io/npm/l/metal-orm.svg)](https://github.com/celsowm/metal-orm/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%23007ACC.svg)](https://www.typescriptlang.org/)
+
+**Start as a type-safe SQL query builder. Grow into a full ORM with entities and a Unit of Work.**
+
+MetalORM is a TypeScript-first, AST-driven SQL toolkit:
+
+- At the **base level**, it's a clear, deterministic query builder with schema definitions and relation-aware hydration.:contentReference[oaicite:0]{index=0}
+- At the **next level**, it becomes an **ORM runtime** with entities, lazy/batched relations, and a Unit of Work (`OrmContext`) that flushes graph changes in one `saveChanges()`.
+
+Use only the parts you need: query builder + hydration for read-heavy/reporting code, or the full ORM runtime for application/business logic.
+
+---
+
+## Documentation
+
+Full docs live in the `docs/` folder:
+
+- [Introduction](docs/index.md)
+- [Getting Started](docs/getting-started.md)
+- [Schema Definition](docs/schema-definition.md)
+- [Query Builder](docs/query-builder.md)
+- [DML Operations](docs/dml-operations.md)
+- [Hydration & Entities](docs/hydration.md)
+- [Runtime & Unit of Work](docs/runtime.md)
+- [Advanced Features](docs/advanced-features.md)
+- [Multi-Dialect Support](docs/multi-dialect-support.md)
+- [API Reference](docs/api-reference.md)
+
+---
+
+## Features
+
+**As a query builder:**
+
+- **Declarative schema definition** with `defineTable`, `col.*`, and typed relations.:contentReference[oaicite:1]{index=1}
+- **Fluent query builder** over a real SQL AST (`SelectQueryBuilder`, `InsertQueryBuilder`, `UpdateQueryBuilder`, `DeleteQueryBuilder`).
+- **Advanced SQL**: CTEs, aggregates, window functions, subqueries, JSON, CASE, EXISTS.
+- **Relation hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.).:contentReference[oaicite:4]{index=4}
+- **Multi-dialect**: compile once, run on MySQL, PostgreSQL, SQLite, or SQL Server.:contentReference[oaicite:5]{index=5}
+- **DML**: type-safe INSERT / UPDATE / DELETE with `RETURNING` where supported.:contentReference[oaicite:6]{index=6}
+
+**As an ORM runtime (optional):**
+
+- **Entities** inferred from your `TableDef`s.
+- **Lazy, batched relations**: `user.posts.load()`, `user.roles.load()`, etc.
+- **Unit of Work (`OrmContext`)** tracking New/Dirty/Removed entities.
+- **Graph persistence**: modify a whole object graph and flush with `ctx.saveChanges()`.
+- **Hooks & domain events** for cross-cutting concerns (audit, outbox, etc.).
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install metal-orm
+
+# yarn
+yarn add metal-orm
+
+# pnpm
+pnpm add metal-orm
+
+
+MetalORM compiles SQL; you bring your own driver:
+
+Dialect	Driver	Install
+MySQL / MariaDB	mysql2	npm install mysql2
+SQLite	sqlite3	npm install sqlite3
+PostgreSQL	pg	npm install pg
+SQL Server	tedious	npm install tedious
+
+Pick the matching dialect (MySqlDialect, SQLiteDialect, PostgresDialect, MSSQLDialect) when compiling queries.
+
+README
+
+1. Start simple: tiny table, tiny query
+
+MetalORM can be just a straightforward query builder.
+
+import mysql from 'mysql2/promise';
+import {
+  defineTable,
+  col,
+  SelectQueryBuilder,
+  eq,
+  MySqlDialect,
+} from 'metal-orm';
+
+// 1) A very small table
+const todos = defineTable('todos', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  done: col.boolean().default(false),
+});
+
+// 2) Build a simple query
+const listOpenTodos = new SelectQueryBuilder(todos)
+  .select({
+    id: todos.columns.id,
+    title: todos.columns.title,
+    done: todos.columns.done,
+  })
+  .where(eq(todos.columns.done, false))
+  .orderBy(todos.columns.id, 'ASC');
+
+// 3) Compile to SQL + params
+const dialect = new MySqlDialect();
+const { sql, params } = listOpenTodos.compile(dialect);
+
+// 4) Run with your favorite driver
+const connection = await mysql.createConnection({ /* ... */ });
+const [rows] = await connection.execute(sql, params);
+
+console.log(rows);
+// [
+//   { id: 1, title: 'Write docs', done: 0 },
+//   { id: 2, title: 'Ship feature', done: 0 },
+// ]
+
+
+That’s it: schema, query, SQL, done.
+
+2. Relations & hydration: nested results without an ORM
+
+Now let’s add relations and get nested objects, still without committing to a full ORM.
+
+import {
+  defineTable,
+  col,
+  hasMany,
+  SelectQueryBuilder,
+  eq,
+  count,
+  rowNumber,
+  hydrateRows,
+} from 'metal-orm';
+
+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(),
+}, {
+  posts: hasMany(posts, 'userId'),
+});
+
+// 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,
+    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(10)
+  .include('posts', {
+    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt],
+  }); // eager relation for hydration
+
+const { sql, params } = builder.compile(dialect);
+const [rows] = await connection.execute(sql, params);
+
+// Turn flat rows into nested objects
+const hydrated = hydrateRows(
+  rows as Record<string, unknown>[],
+  builder.getHydrationPlan(),
+);
+
+console.log(hydrated);
+// [
+//   {
+//     id: 1,
+//     name: 'John Doe',
+//     email: 'john@example.com',
+//     postCount: 15,
+//     rank: 1,
+//     posts: [
+//       { id: 101, title: 'Latest Post', createdAt: '2023-05-15T10:00:00Z' },
+//       // ...
+//     ],
+//   },
+//   // ...
+// ]
+
+
+Use this mode anywhere you want powerful SQL + nice nested results, without changing how you manage your models.
+
+3. Turn it up: entities + Unit of Work (ORM mode)
+
+When you’re ready, you can let MetalORM manage entities and relations for you.
+
+Instead of “naked objects”, your queries can return entities attached to an OrmContext:
+
+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.
+
+
+Here’s what the runtime gives you:
+
+Identity map: the same row ↔ the same entity instance within a context.
+
+Change tracking: field writes mark entities as dirty.
+
+Relation tracking: add/remove/sync on relation collections emits relation changes.
+
+Cascades: relation definitions can opt into cascade: 'all' | 'persist' | 'remove' | 'link'.
+
+Single flush: ctx.saveChanges() figures out inserts, updates, deletes, and pivot changes.
+
+You can start your project using only the query builder + hydration and gradually migrate hot paths to entities as you implement the runtime primitives.
+
+When to use which mode?
+
+Query builder + hydration only
+
+Great for reporting, analytics, and places where you already have a model layer.
+
+You keep full control over how objects map to rows.
+
+Entity + Unit of Work runtime
+
+Great for request-scoped application logic and domain modeling.
+
+You want lazy relations, cascades, and less boilerplate around update/delete logic.
+
+Both modes share the same schema, AST, and dialects, so you don't have to pick one forever.
+
+Contributing
+
+Issues and PRs are welcome! If you're interested in pushing the runtime/ORM side further (soft deletes, multi-tenant filters, outbox patterns, etc.), contributions are especially appreciated.
+
+See the Contributing Guide
+ for details.
+
+License
+
+MetalORM is MIT licensed
+.

package/docs/CHANGES.md

@@ -0,0 +1,104 @@
+# Documentation Updates Summary
+
+This document summarizes the major updates made to the MetalORM documentation to reflect all new features.
+
+## New Documentation Files
+
+### `dml-operations.md`
+- **New File**: Comprehensive documentation for INSERT, UPDATE, and DELETE operations
+- **Features Covered**:
+  - `InsertQueryBuilder` with single and multi-row inserts
+  - `UpdateQueryBuilder` with conditional updates
+  - `DeleteQueryBuilder` with safety best practices
+  - RETURNING clause support across all DML operations
+  - Multi-dialect support for all DML operations
+
+## Updated Documentation Files
+
+### `index.md`
+- **Updates**:
+  - Added DML Operations to the table of contents
+  - Updated philosophy to include PostgreSQL in multi-dialect support
+  - Added "Comprehensive Relation Support" to features list
+  - Added "DML Operations" to features list
+
+### `schema-definition.md`
+- **Updates**:
+  - Added `belongsTo` relation type documentation
+  - Added comprehensive `belongsToMany` relation documentation with pivot table examples
+  - Updated relation section with all three relation types
+
+### `advanced-features.md`
+- **Updates**:
+  - Enhanced window functions section with convenience helpers
+  - Added examples for `rowNumber()`, `rank()`, `lag()`, `lead()` functions
+  - Improved CTE examples with better explanations
+
+### `multi-dialect-support.md`
+- **Updates**:
+  - Added PostgreSQL dialect to supported dialects
+  - Added dialect-specific features section
+  - Added examples showing SQL Server TOP vs LIMIT differences
+
+### `api-reference.md`
+- **Updates**:
+  - Added `InsertQueryBuilder`, `UpdateQueryBuilder`, `DeleteQueryBuilder` to core classes
+  - Added `PostgresDialect` to dialect compilers
+  - Added `belongsToMany()` to relation definitions
+  - Added `notLike()`, `notBetween()`, `firstValue()`, `lastValue()`, `ntile()` to utility functions
+  - Added `isNull()`, `isNotNull()` to null checking functions
+
+### `hydration.md`
+- **Updates**:
+  - Enhanced pivot column hydration documentation
+  - Added comprehensive examples of `_pivot` key usage
+  - Added advanced hydration options with custom aliases
+
+### `query-builder.md`
+- **Updates**:
+  - Added window functions section with examples
+  - Added CTEs (Common Table Expressions) section
+  - Added subqueries section
+  - Enhanced existing sections with more comprehensive examples
+
+### `getting-started.md`
+- **Updates**:
+  - Added `rowNumber()` window function to the main example
+  - Updated imports to include new functions
+  - Enhanced example output to show window function results
+
+## New Features Now Documented
+
+### DML Operations
+- Full INSERT, UPDATE, DELETE query builder support
+- RETURNING clause support for all DML operations
+- Multi-dialect compilation for DML
+
+### Advanced SQL Features
+- Comprehensive window function support (`rowNumber`, `rank`, `denseRank`, `lag`, `lead`, `firstValue`, `lastValue`, `ntile`)
+- Enhanced CTE support with recursive CTEs
+- Advanced subquery support
+
+### Relation Types
+- `belongsToMany` relation type with pivot table support
+- Pivot column hydration with custom alias support
+
+### Dialect Support
+- PostgreSQL dialect support
+- Dialect-specific feature documentation
+
+### Expression Builders
+- Additional comparison operators (`notLike`, `notBetween`)
+- Null checking functions (`isNull`, `isNotNull`)
+- Enhanced window function helpers
+
+## Verification
+
+All documented features have been verified to exist in the codebase:
+- ✅ All DML classes exist and are exported
+- ✅ All window functions exist and are exported
+- ✅ PostgreSQL dialect exists and is exported
+- ✅ `belongsToMany` relation function exists and is exported
+- ✅ All utility functions exist and are exported
+
+The documentation now accurately reflects the current state of the MetalORM library with all its advanced features.

package/docs/advanced-features.md

@@ -23,7 +23,9 @@ const query = new SelectQueryBuilder(activeUsers)
 
 ## Window Functions
 
-MetalORM provides helpers for window functions like `RANK()`, `ROW_NUMBER()`, etc.
+MetalORM provides comprehensive support for window functions including `ROW_NUMBER()`, `RANK()`, `DENSE_RANK()`, `LAG()`, `LEAD()`, and more.
+
+### Basic Window Functions
 
 ```typescript
 const rankedPosts = new SelectQueryBuilder(posts)
@@ -36,6 +38,42 @@ const rankedPosts = new SelectQueryBuilder(posts)
   });
 ```
 
+### Convenience Helpers
+
+MetalORM provides convenience functions for common window functions:
+
+```typescript
+import { rowNumber, rank, denseRank, lag, lead } from 'metal-orm';
+
+// Simple row numbering
+const query1 = new SelectQueryBuilder(users)
+  .select({
+    id: users.columns.id,
+    name: users.columns.name,
+    rowNum: rowNumber()
+  });
+
+// Ranking with partitioning
+const query2 = new SelectQueryBuilder(orders)
+  .select({
+    id: orders.columns.id,
+    customerId: orders.columns.customerId,
+    amount: orders.columns.amount,
+    rank: rank()
+  })
+  .partitionBy(orders.columns.customerId)
+  .orderBy(orders.columns.amount, 'DESC');
+
+// LAG and LEAD functions
+const query3 = new SelectQueryBuilder(sales)
+  .select({
+    date: sales.columns.date,
+    amount: sales.columns.amount,
+    prevAmount: lag(sales.columns.amount, 1, 0),
+    nextAmount: lead(sales.columns.amount, 1, 0)
+  });
+```
+
 ## Subqueries and EXISTS
 
 You can use subqueries and `EXISTS` to perform complex checks.
@@ -82,4 +120,57 @@ const tieredUsers = new SelectQueryBuilder(users)
     ], 'regular')
   })
   .groupBy(users.columns.id);
+
+## Advanced Runtime Patterns
+
+When using the OrmContext runtime, you can implement advanced patterns like soft deletes, multi-tenant filtering, and optimistic concurrency.
+
+### Soft Deletes
+
+Use hooks to implement soft deletes:
+
+```ts
+const users = defineTable('users', {
+  id: col.int().primaryKey(),
+  name: col.varchar(255).notNull(),
+  deletedAt: col.timestamp(),
+}, undefined, {
+  hooks: {
+    beforeRemove(ctx, user) {
+      user.deletedAt = new Date();
+      return false; // prevent actual deletion
+    },
+  },
+});
+```
+
+### Multi-Tenant Filters
+
+Apply global filters via context:
+
+```ts
+const ctx = new OrmContext({
+  dialect: new MySqlDialect(),
+  db: { /* ... */ },
+  tenantId: 'tenant-123',
+});
+
+// All queries in this context automatically filter by tenant
+const users = await new SelectQueryBuilder(usersTable)
+  .execute(ctx); // WHERE tenantId = 'tenant-123'
+```
+
+### Optimistic Concurrency
+
+Track version columns for conflict detection:
+
+```ts
+const posts = defineTable('posts', {
+  id: col.int().primaryKey(),
+  title: col.varchar(255).notNull(),
+  version: col.int().default(1),
+});
+
+ctx.saveChanges(); // throws if version mismatch
+```
 ```

package/docs/api-reference.md

@@ -4,19 +4,28 @@ This section provides a reference for the core classes, key functions, and utili
 
 ### Core Classes
 - `SelectQueryBuilder` - Main query builder class
-- `MySqlDialect` / `SQLiteDialect` / `MSSQLDialect` - SQL dialect compilers
+- `InsertQueryBuilder` - INSERT query builder class
+- `UpdateQueryBuilder` - UPDATE query builder class
+- `DeleteQueryBuilder` - DELETE query builder class
+- `MySqlDialect` / `SQLiteDialect` / `MSSQLDialect` / `PostgresDialect` - SQL dialect compilers
 - `HydrationManager` - Handles relation hydration logic
+- `OrmContext` - Unit of Work context for entities
+- `Entity<TTable>` - Entity proxy wrapping table rows
+- `HasManyCollection<T>` - Lazy/batched has-many relation wrapper
+- `BelongsToReference<T>` - Belongs-to relation wrapper
+- `ManyToManyCollection<T>` - Many-to-many relation wrapper with pivot
 
 ### Key Functions
 - `defineTable()` - Define database tables
 - `col.*()` - Column type definitions
-- `hasMany()` / `belongsTo()` - Relation definitions
+- `hasMany()` / `belongsTo()` / `belongsToMany()` - 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
+- `like()`, `notLike()`, `between()`, `notBetween()`, `inList()`, `notInList()` - Comparison operators
 - `jsonPath()` - JSON extraction
 - `caseWhen()`, `exists()`, `notExists()` - Conditional and subquery helpers
-- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `windowFunction()` - Window function helpers
+- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `firstValue()`, `lastValue()`, `ntile()`, `windowFunction()` - Window function helpers
+- `isNull()`, `isNotNull()` - Null checking functions