metal-orm 1.0.5 → 1.0.7

package/src/constants/sql-operator-config.ts

@@ -19,8 +19,11 @@ export interface SqlOperatorConfig {
  */
 export const SQL_OPERATOR_REGISTRY: Record<SqlOperator, SqlOperatorConfig> = {
   [SQL_OPERATORS.EQUALS]: { sql: SQL_OPERATORS.EQUALS, tsName: 'eq' },
+  [SQL_OPERATORS.NOT_EQUALS]: { sql: SQL_OPERATORS.NOT_EQUALS, tsName: 'neq' },
   [SQL_OPERATORS.GREATER_THAN]: { sql: SQL_OPERATORS.GREATER_THAN, tsName: 'gt' },
+  [SQL_OPERATORS.GREATER_OR_EQUAL]: { sql: SQL_OPERATORS.GREATER_OR_EQUAL, tsName: 'gte' },
   [SQL_OPERATORS.LESS_THAN]: { sql: SQL_OPERATORS.LESS_THAN, tsName: 'lt' },
+  [SQL_OPERATORS.LESS_OR_EQUAL]: { sql: SQL_OPERATORS.LESS_OR_EQUAL, tsName: 'lte' },
   [SQL_OPERATORS.LIKE]: { sql: SQL_OPERATORS.LIKE, tsName: 'like' },
   [SQL_OPERATORS.NOT_LIKE]: { sql: SQL_OPERATORS.NOT_LIKE, tsName: 'notLike' },
   [SQL_OPERATORS.IN]: { sql: SQL_OPERATORS.IN, tsName: 'inList' },

package/src/constants/sql.ts

@@ -33,38 +33,44 @@ export const SQL_KEYWORDS = {
 /**
  * SQL operators used in query conditions
  */
-export const SQL_OPERATORS = {
-  /** Equality operator */
-  EQUALS: '=',
-  /** Greater than operator */
-  GREATER_THAN: '>',
-  /** Less than operator */
-  LESS_THAN: '<',
-  /** LIKE pattern matching operator */
-  LIKE: 'LIKE',
-  /** NOT LIKE pattern matching operator */
-  NOT_LIKE: 'NOT LIKE',
-  /** IN membership operator */
-  IN: 'IN',
-  /** NOT IN membership operator */
-  NOT_IN: 'NOT IN',
-  /** BETWEEN range operator */
-  BETWEEN: 'BETWEEN',
-  /** NOT BETWEEN range operator */
-  NOT_BETWEEN: 'NOT BETWEEN',
-  /** IS NULL null check operator */
-  IS_NULL: 'IS NULL',
-  /** IS NOT NULL null check operator */
-  IS_NOT_NULL: 'IS NOT NULL',
-  /** Logical AND operator */
-  AND: 'AND',
-  /** Logical OR operator */
-  OR: 'OR',
-  /** EXISTS operator */
-  EXISTS: 'EXISTS',
-  /** NOT EXISTS operator */
-  NOT_EXISTS: 'NOT EXISTS'
-} as const;
+export const SQL_OPERATORS = {
+  /** Equality operator */
+  EQUALS: '=',
+  /** Not equals operator */
+  NOT_EQUALS: '!=',
+  /** Greater than operator */
+  GREATER_THAN: '>',
+  /** Greater than or equal operator */
+  GREATER_OR_EQUAL: '>=',
+  /** Less than operator */
+  LESS_THAN: '<',
+  /** Less than or equal operator */
+  LESS_OR_EQUAL: '<=',
+  /** LIKE pattern matching operator */
+  LIKE: 'LIKE',
+  /** NOT LIKE pattern matching operator */
+  NOT_LIKE: 'NOT LIKE',
+  /** IN membership operator */
+  IN: 'IN',
+  /** NOT IN membership operator */
+  NOT_IN: 'NOT IN',
+  /** BETWEEN range operator */
+  BETWEEN: 'BETWEEN',
+  /** NOT BETWEEN range operator */
+  NOT_BETWEEN: 'NOT BETWEEN',
+  /** IS NULL null check operator */
+  IS_NULL: 'IS NULL',
+  /** IS NOT NULL null check operator */
+  IS_NOT_NULL: 'IS NOT NULL',
+  /** Logical AND operator */
+  AND: 'AND',
+  /** Logical OR operator */
+  OR: 'OR',
+  /** EXISTS operator */
+  EXISTS: 'EXISTS',
+  /** NOT EXISTS operator */
+  NOT_EXISTS: 'NOT EXISTS'
+} as const;
 
 /**
  * Type representing any supported SQL operator

package/src/index.ts

@@ -1,15 +1,23 @@
 
-export * from './schema/table';
-export * from './schema/column';
+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 './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/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, belongsToMany } from '../../../../schema/relation';
+import { hasMany, belongsTo, belongsToMany } from '../../../../schema/relation';
 
 export const Users = defineTable('users', {
     id: col.primaryKey(col.int()),
@@ -52,15 +52,15 @@ export const ProjectAssignments = defineTable('project_assignments', {
     assigned_at: col.varchar(50)
 });
 
-Users.relations = {
-    orders: hasMany(Orders, 'user_id'),
-    profiles: hasMany(Profiles, 'user_id'),
-    userRoles: hasMany(UserRoles, 'user_id'),
-    projects: belongsToMany(Projects, ProjectAssignments, {
-        pivotForeignKeyToRoot: 'user_id',
-        pivotForeignKeyToTarget: 'project_id'
-    })
-};
+Users.relations = {
+    orders: hasMany(Orders, 'user_id'),
+    profiles: hasMany(Profiles, 'user_id'),
+    userRoles: hasMany(UserRoles, 'user_id'),
+    projects: belongsToMany(Projects, ProjectAssignments, {
+        pivotForeignKeyToRoot: 'user_id',
+        pivotForeignKeyToTarget: 'project_id'
+    })
+};
 
 Orders.relations = {
     user: belongsTo(Users, 'user_id')

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())
+  );
+}