metal-orm 1.0.66 → 1.0.68

package/src/core/dialect/abstract.ts

@@ -31,10 +31,10 @@ import {
   isOperandNode
 } from '../ast/expression.js';
 import { DialectName } from '../sql/sql.js';
-import type { FunctionStrategy } from '../functions/types.js';
-import { StandardFunctionStrategy } from '../functions/standard-strategy.js';
-import type { TableFunctionStrategy } from '../functions/table-types.js';
-import { StandardTableFunctionStrategy } from '../functions/standard-table-strategy.js';
+import type { FunctionStrategy } from '../functions/types.js';
+import { StandardFunctionStrategy } from '../functions/standard-strategy.js';
+import type { TableFunctionStrategy } from '../functions/table-types.js';
+import { StandardTableFunctionStrategy } from '../functions/standard-table-strategy.js';
 
 /**
  * Context for SQL compilation with parameter management
@@ -291,26 +291,26 @@ export abstract class Dialect
     return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
   }
 
-  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
-  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
-  protected readonly functionStrategy: FunctionStrategy;
-  protected readonly tableFunctionStrategy: TableFunctionStrategy;
-
-  protected constructor(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy) {
-    this.expressionCompilers = new Map();
-    this.operandCompilers = new Map();
-    this.functionStrategy = functionStrategy || new StandardFunctionStrategy();
-    this.tableFunctionStrategy = tableFunctionStrategy || new StandardTableFunctionStrategy();
-    this.registerDefaultOperandCompilers();
-    this.registerDefaultExpressionCompilers();
-  }
+  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
+  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
+  protected readonly functionStrategy: FunctionStrategy;
+  protected readonly tableFunctionStrategy: TableFunctionStrategy;
+
+  protected constructor(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy) {
+    this.expressionCompilers = new Map();
+    this.operandCompilers = new Map();
+    this.functionStrategy = functionStrategy || new StandardFunctionStrategy();
+    this.tableFunctionStrategy = tableFunctionStrategy || new StandardTableFunctionStrategy();
+    this.registerDefaultOperandCompilers();
+    this.registerDefaultExpressionCompilers();
+  }
 
   /**
    * Creates a new Dialect instance (for testing purposes)
    * @param functionStrategy - Optional function strategy
    * @returns New Dialect instance
    */
-  static create(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy): Dialect {
+  static create(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy): Dialect {
     // Create a minimal concrete implementation for testing
     class TestDialect extends Dialect {
       protected readonly dialect: DialectName = 'sqlite';
@@ -330,8 +330,8 @@ export abstract class Dialect
         throw new Error('Not implemented');
       }
     }
-    return new TestDialect(functionStrategy, tableFunctionStrategy);
-  }
+    return new TestDialect(functionStrategy, tableFunctionStrategy);
+  }
 
   /**
    * Registers an expression compiler for a specific node type

package/src/core/functions/array.ts

@@ -1,35 +1,35 @@
-// Pure AST Builders - No Dialect Logic Here!
-
-import { ColumnDef } from '../../schema/column-types.js';
-import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
-import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
-
-type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
-
-const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
-
-const toOperand = (input: OperandInput): OperandNode => {
-    if (isOperandNode(input)) return input;
-    if (isColumnDef(input)) return columnOperand(input);
-
-    return valueToOperand(input);
-};
-
-const fn = (key: string, args: OperandInput[]): FunctionNode => ({
-    type: 'Function',
-    name: key,
-    fn: key,
-    args: args.map(toOperand)
-});
-
-const afn = <T = unknown[]>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
-
-/**
- * Appends a value to the end of an array.
- * 
- * @param array - Array column or value.
- * @param value - Value to append.
- * @returns A `TypedExpression<unknown[]>` representing the `ARRAY_APPEND` SQL function.
- */
-export const arrayAppend = (array: OperandInput, value: OperandInput): TypedExpression<unknown[]> =>
-    afn<unknown[]>('ARRAY_APPEND', [array, value]);
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column-types.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+    if (isOperandNode(input)) return input;
+    if (isColumnDef(input)) return columnOperand(input);
+
+    return valueToOperand(input);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+    type: 'Function',
+    name: key,
+    fn: key,
+    args: args.map(toOperand)
+});
+
+const afn = <T = unknown[]>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+
+/**
+ * Appends a value to the end of an array.
+ * 
+ * @param array - Array column or value.
+ * @param value - Value to append.
+ * @returns A `TypedExpression<unknown[]>` representing the `ARRAY_APPEND` SQL function.
+ */
+export const arrayAppend = (array: OperandInput, value: OperandInput): TypedExpression<unknown[]> =>
+    afn<unknown[]>('ARRAY_APPEND', [array, value]);

package/src/core/functions/json.ts

@@ -1,70 +1,70 @@
-// Pure AST Builders - No Dialect Logic Here!
-
-import { ColumnDef } from '../../schema/column-types.js';
-import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
-import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
-
-type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
-
-const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
-
-const toOperand = (input: OperandInput): OperandNode => {
-    if (isOperandNode(input)) return input;
-    if (isColumnDef(input)) return columnOperand(input);
-
-    return valueToOperand(input);
-};
-
-const fn = (key: string, args: OperandInput[]): FunctionNode => ({
-    type: 'Function',
-    name: key,
-    fn: key,
-    args: args.map(toOperand)
-});
-
-const nfn = (key: string, args: OperandInput[]): TypedExpression<number> => asType<number>(fn(key, args));
-const afn = <T = unknown>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
-
-/**
- * Returns the number of elements in a JSON array or object.
- * 
- * @param target - JSON column or value.
- * @param path - Optional JSON path.
- * @returns A `TypedExpression<number>` representing the `JSON_LENGTH` SQL function.
- */
-export const jsonLength = (target: OperandInput, path?: OperandInput): TypedExpression<number> =>
-    path === undefined ? nfn('JSON_LENGTH', [target]) : nfn('JSON_LENGTH', [target, path]);
-
-/**
- * Inserts or updates a value in a JSON document.
- * 
- * @param target - JSON column or value.
- * @param path - JSON path to set.
- * @param value - Value to set.
- * @returns A `TypedExpression<T>` representing the `JSON_SET` SQL function.
- */
-export const jsonSet = <T = unknown>(target: OperandInput, path: OperandInput, value: OperandInput): TypedExpression<T> =>
-    afn<T>('JSON_SET', [target, path, value]);
-
-/**
- * Aggregates values into a JSON array.
- * 
- * @param value - Column or expression to aggregate.
- * @returns A `TypedExpression<unknown[]>` representing the `JSON_ARRAYAGG` SQL function.
- */
-export const jsonArrayAgg = (value: OperandInput): TypedExpression<unknown[]> => afn<unknown[]>('JSON_ARRAYAGG', [value]);
-
-/**
- * Checks if a JSON document contains a specific piece of data.
- * 
- * @param target - JSON column or value.
- * @param candidate - Data to look for.
- * @param path - Optional JSON path to search within.
- * @returns A `TypedExpression<boolean>` representing the `JSON_CONTAINS` SQL function.
- */
-export const jsonContains = (
-    target: OperandInput,
-    candidate: OperandInput,
-    path?: OperandInput
-): TypedExpression<boolean> =>
-    path === undefined ? afn<boolean>('JSON_CONTAINS', [target, candidate]) : afn<boolean>('JSON_CONTAINS', [target, candidate, path]);
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column-types.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+    if (isOperandNode(input)) return input;
+    if (isColumnDef(input)) return columnOperand(input);
+
+    return valueToOperand(input);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+    type: 'Function',
+    name: key,
+    fn: key,
+    args: args.map(toOperand)
+});
+
+const nfn = (key: string, args: OperandInput[]): TypedExpression<number> => asType<number>(fn(key, args));
+const afn = <T = unknown>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+
+/**
+ * Returns the number of elements in a JSON array or object.
+ * 
+ * @param target - JSON column or value.
+ * @param path - Optional JSON path.
+ * @returns A `TypedExpression<number>` representing the `JSON_LENGTH` SQL function.
+ */
+export const jsonLength = (target: OperandInput, path?: OperandInput): TypedExpression<number> =>
+    path === undefined ? nfn('JSON_LENGTH', [target]) : nfn('JSON_LENGTH', [target, path]);
+
+/**
+ * Inserts or updates a value in a JSON document.
+ * 
+ * @param target - JSON column or value.
+ * @param path - JSON path to set.
+ * @param value - Value to set.
+ * @returns A `TypedExpression<T>` representing the `JSON_SET` SQL function.
+ */
+export const jsonSet = <T = unknown>(target: OperandInput, path: OperandInput, value: OperandInput): TypedExpression<T> =>
+    afn<T>('JSON_SET', [target, path, value]);
+
+/**
+ * Aggregates values into a JSON array.
+ * 
+ * @param value - Column or expression to aggregate.
+ * @returns A `TypedExpression<unknown[]>` representing the `JSON_ARRAYAGG` SQL function.
+ */
+export const jsonArrayAgg = (value: OperandInput): TypedExpression<unknown[]> => afn<unknown[]>('JSON_ARRAYAGG', [value]);
+
+/**
+ * Checks if a JSON document contains a specific piece of data.
+ * 
+ * @param target - JSON column or value.
+ * @param candidate - Data to look for.
+ * @param path - Optional JSON path to search within.
+ * @returns A `TypedExpression<boolean>` representing the `JSON_CONTAINS` SQL function.
+ */
+export const jsonContains = (
+    target: OperandInput,
+    candidate: OperandInput,
+    path?: OperandInput
+): TypedExpression<boolean> =>
+    path === undefined ? afn<boolean>('JSON_CONTAINS', [target, candidate]) : afn<boolean>('JSON_CONTAINS', [target, candidate, path]);

package/src/orm/entity-hydration.ts

@@ -1,72 +1,72 @@
-import { TableDef } from '../schema/table.js';
-import { RelationKinds } from '../schema/relation.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import { EntityMeta } from './entity-meta.js';
-
-/**
- * Type representing an array of database rows.
- */
-type Rows = Record<string, unknown>[];
-
-/**
- * Converts a value to a string key.
- * @param value - The value to convert
- * @returns String representation of the value
- */
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-/**
- * Populates the hydration cache with relation data from the database row.
- * @template TTable - The table type
- * @param entity - The entity instance
- * @param row - The database row
- * @param meta - The entity metadata
- */
-export const populateHydrationCache = <TTable extends TableDef>(
-  entity: Record<string, unknown>,
-  row: Record<string, unknown>,
-  meta: EntityMeta<TTable>
-): void => {
-  for (const relationName of Object.keys(meta.table.relations)) {
-    const relation = meta.table.relations[relationName];
-    const data = row[relationName];
-    if (relation.type === RelationKinds.HasOne) {
-      const localKey = relation.localKey || findPrimaryKey(meta.table);
-      const rootValue = entity[localKey];
-      if (rootValue === undefined || rootValue === null) continue;
-      if (!data || typeof data !== 'object') continue;
-      const cache = new Map<string, Record<string, unknown>>();
-      cache.set(toKey(rootValue), data as Record<string, unknown>);
-      meta.relationHydration.set(relationName, cache);
-      meta.relationCache.set(relationName, Promise.resolve(cache));
-      continue;
-    }
-
-    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, unknown>>();
-      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));
-      }
-    }
-  }
-};
+import { TableDef } from '../schema/table.js';
+import { RelationKinds } from '../schema/relation.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import { EntityMeta } from './entity-meta.js';
+
+/**
+ * Type representing an array of database rows.
+ */
+type Rows = Record<string, unknown>[];
+
+/**
+ * Converts a value to a string key.
+ * @param value - The value to convert
+ * @returns String representation of the value
+ */
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+/**
+ * Populates the hydration cache with relation data from the database row.
+ * @template TTable - The table type
+ * @param entity - The entity instance
+ * @param row - The database row
+ * @param meta - The entity metadata
+ */
+export const populateHydrationCache = <TTable extends TableDef>(
+  entity: Record<string, unknown>,
+  row: Record<string, unknown>,
+  meta: EntityMeta<TTable>
+): void => {
+  for (const relationName of Object.keys(meta.table.relations)) {
+    const relation = meta.table.relations[relationName];
+    const data = row[relationName];
+    if (relation.type === RelationKinds.HasOne) {
+      const localKey = relation.localKey || findPrimaryKey(meta.table);
+      const rootValue = entity[localKey];
+      if (rootValue === undefined || rootValue === null) continue;
+      if (!data || typeof data !== 'object') continue;
+      const cache = new Map<string, Record<string, unknown>>();
+      cache.set(toKey(rootValue), data as Record<string, unknown>);
+      meta.relationHydration.set(relationName, cache);
+      meta.relationCache.set(relationName, Promise.resolve(cache));
+      continue;
+    }
+
+    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, unknown>>();
+      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));
+      }
+    }
+  }
+};

package/src/orm/entity-materializer.ts

@@ -1,6 +1,6 @@
-import { EntityConstructor } from './entity-metadata.js';
-import { rebuildRegistry } from './entity-registry.js';
-import { hasEntityMeta } from './entity-meta.js';
+import { EntityConstructor } from './entity-metadata.js';
+import { rebuildRegistry } from './entity-registry.js';
+import { hasEntityMeta } from './entity-meta.js';
 
 /**
  * Strategy interface for materializing entity instances (Open/Closed Principle).
@@ -70,20 +70,20 @@ export interface EntityMaterializer {
  * users[0] instanceof User; // true
  * users[0].getFullName();   // works!
  */
-export class DefaultEntityMaterializer implements EntityMaterializer {
-    constructor(
-        private readonly strategy: EntityMaterializationStrategy = new ConstructorMaterializationStrategy()
-    ) { }
-
-    materialize<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
-        if (hasEntityMeta(row)) {
-            return this.materializeEntityProxy(ctor, row);
-        }
-
-        const instance = this.strategy.materialize(ctor, row);
-        this.materializeRelations(instance as Record<string, unknown>);
-        return instance;
-    }
+export class DefaultEntityMaterializer implements EntityMaterializer {
+    constructor(
+        private readonly strategy: EntityMaterializationStrategy = new ConstructorMaterializationStrategy()
+    ) { }
+
+    materialize<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
+        if (hasEntityMeta(row)) {
+            return this.materializeEntityProxy(ctor, row);
+        }
+
+        const instance = this.strategy.materialize(ctor, row);
+        this.materializeRelations(instance as Record<string, unknown>);
+        return instance;
+    }
 
     materializeMany<T>(ctor: EntityConstructor<T>, rows: Record<string, unknown>[]): T[] {
         return rows.map(row => this.materialize(ctor, row));
@@ -92,12 +92,12 @@ export class DefaultEntityMaterializer implements EntityMaterializer {
     /**
      * Recursively materializes nested relation data.
      */
-    private materializeRelations(instance: Record<string, unknown>): void {
-        // Rebuild registry to ensure we have latest metadata
-        rebuildRegistry();
-
-        for (const value of Object.values(instance)) {
-            if (value === null || value === undefined) continue;
+    private materializeRelations(instance: Record<string, unknown>): void {
+        // Rebuild registry to ensure we have latest metadata
+        rebuildRegistry();
+
+        for (const value of Object.values(instance)) {
+            if (value === null || value === undefined) continue;
 
             // Handle has-one / belongs-to (single object)
             if (typeof value === 'object' && !Array.isArray(value)) {
@@ -123,24 +123,24 @@ export class DefaultEntityMaterializer implements EntityMaterializer {
     /**
      * Simple heuristic to check if an object looks like an entity.
      */
-    private isEntityLike(obj: Record<string, unknown>): boolean {
-        return 'id' in obj || Object.keys(obj).some(k =>
-            k.endsWith('Id') || k === 'createdAt' || k === 'updatedAt'
-        );
-    }
-
-    private materializeEntityProxy<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
-        const proxy = row as Record<string, unknown>;
-        const baseline = this.strategy.materialize(ctor, {}) as Record<string, unknown>;
-        for (const key of Object.keys(baseline)) {
-            if (!Object.prototype.hasOwnProperty.call(proxy, key)) {
-                proxy[key] = baseline[key];
-            }
-        }
-        Object.setPrototypeOf(proxy, ctor.prototype);
-        return proxy as T;
-    }
-}
+    private isEntityLike(obj: Record<string, unknown>): boolean {
+        return 'id' in obj || Object.keys(obj).some(k =>
+            k.endsWith('Id') || k === 'createdAt' || k === 'updatedAt'
+        );
+    }
+
+    private materializeEntityProxy<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
+        const proxy = row as Record<string, unknown>;
+        const baseline = this.strategy.materialize(ctor, {}) as Record<string, unknown>;
+        for (const key of Object.keys(baseline)) {
+            if (!Object.prototype.hasOwnProperty.call(proxy, key)) {
+                proxy[key] = baseline[key];
+            }
+        }
+        Object.setPrototypeOf(proxy, ctor.prototype);
+        return proxy as T;
+    }
+}
 
 /**
  * Convenience function to materialize query results as real class instances.

package/src/orm/entity-meta.ts

@@ -1,30 +1,30 @@
-import { TableDef } from '../schema/table.js';
-import { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { TableDef } from '../schema/table.js';
+import { RelationIncludeOptions } from '../query-builder/relation-types.js';
 import { EntityContext } from './entity-context.js';
-import { RelationMap } from '../schema/types.js';
+import { RelationMap } from '../schema/types.js';
 
 /**
  * Symbol used to store entity metadata on entity instances
  */
-export const ENTITY_META = Symbol('EntityMeta');
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-export type RelationKey<TTable extends TableDef> = Extract<keyof RelationMap<TTable>, string>;
-
-/**
- * Metadata stored on entity instances for ORM internal use
- * @typeParam TTable - Table definition type
- */
-export interface EntityMeta<TTable extends TableDef> {
+export const ENTITY_META = Symbol('EntityMeta');
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+export type RelationKey<TTable extends TableDef> = Extract<keyof RelationMap<TTable>, string>;
+
+/**
+ * Metadata stored on entity instances for ORM internal use
+ * @typeParam TTable - Table definition type
+ */
+export interface EntityMeta<TTable extends TableDef> {
   /** Entity context */
   ctx: EntityContext;
   /** Table definition */
   table: TTable;
-  /** Relations that should be loaded lazily */
-  lazyRelations: RelationKey<TTable>[];
-  /** Include options for lazy relations */
-  lazyRelationOptions: Map<string, RelationIncludeOptions>;
+  /** Relations that should be loaded lazily */
+  lazyRelations: RelationKey<TTable>[];
+  /** Include options for lazy relations */
+  lazyRelationOptions: Map<string, RelationIncludeOptions>;
   /** Cache for relation promises */
   relationCache: Map<string, Promise<unknown>>;
   /** Hydration data for relations */