metal-orm 1.0.55 → 1.0.57

package/src/orm/relations/many-to-many.ts

@@ -21,10 +21,28 @@ const hideInternal = (obj: object, keys: string[]): void => {
   }
 };
 
+/**
+ * Default implementation of a many-to-many collection.
+ * Manages the relationship between two entities through a pivot table.
+ * Supports lazy loading, attaching/detaching entities, and syncing by IDs.
+ *
+ * @template TTarget The type of the target entities in the collection.
+ */
 export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
   private loaded = false;
   private items: TTarget[] = [];
 
+  /**
+   * @param ctx The entity context for tracking changes.
+   * @param meta Metadata for the root entity.
+   * @param root The root entity instance.
+   * @param relationName The name of the relation.
+   * @param relation Relation definition.
+   * @param rootTable Table definition of the root entity.
+   * @param loader Function to load the collection items.
+   * @param createEntity Function to create entity instances from rows.
+   * @param localKey The local key used for joining.
+   */
   constructor(
     private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<TableDef>,
@@ -40,6 +58,10 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     this.hydrateFromCache();
   }
 
+  /**
+   * Loads the collection items if not already loaded.
+   * @returns A promise that resolves to the array of target entities.
+   */
   async load(): Promise<TTarget[]> {
     if (this.loaded) return this.items;
     const map = await this.loader();
@@ -56,10 +78,19 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     return this.items;
   }
 
+  /**
+   * Returns the currently loaded items.
+   * @returns Array of target entities.
+   */
   getItems(): TTarget[] {
     return this.items;
   }
 
+  /**
+   * Attaches an entity to the collection.
+   * Registers an 'attach' change in the entity context.
+   * @param target Entity instance or its primary key value.
+   */
   attach(target: TTarget | number | string): void {
     const entity = this.ensureEntity(target);
     const id = this.extractId(entity);
@@ -80,6 +111,11 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     );
   }
 
+  /**
+   * Detaches an entity from the collection.
+   * Registers a 'detach' change in the entity context.
+   * @param target Entity instance or its primary key value.
+   */
   detach(target: TTarget | number | string): void {
     const id = typeof target === 'number' || typeof target === 'string'
       ? target
@@ -101,6 +137,11 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     );
   }
 
+  /**
+   * Syncs the collection with a list of IDs.
+   * Attaches missing IDs and detaches IDs not in the list.
+   * @param ids Array of primary key values to sync with.
+   */
   async syncByIds(ids: (number | string)[]): Promise<void> {
     await this.load();
     const normalized = new Set(ids.map(id => toKey(id)));

package/src/query-builder/select.ts

@@ -533,74 +533,74 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param ctx - ORM session context
    * @returns Promise of entity instances
    */
-  async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    return executeHydrated(ctx, this);
-  }
-
-  private withAst(ast: SelectQueryNode): SelectQueryBuilder<T, TTable> {
-    const nextState = new SelectQueryState(this.env.table as TTable, ast);
-    const nextContext: SelectQueryBuilderContext = {
-      ...this.context,
-      state: nextState
-    };
-    return this.clone(nextContext);
-  }
-
-  async count(session: OrmSession): Promise<number> {
-    const unpagedAst: SelectQueryNode = {
-      ...this.context.state.ast,
-      orderBy: undefined,
-      limit: undefined,
-      offset: undefined
-    };
-
-    const subAst = this.withAst(unpagedAst).getAST();
-
-    const countQuery: SelectQueryNode = {
-      type: 'SelectQuery',
-      from: derivedTable(subAst, '__metal_count'),
-      columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
-      joins: []
-    };
-
-    const execCtx = session.getExecutionContext();
-    const compiled = execCtx.dialect.compileSelect(countQuery);
-    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-    const value = results[0]?.values?.[0]?.[0];
-
-    if (typeof value === 'number') return value;
-    if (typeof value === 'bigint') return Number(value);
-    if (typeof value === 'string') return Number(value);
-    return value === null || value === undefined ? 0 : Number(value);
-  }
-
-  async executePaged(
-    session: OrmSession,
-    options: { page: number; pageSize: number }
-  ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
-    const { page, pageSize } = options;
-    if (!Number.isInteger(page) || page < 1) {
-      throw new Error('executePaged: page must be an integer >= 1');
-    }
-    if (!Number.isInteger(pageSize) || pageSize < 1) {
-      throw new Error('executePaged: pageSize must be an integer >= 1');
-    }
-
-    const offset = (page - 1) * pageSize;
-    const [items, totalItems] = await Promise.all([
-      this.limit(pageSize).offset(offset).execute(session),
-      this.count(session)
-    ]);
-
-    return { items, totalItems };
-  }
-
-  /**
-   * Executes the query with provided execution and hydration contexts
-   * @param execCtx - Execution context
-   * @param hydCtx - Hydration context
-   * @returns Promise of entity instances
-   */
+  async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
+    return executeHydrated(ctx, this);
+  }
+
+  private withAst(ast: SelectQueryNode): SelectQueryBuilder<T, TTable> {
+    const nextState = new SelectQueryState(this.env.table as TTable, ast);
+    const nextContext: SelectQueryBuilderContext = {
+      ...this.context,
+      state: nextState
+    };
+    return this.clone(nextContext);
+  }
+
+  async count(session: OrmSession): Promise<number> {
+    const unpagedAst: SelectQueryNode = {
+      ...this.context.state.ast,
+      orderBy: undefined,
+      limit: undefined,
+      offset: undefined
+    };
+
+    const subAst = this.withAst(unpagedAst).getAST();
+
+    const countQuery: SelectQueryNode = {
+      type: 'SelectQuery',
+      from: derivedTable(subAst, '__metal_count'),
+      columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
+      joins: []
+    };
+
+    const execCtx = session.getExecutionContext();
+    const compiled = execCtx.dialect.compileSelect(countQuery);
+    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    const value = results[0]?.values?.[0]?.[0];
+
+    if (typeof value === 'number') return value;
+    if (typeof value === 'bigint') return Number(value);
+    if (typeof value === 'string') return Number(value);
+    return value === null || value === undefined ? 0 : Number(value);
+  }
+
+  async executePaged(
+    session: OrmSession,
+    options: { page: number; pageSize: number }
+  ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
+    const { page, pageSize } = options;
+    if (!Number.isInteger(page) || page < 1) {
+      throw new Error('executePaged: page must be an integer >= 1');
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1) {
+      throw new Error('executePaged: pageSize must be an integer >= 1');
+    }
+
+    const offset = (page - 1) * pageSize;
+    const [items, totalItems] = await Promise.all([
+      this.limit(pageSize).offset(offset).execute(session),
+      this.count(session)
+    ]);
+
+    return { items, totalItems };
+  }
+
+  /**
+   * Executes the query with provided execution and hydration contexts
+   * @param execCtx - Execution context
+   * @param hydCtx - Hydration context
+   * @returns Promise of entity instances
+   */
   async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]> {
     return executeHydratedWithContexts(execCtx, hydCtx, this);
   }

package/src/schema/table-guards.ts

@@ -9,6 +9,12 @@ const isRelationsRecord = (relations: unknown): relations is Record<string, unkn
     return typeof relations === 'object' && relations !== null;
 };
 
+/**
+ * Type guard that checks if a value is a TableDef.
+ * 
+ * @param value The value to check.
+ * @returns True if the value follows the TableDef structure.
+ */
 export const isTableDef = (value: unknown): value is TableDef => {
     if (typeof value !== 'object' || value === null) {
         return false;

package/src/schema/types.ts

@@ -1,4 +1,5 @@
-import { ColumnDef } from './column-types.js';
+import type { ColumnDef } from './column-types.js';
+export type { ColumnDef };
 import { TableDef } from './table.js';
 import {
   RelationDef,
@@ -102,3 +103,9 @@ export type EntityInstance<
 } & {
   $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
 };
+
+export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
+
+export type SelectableKeys<T> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends Primitive ? K : never
+}[keyof T];