metal-orm 1.0.42 → 1.0.44

package/src/decorators/relations.ts

@@ -9,7 +9,6 @@ import {
   DualModePropertyDecorator,
   getOrCreateMetadataBag,
   isStandardDecoratorContext,
-  registerInitializer,
   StandardDecoratorContext
 } from './decorator-metadata.js';
 
@@ -19,18 +18,30 @@ interface BaseRelationOptions {
   localKey?: string;
 }
 
+/**
+ * Options for HasMany relation.
+ */
 export interface HasManyOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for HasOne relation.
+ */
 export interface HasOneOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for BelongsTo relation.
+ */
 export interface BelongsToOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+/**
+ * Options for BelongsToMany relation.
+ */
 export interface BelongsToManyOptions {
   target: EntityOrTableTargetResolver;
   pivotTable: EntityOrTableTargetResolver;
@@ -54,8 +65,8 @@ const resolveConstructor = (instanceOrCtor: unknown): EntityConstructor | undefi
   if (typeof instanceOrCtor === 'function') {
     return instanceOrCtor as EntityConstructor;
   }
-  if (instanceOrCtor && typeof (instanceOrCtor as any).constructor === 'function') {
-    return (instanceOrCtor as any).constructor 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;
 };
@@ -80,14 +91,6 @@ const createFieldDecorator = (
       if (!bag.relations.some(entry => entry.propertyName === propertyName)) {
         bag.relations.push({ propertyName, relation: relationMetadata });
       }
-
-      registerInitializer(ctx, function () {
-        const ctor = resolveConstructor(this);
-        if (!ctor) {
-          return;
-        }
-        registerRelation(ctor, propertyName, relationMetadata);
-      });
       return;
     }
 
@@ -102,6 +105,11 @@ const createFieldDecorator = (
   return decorator;
 };
 
+/**
+ * Decorator to define a HasMany relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function HasMany(options: HasManyOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.HasMany,
@@ -113,6 +121,11 @@ export function HasMany(options: HasManyOptions) {
   }));
 }
 
+/**
+ * Decorator to define a HasOne relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function HasOne(options: HasOneOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.HasOne,
@@ -124,6 +137,11 @@ export function HasOne(options: HasOneOptions) {
   }));
 }
 
+/**
+ * Decorator to define a BelongsTo relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function BelongsTo(options: BelongsToOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsTo,
@@ -135,6 +153,11 @@ export function BelongsTo(options: BelongsToOptions) {
   }));
 }
 
+/**
+ * Decorator to define a BelongsToMany relation on an entity property.
+ * @param options - The relation options.
+ * @returns A property decorator that registers the relation metadata.
+ */
 export function BelongsToMany(options: BelongsToManyOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsToMany,

package/src/orm/als.ts

@@ -1,18 +1,31 @@
 // In a real Node environment: import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
- * Browser-compatible implementation of AsyncLocalStorage
- * Provides a simple in-memory store for browser environments
- * @typeParam T - Type of the stored data
+ * Browser-compatible implementation of AsyncLocalStorage.
+ * Provides a simple in-memory store for browser environments while maintaining
+ * Node.js AsyncLocalStorage API compatibility.
+ * 
+ * @template T Type of the data stored in the async context
  */
 export class AsyncLocalStorage<T> {
   private store: T | undefined;
 
   /**
-   * Executes a callback with the specified store value
-   * @param store - Value to store during callback execution
-   * @param callback - Function to execute with the store value
-   * @returns Result of the callback function
+   * Executes a callback function within a context containing the specified store value.
+   * The store value is only available during the callback's execution and is automatically
+   * cleared afterward.
+   * 
+   * @param store - The context value to make available during callback execution
+   * @param callback - Function to execute with the store value available
+   * @returns Result of the callback function execution
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<number>();
+   * als.run(42, () => {
+   *   console.log(als.getStore()); // Outputs: 42
+   * });
+   * ```
    */
   run<R>(store: T, callback: () => R): R {
     this.store = store;
@@ -24,8 +37,20 @@ export class AsyncLocalStorage<T> {
   }
 
   /**
-   * Gets the currently stored value
-   * @returns Current store value or undefined if none exists
+   * Retrieves the current store value from the async context.
+   * Returns undefined if called outside of a `run()` callback execution.
+   * 
+   * @returns Current store value or undefined if no context exists
+   * 
+   * @example
+   * ```
+   * const als = new AsyncLocalStorage<string>();
+   * console.log(als.getStore()); // Outputs: undefined
+   * 
+   * als.run('hello', () => {
+   *   console.log(als.getStore()); // Outputs: 'hello'
+   * });
+   * ```
    */
   getStore(): T | undefined {
     return this.store;

package/src/orm/entity-context.ts

@@ -4,27 +4,81 @@ import { TableDef } from '../schema/table.js';
 import { RelationDef } from '../schema/relation.js';
 import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
 
+/**
+ * Interface for entity context providing entity tracking and management.
+ */
 export interface EntityContext {
+    /** The database dialect */
     dialect: Dialect;
+    /** The database executor */
     executor: DbExecutor;
 
-    getEntity(table: TableDef, pk: any): any;
-    setEntity(table: TableDef, pk: any, entity: any): void;
+    /**
+     * Gets an entity by table and primary key.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @returns The entity or undefined
+     */
+    getEntity(table: TableDef, pk: unknown): unknown;
 
-    trackNew(table: TableDef, entity: any, pk?: any): void;
-    trackManaged(table: TableDef, pk: any, entity: any): void;
+    /**
+     * Sets an entity in the context.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity to set
+     */
+    setEntity(table: TableDef, pk: unknown, entity: unknown): void;
 
-    markDirty(entity: any): void;
-    markRemoved(entity: any): void;
+    /**
+     * Tracks a new entity.
+     * @param table - The table definition
+     * @param entity - The new entity
+     * @param pk - Optional primary key
+     */
+    trackNew(table: TableDef, entity: unknown, pk?: unknown): void;
 
+    /**
+     * Tracks a managed entity.
+     * @param table - The table definition
+     * @param pk - The primary key
+     * @param entity - The managed entity
+     */
+    trackManaged(table: TableDef, pk: unknown, entity: unknown): void;
+
+    /**
+     * Marks an entity as dirty.
+     * @param entity - The entity to mark
+     */
+    markDirty(entity: unknown): void;
+
+    /**
+     * Marks an entity as removed.
+     * @param entity - The entity to mark
+     */
+    markRemoved(entity: unknown): void;
+
+    /**
+     * Gets all tracked entities for a table.
+     * @param table - The table definition
+     * @returns Array of tracked entities
+     */
     getEntitiesForTable(table: TableDef): TrackedEntity[];
 
+    /**
+     * Registers a relation change.
+     * @param root - The root entity
+     * @param relationKey - The relation key
+     * @param rootTable - The root table definition
+     * @param relationName - The relation name
+     * @param relation - The relation definition
+     * @param change - The relation change
+     */
     registerRelationChange(
-        root: any,
+        root: unknown,
         relationKey: RelationKey,
         rootTable: TableDef,
         relationName: string,
         relation: RelationDef,
-        change: RelationChange<any>
+        change: RelationChange<unknown>
     ): void;
 }

package/src/orm/entity-meta.ts

@@ -21,9 +21,9 @@ export interface EntityMeta<TTable extends TableDef> {
   /** Relations that should be loaded lazily */
   lazyRelations: (keyof RelationMap<TTable>)[];
   /** Cache for relation promises */
-  relationCache: Map<string, Promise<any>>;
+  relationCache: Map<string, Promise<unknown>>;
   /** Hydration data for relations */
-  relationHydration: Map<string, Map<string, any>>;
+  relationHydration: Map<string, Map<string, unknown>>;
   /** Relation wrapper instances */
   relationWrappers: Map<string, unknown>;
 }
@@ -40,7 +40,7 @@ export const getHydrationRows = <TTable extends TableDef>(
   meta: EntityMeta<TTable>,
   relationName: string,
   key: unknown
-): Record<string, any>[] | undefined => {
+): Record<string, unknown>[] | undefined => {
   const map = meta.relationHydration.get(relationName);
   if (!map) return undefined;
   const rows = map.get(toKey(key));
@@ -60,7 +60,7 @@ export const getHydrationRecord = <TTable extends TableDef>(
   meta: EntityMeta<TTable>,
   relationName: string,
   key: unknown
-): Record<string, any> | undefined => {
+): Record<string, unknown> | undefined => {
   const map = meta.relationHydration.get(relationName);
   if (!map) return undefined;
   const value = map.get(toKey(key));
@@ -68,7 +68,7 @@ export const getHydrationRecord = <TTable extends TableDef>(
   if (Array.isArray(value)) {
     return value[0];
   }
-  return value;
+  return value as Record<string, unknown>;
 };
 
 /**
@@ -77,9 +77,9 @@ export const getHydrationRecord = <TTable extends TableDef>(
  * @returns Entity metadata or undefined if not found
  * @typeParam TTable - Table definition type
  */
-export const getEntityMeta = <TTable extends TableDef>(entity: any): EntityMeta<TTable> | undefined => {
+export const getEntityMeta = <TTable extends TableDef>(entity: unknown): EntityMeta<TTable> | undefined => {
   if (!entity || typeof entity !== 'object') return undefined;
-  return (entity as any)[ENTITY_META];
+  return (entity as { [ENTITY_META]: EntityMeta<TTable> })[ENTITY_META];
 };
 
 /**
@@ -87,6 +87,6 @@ export const getEntityMeta = <TTable extends TableDef>(entity: any): EntityMeta<
  * @param entity - Entity instance to check
  * @returns True if the entity has metadata, false otherwise
  */
-export const hasEntityMeta = (entity: any): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
+export const hasEntityMeta = (entity: unknown): entity is { [ENTITY_META]: EntityMeta<TableDef> } => {
   return Boolean(getEntityMeta(entity));
 };

package/src/orm/entity-metadata.ts

@@ -1,13 +1,34 @@
-import { ColumnType, ColumnDef } from '../schema/column.js';
+import { ColumnDef } from '../schema/column.js';
 import { defineTable, TableDef, TableHooks } from '../schema/table.js';
 import { CascadeMode, RelationKinds } from '../schema/relation.js';
 
-export type EntityConstructor<T = object> = new (...args: any[]) => T;
-export type EntityOrTableTarget = EntityConstructor<any> | TableDef;
+/**
+ * Constructor type for entities.
+ * Supports any constructor signature for maximum flexibility with decorator-based entities.
+ * @template T - The entity type
+ */
+export type EntityConstructor<T = object> = new (...args: never[]) => T;
+
+/**
+ * Target that can be an entity constructor or table definition.
+ */
+export type EntityOrTableTarget = EntityConstructor | TableDef;
+
+/**
+ * Resolver for entity or table target, can be direct or function.
+ */
 export type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
+/**
+ * Simplified column definition structure used during metadata registration.
+ * @template T - Concrete column definition type being extended
+ */
 export type ColumnDefLike<T extends ColumnDef = ColumnDef> = Omit<T, 'name' | 'table'>;
 
+/**
+ * Transforms simplified column metadata into full ColumnDef objects during table building.
+ * @template TColumns - Mapping of column names to simplified definitions
+ */
 type MaterializeColumns<TColumns extends Record<string, ColumnDefLike>> = {
   [K in keyof TColumns]: ColumnDef<TColumns[K]['type'], TColumns[K]['tsType']> & Omit<
     TColumns[K],
@@ -15,63 +36,120 @@ type MaterializeColumns<TColumns extends Record<string, ColumnDefLike>> = {
   > & { name: string; table: string };
 };
 
+/**
+ * Common properties shared by all relation metadata types.
+ */
 interface BaseRelationMetadata {
+  /** The property key for the relation */
   propertyKey: string;
+  /** The target entity or table */
   target: EntityOrTableTargetResolver;
+  /** Optional cascade mode */
   cascade?: CascadeMode;
 }
 
+/**
+ * Metadata for has many relations.
+ */
 export interface HasManyRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.HasMany;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for has one relations.
+ */
 export interface HasOneRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.HasOne;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for belongs to relations.
+ */
 export interface BelongsToRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.BelongsTo;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for belongs to many relations.
+ */
 export interface BelongsToManyRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.BelongsToMany;
+  /** The pivot table */
   pivotTable: EntityOrTableTargetResolver;
+  /** The pivot foreign key to root */
   pivotForeignKeyToRoot: string;
+  /** The pivot foreign key to target */
   pivotForeignKeyToTarget: string;
+  /** Optional local key */
   localKey?: string;
+  /** Optional target key */
   targetKey?: string;
+  /** Optional pivot primary key */
   pivotPrimaryKey?: string;
+  /** Optional default pivot columns */
   defaultPivotColumns?: string[];
 }
 
+/**
+ * Union type for all relation metadata.
+ */
 export type RelationMetadata =
   | HasManyRelationMetadata
   | HasOneRelationMetadata
   | BelongsToRelationMetadata
   | BelongsToManyRelationMetadata;
 
+/**
+ * Metadata for entities.
+ * @template TColumns - The columns type
+ */
 export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> = Record<string, ColumnDefLike>> {
-  target: EntityConstructor<any>;
+  /** The entity constructor */
+  target: EntityConstructor;
+  /** The table name */
   tableName: string;
+  /** The columns */
   columns: TColumns;
+  /** The relations */
   relations: Record<string, RelationMetadata>;
+  /** Optional hooks */
   hooks?: TableHooks;
+  /** Optional table definition */
   table?: TableDef<MaterializeColumns<TColumns>>;
 }
 
-const metadataMap = new Map<EntityConstructor<any>, EntityMetadata>();
+const metadataMap = new Map<EntityConstructor, EntityMetadata>();
 
+/**
+ * Registers entity metadata.
+ * @param meta - The entity metadata to register
+ */
 export const registerEntityMetadata = (meta: EntityMetadata): void => {
   metadataMap.set(meta.target, meta);
 };
 
-export const ensureEntityMetadata = (target: EntityConstructor<any>): EntityMetadata => {
+/**
+ * Ensures entity metadata exists for the target, creating it if necessary.
+ * @param target - The entity constructor
+ * @returns The entity metadata
+ */
+export const ensureEntityMetadata = (target: EntityConstructor): EntityMetadata => {
   let meta = metadataMap.get(target);
   if (!meta) {
     meta = {
@@ -85,20 +163,38 @@ export const ensureEntityMetadata = (target: EntityConstructor<any>): EntityMeta
   return meta;
 };
 
-export const getEntityMetadata = (target: EntityConstructor<any>): EntityMetadata | undefined => {
+/**
+ * Gets entity metadata for the target.
+ * @param target - The entity constructor
+ * @returns The entity metadata or undefined if not found
+ */
+export const getEntityMetadata = (target: EntityConstructor): EntityMetadata | undefined => {
   return metadataMap.get(target);
 };
 
+/**
+ * Gets all entity metadata.
+ * @returns Array of all entity metadata
+ */
 export const getAllEntityMetadata = (): EntityMetadata[] => {
   return Array.from(metadataMap.values());
 };
 
+/**
+ * Clears all entity metadata.
+ */
 export const clearEntityMetadata = (): void => {
   metadataMap.clear();
 };
 
+/**
+ * Adds column metadata to an entity.
+ * @param target - The entity constructor
+ * @param propertyKey - The property key
+ * @param column - The column definition
+ */
 export const addColumnMetadata = (
-  target: EntityConstructor<any>,
+  target: EntityConstructor,
   propertyKey: string,
   column: ColumnDefLike
 ): void => {
@@ -106,8 +202,14 @@ export const addColumnMetadata = (
   (meta.columns as Record<string, ColumnDefLike>)[propertyKey] = { ...column };
 };
 
+/**
+ * Adds relation metadata to an entity.
+ * @param target - The entity constructor
+ * @param propertyKey - The property key
+ * @param relation - The relation metadata
+ */
 export const addRelationMetadata = (
-  target: EntityConstructor<any>,
+  target: EntityConstructor,
   propertyKey: string,
   relation: RelationMetadata
 ): void => {
@@ -115,8 +217,14 @@ export const addRelationMetadata = (
   meta.relations[propertyKey] = relation;
 };
 
+/**
+ * Sets the table name and hooks for an entity.
+ * @param target - The entity constructor
+ * @param tableName - The table name
+ * @param hooks - Optional table hooks
+ */
 export const setEntityTableName = (
-  target: EntityConstructor<any>,
+  target: EntityConstructor,
   tableName: string,
   hooks?: TableHooks
 ): void => {
@@ -129,21 +237,28 @@ export const setEntityTableName = (
   }
 };
 
+/**
+ * Builds a table definition from entity metadata.
+ * @template TColumns - The columns type
+ * @param meta - The entity metadata
+ * @returns The table definition
+ */
 export const buildTableDef = <TColumns extends Record<string, ColumnDefLike>>(meta: EntityMetadata<TColumns>): TableDef<MaterializeColumns<TColumns>> => {
   if (meta.table) {
     return meta.table;
   }
 
-  const columns = Object.entries(meta.columns).reduce<MaterializeColumns<TColumns>>((acc, [key, def]) => {
-    (acc as any)[key] = {
+  // Build columns using a simpler approach that avoids type assertion
+  const columns: Record<string, ColumnDef> = {};
+  for (const [key, def] of Object.entries(meta.columns)) {
+    columns[key] = {
       ...def,
       name: key,
       table: meta.tableName
-    };
-    return acc;
-  }, {} as MaterializeColumns<TColumns>);
+    } as ColumnDef;
+  }
 
-  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
+  const table = defineTable(meta.tableName, columns as MaterializeColumns<TColumns>, {}, meta.hooks);
   meta.table = table;
   return table;
 };