metal-orm 1.0.7 → 1.0.9

package/docs/CHANGES.md

@@ -1,104 +0,0 @@
-# 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

@@ -1,176 +0,0 @@
-# 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 comprehensive support for window functions including `ROW_NUMBER()`, `RANK()`, `DENSE_RANK()`, `LAG()`, `LEAD()`, and more.
-
-### Basic Window Functions
-
-```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' }
-    ])
-  });
-```
-
-### 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.
-
-```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);
-
-## 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

@@ -1,31 +0,0 @@
-# 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
-- `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()` / `belongsToMany()` - Relation definitions
-- `eq()`, `and()`, `or()`, etc. - Expression builders
-- `hydrateRows()` - Transform flat rows to nested objects
-
-### Utility Functions
-- `count()`, `sum()`, `avg()` - Aggregate functions
-- `like()`, `notLike()`, `between()`, `notBetween()`, `inList()`, `notInList()` - Comparison operators
-- `jsonPath()` - JSON extraction
-- `caseWhen()`, `exists()`, `notExists()` - Conditional and subquery helpers
-- `rowNumber()`, `rank()`, `denseRank()`, `lag()`, `lead()`, `firstValue()`, `lastValue()`, `ntile()`, `windowFunction()` - Window function helpers
-- `isNull()`, `isNotNull()` - Null checking functions

package/docs/dml-operations.md

@@ -1,156 +0,0 @@
-# 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,171 +0,0 @@
-# Getting Started
-
-This guide walks you through:
-
-1. Using MetalORM as a **simple query builder**.
-2. Hydrating relations into nested objects.
-3. Taking a first look at the **OrmContext** runtime.
-
-## 1. Installation
-
-```bash
-npm install metal-orm
-# or
-yarn add metal-orm
-# or
-pnpm add metal-orm
-```
-
-## 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.
-```
-
-## 3. Adding relations & hydration
-
-```typescript
-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' },
-//       // ...
-//     ],
-//   },
-//   // ...
-// ]
-```
-
-## 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.