metal-orm 1.0.4 → 1.0.6

package/src/index.ts

@@ -1,12 +1,23 @@
 
-export * from './schema/table';
-export * from './schema/column';
-export * from './schema/relation';
-export * from './builder/select';
-export * from './ast/expression';
-export * from './dialect/mysql';
-export * from './dialect/mssql';
-export * from './dialect/sqlite';
-export * from './runtime/als';
-export * from './runtime/hydration';
-export * from './codegen/typescript';
+export * from './schema/table';
+export * from './schema/column';
+export * from './schema/relation';
+export * from './schema/types';
+export * from './builder/select';
+export * from './builder/insert';
+export * from './builder/update';
+export * from './builder/delete';
+export * from './ast/expression';
+export * from './dialect/mysql';
+export * from './dialect/mssql';
+export * from './dialect/sqlite';
+export * from './runtime/als';
+export * from './runtime/hydration';
+export * from './codegen/typescript';
+export * from './runtime/orm-context';
+export * from './runtime/entity';
+export * from './runtime/lazy-batch';
+export * from './runtime/relations/has-many';
+export * from './runtime/relations/belongs-to';
+export * from './runtime/relations/many-to-many';
+export * from './runtime/execute';

package/src/playground/features/playground/data/scenarios/hydration.ts

@@ -2,14 +2,26 @@ import { eq } from '../../../../../ast/expression';
 import { Users } from '../schema';
 import { createScenario } from './types';
 
-export const HYDRATION_SCENARIOS = [
-    createScenario({
-        id: 'user_with_orders',
-        category: 'Hydration',
-        title: 'Nested User Graph',
-        description: 'Eager-load orders for a single user and hydrate a JSON graph from flat SQL rows.',
-        build: (qb) => qb
-            .include('orders', { columns: ['id', 'total', 'status', 'user_id'] })
-            .where(eq(Users.columns.id, 1))
-    })
-];
+export const HYDRATION_SCENARIOS = [
+    createScenario({
+        id: 'user_with_orders',
+        category: 'Hydration',
+        title: 'Nested User Graph',
+        description: 'Eager-load orders for a single user and hydrate a JSON graph from flat SQL rows.',
+        build: (qb) => qb
+            .include('orders', { columns: ['id', 'total', 'status', 'user_id'] })
+            .where(eq(Users.columns.id, 1))
+    }),
+    createScenario({
+        id: 'user_projects_with_pivot',
+        category: 'Hydration',
+        title: 'Projects with Pivot Data',
+        description: 'Include projects for a user along with pivot metadata stored in `_pivot`.',
+        build: (qb) => qb
+            .include('projects', {
+                columns: ['id', 'name', 'client'],
+                pivot: { columns: ['assigned_at', 'role_id'] }
+            })
+            .where(eq(Users.columns.id, 1))
+    })
+];

package/src/playground/features/playground/data/scenarios/types.ts

@@ -1,9 +1,12 @@
-import { SelectQueryBuilder } from '../../../../../builder/select';
+import { SelectQueryBuilder } from '../../../../../builder/select';
+import { TableDef } from '../../../../../schema/table';
 
 /**
  * Extracts the TypeScript code from a build function
  */
-function extractTypeScriptCode(buildFn: (builder: SelectQueryBuilder<any>) => SelectQueryBuilder<any>): string {
+function extractTypeScriptCode<TTable extends TableDef>(
+  buildFn: (builder: SelectQueryBuilder<any, TTable>) => SelectQueryBuilder<any, TTable>
+): string {
     const fnString = buildFn.toString();
 
     // Remove the function wrapper and return statement
@@ -34,12 +37,12 @@ function extractTypeScriptCode(buildFn: (builder: SelectQueryBuilder<any>) => Se
     return fnString;
 }
 
-export interface Scenario {
-    id: string;
-    title: string;
-    description: string;
-    category: string;
-    build: (builder: SelectQueryBuilder<any>) => SelectQueryBuilder<any>;
+export interface Scenario {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    build: <TTable extends TableDef>(builder: SelectQueryBuilder<any, TTable>) => SelectQueryBuilder<any, TTable>;
 
     code?: string;
     typescriptCode?: string;
@@ -48,13 +51,13 @@ export interface Scenario {
 /**
  * Creates a scenario with auto-extracted TypeScript code
  */
-export function createScenario(config: {
-    id: string;
-    title: string;
-    description: string;
-    category: string;
-    build: (builder: SelectQueryBuilder<any>) => SelectQueryBuilder<any>;
-}): Scenario {
+export function createScenario(config: {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    build: <TTable extends TableDef>(builder: SelectQueryBuilder<any, TTable>) => SelectQueryBuilder<any, TTable>;
+}): Scenario {
     return {
         ...config,
         get code() {

package/src/playground/features/playground/data/schema.ts

@@ -1,6 +1,6 @@
 import { defineTable } from '../../../../schema/table';
 import { col } from '../../../../schema/column';
-import { hasMany, belongsTo } from '../../../../schema/relation';
+import { hasMany, belongsTo, belongsToMany } from '../../../../schema/relation';
 
 export const Users = defineTable('users', {
     id: col.primaryKey(col.int()),
@@ -55,7 +55,11 @@ export const ProjectAssignments = defineTable('project_assignments', {
 Users.relations = {
     orders: hasMany(Orders, 'user_id'),
     profiles: hasMany(Profiles, 'user_id'),
-    userRoles: hasMany(UserRoles, 'user_id')
+    userRoles: hasMany(UserRoles, 'user_id'),
+    projects: belongsToMany(Projects, ProjectAssignments, {
+        pivotForeignKeyToRoot: 'user_id',
+        pivotForeignKeyToTarget: 'project_id'
+    })
 };
 
 Orders.relations = {

package/src/playground/features/playground/services/QueryExecutionService.ts

@@ -6,11 +6,12 @@ import { hydrateRows } from '../../../../runtime/hydration';
 import type { IDatabaseClient } from '../common/IDatabaseClient';
 import type { QueryExecutionResult } from '../api/types';
 import type { Scenario } from '../data/scenarios';
+import type { TableDef } from '../../../../schema/table';
 
 /**
  * Extracts the TypeScript code from a build function
  */
-function extractTypeScriptCode(buildFn: (builder: SelectQueryBuilder<any>) => SelectQueryBuilder<any>): string {
+function extractTypeScriptCode<TTable extends TableDef>(buildFn: (builder: SelectQueryBuilder<any, TTable>) => SelectQueryBuilder<any, TTable>): string {
     const fnString = buildFn.toString();
 
     // Remove the function wrapper and return statement

package/src/runtime/entity-meta.ts

@@ -0,0 +1,52 @@
+import { TableDef } from '../schema/table';
+import { OrmContext } from './orm-context';
+import { RelationMap } from '../schema/types';
+
+export const ENTITY_META = Symbol('EntityMeta');
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+export interface EntityMeta<TTable extends TableDef> {
+  ctx: OrmContext;
+  table: TTable;
+  lazyRelations: (keyof RelationMap<TTable>)[];
+  relationCache: Map<string, Promise<any>>;
+  relationHydration: Map<string, Map<string, any>>;
+  relationWrappers: Map<string, unknown>;
+}
+
+export const getHydrationRows = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  key: unknown
+): Record<string, any>[] | undefined => {
+  const map = meta.relationHydration.get(relationName);
+  if (!map) return undefined;
+  const rows = map.get(toKey(key));
+  if (!rows) return undefined;
+  return Array.isArray(rows) ? rows : undefined;
+};
+
+export const getHydrationRecord = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  key: unknown
+): Record<string, any> | undefined => {
+  const map = meta.relationHydration.get(relationName);
+  if (!map) return undefined;
+  const value = map.get(toKey(key));
+  if (!value) return undefined;
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+};
+
+export const getEntityMeta = <TTable extends TableDef>(entity: any): EntityMeta<TTable> | undefined => {
+  if (!entity || typeof entity !== 'object') return undefined;
+  return (entity as any)[ENTITY_META];
+};
+
+export const hasEntityMeta = (entity: any): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
+  return Boolean(getEntityMeta(entity));
+};

package/src/runtime/entity.ts

@@ -0,0 +1,252 @@
+import { TableDef } from '../schema/table';
+import { Entity, RelationMap, HasManyCollection, BelongsToReference, ManyToManyCollection } from '../schema/types';
+import { OrmContext } from './orm-context';
+import { ENTITY_META, EntityMeta, getEntityMeta } from './entity-meta';
+import { DefaultHasManyCollection } from './relations/has-many';
+import { DefaultBelongsToReference } from './relations/belongs-to';
+import { DefaultManyToManyCollection } from './relations/many-to-many';
+import { HasManyRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation';
+import { loadHasManyRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch';
+import { findPrimaryKey } from '../builder/hydration-planner';
+
+type Rows = Record<string, any>[];
+
+const relationLoaderCache = <T extends Map<string, any>>(
+  meta: EntityMeta<any>,
+  relationName: string,
+  factory: () => Promise<T>
+): Promise<T> => {
+  if (meta.relationCache.has(relationName)) {
+    return meta.relationCache.get(relationName)! as Promise<T>;
+  }
+
+  const promise = factory().then(value => {
+    for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+      const otherMeta = getEntityMeta(tracked.entity);
+      if (!otherMeta) continue;
+      otherMeta.relationHydration.set(relationName, value);
+    }
+    return value;
+  });
+
+  meta.relationCache.set(relationName, promise);
+
+  for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+    const otherMeta = getEntityMeta(tracked.entity);
+    if (!otherMeta) continue;
+    otherMeta.relationCache.set(relationName, promise);
+  }
+
+  return promise;
+};
+
+export const createEntityProxy = <
+  TTable extends TableDef,
+  TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>
+>(
+  ctx: OrmContext,
+  table: TTable,
+  row: Record<string, any>,
+  lazyRelations: TLazy[] = [] as TLazy[]
+): Entity<TTable> => {
+  const target: Record<string, any> = { ...row };
+  const meta: EntityMeta<TTable> = {
+    ctx,
+    table,
+    lazyRelations: [...lazyRelations],
+    relationCache: new Map(),
+    relationHydration: new Map(),
+    relationWrappers: new Map()
+  };
+
+  Object.defineProperty(target, ENTITY_META, {
+    value: meta,
+    enumerable: false,
+    writable: false
+  });
+
+  let proxy: Entity<TTable>;
+  const handler: ProxyHandler<any> = {
+    get(targetObj, prop, receiver) {
+      if (prop === ENTITY_META) {
+        return meta;
+      }
+
+      if (prop === '$load') {
+        return async (relationName: keyof RelationMap<TTable>) => {
+          const wrapper = getRelationWrapper(meta, relationName as string, proxy);
+          if (wrapper && typeof wrapper.load === 'function') {
+            return wrapper.load();
+          }
+          return undefined;
+        };
+      }
+
+      if (typeof prop === 'string' && table.relations[prop]) {
+        return getRelationWrapper(meta, prop, proxy);
+      }
+
+      return Reflect.get(targetObj, prop, receiver);
+    },
+
+    set(targetObj, prop, value, receiver) {
+      const result = Reflect.set(targetObj, prop, value, receiver);
+      if (typeof prop === 'string' && table.columns[prop]) {
+        ctx.markDirty(proxy);
+      }
+      return result;
+    }
+  };
+
+  proxy = new Proxy(target, handler) as Entity<TTable>;
+  populateHydrationCache(proxy, row, meta);
+  return proxy;
+};
+
+export const createEntityFromRow = <TTable extends TableDef>(
+  ctx: OrmContext,
+  table: TTable,
+  row: Record<string, any>,
+  lazyRelations: (keyof RelationMap<TTable>)[] = []
+): Entity<TTable> => {
+  const pkName = findPrimaryKey(table);
+  const pkValue = row[pkName];
+  if (pkValue !== undefined && pkValue !== null) {
+    const tracked = ctx.getEntity(table, pkValue);
+    if (tracked) return tracked;
+  }
+
+  const entity = createEntityProxy(ctx, table, row, lazyRelations);
+  if (pkValue !== undefined && pkValue !== null) {
+    ctx.trackManaged(table, pkValue, entity);
+  } else {
+    ctx.trackNew(table, entity);
+  }
+
+  return entity;
+};
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+  const populateHydrationCache = <TTable extends TableDef>(
+    entity: any,
+    row: Record<string, any>,
+    meta: EntityMeta<TTable>
+  ): void => {
+    for (const relationName of Object.keys(meta.table.relations)) {
+      const relation = meta.table.relations[relationName];
+      const data = row[relationName];
+      if (!Array.isArray(data)) continue;
+
+      if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
+        const localKey = relation.localKey || findPrimaryKey(meta.table);
+        const rootValue = entity[localKey];
+        if (rootValue === undefined || rootValue === null) continue;
+        const cache = new Map<string, Rows>();
+        cache.set(toKey(rootValue), data as Rows);
+        meta.relationHydration.set(relationName, cache);
+        meta.relationCache.set(relationName, Promise.resolve(cache));
+        continue;
+      }
+
+      if (relation.type === RelationKinds.BelongsTo) {
+        const targetKey = relation.localKey || findPrimaryKey(relation.target);
+        const cache = new Map<string, Record<string, any>>();
+        for (const item of data) {
+          const pkValue = item[targetKey];
+          if (pkValue === undefined || pkValue === null) continue;
+          cache.set(toKey(pkValue), item);
+        }
+        if (cache.size) {
+          meta.relationHydration.set(relationName, cache);
+          meta.relationCache.set(relationName, Promise.resolve(cache));
+        }
+      }
+    }
+  };
+
+const getRelationWrapper = (
+  meta: EntityMeta<any>,
+  relationName: string,
+  owner: any
+): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+  if (meta.relationWrappers.has(relationName)) {
+    return meta.relationWrappers.get(relationName) as HasManyCollection<any>;
+  }
+
+  const relation = meta.table.relations[relationName];
+  if (!relation) return undefined;
+
+  const wrapper = instantiateWrapper(meta, relationName, relation as any, owner);
+  if (wrapper) {
+    meta.relationWrappers.set(relationName, wrapper);
+  }
+
+  return wrapper;
+};
+
+const instantiateWrapper = (
+  meta: EntityMeta<any>,
+  relationName: string,
+  relation: HasManyRelation | BelongsToRelation | BelongsToManyRelation,
+  owner: any
+): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+  switch (relation.type) {
+    case RelationKinds.HasMany: {
+      const hasMany = relation as HasManyRelation;
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+      const loader = () => relationLoaderCache(meta, relationName, () =>
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany)
+      );
+      return new DefaultHasManyCollection(
+        meta.ctx,
+        meta,
+        owner,
+        relationName,
+        hasMany,
+        meta.table,
+        loader,
+        (row: Record<string, any>) => createEntityFromRow(meta.ctx, relation.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.BelongsTo: {
+      const belongsTo = relation as BelongsToRelation;
+      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
+      const loader = () => relationLoaderCache(meta, relationName, () =>
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo)
+      );
+      return new DefaultBelongsToReference(
+        meta.ctx,
+        meta,
+        owner,
+        relationName,
+        belongsTo,
+        meta.table,
+        loader,
+        (row: Record<string, any>) => createEntityFromRow(meta.ctx, relation.target, row),
+        targetKey
+      );
+    }
+    case RelationKinds.BelongsToMany: {
+      const many = relation as BelongsToManyRelation;
+      const localKey = many.localKey || findPrimaryKey(meta.table);
+      const loader = () => relationLoaderCache(meta, relationName, () =>
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many)
+      );
+      return new DefaultManyToManyCollection(
+        meta.ctx,
+        meta,
+        owner,
+        relationName,
+        many,
+        meta.table,
+        loader,
+        (row: Record<string, any>) => createEntityFromRow(meta.ctx, relation.target, row),
+        localKey
+      );
+    }
+    default:
+      return undefined;
+  }
+};

package/src/runtime/execute.ts

@@ -0,0 +1,36 @@
+import { TableDef } from '../schema/table';
+import { Entity } from '../schema/types';
+import { hydrateRows } from './hydration';
+import { OrmContext } from './orm-context';
+import { SelectQueryBuilder } from '../builder/select';
+import { createEntityFromRow } from './entity';
+
+type Row = Record<string, any>;
+
+const flattenResults = (results: { columns: string[]; values: unknown[][] }[]): Row[] => {
+  const rows: Row[] = [];
+  for (const result of results) {
+    const { columns, values } = result;
+    for (const valueRow of values) {
+      const row: Row = {};
+      columns.forEach((column, idx) => {
+        row[column] = valueRow[idx];
+      });
+      rows.push(row);
+    }
+  }
+  return rows;
+};
+
+export async function executeHydrated<TTable extends TableDef>(
+  ctx: OrmContext,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> {
+  const compiled = ctx.dialect.compileSelect(qb.getAST());
+  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  const rows = flattenResults(executed);
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  return hydrated.map(row =>
+    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
+  );
+}

package/src/runtime/hydration.ts

@@ -1,4 +1,4 @@
-import { HydrationPlan } from '../ast/query';
+import { HydrationPlan, HydrationRelationPlan } from '../ast/query';
 import { isRelationAlias, makeRelationAlias } from '../utils/relation-alias';
 
 /**
@@ -7,42 +7,104 @@ import { isRelationAlias, makeRelationAlias } from '../utils/relation-alias';
  * @param plan - Hydration plan
  * @returns Hydrated result objects with nested relations
  */
-export const hydrateRows = (rows: Record<string, any>[], plan?: HydrationPlan): Record<string, any>[] => {
-  if (!plan || !rows.length) return rows;
-
-  const rootMap = new Map<any, any>();
-
-  rows.forEach(row => {
-    const rootId = row[plan.rootPrimaryKey];
-    if (rootId === undefined) return;
-
-    if (!rootMap.has(rootId)) {
-      const base: Record<string, any> = {};
-      const baseKeys = plan.rootColumns.length ? plan.rootColumns : Object.keys(row).filter(k => !isRelationAlias(k));
-      baseKeys.forEach(key => { base[key] = row[key]; });
-      plan.relations.forEach(rel => { base[rel.name] = []; });
-      rootMap.set(rootId, base);
-    }
-
-    const parent = rootMap.get(rootId);
-
-    plan.relations.forEach(rel => {
+export const hydrateRows = (rows: Record<string, any>[], plan?: HydrationPlan): Record<string, any>[] => {
+  if (!plan || !rows.length) return rows;
+
+  const rootMap = new Map<any, Record<string, any>>();
+  const relationIndex = new Map<any, Record<string, Set<any>>>();
+
+  const getOrCreateParent = (row: Record<string, any>) => {
+    const rootId = row[plan.rootPrimaryKey];
+    if (rootId === undefined) return undefined;
+
+    if (!rootMap.has(rootId)) {
+      rootMap.set(rootId, createBaseRow(row, plan));
+    }
+
+    return rootMap.get(rootId);
+  };
+
+  const getRelationSeenSet = (rootId: any, relationName: string): Set<any> => {
+    let byRelation = relationIndex.get(rootId);
+    if (!byRelation) {
+      byRelation = {};
+      relationIndex.set(rootId, byRelation);
+    }
+
+    let seen = byRelation[relationName];
+    if (!seen) {
+      seen = new Set<any>();
+      byRelation[relationName] = seen;
+    }
+
+    return seen;
+  };
+
+  for (const row of rows) {
+    const rootId = row[plan.rootPrimaryKey];
+    if (rootId === undefined) continue;
+
+    const parent = getOrCreateParent(row);
+    if (!parent) continue;
+
+    for (const rel of plan.relations) {
       const childPkKey = makeRelationAlias(rel.aliasPrefix, rel.targetPrimaryKey);
       const childPk = row[childPkKey];
-      if (childPk === null || childPk === undefined) return;
-
-      const bucket = parent[rel.name] as any[];
-      if (bucket.some(item => item[rel.targetPrimaryKey] === childPk)) return;
-
-      const child: Record<string, any> = {};
-      rel.columns.forEach(col => {
-        const key = makeRelationAlias(rel.aliasPrefix, col);
-        child[col] = row[key];
-      });
-
-      bucket.push(child);
-    });
-  });
-
-  return Array.from(rootMap.values());
-};
+      if (childPk === null || childPk === undefined) continue;
+
+      const seen = getRelationSeenSet(rootId, rel.name);
+      if (seen.has(childPk)) continue;
+      seen.add(childPk);
+
+      const bucket = parent[rel.name] as any[];
+      bucket.push(buildChild(row, rel));
+    }
+  }
+
+  return Array.from(rootMap.values());
+};
+
+const createBaseRow = (row: Record<string, any>, plan: HydrationPlan): Record<string, any> => {
+  const base: Record<string, any> = {};
+  const baseKeys = plan.rootColumns.length
+    ? plan.rootColumns
+    : Object.keys(row).filter(k => !isRelationAlias(k));
+
+  for (const key of baseKeys) {
+    base[key] = row[key];
+  }
+
+  for (const rel of plan.relations) {
+    base[rel.name] = [];
+  }
+
+  return base;
+};
+
+const buildChild = (row: Record<string, any>, rel: HydrationRelationPlan): Record<string, any> => {
+  const child: Record<string, any> = {};
+  for (const col of rel.columns) {
+    const key = makeRelationAlias(rel.aliasPrefix, col);
+    child[col] = row[key];
+  }
+
+  const pivot = buildPivot(row, rel);
+  if (pivot) {
+    (child as any)._pivot = pivot;
+  }
+
+  return child;
+};
+
+const buildPivot = (row: Record<string, any>, rel: HydrationRelationPlan): Record<string, any> | undefined => {
+  if (!rel.pivot) return undefined;
+
+  const pivot: Record<string, any> = {};
+  for (const col of rel.pivot.columns) {
+    const key = makeRelationAlias(rel.pivot.aliasPrefix, col);
+    pivot[col] = row[key];
+  }
+
+  const hasValue = Object.values(pivot).some(v => v !== null && v !== undefined);
+  return hasValue ? pivot : undefined;
+};