metal-orm 1.0.7 → 1.0.9

package/docs/hydration.md

@@ -1,115 +0,0 @@
-# Hydration & Entities
-
-MetalORM offers two ways to go from SQL rows to richer structures:
-
-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.
-
-```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.
-
-## 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,36 +0,0 @@
-# Introduction to MetalORM
-
-MetalORM is a TypeScript-first SQL toolkit that can be used as:
-
-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.
-
-## Philosophy
-
-- **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 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)
-- [Multi-Dialect Support](./multi-dialect-support.md)
-- [API Reference](./api-reference.md)

package/docs/multi-dialect-support.md

@@ -1,59 +0,0 @@
-# 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`
-- **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

@@ -1,135 +0,0 @@
-# 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);
-```
-
-### 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.
-```

package/docs/runtime.md

@@ -1,105 +0,0 @@
-# Runtime & Unit of Work
-
-This page describes MetalORM's optional entity runtime:
-
-- `OrmContext` – the Unit of Work.
-- entities – proxies wrapping hydrated rows.
-- relation wrappers – lazy, batched collections and references.
-
-## OrmContext
-
-`OrmContext` owns:
-
-- a SQL dialect,
-- a DB executor (`executeSql(sql, params)`),
-- an identity map (`table + primaryKey → entity`),
-- change tracking for entities and relations,
-- hooks and (optionally) domain event dispatch.
-
-```ts
-const ctx = new OrmContext({
-  dialect: new MySqlDialect(),
-  db: {
-    async executeSql(sql, params) {
-      // call your DB driver here
-    }
-  }
-});
-```
-
-## Entities
-
-Entities are created when you call `.execute(ctx)` on a SelectQueryBuilder.
-
-They:
-
-- expose table columns as properties (user.id, user.name, …)
-- expose relations as wrappers:
-  - HasManyCollection<T> (e.g. user.posts)
-  - BelongsToReference<T> (e.g. post.author)
-  - ManyToManyCollection<T> (e.g. user.roles)
-- track changes to fields and collections for the Unit of Work.
-
-```ts
-const [user] = await new SelectQueryBuilder(users)
-  .select({ id: users.columns.id, name: users.columns.name })
-  .includeLazy('posts')
-  .execute(ctx);
-
-user.name = 'Updated Name';          // marks entity as Dirty
-const posts = await user.posts.load(); // lazy-batched load
-```
-
-## Unit of Work
-
-Each entity in an OrmContext has a status:
-
-- New – created in memory and not yet persisted.
-- Managed – loaded from the database and unchanged.
-- Dirty – modified scalar properties.
-- Removed – scheduled for deletion.
-
-Relations track:
-
-- additions (add, attach, syncByIds),
-- removals (remove, detach).
-
-`ctx.saveChanges()`:
-
-- runs hooks / interceptors,
-- flushes entity changes as INSERT / UPDATE / DELETE,
-- flushes relation changes (FK / pivot),
-- dispatches domain events (optional),
-- resets tracking.
-
-```ts
-user.posts.add({ title: 'From entities' });
-user.posts.remove(posts[0]);
-
-await ctx.saveChanges();
-```
-
-## Hooks & Domain Events
-
-Each TableDef can define hooks:
-
-```ts
-const users = defineTable('users', { /* ... */ }, undefined, {
-  hooks: {
-    beforeInsert(ctx, user) {
-      user.createdAt = new Date();
-    },
-    afterUpdate(ctx, user) {
-      // log audit event
-    },
-  },
-});
-```
-
-Entities may accumulate domain events:
-
-```ts
-addDomainEvent(user, new UserRegisteredEvent(user.id));
-```
-
-After flushing, the context dispatches these events to registered handlers or writes them to an outbox table.

package/docs/schema-definition.md

@@ -1,112 +0,0 @@
-# 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`, `belongsTo`, and `belongsToMany`:
-
-### One-to-Many Relations
-
-```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'),
-  }
-);
-```
-
-### Many-to-One Relations
-
-```typescript
-const posts = defineTable('posts', {
-  id: col.int().primaryKey(),
-  title: col.varchar(255).notNull(),
-  userId: col.int().notNull(),
-}, {
-  author: belongsTo(users, 'userId')
-});
-```
-
-### Many-to-Many Relations
-
-```typescript
-const projects = defineTable('projects', {
-  id: col.int().primaryKey(),
-  name: col.varchar(255).notNull(),
-});
-
-const projectAssignments = defineTable('project_assignments', {
-  id: col.int().primaryKey(),
-  userId: col.int().notNull(),
-  projectId: col.int().notNull(),
-  role: col.varchar(50),
-  assignedAt: col.timestamp(),
-});
-
-const users = defineTable('users', {
-  id: col.int().primaryKey(),
-  name: col.varchar(255).notNull(),
-}, {
-  projects: belongsToMany(
-    projects,
-    projectAssignments,
-    {
-      pivotForeignKeyToRoot: 'userId',
-      pivotForeignKeyToTarget: 'projectId',
-      defaultPivotColumns: ['role', 'assignedAt']
-    }
-  )
-});
-
-> **Note**: When using the runtime, relation definitions (`hasMany`, `belongsTo`, `belongsToMany`) are also used to:
-> - generate hydration plans for eager loading
-> - configure lazy relation loaders
-> - control cascade behavior in `OrmContext.saveChanges()`.
-```

package/metadata.json

@@ -1,5 +0,0 @@
-{
-  "name": "metal-orm",
-  "description": "A high-performance, close-to-metal TypeScript ORM playground and documentation site, demonstrating AST-based query building and dialect compilation.",
-  "requestFramePermissions": []
-}

package/playground/api/playground-api.ts

@@ -1,94 +0,0 @@
-import { IncomingMessage, ServerResponse } from 'node:http';
-import { SqliteClient } from '../../src/playground/features/playground/clients/SqliteClient';
-import { SCENARIOS } from '../../src/playground/features/playground/data/scenarios';
-import { QueryExecutionService } from '../../src/playground/features/playground/services/QueryExecutionService';
-import type { ApiStatusResponse } from '../../src/playground/features/playground/api/types';
-
-export const PLAYGROUND_API_PREFIX = '/api/playground';
-
-const sqliteClient = new SqliteClient();
-const queryExecutionService = new QueryExecutionService(sqliteClient);
-
-const sendJson = (res: ServerResponse, payload: unknown, status = 200) => {
-  res.statusCode = status;
-  res.setHeader('Content-Type', 'application/json');
-  res.end(JSON.stringify(payload));
-};
-
-const parseJsonBody = (req: IncomingMessage) =>
-  new Promise<Record<string, unknown>>((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    req.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
-    req.on('end', () => {
-      const body = Buffer.concat(chunks).toString('utf8');
-      if (!body) {
-        resolve({});
-        return;
-      }
-
-      try {
-        resolve(JSON.parse(body));
-      } catch (error) {
-        reject(error);
-      }
-    });
-    req.on('error', reject);
-  });
-
-const handleStatus = (_req: IncomingMessage, res: ServerResponse) => {
-  const body: ApiStatusResponse = {
-    ready: sqliteClient.isReady,
-    error: sqliteClient.error
-  };
-  sendJson(res, body);
-};
-
-const handleExecute = async (req: IncomingMessage, res: ServerResponse) => {
-  try {
-    const { scenarioId } = await parseJsonBody(req);
-    if (!scenarioId || typeof scenarioId !== 'string') {
-      sendJson(res, { error: 'Missing scenarioId' }, 400);
-      return;
-    }
-
-    const scenario = SCENARIOS.find(s => s.id === scenarioId);
-    if (!scenario) {
-      sendJson(res, { error: `Scenario '${scenarioId}' not found` }, 404);
-      return;
-    }
-
-    const result = await queryExecutionService.executeScenario(scenario);
-    sendJson(res, result);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : 'Unknown error';
-    sendJson(res, { error: message }, 500);
-  }
-};
-
-export const createPlaygroundApiMiddleware = () => {
-  return async (req: IncomingMessage, res: ServerResponse, next: () => void) => {
-    const pathname = req.url ? req.url.split('?')[0] : '';
-
-    if (req.method === 'GET' && pathname === '/status') {
-      handleStatus(req, res);
-      return;
-    }
-
-    if (req.method === 'POST' && pathname === '/execute') {
-      await handleExecute(req, res);
-      return;
-    }
-
-    next();
-  };
-};
-
-export const playgroundApiPlugin = () => ({
-  name: 'metal-orm-playground-api',
-  configureServer(server) {
-    server.middlewares.use(PLAYGROUND_API_PREFIX, createPlaygroundApiMiddleware());
-  },
-  configurePreviewServer(server) {
-    server.middlewares.use(PLAYGROUND_API_PREFIX, createPlaygroundApiMiddleware());
-  },
-});

package/playground/index.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-
-<head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Metal ORM Playground</title>
-</head>
-
-<body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-</body>
-
-</html>

package/playground/src/App.css

@@ -1 +0,0 @@
-/* App.css is no longer needed as we are using Mantine UI */