metal-orm 1.1.11 → 1.1.16

package/src/orm/entity-materializer.ts

@@ -1,159 +1,159 @@
-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).
- */
-export interface EntityMaterializationStrategy {
-    /**
-     * Creates an instance of the entity class and populates it with data.
-     * @param ctor - The entity constructor
-     * @param data - The raw data to populate
-     * @returns The materialized entity instance
-     */
-    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
-}
-
-/**
- * Default strategy: Uses Object.create() to create instance without calling constructor.
- * Safe for classes with required constructor parameters.
- */
-export class PrototypeMaterializationStrategy implements EntityMaterializationStrategy {
-    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
-        const instance = Object.create(ctor.prototype) as T;
-        Object.assign(instance, data);
-        return instance;
-    }
-}
-
-/**
- * Alternative strategy: Calls default constructor then assigns properties.
- * Use when class constructor initializes important state.
- */
-export class ConstructorMaterializationStrategy implements EntityMaterializationStrategy {
-    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
-        const instance = Reflect.construct(ctor, []) as T & Record<string, unknown>;
-        Object.assign(instance, data);
-        return instance;
-    }
-}
-
-/**
- * Interface for materializing query results into real entity class instances.
- */
-export interface EntityMaterializer {
-    /**
-     * Materializes a single row into a real entity instance.
-     * @param entityClass - The entity constructor
-     * @param row - The raw data row
-     * @returns The materialized entity instance
-     */
-    materialize<T>(entityClass: EntityConstructor<T>, row: Record<string, unknown>): T;
-
-    /**
-     * Materializes multiple rows into real entity instances.
-     * @param entityClass - The entity constructor
-     * @param rows - The raw data rows
-     * @returns Array of materialized entity instances
-     */
-    materializeMany<T>(entityClass: EntityConstructor<T>, rows: Record<string, unknown>[]): T[];
-}
-
-/**
- * Default implementation of EntityMaterializer.
- * Converts query results into actual class instances with working methods.
- * 
- * @example
- * const materializer = new DefaultEntityMaterializer();
- * const users = materializer.materializeMany(User, queryResults);
- * 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;
-    }
-
-    materializeMany<T>(ctor: EntityConstructor<T>, rows: Record<string, unknown>[]): T[] {
-        return rows.map(row => this.materialize(ctor, row));
-    }
-
-    /**
-     * 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;
-
-            // Handle has-one / belongs-to (single object)
-            if (typeof value === 'object' && !Array.isArray(value)) {
-                const nested = value as Record<string, unknown>;
-                // Check if this looks like an entity (has common entity patterns)
-                if (this.isEntityLike(nested)) {
-                    // For now, keep as-is since we don't have relation metadata here
-                    // Future: use relation metadata to get target constructor
-                }
-            }
-
-            // Handle has-many / belongs-to-many (array)
-            if (Array.isArray(value) && value.length > 0) {
-                const first = value[0];
-                if (typeof first === 'object' && first !== null && this.isEntityLike(first)) {
-                    // For now, keep array as-is
-                    // Future: materialize each item if we can resolve the target class
-                }
-            }
-        }
-    }
-
-    /**
-     * 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;
-    }
-}
-
-/**
- * Convenience function to materialize query results as real class instances.
- * 
- * @example
- * const results = await selectFromEntity(User).execute(session);
- * const users = materializeAs(User, results);
- * users[0] instanceof User; // true!
- */
-export const materializeAs = <TEntity extends object>(
-    ctor: EntityConstructor<TEntity>,
-    results: Record<string, unknown>[]
-): TEntity[] => {
-    const materializer = new DefaultEntityMaterializer();
-    return materializer.materializeMany(ctor, results);
-};
+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).
+ */
+export interface EntityMaterializationStrategy {
+    /**
+     * Creates an instance of the entity class and populates it with data.
+     * @param ctor - The entity constructor
+     * @param data - The raw data to populate
+     * @returns The materialized entity instance
+     */
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
+}
+
+/**
+ * Default strategy: Uses Object.create() to create instance without calling constructor.
+ * Safe for classes with required constructor parameters.
+ */
+export class PrototypeMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
+        const instance = Object.create(ctor.prototype) as T;
+        Object.assign(instance, data);
+        return instance;
+    }
+}
+
+/**
+ * Alternative strategy: Calls default constructor then assigns properties.
+ * Use when class constructor initializes important state.
+ */
+export class ConstructorMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
+        const instance = Reflect.construct(ctor, []) as T & Record<string, unknown>;
+        Object.assign(instance, data);
+        return instance;
+    }
+}
+
+/**
+ * Interface for materializing query results into real entity class instances.
+ */
+export interface EntityMaterializer {
+    /**
+     * Materializes a single row into a real entity instance.
+     * @param entityClass - The entity constructor
+     * @param row - The raw data row
+     * @returns The materialized entity instance
+     */
+    materialize<T>(entityClass: EntityConstructor<T>, row: Record<string, unknown>): T;
+
+    /**
+     * Materializes multiple rows into real entity instances.
+     * @param entityClass - The entity constructor
+     * @param rows - The raw data rows
+     * @returns Array of materialized entity instances
+     */
+    materializeMany<T>(entityClass: EntityConstructor<T>, rows: Record<string, unknown>[]): T[];
+}
+
+/**
+ * Default implementation of EntityMaterializer.
+ * Converts query results into actual class instances with working methods.
+ * 
+ * @example
+ * const materializer = new DefaultEntityMaterializer();
+ * const users = materializer.materializeMany(User, queryResults);
+ * 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;
+    }
+
+    materializeMany<T>(ctor: EntityConstructor<T>, rows: Record<string, unknown>[]): T[] {
+        return rows.map(row => this.materialize(ctor, row));
+    }
+
+    /**
+     * 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;
+
+            // Handle has-one / belongs-to (single object)
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                const nested = value as Record<string, unknown>;
+                // Check if this looks like an entity (has common entity patterns)
+                if (this.isEntityLike(nested)) {
+                    // For now, keep as-is since we don't have relation metadata here
+                    // Future: use relation metadata to get target constructor
+                }
+            }
+
+            // Handle has-many / belongs-to-many (array)
+            if (Array.isArray(value) && value.length > 0) {
+                const first = value[0];
+                if (typeof first === 'object' && first !== null && this.isEntityLike(first)) {
+                    // For now, keep array as-is
+                    // Future: materialize each item if we can resolve the target class
+                }
+            }
+        }
+    }
+
+    /**
+     * 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;
+    }
+}
+
+/**
+ * Convenience function to materialize query results as real class instances.
+ * 
+ * @example
+ * const results = await selectFromEntity(User).execute(session);
+ * const users = materializeAs(User, results);
+ * users[0] instanceof User; // true!
+ */
+export const materializeAs = <TEntity extends object>(
+    ctor: EntityConstructor<TEntity>,
+    results: Record<string, unknown>[]
+): TEntity[] => {
+    const materializer = new DefaultEntityMaterializer();
+    return materializer.materializeMany(ctor, results);
+};

package/src/orm/entity-meta.ts

@@ -1,97 +1,97 @@
-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';
-
-/**
- * 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> {
-  /** 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>;
-  /** Cache for relation promises */
-  relationCache: Map<string, Promise<unknown>>;
-  /** Hydration data for relations */
-  relationHydration: Map<string, Map<string, unknown>>;
-  /** Relation wrapper instances */
-  relationWrappers: Map<string, unknown>;
-}
-
-/**
- * Gets hydration rows for a specific relation and key
- * @param meta - Entity metadata
- * @param relationName - Name of the relation
- * @param key - Key to look up in the hydration map
- * @returns Array of hydration rows or undefined if not found
- * @typeParam TTable - Table definition type
- */
-export const getHydrationRows = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: string,
-  key: unknown
-): Record<string, unknown>[] | 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;
-};
-
-/**
- * Gets a single hydration record for a specific relation and key
- * @param meta - Entity metadata
- * @param relationName - Name of the relation
- * @param key - Key to look up in the hydration map
- * @returns Single hydration record or undefined if not found
- * @typeParam TTable - Table definition type
- */
-export const getHydrationRecord = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: string,
-  key: unknown
-): Record<string, unknown> | 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 as Record<string, unknown>;
-};
-
-/**
- * Gets entity metadata from an entity instance
- * @param entity - Entity instance to get metadata from
- * @returns Entity metadata or undefined if not found
- * @typeParam TTable - Table definition type
- */
-export const getEntityMeta = <TTable extends TableDef>(entity: unknown): EntityMeta<TTable> | undefined => {
-  if (!entity || typeof entity !== 'object') return undefined;
-  return (entity as { [ENTITY_META]: EntityMeta<TTable> })[ENTITY_META];
-};
-
-/**
- * Checks if an entity has metadata attached
- * @param entity - Entity instance to check
- * @returns True if the entity has metadata, false otherwise
- */
-export const hasEntityMeta = (entity: unknown): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
-  return Boolean(getEntityMeta(entity));
-};
+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';
+
+/**
+ * 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> {
+  /** 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>;
+  /** Cache for relation promises */
+  relationCache: Map<string, Promise<unknown>>;
+  /** Hydration data for relations */
+  relationHydration: Map<string, Map<string, unknown>>;
+  /** Relation wrapper instances */
+  relationWrappers: Map<string, unknown>;
+}
+
+/**
+ * Gets hydration rows for a specific relation and key
+ * @param meta - Entity metadata
+ * @param relationName - Name of the relation
+ * @param key - Key to look up in the hydration map
+ * @returns Array of hydration rows or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
+export const getHydrationRows = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  key: unknown
+): Record<string, unknown>[] | 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;
+};
+
+/**
+ * Gets a single hydration record for a specific relation and key
+ * @param meta - Entity metadata
+ * @param relationName - Name of the relation
+ * @param key - Key to look up in the hydration map
+ * @returns Single hydration record or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
+export const getHydrationRecord = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  key: unknown
+): Record<string, unknown> | 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 as Record<string, unknown>;
+};
+
+/**
+ * Gets entity metadata from an entity instance
+ * @param entity - Entity instance to get metadata from
+ * @returns Entity metadata or undefined if not found
+ * @typeParam TTable - Table definition type
+ */
+export const getEntityMeta = <TTable extends TableDef>(entity: unknown): EntityMeta<TTable> | undefined => {
+  if (!entity || typeof entity !== 'object') return undefined;
+  return (entity as { [ENTITY_META]: EntityMeta<TTable> })[ENTITY_META];
+};
+
+/**
+ * Checks if an entity has metadata attached
+ * @param entity - Entity instance to check
+ * @returns True if the entity has metadata, false otherwise
+ */
+export const hasEntityMeta = (entity: unknown): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
+  return Boolean(getEntityMeta(entity));
+};

package/src/orm/entity-registry.ts

@@ -1,39 +1,39 @@
-import { TableDef } from '../schema/table.js';
-import { EntityConstructor, getAllEntityMetadata } from './entity-metadata.js';
-
-/**
- * Reverse lookup registry: TableDef → EntityConstructor
- */
-const tableToConstructor = new Map<TableDef, EntityConstructor>();
-
-/**
- * Gets the entity constructor for a given table definition.
- * @param table - The table definition
- * @returns The entity constructor or undefined if not found
- */
-export const getConstructorForTable = (table: TableDef): EntityConstructor | undefined => {
-    if (!tableToConstructor.size) {
-        rebuildRegistry();
-    }
-    return tableToConstructor.get(table);
-};
-
-/**
- * Rebuilds the registry from entity metadata.
- * Called automatically on first lookup or when metadata changes.
- */
-export const rebuildRegistry = (): void => {
-    tableToConstructor.clear();
-    for (const meta of getAllEntityMetadata()) {
-        if (meta.table) {
-            tableToConstructor.set(meta.table, meta.target);
-        }
-    }
-};
-
-/**
- * Clears the entity registry.
- */
-export const clearEntityRegistry = (): void => {
-    tableToConstructor.clear();
-};
+import { TableDef } from '../schema/table.js';
+import { EntityConstructor, getAllEntityMetadata } from './entity-metadata.js';
+
+/**
+ * Reverse lookup registry: TableDef → EntityConstructor
+ */
+const tableToConstructor = new Map<TableDef, EntityConstructor>();
+
+/**
+ * Gets the entity constructor for a given table definition.
+ * @param table - The table definition
+ * @returns The entity constructor or undefined if not found
+ */
+export const getConstructorForTable = (table: TableDef): EntityConstructor | undefined => {
+    if (!tableToConstructor.size) {
+        rebuildRegistry();
+    }
+    return tableToConstructor.get(table);
+};
+
+/**
+ * Rebuilds the registry from entity metadata.
+ * Called automatically on first lookup or when metadata changes.
+ */
+export const rebuildRegistry = (): void => {
+    tableToConstructor.clear();
+    for (const meta of getAllEntityMetadata()) {
+        if (meta.table) {
+            tableToConstructor.set(meta.table, meta.target);
+        }
+    }
+};
+
+/**
+ * Clears the entity registry.
+ */
+export const clearEntityRegistry = (): void => {
+    tableToConstructor.clear();
+};