metal-orm 1.0.57 → 1.0.59

package/src/decorators/decorator-metadata.ts

@@ -1,34 +1,5 @@
 import { ColumnDefLike, RelationMetadata } from '../orm/entity-metadata.js';
 
-/**
- * Context object provided by standard decorators in newer TypeScript versions.
- */
-export interface StandardDecoratorContext {
-  kind: string;
-  name?: string | symbol;
-  metadata?: Record<PropertyKey, unknown>;
-  static?: boolean;
-  private?: boolean;
-}
-
-/**
- * Dual-mode property decorator that supports both legacy and standard decorator syntax.
- */
-export interface DualModePropertyDecorator {
-  (target: object, propertyKey: string | symbol): void;
-  (value: unknown, context: StandardDecoratorContext): void;
-}
-
-/**
- * Dual-mode class decorator that supports both legacy and standard decorator syntax.
- */
-export interface DualModeClassDecorator {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  <TFunction extends Function>(value: TFunction): void | TFunction;
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
-}
-
 /**
  * Bag for storing decorator metadata during the decoration phase.
  */
@@ -39,37 +10,31 @@ export interface DecoratorMetadataBag {
 
 const METADATA_KEY = 'metal-orm:decorators';
 
-/**
- * Checks if a value is a StandardDecoratorContext.
- * @param value - The value to check.
- * @returns True if the value is a StandardDecoratorContext.
- */
-export const isStandardDecoratorContext = (value: unknown): value is StandardDecoratorContext => {
-  return typeof value === 'object' && value !== null && 'kind' in (value as object);
+type MetadataCarrier = {
+  metadata?: Record<PropertyKey, unknown>;
 };
 
 /**
  * Gets or creates a metadata bag for the given decorator context.
- * @param context - The decorator context.
+ * @param context - The decorator context with metadata support.
  * @returns The metadata bag.
  */
-export const getOrCreateMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag => {
+export const getOrCreateMetadataBag = (context: MetadataCarrier): DecoratorMetadataBag => {
   const metadata = context.metadata || (context.metadata = {} as Record<PropertyKey, unknown>);
-  const existing = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
-  if (existing) {
-    return existing;
+  let bag = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
+  if (!bag) {
+    bag = { columns: [], relations: [] };
+    metadata[METADATA_KEY] = bag;
   }
-  const bag: DecoratorMetadataBag = { columns: [], relations: [] };
-  metadata[METADATA_KEY] = bag;
   return bag;
 };
 
 /**
  * Reads the metadata bag from the given decorator context.
- * @param context - The decorator context.
+ * @param context - The decorator context with metadata support.
  * @returns The metadata bag if present.
  */
-export const readMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag | undefined => {
+export const readMetadataBag = (context: MetadataCarrier): DecoratorMetadataBag | undefined => {
   return context.metadata?.[METADATA_KEY] as DecoratorMetadataBag | undefined;
 };
 
@@ -87,7 +52,6 @@ export const readMetadataBagFromConstructor = (ctor: object): DecoratorMetadataB
 
 /**
  * Public helper to read decorator metadata from a class constructor.
- * Standard decorators only; legacy metadata is intentionally ignored.
  * @param ctor - The entity constructor.
  * @returns The metadata bag if present.
  */

package/src/decorators/entity.ts

@@ -7,7 +7,7 @@ import {
   ensureEntityMetadata,
   setEntityTableName
 } from '../orm/entity-metadata.js';
-import { DualModeClassDecorator, isStandardDecoratorContext, readMetadataBag } from './decorator-metadata.js';
+import { readMetadataBag } from './decorator-metadata.js';
 
 /**
  * Options for defining an entity.
@@ -43,51 +43,41 @@ const deriveTableNameFromConstructor = (ctor: EntityConstructor<unknown>): strin
  * @returns A class decorator that registers the entity metadata.
  */
 export function Entity(options: EntityOptions = {}) {
-  const decorator: DualModeClassDecorator = value => {
-    const tableName = options.tableName ?? deriveTableNameFromConstructor(value);
-    setEntityTableName(value as EntityConstructor, tableName, options.hooks);
+  return function <T extends EntityConstructor>(value: T, context: ClassDecoratorContext): T {
+    const ctor = value;
+    const tableName = options.tableName ?? deriveTableNameFromConstructor(ctor);
+    setEntityTableName(ctor, tableName, options.hooks);
 
-    return value;
-  };
-
-  const decoratorWithContext: DualModeClassDecorator = (value, context?) => {
-    const ctor = value as EntityConstructor;
-    decorator(ctor);
-
-    if (context && isStandardDecoratorContext(context)) {
-      const bag = readMetadataBag(context);
-      if (bag) {
-        const meta = ensureEntityMetadata(ctor);
-        for (const entry of bag.columns) {
-          if (meta.columns[entry.propertyName]) {
-            throw new Error(
-              `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
-            );
-          }
-          addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+    const bag = readMetadataBag(context);
+    if (bag) {
+      const meta = ensureEntityMetadata(ctor);
+      for (const entry of bag.columns) {
+        if (meta.columns[entry.propertyName]) {
+          throw new Error(
+            `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+          );
         }
-        for (const entry of bag.relations) {
-          if (meta.relations[entry.propertyName]) {
-            throw new Error(
-              `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
-            );
-          }
-          const relationCopy =
-            entry.relation.kind === RelationKinds.BelongsToMany
-              ? {
-                ...entry.relation,
-                defaultPivotColumns: entry.relation.defaultPivotColumns
-                  ? [...entry.relation.defaultPivotColumns]
-                  : undefined
-              }
-              : { ...entry.relation };
-          addRelationMetadata(ctor, entry.propertyName, relationCopy);
+        addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+      }
+      for (const entry of bag.relations) {
+        if (meta.relations[entry.propertyName]) {
+          throw new Error(
+            `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+          );
         }
+        const relationCopy =
+          entry.relation.kind === RelationKinds.BelongsToMany
+            ? {
+              ...entry.relation,
+              defaultPivotColumns: entry.relation.defaultPivotColumns
+                ? [...entry.relation.defaultPivotColumns]
+                : undefined
+            }
+            : { ...entry.relation };
+        addRelationMetadata(ctor, entry.propertyName, relationCopy);
       }
     }
 
     return ctor;
   };
-
-  return decoratorWithContext;
 }

package/src/decorators/relations.ts

@@ -1,16 +1,10 @@
 import { CascadeMode, RelationKinds } from '../schema/relation.js';
 import {
-  addRelationMetadata,
-  EntityConstructor,
+  EntityOrTableTarget,
   EntityOrTableTargetResolver,
   RelationMetadata
 } from '../orm/entity-metadata.js';
-import {
-  DualModePropertyDecorator,
-  getOrCreateMetadataBag,
-  isStandardDecoratorContext,
-  StandardDecoratorContext
-} from './decorator-metadata.js';
+import { getOrCreateMetadataBag } from './decorator-metadata.js';
 
 interface BaseRelationOptions {
   target: EntityOrTableTargetResolver;
@@ -22,31 +16,34 @@ interface BaseRelationOptions {
  * Options for HasMany relation.
  */
 export interface HasManyOptions extends BaseRelationOptions {
-  foreignKey: string;
+  foreignKey?: string;
 }
 
 /**
  * Options for HasOne relation.
  */
 export interface HasOneOptions extends BaseRelationOptions {
-  foreignKey: string;
+  foreignKey?: string;
 }
 
 /**
  * Options for BelongsTo relation.
  */
 export interface BelongsToOptions extends BaseRelationOptions {
-  foreignKey: string;
+  foreignKey?: string;
 }
 
 /**
  * Options for BelongsToMany relation.
  */
-export interface BelongsToManyOptions {
-  target: EntityOrTableTargetResolver;
-  pivotTable: EntityOrTableTargetResolver;
-  pivotForeignKeyToRoot: string;
-  pivotForeignKeyToTarget: string;
+export interface BelongsToManyOptions<
+  TTarget extends EntityOrTableTarget = EntityOrTableTarget,
+  TPivot extends EntityOrTableTarget = EntityOrTableTarget
+> {
+  target: EntityOrTableTargetResolver<TTarget>;
+  pivotTable: EntityOrTableTargetResolver<TPivot>;
+  pivotForeignKeyToRoot?: string;
+  pivotForeignKeyToTarget?: string;
   localKey?: string;
   targetKey?: string;
   pivotPrimaryKey?: string;
@@ -61,48 +58,22 @@ const normalizePropertyName = (name: string | symbol): string => {
   return name;
 };
 
-const resolveConstructor = (instanceOrCtor: unknown): EntityConstructor | undefined => {
-  if (typeof instanceOrCtor === 'function') {
-    return instanceOrCtor as EntityConstructor;
-  }
-  if (instanceOrCtor && typeof (instanceOrCtor as { constructor: new (...args: unknown[]) => unknown }).constructor === 'function') {
-    return (instanceOrCtor as { constructor: new (...args: unknown[]) => unknown }).constructor as EntityConstructor;
-  }
-  return undefined;
-};
-
-const registerRelation = (ctor: EntityConstructor, propertyName: string, metadata: RelationMetadata): void => {
-  addRelationMetadata(ctor, propertyName, metadata);
-};
-
-const createFieldDecorator = (
-  metadataFactory: (propertyName: string) => RelationMetadata
-) => {
-  const decorator: DualModePropertyDecorator = (targetOrValue, propertyKeyOrContext) => {
-    if (isStandardDecoratorContext(propertyKeyOrContext)) {
-      const ctx = propertyKeyOrContext as StandardDecoratorContext;
-      if (!ctx.name) {
-        throw new Error('Relation decorator requires a property name');
-      }
-      const propertyName = normalizePropertyName(ctx.name);
-      const bag = getOrCreateMetadataBag(ctx);
-      const relationMetadata = metadataFactory(propertyName);
-
-      if (!bag.relations.some(entry => entry.propertyName === propertyName)) {
-        bag.relations.push({ propertyName, relation: relationMetadata });
-      }
-      return;
+const createFieldDecorator = (metadataFactory: (propertyName: string) => RelationMetadata) => {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    if (!context.name) {
+      throw new Error('Relation decorator requires a property name');
     }
+    if (context.private) {
+      throw new Error('Relation decorator does not support private fields');
+    }
+    const propertyName = normalizePropertyName(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    const relationMetadata = metadataFactory(propertyName);
 
-    const propertyName = normalizePropertyName(propertyKeyOrContext);
-    const ctor = resolveConstructor(targetOrValue);
-    if (!ctor) {
-      throw new Error('Unable to resolve constructor when registering relation metadata');
+    if (!bag.relations.some(entry => entry.propertyName === propertyName)) {
+      bag.relations.push({ propertyName, relation: relationMetadata });
     }
-    registerRelation(ctor, propertyName, metadataFactory(propertyName));
   };
-
-  return decorator;
 };
 
 /**
@@ -147,7 +118,7 @@ export function BelongsTo(options: BelongsToOptions) {
     kind: RelationKinds.BelongsTo,
     propertyKey: propertyName,
     target: options.target,
-    foreignKey: options.foreignKey,
+    foreignKey: options.foreignKey ?? `${propertyName}_id`,
     localKey: options.localKey,
     cascade: options.cascade
   }));
@@ -158,7 +129,10 @@ export function BelongsTo(options: BelongsToOptions) {
  * @param options - The relation options.
  * @returns A property decorator that registers the relation metadata.
  */
-export function BelongsToMany(options: BelongsToManyOptions) {
+export function BelongsToMany<
+  TTarget extends EntityOrTableTarget = EntityOrTableTarget,
+  TPivot extends EntityOrTableTarget = EntityOrTableTarget
+>(options: BelongsToManyOptions<TTarget, TPivot>) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsToMany,
     propertyKey: propertyName,

package/src/orm/entity-hydration.ts

@@ -0,0 +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));
+      }
+    }
+  }
+};

package/src/orm/entity-meta.ts

@@ -1,25 +1,30 @@
-import { TableDef } from '../schema/table.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));
-
-/**
- * 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: (keyof RelationMap<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 */