metal-orm 1.0.5 → 1.0.6

package/src/runtime/relations/has-many.ts

@@ -0,0 +1,111 @@
+import { HasManyCollection } from '../../schema/types';
+import { OrmContext, RelationKey } from '../orm-context';
+import { HasManyRelation } from '../../schema/relation';
+import { TableDef } from '../../schema/table';
+import { EntityMeta, getHydrationRows } from '../entity-meta';
+
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
+  private loaded = false;
+  private items: TChild[] = [];
+  private readonly added = new Set<TChild>();
+  private readonly removed = new Set<TChild>();
+
+  constructor(
+    private readonly ctx: OrmContext,
+    private readonly meta: EntityMeta<any>,
+    private readonly root: any,
+    private readonly relationName: string,
+    private readonly relation: HasManyRelation,
+    private readonly rootTable: TableDef,
+    private readonly loader: () => Promise<Map<string, Rows>>,
+    private readonly createEntity: (row: Record<string, any>) => TChild,
+    private readonly localKey: string
+  ) {
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TChild[]> {
+    if (this.loaded) return this.items;
+    const map = await this.loader();
+    const key = toKey(this.root[this.localKey]);
+    const rows = map.get(key) ?? [];
+    this.items = rows.map(row => this.createEntity(row));
+    this.loaded = true;
+    return this.items;
+  }
+
+  getItems(): TChild[] {
+    return this.items;
+  }
+
+  add(data: Partial<TChild>): TChild {
+    const keyValue = this.root[this.localKey];
+    const childRow: Record<string, any> = {
+      ...data,
+      [this.relation.foreignKey]: keyValue
+    };
+    const entity = this.createEntity(childRow);
+    this.added.add(entity);
+    this.items.push(entity);
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'add', entity }
+    );
+    return entity;
+  }
+
+  attach(entity: TChild): void {
+    const keyValue = this.root[this.localKey];
+    (entity as Record<string, any>)[this.relation.foreignKey] = keyValue;
+    this.ctx.markDirty(entity);
+    this.items.push(entity);
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'attach', entity }
+    );
+  }
+
+  remove(entity: TChild): void {
+    this.items = this.items.filter(item => item !== entity);
+    this.removed.add(entity);
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'remove', entity }
+    );
+  }
+
+  clear(): void {
+    for (const entity of [...this.items]) {
+      this.remove(entity);
+    }
+  }
+
+  private get relationKey(): RelationKey {
+    return `${this.rootTable.name}.${this.relationName}`;
+  }
+
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
+    this.items = rows.map(row => this.createEntity(row));
+    this.loaded = true;
+  }
+}

package/src/runtime/relations/many-to-many.ts

@@ -0,0 +1,149 @@
+import { ManyToManyCollection } from '../../schema/types';
+import { OrmContext, RelationKey } from '../orm-context';
+import { BelongsToManyRelation } from '../../schema/relation';
+import { TableDef } from '../../schema/table';
+import { findPrimaryKey } from '../../builder/hydration-planner';
+import { EntityMeta, getHydrationRows } from '../entity-meta';
+
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
+  private loaded = false;
+  private items: TTarget[] = [];
+
+  constructor(
+    private readonly ctx: OrmContext,
+    private readonly meta: EntityMeta<any>,
+    private readonly root: any,
+    private readonly relationName: string,
+    private readonly relation: BelongsToManyRelation,
+    private readonly rootTable: TableDef,
+    private readonly loader: () => Promise<Map<string, Rows>>,
+    private readonly createEntity: (row: Record<string, any>) => TTarget,
+    private readonly localKey: string
+  ) {
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TTarget[]> {
+    if (this.loaded) return this.items;
+    const map = await this.loader();
+    const key = toKey(this.root[this.localKey]);
+    const rows = map.get(key) ?? [];
+    this.items = rows.map(row => {
+      const entity = this.createEntity(row);
+      if ((row as any)._pivot) {
+        (entity as any)._pivot = row._pivot;
+      }
+      return entity;
+    });
+    this.loaded = true;
+    return this.items;
+  }
+
+  getItems(): TTarget[] {
+    return this.items;
+  }
+
+  attach(target: TTarget | number | string): void {
+    const entity = this.ensureEntity(target);
+    const id = this.extractId(entity);
+    if (id == null) return;
+    if (this.items.some(item => this.extractId(item) === id)) {
+      return;
+    }
+    this.items.push(entity);
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'attach', entity }
+    );
+  }
+
+  detach(target: TTarget | number | string): void {
+    const id = typeof target === 'number' || typeof target === 'string'
+      ? target
+      : this.extractId(target);
+
+    if (id == null) return;
+
+    const existing = this.items.find(item => this.extractId(item) === id);
+    if (!existing) return;
+
+    this.items = this.items.filter(item => this.extractId(item) !== id);
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'detach', entity: existing }
+    );
+  }
+
+  async syncByIds(ids: (number | string)[]): Promise<void> {
+    await this.load();
+    const targetKey = this.relation.targetKey || findPrimaryKey(this.relation.target);
+    const normalized = new Set(ids.map(id => toKey(id)));
+    const currentIds = new Set(this.items.map(item => toKey(this.extractId(item))));
+
+    for (const id of normalized) {
+      if (!currentIds.has(id)) {
+        this.attach(id);
+      }
+    }
+
+    for (const item of [...this.items]) {
+      const itemId = toKey(this.extractId(item));
+      if (!normalized.has(itemId)) {
+        this.detach(item);
+      }
+    }
+  }
+
+  private ensureEntity(target: TTarget | number | string): TTarget {
+    if (typeof target === 'number' || typeof target === 'string') {
+      const stub: Record<string, any> = {
+        [this.targetKey]: target
+      };
+      return this.createEntity(stub);
+    }
+    return target;
+  }
+
+  private extractId(entity: TTarget | number | string | null | undefined): number | string | null {
+    if (entity === null || entity === undefined) return null;
+    if (typeof entity === 'number' || typeof entity === 'string') {
+      return entity;
+    }
+    return (entity as any)[this.targetKey] ?? null;
+  }
+
+  private get relationKey(): RelationKey {
+    return `${this.rootTable.name}.${this.relationName}`;
+  }
+
+  private get targetKey(): string {
+    return this.relation.targetKey || findPrimaryKey(this.relation.target);
+  }
+
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
+    this.items = rows.map(row => {
+      const entity = this.createEntity(row);
+      if ((row as any)._pivot) {
+        (entity as any)._pivot = (row as any)._pivot;
+      }
+      return entity;
+    });
+    this.loaded = true;
+  }
+}

package/src/schema/column.ts

@@ -1,7 +1,21 @@
 /**
  * Supported column data types for database schema definitions
  */
-export type ColumnType = 'INT' | 'VARCHAR' | 'JSON' | 'ENUM' | 'BOOLEAN';
+export type ColumnType =
+  | 'INT'
+  | 'INTEGER'
+  | 'VARCHAR'
+  | 'TEXT'
+  | 'JSON'
+  | 'ENUM'
+  | 'BOOLEAN'
+  | 'int'
+  | 'integer'
+  | 'varchar'
+  | 'text'
+  | 'json'
+  | 'enum'
+  | 'boolean';
 
 /**
  * Definition of a database column

package/src/schema/relation.ts

@@ -17,32 +17,36 @@ export const RelationKinds = {
  */
 export type RelationType = (typeof RelationKinds)[keyof typeof RelationKinds];
 
+export type CascadeMode = 'none' | 'all' | 'persist' | 'remove' | 'link';
+
 /**
  * One-to-many relationship definition
  */
-export interface HasManyRelation {
+export interface HasManyRelation<TTarget extends TableDef = TableDef> {
     type: typeof RelationKinds.HasMany;
-    target: TableDef;
+    target: TTarget;
     foreignKey: string;
     localKey?: string;
+    cascade?: CascadeMode;
 }
 
 /**
  * Many-to-one relationship definition
  */
-export interface BelongsToRelation {
+export interface BelongsToRelation<TTarget extends TableDef = TableDef> {
     type: typeof RelationKinds.BelongsTo;
-    target: TableDef;
+    target: TTarget;
     foreignKey: string;
     localKey?: string;
+    cascade?: CascadeMode;
 }
 
 /**
  * Many-to-many relationship definition with rich pivot metadata
  */
-export interface BelongsToManyRelation {
+export interface BelongsToManyRelation<TTarget extends TableDef = TableDef> {
     type: typeof RelationKinds.BelongsToMany;
-    target: TableDef;
+    target: TTarget;
     pivotTable: TableDef;
     pivotForeignKeyToRoot: string;
     pivotForeignKeyToTarget: string;
@@ -50,70 +54,89 @@ export interface BelongsToManyRelation {
     targetKey?: string;
     pivotPrimaryKey?: string;
     defaultPivotColumns?: string[];
+    cascade?: CascadeMode;
 }
 
 /**
  * Union type representing any supported relationship definition
  */
-export type RelationDef = HasManyRelation | BelongsToRelation | BelongsToManyRelation;
-
-/**
- * Creates a one-to-many relationship definition
- * @param target - Target table of the relationship
- * @param foreignKey - Foreign key column name on the child table
- * @param localKey - Local key column name (optional)
- * @returns HasManyRelation definition
- *
- * @example
- * ```typescript
- * hasMany(usersTable, 'user_id')
- * ```
- */
-export const hasMany = (target: TableDef, foreignKey: string, localKey?: string): HasManyRelation => ({
+export type RelationDef =
+  | HasManyRelation
+  | BelongsToRelation
+  | BelongsToManyRelation;
+
+/**
+ * Creates a one-to-many relationship definition
+ * @param target - Target table of the relationship
+ * @param foreignKey - Foreign key column name on the child table
+ * @param localKey - Local key column name (optional)
+ * @returns HasManyRelation definition
+ *
+ * @example
+ * ```typescript
+ * hasMany(usersTable, 'user_id')
+ * ```
+ */
+export const hasMany = <TTarget extends TableDef>(
+  target: TTarget,
+  foreignKey: string,
+  localKey?: string,
+  cascade?: CascadeMode
+): HasManyRelation<TTarget> => ({
     type: RelationKinds.HasMany,
     target,
     foreignKey,
-    localKey
+    localKey,
+    cascade
 });
-
-/**
- * Creates a many-to-one relationship definition
- * @param target - Target table of the relationship
- * @param foreignKey - Foreign key column name on the child table
- * @param localKey - Local key column name (optional)
- * @returns BelongsToRelation definition
- *
- * @example
- * ```typescript
- * belongsTo(usersTable, 'user_id')
- * ```
- */
-export const belongsTo = (target: TableDef, foreignKey: string, localKey?: string): BelongsToRelation => ({
+
+/**
+ * Creates a many-to-one relationship definition
+ * @param target - Target table of the relationship
+ * @param foreignKey - Foreign key column name on the child table
+ * @param localKey - Local key column name (optional)
+ * @returns BelongsToRelation definition
+ *
+ * @example
+ * ```typescript
+ * belongsTo(usersTable, 'user_id')
+ * ```
+ */
+export const belongsTo = <TTarget extends TableDef>(
+  target: TTarget,
+  foreignKey: string,
+  localKey?: string,
+  cascade?: CascadeMode
+): BelongsToRelation<TTarget> => ({
     type: RelationKinds.BelongsTo,
     target,
     foreignKey,
-    localKey
+    localKey,
+    cascade
 });
-
-/**
- * Creates a many-to-many relationship definition with pivot metadata
- * @param target - Target table
- * @param pivotTable - Intermediate pivot table definition
- * @param options - Pivot metadata configuration
- * @returns BelongsToManyRelation definition
- */
-export const belongsToMany = (
-    target: TableDef,
-    pivotTable: TableDef,
-    options: {
-        pivotForeignKeyToRoot: string;
-        pivotForeignKeyToTarget: string;
-        localKey?: string;
-        targetKey?: string;
-        pivotPrimaryKey?: string;
-        defaultPivotColumns?: string[];
-    }
-): BelongsToManyRelation => ({
+
+/**
+ * Creates a many-to-many relationship definition with pivot metadata
+ * @param target - Target table
+ * @param pivotTable - Intermediate pivot table definition
+ * @param options - Pivot metadata configuration
+ * @returns BelongsToManyRelation definition
+ */
+export const belongsToMany = <
+  TTarget extends TableDef
+>(
+  target: TTarget,
+  pivotTable: TableDef,
+  options: {
+    pivotForeignKeyToRoot: string;
+    pivotForeignKeyToTarget: string;
+    localKey?: string;
+    targetKey?: string;
+    pivotPrimaryKey?: string;
+    defaultPivotColumns?: string[];
+    cascade?: CascadeMode;
+  }
+): BelongsToManyRelation<TTarget> => ({
     type: RelationKinds.BelongsToMany,
     target,
     pivotTable,
@@ -122,5 +145,6 @@ export const belongsToMany = (
     localKey: options.localKey,
     targetKey: options.targetKey,
     pivotPrimaryKey: options.pivotPrimaryKey,
-    defaultPivotColumns: options.defaultPivotColumns
+    defaultPivotColumns: options.defaultPivotColumns,
+    cascade: options.cascade
 });

package/src/schema/table.ts

@@ -1,18 +1,29 @@
-import { ColumnDef } from './column';
-import { RelationDef } from './relation';
-
-/**
- * Definition of a database table with its columns and relationships
- * @typeParam T - Type of the columns record
- */
-export interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
-  /** Name of the table */
-  name: string;
-  /** Record of column definitions keyed by column name */
-  columns: T;
-  /** Record of relationship definitions keyed by relation name */
-  relations: Record<string, RelationDef>;
-}
+import { ColumnDef } from './column';
+import { RelationDef } from './relation';
+
+export interface TableHooks {
+  beforeInsert?(ctx: unknown, entity: any): Promise<void> | void;
+  afterInsert?(ctx: unknown, entity: any): Promise<void> | void;
+  beforeUpdate?(ctx: unknown, entity: any): Promise<void> | void;
+  afterUpdate?(ctx: unknown, entity: any): Promise<void> | void;
+  beforeDelete?(ctx: unknown, entity: any): Promise<void> | void;
+  afterDelete?(ctx: unknown, entity: any): Promise<void> | void;
+}
+
+/**
+ * Definition of a database table with its columns and relationships
+ * @typeParam T - Type of the columns record
+ */
+export interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
+  /** Name of the table */
+  name: string;
+  /** Record of column definitions keyed by column name */
+  columns: T;
+  /** Record of relationship definitions keyed by relation name */
+  relations: Record<string, RelationDef>;
+  /** Optional lifecycle hooks */
+  hooks?: TableHooks;
+}
 
 /**
  * Creates a table definition with columns and relationships
@@ -31,16 +42,17 @@ export interface TableDef<T extends Record<string, ColumnDef> = Record<string, C
  * });
  * ```
  */
-export const defineTable = <T extends Record<string, ColumnDef>>(
-    name: string,
-    columns: T,
-    relations: Record<string, RelationDef> = {}
-): TableDef<T> => {
+export const defineTable = <T extends Record<string, ColumnDef>>(
+    name: string,
+    columns: T,
+    relations: Record<string, RelationDef> = {},
+    hooks?: TableHooks
+): TableDef<T> => {
   // Runtime mutability to assign names to column definitions for convenience
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
     (acc as any)[key] = { ...def, name: key, table: name };
     return acc;
   }, {} as T);
 
-  return { name, columns: colsWithNames, relations };
-};
+  return { name, columns: colsWithNames, relations, hooks };
+};

package/src/schema/types.ts

@@ -0,0 +1,76 @@
+import { ColumnDef } from './column';
+import { TableDef } from './table';
+import {
+  RelationDef,
+  HasManyRelation,
+  BelongsToRelation,
+  BelongsToManyRelation
+} from './relation';
+
+/**
+ * Maps a ColumnDef to its TypeScript type representation
+ */
+export type ColumnToTs<T extends ColumnDef> =
+  T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
+  T['type'] extends 'BOOLEAN' | 'boolean' ? boolean :
+  T['type'] extends 'JSON' | 'json' ? unknown :
+  string;
+
+/**
+ * Infers a row shape from a table definition
+ */
+export type InferRow<TTable extends TableDef> = {
+  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
+};
+
+type RelationResult<T extends RelationDef> =
+  T extends HasManyRelation<infer TTarget>        ? InferRow<TTarget>[] :
+  T extends BelongsToRelation<infer TTarget>      ? InferRow<TTarget> | null :
+  T extends BelongsToManyRelation<infer TTarget>  ? (InferRow<TTarget> & { _pivot?: any })[] :
+  never;
+
+/**
+ * Maps relation names to the expected row results
+ */
+export type RelationMap<TTable extends TableDef> = {
+  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
+};
+
+export interface HasManyCollection<TChild> {
+  load(): Promise<TChild[]>;
+  getItems(): TChild[];
+  add(data: Partial<TChild>): TChild;
+  attach(entity: TChild): void;
+  remove(entity: TChild): void;
+  clear(): void;
+}
+
+export interface BelongsToReference<TParent> {
+  load(): Promise<TParent | null>;
+  get(): TParent | null;
+  set(data: Partial<TParent> | TParent | null): TParent | null;
+}
+
+export interface ManyToManyCollection<TTarget> {
+  load(): Promise<TTarget[]>;
+  getItems(): TTarget[];
+  attach(target: TTarget | number | string): void;
+  detach(target: TTarget | number | string): void;
+  syncByIds(ids: (number | string)[]): Promise<void>;
+}
+
+export type Entity<
+  TTable extends TableDef,
+  TRow = InferRow<TTable>
+> = TRow & {
+  [K in keyof RelationMap<TTable>]:
+    TTable['relations'][K] extends HasManyRelation<infer TTarget>
+      ? HasManyCollection<Entity<TTarget>>
+      : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
+        ? ManyToManyCollection<Entity<TTarget>>
+        : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
+          ? BelongsToReference<Entity<TTarget>>
+          : never;
+} & {
+  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
+};