metal-orm 1.0.5 → 1.0.6

package/docs/runtime.md

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

@@ -37,7 +37,9 @@ You can also chain modifiers to define column constraints:
 
 ## Relations
 
-You can define relations between tables using `hasMany` and `belongsTo`:
+You can define relations between tables using `hasMany`, `belongsTo`, and `belongsToMany`:
+
+### One-to-Many Relations
 
 ```typescript
 import { defineTable, col, hasMany } from 'metal-orm';
@@ -59,3 +61,52 @@ const users = defineTable(
   }
 );
 ```
+
+### 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/package.json

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

package/src/ast/expression.ts

@@ -270,30 +270,50 @@ const createBinaryExpression = (
  * @param right - Right operand
  * @returns Binary expression node with equality operator
  */
-export const eq = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
-  createBinaryExpression('=', left, right);
-
+export const eq = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('=', left, right);
+
+/**
+ * Creates a not equal expression (left != right)
+ */
+export const neq = (
+  left: OperandNode | ColumnDef,
+  right: OperandNode | ColumnDef | string | number
+): BinaryExpressionNode => createBinaryExpression('!=', left, right);
+
 /**
  * Creates a greater-than expression (left > right)
  * @param left - Left operand
  * @param right - Right operand
  * @returns Binary expression node with greater-than operator
  */
-export const gt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
-  createBinaryExpression('>', left, right);
-
-/**
- * Creates a less-than expression (left < right)
- * @param left - Left operand
- * @param right - Right operand
- * @returns Binary expression node with less-than operator
- */
-export const lt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
-  createBinaryExpression('<', left, right);
-
-/**
- * Creates a LIKE pattern matching expression
- * @param left - Left operand
+export const gt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('>', left, right);
+
+/**
+ * Creates a greater than or equal expression (left >= right)
+ */
+export const gte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('>=', left, right);
+
+/**
+ * Creates a less-than expression (left < right)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @returns Binary expression node with less-than operator
+ */
+export const lt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('<', left, right);
+
+/**
+ * Creates a less than or equal expression (left <= right)
+ */
+export const lte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('<=', left, right);
+
+/**
+ * Creates a LIKE pattern matching expression
+ * @param left - Left operand
  * @param pattern - Pattern to match
  * @param escape - Optional escape character
  * @returns Binary expression node with LIKE operator

package/src/builder/hydration-planner.ts

@@ -14,55 +14,55 @@ export const findPrimaryKey = (table: TableDef): string => {
   const pk = Object.values(table.columns).find(c => c.primary);
   return pk?.name || 'id';
 };
-
-/**
- * Manages hydration planning for query results
- */
-export class HydrationPlanner {
-  /**
-   * Creates a new HydrationPlanner instance
-   * @param table - Table definition
-   * @param plan - Optional existing hydration plan
-   */
-  constructor(private readonly table: TableDef, private readonly plan?: HydrationPlan) { }
-
-  /**
-   * Captures root table columns for hydration planning
-   * @param columns - Columns to capture
-   * @returns Updated HydrationPlanner with captured columns
-   */
+
+/**
+ * Manages hydration planning for query results
+ */
+export class HydrationPlanner {
+  /**
+   * Creates a new HydrationPlanner instance
+   * @param table - Table definition
+   * @param plan - Optional existing hydration plan
+   */
+  constructor(private readonly table: TableDef, private readonly plan?: HydrationPlan) { }
+
+  /**
+   * Captures root table columns for hydration planning
+   * @param columns - Columns to capture
+   * @returns Updated HydrationPlanner with captured columns
+   */
   captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
     const currentPlan = this.getPlanOrDefault();
-    const rootCols = new Set(currentPlan.rootColumns);
-    let changed = false;
-
-    columns.forEach(node => {
-      if (node.type !== 'Column') return;
-      if (node.table !== this.table.name) return;
-
-      const alias = node.alias || node.name;
-      if (isRelationAlias(alias)) return;
-      if (!rootCols.has(alias)) {
-        rootCols.add(alias);
-        changed = true;
-      }
-    });
-
-    if (!changed) return this;
-    return new HydrationPlanner(this.table, {
-      ...currentPlan,
-      rootColumns: Array.from(rootCols)
-    });
-  }
-
-  /**
-   * Includes a relation in the hydration plan
-   * @param rel - Relation definition
-   * @param relationName - Name of the relation
-   * @param aliasPrefix - Alias prefix for relation columns
-   * @param columns - Columns to include from the relation
-   * @returns Updated HydrationPlanner with included relation
-   */
+    const rootCols = new Set(currentPlan.rootColumns);
+    let changed = false;
+
+    columns.forEach(node => {
+      if (node.type !== 'Column') return;
+      if (node.table !== this.table.name) return;
+
+      const alias = node.alias || node.name;
+      if (isRelationAlias(alias)) return;
+      if (!rootCols.has(alias)) {
+        rootCols.add(alias);
+        changed = true;
+      }
+    });
+
+    if (!changed) return this;
+    return new HydrationPlanner(this.table, {
+      ...currentPlan,
+      rootColumns: Array.from(rootCols)
+    });
+  }
+
+  /**
+   * Includes a relation in the hydration plan
+   * @param rel - Relation definition
+   * @param relationName - Name of the relation
+   * @param aliasPrefix - Alias prefix for relation columns
+   * @param columns - Columns to include from the relation
+   * @returns Updated HydrationPlanner with included relation
+   */
   includeRelation(
     rel: RelationDef,
     relationName: string,
@@ -78,31 +78,31 @@ export class HydrationPlanner {
       relations
     });
   }
-
-  /**
-   * Gets the current hydration plan
-   * @returns Current hydration plan or undefined
-   */
-  getPlan(): HydrationPlan | undefined {
-    return this.plan;
-  }
-
-  /**
-   * Gets the current hydration plan or creates a default one
-   * @returns Current hydration plan or default plan
-   */
-  private getPlanOrDefault(): HydrationPlan {
-    return this.plan ?? buildDefaultHydrationPlan(this.table);
-  }
-
-  /**
-   * Builds a relation plan for hydration
-   * @param rel - Relation definition
-   * @param relationName - Name of the relation
-   * @param aliasPrefix - Alias prefix for relation columns
-   * @param columns - Columns to include from the relation
-   * @returns Hydration relation plan
-   */
+
+  /**
+   * Gets the current hydration plan
+   * @returns Current hydration plan or undefined
+   */
+  getPlan(): HydrationPlan | undefined {
+    return this.plan;
+  }
+
+  /**
+   * Gets the current hydration plan or creates a default one
+   * @returns Current hydration plan or default plan
+   */
+  private getPlanOrDefault(): HydrationPlan {
+    return this.plan ?? buildDefaultHydrationPlan(this.table);
+  }
+
+  /**
+   * Builds a relation plan for hydration
+   * @param rel - Relation definition
+   * @param relationName - Name of the relation
+   * @param aliasPrefix - Alias prefix for relation columns
+   * @param columns - Columns to include from the relation
+   * @returns Hydration relation plan
+   */
   private buildRelationPlan(
     rel: RelationDef,
     relationName: string,
@@ -167,8 +167,8 @@ export class HydrationPlanner {
       }
     }
   }
-}
-
+}
+
 /**
  * Builds a default hydration plan for a table
  * @param table - Table definition