metal-orm 1.0.11 → 1.0.13

package/src/core/dialect/sqlite/index.ts

@@ -1,15 +1,15 @@
-import { CompilerContext, Dialect } from '../abstract.js';
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
-import { JsonPathNode, ColumnNode } from '../../ast/expression.js';
-
-/**
- * SQLite dialect implementation
- */
-export class SqliteDialect extends Dialect {
-  /**
-   * Creates a new SqliteDialect instance
-   */
-  public constructor() {
+import { CompilerContext } from '../abstract.js';
+import { JsonPathNode, ColumnNode } from '../../ast/expression.js';
+import { SqlDialectBase } from '../base/sql-dialect.js';
+
+/**
+ * SQLite dialect implementation
+ */
+export class SqliteDialect extends SqlDialectBase {
+  /**
+   * Creates a new SqliteDialect instance
+   */
+  public constructor() {
     super();
   }
 
@@ -27,120 +27,19 @@ export class SqliteDialect extends Dialect {
    * @param node - JSON path node
    * @returns SQLite JSON path expression
    */
-  protected compileJsonPath(node: JsonPathNode): string {
-    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
-    // SQLite uses json_extract(col, '$.path')
-    return `json_extract(${col}, '${node.path}')`;
-  }
-
-  /**
-   * Compiles SELECT query AST to SQLite SQL
-   * @param ast - Query AST
-   * @param ctx - Compiler context
-   * @returns SQLite SQL string
-   */
-  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
-    const columns = ast.columns.map(c => {
-      let expr = '';
-      if (c.type === 'Function') {
-        expr = this.compileOperand(c, ctx);
-      } else if (c.type === 'Column') {
-        expr = `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`;
-      } else if (c.type === 'ScalarSubquery') {
-        expr = this.compileOperand(c, ctx);
-      } else if (c.type === 'CaseExpression') {
-        expr = this.compileOperand(c, ctx);
-      } else if (c.type === 'WindowFunction') {
-        expr = this.compileOperand(c, ctx);
-      }
-
-      // Handle alias
-      if (c.alias) {
-        // Backward compat for the raw string parsing alias hack in playground
-        if (c.alias.includes('(')) return c.alias;
-        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
-      }
-      return expr;
-    }).join(', ');
-
-    const distinct = ast.distinct ? 'DISTINCT ' : '';
-    const from = `${this.quoteIdentifier(ast.from.name)}`;
-
-    const joins = ast.joins.map(j => {
-      const table = this.quoteIdentifier(j.table.name);
-      const cond = this.compileExpression(j.condition, ctx);
-      return `${j.kind} JOIN ${table} ON ${cond}`;
-    }).join(' ');
-    const whereClause = this.compileWhere(ast.where, ctx);
-
-    const groupBy = ast.groupBy && ast.groupBy.length > 0
-      ? ' GROUP BY ' + ast.groupBy.map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`).join(', ')
-      : '';
-
-    const having = ast.having
-      ? ` HAVING ${this.compileExpression(ast.having, ctx)}`
-      : '';
-
-    const orderBy = ast.orderBy && ast.orderBy.length > 0
-      ? ' ORDER BY ' + ast.orderBy.map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`).join(', ')
-      : '';
-
-    const limit = ast.limit ? ` LIMIT ${ast.limit}` : '';
-    const offset = ast.offset ? ` OFFSET ${ast.offset}` : '';
-
-    const ctes = ast.ctes && ast.ctes.length > 0
-      ? (() => {
-        const hasRecursive = ast.ctes.some(cte => cte.recursive);
-        const prefix = hasRecursive ? 'WITH RECURSIVE ' : 'WITH ';
-        const cteDefs = ast.ctes.map(cte => {
-          const name = this.quoteIdentifier(cte.name);
-          const cols = cte.columns ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})` : '';
-          const query = this.compileSelectAst(cte.query, ctx).trim().replace(/;$/, '');
-          return `${name}${cols} AS (${query})`;
-        }).join(', ');
-        return prefix + cteDefs + ' ';
-      })()
-      : '';
-
-    return `${ctes}SELECT ${distinct}${columns} FROM ${from}${joins ? ' ' + joins : ''}${whereClause}${groupBy}${having}${orderBy}${limit}${offset};`;
-  }
-
-  protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.into.name);
-    const columnList = ast.columns.map(column => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`).join(', ');
-    const values = ast.values.map(row => `(${row.map(value => this.compileOperand(value, ctx)).join(', ')})`).join(', ');
-    const returning = this.compileReturning(ast.returning, ctx);
-    return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning};`;
-  }
-
-  protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.table.name);
-    const assignments = ast.set.map(assignment => {
-      const col = assignment.column;
-      const target = `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`;
-      const value = this.compileOperand(assignment.value, ctx);
-      return `${target} = ${value}`;
-    }).join(', ');
-    const whereClause = this.compileWhere(ast.where, ctx);
-    const returning = this.compileReturning(ast.returning, ctx);
-    return `UPDATE ${table} SET ${assignments}${whereClause}${returning};`;
-  }
-
-  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.from.name);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    const returning = this.compileReturning(ast.returning, ctx);
-    return `DELETE FROM ${table}${whereClause}${returning};`;
-  }
-
-  protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
-    if (!returning || returning.length === 0) return '';
-    const columns = returning
-      .map(column => {
-        const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : '';
-        return `${tablePart}${this.quoteIdentifier(column.name)}`;
-      })
-      .join(', ');
-    return ` RETURNING ${columns}`;
-  }
-}
+  protected compileJsonPath(node: JsonPathNode): string {
+    const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
+    // SQLite uses json_extract(col, '$.path')
+    return `json_extract(${col}, '${node.path}')`;
+  }
+
+  protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
+    if (!returning || returning.length === 0) return '';
+    const columns = this.formatReturningColumns(returning);
+    return ` RETURNING ${columns}`;
+  }
+
+  supportsReturning(): boolean {
+    return true;
+  }
+}

package/src/index.ts

@@ -12,6 +12,10 @@ export * from './core/dialect/mysql/index.js';
 export * from './core/dialect/mssql/index.js';
 export * from './core/dialect/sqlite/index.js';
 export * from './core/dialect/postgres/index.js';
+export * from './core/ddl/schema-generator.js';
+export * from './core/ddl/schema-types.js';
+export * from './core/ddl/schema-diff.js';
+export * from './core/ddl/schema-introspect.js';
 export * from './orm/als.js';
 export * from './orm/hydration.js';
 export * from './codegen/typescript.js';

package/src/orm/execute.ts

@@ -1,9 +1,9 @@
 import { TableDef } from '../schema/table.js';
 import { Entity } from '../schema/types.js';
-import { hydrateRows } from './hydration.js';
-import { OrmContext } from './orm-context.js';
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import { createEntityFromRow } from './entity.js';
+import { hydrateRows } from './hydration.js';
+import { OrmContext } from './orm-context.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { createEntityFromRow, createEntityProxy } from './entity.js';
 
 type Row = Record<string, any>;
 
@@ -22,15 +22,24 @@ const flattenResults = (results: { columns: string[]; values: unknown[][] }[]):
   return rows;
 };
 
-export async function executeHydrated<TTable extends TableDef>(
-  ctx: OrmContext,
-  qb: SelectQueryBuilder<any, TTable>
-): Promise<Entity<TTable>[]> {
-  const compiled = ctx.dialect.compileSelect(qb.getAST());
-  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
-  const rows = flattenResults(executed);
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map(row =>
-    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
-  );
-}
+export async function executeHydrated<TTable extends TableDef>(
+  ctx: OrmContext,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> {
+  const ast = qb.getAST();
+  const compiled = ctx.dialect.compileSelect(ast);
+  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  const rows = flattenResults(executed);
+
+  // Set-operation queries cannot be reliably hydrated and should not collapse duplicates.
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows.map(row =>
+      createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
+    );
+  }
+
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  return hydrated.map(row =>
+    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
+  );
+}

package/src/orm/orm-context.ts

@@ -1,20 +1,21 @@
 import type { Dialect } from '../core/dialect/abstract.js';
 import type { RelationDef } from '../schema/relation.js';
 import type { TableDef } from '../schema/table.js';
-import type { DbExecutor, QueryResult } from './db-executor.js';
-import { DomainEventBus, DomainEventHandler as DomainEventHandlerFn, addDomainEvent } from './domain-event-bus.js';
-import { IdentityMap } from './identity-map.js';
-import { RelationChangeProcessor } from './relation-change-processor.js';
-import { runInTransaction } from './transaction-runner.js';
-import { UnitOfWork } from './unit-of-work.js';
-import {
-  EntityStatus,
-  HasDomainEvents,
-  RelationChange,
-  RelationChangeEntry,
-  RelationKey,
-  TrackedEntity
-} from './runtime-types.js';
+import type { DbExecutor, QueryResult } from './db-executor.js';
+import { DomainEventBus, DomainEventHandler as DomainEventHandlerFn, addDomainEvent } from './domain-event-bus.js';
+import { IdentityMap } from './identity-map.js';
+import { RelationChangeProcessor } from './relation-change-processor.js';
+import { runInTransaction } from './transaction-runner.js';
+import { UnitOfWork } from './unit-of-work.js';
+import {
+  EntityStatus,
+  HasDomainEvents,
+  RelationChange,
+  RelationChangeEntry,
+  RelationKey,
+  TrackedEntity
+} from './runtime-types.js';
+import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
 
 export interface OrmInterceptor {
   beforeFlush?(ctx: OrmContext): Promise<void> | void;
@@ -23,43 +24,46 @@ export interface OrmInterceptor {
 
 export type DomainEventHandler = DomainEventHandlerFn<OrmContext>;
 
-export interface OrmContextOptions {
-  dialect: Dialect;
-  executor: DbExecutor;
-  interceptors?: OrmInterceptor[];
-  domainEventHandlers?: Record<string, DomainEventHandler[]>;
-}
-
-export class OrmContext {
-  private readonly identityMap = new IdentityMap();
-  private readonly unitOfWork: UnitOfWork;
-  private readonly relationChanges: RelationChangeProcessor;
-  private readonly interceptors: OrmInterceptor[];
-  private readonly domainEvents: DomainEventBus<OrmContext>;
-
-  constructor(private readonly options: OrmContextOptions) {
-    this.interceptors = [...(options.interceptors ?? [])];
-    this.unitOfWork = new UnitOfWork(
-      options.dialect,
-      options.executor,
-      this.identityMap,
-      () => this
-    );
-    this.relationChanges = new RelationChangeProcessor(
-      this.unitOfWork,
-      options.dialect,
-      options.executor
-    );
-    this.domainEvents = new DomainEventBus<OrmContext>(options.domainEventHandlers);
-  }
+export interface OrmContextOptions {
+  dialect: Dialect;
+  executor: DbExecutor;
+  interceptors?: OrmInterceptor[];
+  domainEventHandlers?: Record<string, DomainEventHandler[]>;
+  queryLogger?: QueryLogger;
+}
+
+export class OrmContext {
+  private readonly identityMap = new IdentityMap();
+  private readonly executorWithLogging: DbExecutor;
+  private readonly unitOfWork: UnitOfWork;
+  private readonly relationChanges: RelationChangeProcessor;
+  private readonly interceptors: OrmInterceptor[];
+  private readonly domainEvents: DomainEventBus<OrmContext>;
+
+  constructor(private readonly options: OrmContextOptions) {
+    this.interceptors = [...(options.interceptors ?? [])];
+    this.executorWithLogging = createQueryLoggingExecutor(options.executor, options.queryLogger);
+    this.unitOfWork = new UnitOfWork(
+      options.dialect,
+      this.executorWithLogging,
+      this.identityMap,
+      () => this
+    );
+    this.relationChanges = new RelationChangeProcessor(
+      this.unitOfWork,
+      options.dialect,
+      this.executorWithLogging
+    );
+    this.domainEvents = new DomainEventBus<OrmContext>(options.domainEventHandlers);
+  }
 
   get dialect(): Dialect {
     return this.options.dialect;
   }
 
-  get executor(): DbExecutor {
-    return this.options.executor;
-  }
+  get executor(): DbExecutor {
+    return this.executorWithLogging;
+  }
 
   get identityBuckets(): Map<string, Map<string, TrackedEntity>> {
     return this.unitOfWork.identityBuckets;
@@ -143,12 +147,13 @@ export class OrmContext {
   }
 }
 
-export { addDomainEvent };
-export { EntityStatus };
-export type {
-  QueryResult,
-  DbExecutor,
-  RelationKey,
-  RelationChange,
-  HasDomainEvents
-};
+export { addDomainEvent };
+export { EntityStatus };
+export type {
+  QueryResult,
+  DbExecutor,
+  RelationKey,
+  RelationChange,
+  HasDomainEvents
+};
+export type { QueryLogEntry, QueryLogger } from './query-logger.js';

package/src/orm/query-logger.ts

@@ -0,0 +1,38 @@
+import type { DbExecutor } from './db-executor.js';
+
+export interface QueryLogEntry {
+  sql: string;
+  params?: unknown[];
+}
+
+export type QueryLogger = (entry: QueryLogEntry) => void;
+
+export const createQueryLoggingExecutor = (
+  executor: DbExecutor,
+  logger?: QueryLogger
+): DbExecutor => {
+  if (!logger) {
+    return executor;
+  }
+
+  const wrapped: DbExecutor = {
+    async executeSql(sql, params) {
+      logger({ sql, params });
+      return executor.executeSql(sql, params);
+    }
+  };
+
+  if (executor.beginTransaction) {
+    wrapped.beginTransaction = executor.beginTransaction.bind(executor);
+  }
+
+  if (executor.commitTransaction) {
+    wrapped.commitTransaction = executor.commitTransaction.bind(executor);
+  }
+
+  if (executor.rollbackTransaction) {
+    wrapped.rollbackTransaction = executor.rollbackTransaction.bind(executor);
+  }
+
+  return wrapped;
+};

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

@@ -4,15 +4,26 @@ import { BelongsToRelation } from '../../schema/relation.js';
 import { TableDef } from '../../schema/table.js';
 import { EntityMeta, getHydrationRecord, hasEntityMeta } from '../entity-meta.js';
 
-type Rows = Record<string, any>;
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-export class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
-  private loaded = false;
-  private current: TParent | null = null;
-
-  constructor(
+type Rows = Record<string, any>;
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
+  private loaded = false;
+  private current: TParent | null = null;
+
+  constructor(
     private readonly ctx: OrmContext,
     private readonly meta: EntityMeta<any>,
     private readonly root: any,
@@ -20,14 +31,15 @@ export class DefaultBelongsToReference<TParent> implements BelongsToReference<TP
     private readonly relation: BelongsToRelation,
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
-    private readonly createEntity: (row: Record<string, any>) => TParent,
-    private readonly targetKey: string
-  ) {
-    this.populateFromHydrationCache();
-  }
-
-  async load(): Promise<TParent | null> {
-    if (this.loaded) return this.current;
+    private readonly createEntity: (row: Record<string, any>) => TParent,
+    private readonly targetKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'targetKey']);
+    this.populateFromHydrationCache();
+  }
+
+  async load(): Promise<TParent | null> {
+    if (this.loaded) return this.current;
     const map = await this.loader();
     const fkValue = this.root[this.relation.foreignKey];
     if (fkValue === null || fkValue === undefined) {
@@ -81,12 +93,16 @@ export class DefaultBelongsToReference<TParent> implements BelongsToReference<TP
     return `${this.rootTable.name}.${this.relationName}`;
   }
 
-  private populateFromHydrationCache(): void {
-    const fkValue = this.root[this.relation.foreignKey];
-    if (fkValue === undefined || fkValue === null) return;
-    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
-    if (!row) return;
-    this.current = this.createEntity(row);
-    this.loaded = true;
-  }
-}
+  private populateFromHydrationCache(): void {
+    const fkValue = this.root[this.relation.foreignKey];
+    if (fkValue === undefined || fkValue === null) return;
+    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
+    if (!row) return;
+    this.current = this.createEntity(row);
+    this.loaded = true;
+  }
+
+  toJSON(): TParent | null {
+    return this.current;
+  }
+}

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

@@ -4,15 +4,26 @@ import { HasManyRelation } from '../../schema/relation.js';
 import { TableDef } from '../../schema/table.js';
 import { EntityMeta, getHydrationRows } from '../entity-meta.js';
 
-type Rows = Record<string, any>[];
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
-  private loaded = false;
-  private items: TChild[] = [];
-  private readonly added = new Set<TChild>();
-  private readonly removed = new Set<TChild>();
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
+  private loaded = false;
+  private items: TChild[] = [];
+  private readonly added = new Set<TChild>();
+  private readonly removed = new Set<TChild>();
 
   constructor(
     private readonly ctx: OrmContext,
@@ -23,13 +34,14 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
     private readonly createEntity: (row: Record<string, any>) => TChild,
-    private readonly localKey: string
-  ) {
-    this.hydrateFromCache();
-  }
-
-  async load(): Promise<TChild[]> {
-    if (this.loaded) return this.items;
+    private readonly localKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TChild[]> {
+    if (this.loaded) return this.items;
     const map = await this.loader();
     const key = toKey(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
@@ -100,12 +112,16 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return `${this.rootTable.name}.${this.relationName}`;
   }
 
-  private hydrateFromCache(): void {
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) return;
-    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
-    if (!rows?.length) return;
-    this.items = rows.map(row => this.createEntity(row));
-    this.loaded = true;
-  }
-}
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
+    this.items = rows.map(row => this.createEntity(row));
+    this.loaded = true;
+  }
+
+  toJSON(): TChild[] {
+    return this.items;
+  }
+}

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

@@ -5,15 +5,26 @@ import { TableDef } from '../../schema/table.js';
 import { findPrimaryKey } from '../../query-builder/hydration-planner.js';
 import { EntityMeta, getHydrationRows } from '../entity-meta.js';
 
-type Rows = Record<string, any>[];
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
-  private loaded = false;
-  private items: TTarget[] = [];
-
-  constructor(
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
+  private loaded = false;
+  private items: TTarget[] = [];
+
+  constructor(
     private readonly ctx: OrmContext,
     private readonly meta: EntityMeta<any>,
     private readonly root: any,
@@ -21,14 +32,15 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     private readonly relation: BelongsToManyRelation,
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
-    private readonly createEntity: (row: Record<string, any>) => TTarget,
-    private readonly localKey: string
-  ) {
-    this.hydrateFromCache();
-  }
-
-  async load(): Promise<TTarget[]> {
-    if (this.loaded) return this.items;
+    private readonly createEntity: (row: Record<string, any>) => TTarget,
+    private readonly localKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TTarget[]> {
+    if (this.loaded) return this.items;
     const map = await this.loader();
     const key = toKey(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
@@ -132,18 +144,22 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     return this.relation.targetKey || findPrimaryKey(this.relation.target);
   }
 
-  private hydrateFromCache(): void {
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) return;
-    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
-    if (!rows?.length) return;
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
     this.items = rows.map(row => {
       const entity = this.createEntity(row);
       if ((row as any)._pivot) {
         (entity as any)._pivot = (row as any)._pivot;
       }
-      return entity;
-    });
-    this.loaded = true;
-  }
-}
+      return entity;
+    });
+    this.loaded = true;
+  }
+
+  toJSON(): TTarget[] {
+    return this.items;
+  }
+}