metal-orm 1.1.8 → 1.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -40,14 +40,18 @@
     "lint:fix": "node scripts/run-eslint.mjs --fix"
   },
   "peerDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "ioredis": "^5.0.0",
+    "keyv": "^5.6.0",
     "mysql2": "^3.9.0",
     "pg": "^8.0.0",
     "sqlite3": "^5.1.6",
-    "tedious": "^19.0.0",
-    "keyv": "^5.6.0",
-    "ioredis": "^5.0.0"
+    "tedious": "^19.0.0"
   },
   "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     },
@@ -68,24 +72,25 @@
     }
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.3.15",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
-    "@vitest/ui": "^4.0.18",
-    "eslint": "^9.39.2",
+    "@electric-sql/pglite": "^0.4.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "@vitest/ui": "^4.1.2",
+    "better-sqlite3": "^12.8.0",
+    "eslint": "^10.1.0",
     "express": "^5.2.1",
-    "ioredis": "^5.6.1",
-    "ioredis-mock": "^8.9.0",
+    "ioredis": "^5.10.1",
+    "ioredis-mock": "^8.13.1",
     "keyv": "^5.6.0",
-    "mysql-memory-server": "^1.14.0",
-    "mysql2": "^3.16.2",
-    "pg": "^8.17.2",
-    "sqlite3": "^5.1.7",
+    "mysql-memory-server": "^1.14.1",
+    "mysql2": "^3.20.0",
+    "pg": "^8.20.0",
+    "sqlite3": "^6.0.1",
     "supertest": "^7.2.2",
-    "tedious": "^19.2.0",
+    "tedious": "^19.2.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.2"
   }
 }

package/src/bulk/bulk-context.ts

@@ -0,0 +1,83 @@
+import type { OrmSession } from '../orm/orm-session.js';
+import type { ExecutionContext } from '../orm/execution-context.js';
+import type { Dialect, CompiledQuery } from '../core/dialect/abstract.js';
+import type { ColumnNode } from '../core/ast/expression.js';
+import type { TableDef } from '../schema/table.js';
+import type { ColumnDef } from '../schema/column-types.js';
+import type { QueryResult } from '../core/execution/db-executor.js';
+
+export interface BulkExecutionContext {
+  readonly session: OrmSession;
+  readonly executionContext: ExecutionContext;
+  readonly dialect: Dialect;
+  readonly supportsReturning: boolean;
+}
+
+export function createBulkExecutionContext(session: OrmSession): BulkExecutionContext {
+  const executionContext = session.getExecutionContext();
+  return {
+    session,
+    executionContext,
+    dialect: executionContext.dialect,
+    supportsReturning: executionContext.dialect.supportsDmlReturningClause(),
+  };
+}
+
+export async function executeCompiled(
+  ctx: BulkExecutionContext,
+  compiled: CompiledQuery
+): Promise<QueryResult[]> {
+  const payload = await ctx.executionContext.interceptors.run(
+    { sql: compiled.sql, params: compiled.params },
+    ctx.executionContext.executor
+  );
+  return extractResultSets(payload);
+}
+
+export function extractResultSets(payload: unknown): QueryResult[] {
+  const result = payload as { resultSets?: QueryResult[] };
+  if (result.resultSets) {
+    return result.resultSets;
+  }
+  return [];
+}
+
+export function flattenQueryResults(resultSets: QueryResult[]): Record<string, unknown>[] {
+  const rows: Record<string, unknown>[] = [];
+  for (const rs of resultSets) {
+    for (const valueRow of rs.values) {
+      const obj: Record<string, unknown> = {};
+      rs.columns.forEach((col, idx) => {
+        const bare = col.split('.').pop()!.replace(/^["`[\]]+|["`[\]]+$/g, '');
+        obj[bare] = valueRow[idx];
+      });
+      rows.push(obj);
+    }
+  }
+  return rows;
+}
+
+export function resolveReturningColumns(
+  ctx: BulkExecutionContext,
+  table: TableDef,
+  returning: boolean | ColumnDef[] | undefined
+): ColumnNode[] | undefined {
+  if (!returning) return undefined;
+  if (!ctx.supportsReturning) return undefined;
+
+  if (returning === true) {
+    return Object.values(table.columns).map(col => ({
+      type: 'Column' as const,
+      table: table.name,
+      name: col.name,
+      alias: col.name,
+    }));
+  }
+
+  return returning.map(col => ({
+    type: 'Column' as const,
+    table: table.name,
+    name: col.name,
+    alias: col.name,
+  }));
+}

package/src/bulk/bulk-delete-executor.ts

@@ -0,0 +1,89 @@
+import { DeleteQueryBuilder } from '../query-builder/delete.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import { and, inList } from '../core/ast/expression-builders.js';
+import type { TableDef } from '../schema/table.js';
+import type { OrmSession } from '../orm/orm-session.js';
+import type { BulkDeleteOptions, ChunkOutcome } from './bulk-types.js';
+import type { ValueOperandInput } from '../core/ast/expression.js';
+import type { ExpressionNode } from '../core/ast/expression-nodes.js';
+import { BulkBaseExecutor, type BulkExecutorOptions } from './bulk-executor.base.js';
+import { createBulkExecutionContext, executeCompiled } from './bulk-context.js';
+import { splitIntoChunks, runWithConcurrency, runChunk, maybeTransaction, aggregateOutcomes, aggregateOutcomesWithTimings } from './bulk-utils.js';
+
+const DEFAULT_CHUNK_SIZE = 1000;
+
+interface DeleteExecutorOptions extends BulkExecutorOptions {
+  by?: string;
+  where?: ExpressionNode;
+}
+
+export class BulkDeleteExecutor extends BulkBaseExecutor<DeleteExecutorOptions> {
+  private readonly byColumnName: string;
+
+  constructor(
+    session: OrmSession,
+    table: TableDef,
+    ids: ValueOperandInput[],
+    options: BulkDeleteOptions = {}
+  ) {
+    super(session, table, ids, options);
+    this.byColumnName = options.by ?? findPrimaryKey(table);
+  }
+
+  protected async executeChunk(chunk: ValueOperandInput[], chunkIndex: number): Promise<ChunkOutcome> {
+    const byColumn = this.table.columns[this.byColumnName];
+    if (!byColumn) {
+      throw new Error(
+        `bulkDelete: column "${this.byColumnName}" not found in table "${this.table.name}"`
+      );
+    }
+
+    const extraWhere = this.options.where;
+    const inExpr = inList(byColumn, chunk as any);
+    const finalWhere = extraWhere ? and(inExpr, extraWhere) : inExpr;
+
+    const builder = new DeleteQueryBuilder(this.table).where(finalWhere as ExpressionNode);
+    const compiled = builder.compile(this.ctx.dialect);
+    await executeCompiled(this.ctx, compiled);
+
+    return {
+      processedRows: chunk.length,
+      returning: [],
+      elapsedMs: 0,
+    };
+  }
+}
+
+export async function bulkDelete<TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  ids: ValueOperandInput[],
+  options: BulkDeleteOptions = {}
+): Promise<import('./bulk-types.js').BulkResult> {
+  if (!ids.length) {
+    return { processedRows: 0, chunksExecuted: 0, returning: [] };
+  }
+
+  const executor = new BulkDeleteExecutor(session, table, ids, options);
+  return executor.execute();
+}
+
+export async function bulkDeleteWhere<TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  where: ExpressionNode,
+  options: Pick<BulkDeleteOptions, 'transactional'> = {}
+): Promise<import('./bulk-types.js').BulkResult> {
+  const { transactional = false } = options;
+
+  const ctx = createBulkExecutionContext(session);
+  const builder = new DeleteQueryBuilder(table).where(where);
+  const compiled = builder.compile(ctx.dialect);
+
+  const execute = async (): Promise<import('./bulk-types.js').BulkResult> => {
+    await executeCompiled(ctx, compiled);
+    return { processedRows: 0, chunksExecuted: 1, returning: [] };
+  };
+
+  return maybeTransaction(session, transactional, execute);
+}

package/src/bulk/bulk-executor.base.ts

@@ -0,0 +1,73 @@
+import type { TableDef } from '../schema/table.js';
+import type { OrmSession } from '../orm/orm-session.js';
+import type { BulkResult, BulkBaseOptions, ChunkOutcome } from './bulk-types.js';
+import { createBulkExecutionContext, type BulkExecutionContext } from './bulk-context.js';
+import {
+  splitIntoChunks,
+  runWithConcurrency,
+  runChunk,
+  maybeTransaction,
+  aggregateOutcomes,
+  aggregateOutcomesWithTimings,
+} from './bulk-utils.js';
+
+const DEFAULT_CHUNK_SIZE = 500;
+
+export interface BulkExecutorOptions extends BulkBaseOptions {
+  chunkSize?: number;
+  concurrency?: 'sequential' | number;
+  transactional?: boolean;
+  timing?: boolean;
+  onChunkComplete?: (info: { chunkIndex: number; totalChunks: number; rowsInChunk: number; elapsedMs: number }) => void | Promise<void>;
+}
+
+export abstract class BulkBaseExecutor<TOptions extends BulkExecutorOptions> {
+  protected readonly session: OrmSession;
+  protected readonly table: TableDef;
+  protected readonly ctx: BulkExecutionContext;
+  protected readonly options: TOptions;
+  protected readonly chunks: unknown[][];
+  protected readonly totalChunks: number;
+
+  constructor(session: OrmSession, table: TableDef, rows: unknown[], options: TOptions = {} as TOptions) {
+    this.session = session;
+    this.table = table;
+    this.ctx = createBulkExecutionContext(session);
+    this.options = {
+      chunkSize: DEFAULT_CHUNK_SIZE,
+      concurrency: 'sequential',
+      transactional: true,
+      timing: false,
+      ...options,
+    } as TOptions;
+    this.chunks = splitIntoChunks(rows, this.options.chunkSize!);
+    this.totalChunks = this.chunks.length;
+  }
+
+  protected abstract executeChunk(chunk: unknown[], chunkIndex: number): Promise<ChunkOutcome>;
+
+  async execute(): Promise<BulkResult> {
+    const buildTask = (chunk: unknown[], chunkIndex: number) => async (): Promise<ChunkOutcome> => {
+      return runChunk(
+        () => this.executeChunk(chunk, chunkIndex),
+        chunkIndex,
+        this.totalChunks,
+        chunk.length,
+        this.options.timing!,
+        this.options.onChunkComplete
+      );
+    };
+
+    const tasks = this.chunks.map((chunk, i) => buildTask(chunk, i));
+
+    const outcomes = await maybeTransaction(
+      this.session,
+      this.options.transactional!,
+      () => runWithConcurrency(tasks, this.options.concurrency!)
+    );
+
+    return this.options.timing
+      ? aggregateOutcomesWithTimings(outcomes)
+      : aggregateOutcomes(outcomes);
+  }
+}

package/src/bulk/bulk-insert-executor.ts

@@ -0,0 +1,74 @@
+import { InsertQueryBuilder, ConflictBuilder } from '../query-builder/insert.js';
+import type { TableDef } from '../schema/table.js';
+import type { OrmSession } from '../orm/orm-session.js';
+import type { BulkInsertOptions, ChunkOutcome, InsertRow } from './bulk-types.js';
+import { BulkBaseExecutor, type BulkExecutorOptions } from './bulk-executor.base.js';
+import { resolveReturningColumns, flattenQueryResults, executeCompiled } from './bulk-context.js';
+
+interface InsertExecutorOptions extends BulkExecutorOptions {
+  returning?: boolean | import('../schema/column-types.js').ColumnDef[];
+  onConflict?: import('../core/ast/query.js').UpsertClause;
+}
+
+export class BulkInsertExecutor extends BulkBaseExecutor<InsertExecutorOptions> {
+  constructor(
+    session: OrmSession,
+    table: TableDef,
+    rows: InsertRow[],
+    options: BulkInsertOptions = {}
+  ) {
+    super(session, table, rows, options);
+  }
+
+  protected async executeChunk(chunk: InsertRow[], chunkIndex: number): Promise<ChunkOutcome> {
+    const returningColumns = resolveReturningColumns(this.ctx, this.table, this.options.returning);
+
+    let builder: InsertQueryBuilder<unknown> | ConflictBuilder<unknown> = 
+      new InsertQueryBuilder(this.table).values(chunk);
+
+    if (this.options.onConflict) {
+      const conflictColumns = this.options.onConflict.target?.columns ?? [];
+      builder = (builder as InsertQueryBuilder<unknown>).onConflict(conflictColumns as any);
+      
+      if (this.options.onConflict.action.type === 'DoNothing') {
+        builder = (builder as ConflictBuilder<unknown>).doNothing();
+      } else if (this.options.onConflict.action.type === 'DoUpdate' && this.options.onConflict.action.set) {
+        const setMap: Record<string, unknown> = {};
+        for (const assignment of this.options.onConflict.action.set) {
+          const colName = typeof assignment.column === 'object' ? assignment.column.name : assignment.column;
+          setMap[colName] = assignment.value;
+        }
+        builder = (builder as ConflictBuilder<unknown>).doUpdate(setMap as any);
+      }
+    }
+
+    const finalBuilder = builder as InsertQueryBuilder<unknown>;
+
+    if (returningColumns?.length) {
+      finalBuilder.returning(...returningColumns);
+    }
+
+    const compiled = finalBuilder.compile(this.ctx.dialect);
+    const resultSets = await executeCompiled(this.ctx, compiled);
+
+    return {
+      processedRows: chunk.length,
+      returning: returningColumns ? flattenQueryResults(resultSets) : [],
+      elapsedMs: 0,
+    };
+  }
+}
+
+export async function bulkInsert<TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  rows: InsertRow[],
+  options: BulkInsertOptions = {}
+): Promise<import('./bulk-types.js').BulkResult> {
+  if (!rows.length) {
+    return { processedRows: 0, chunksExecuted: 0, returning: [] };
+  }
+
+  const executor = new BulkInsertExecutor(session, table, rows, options);
+  return executor.execute();
+}

package/src/bulk/bulk-types.ts

@@ -0,0 +1,70 @@
+import type { TableDef } from '../schema/table.js';
+import type { OrmSession } from '../orm/orm-session.js';
+import type { ExpressionNode } from '../core/ast/expression-nodes.js';
+import type { ColumnDef } from '../schema/column-types.js';
+import type { UpsertClause } from '../core/ast/query.js';
+import type { ValueOperandInput } from '../core/ast/expression.js';
+
+export type { TableDef, OrmSession };
+
+export type BulkConcurrency = 'sequential' | number;
+
+export interface BulkResult {
+  processedRows: number;
+  chunksExecuted: number;
+  returning: Record<string, unknown>[];
+  chunkTimings?: number[];
+  metadata?: BulkResultMetadata;
+}
+
+export interface BulkResultMetadata {
+  strategy: 'individual' | 'batch' | 'whereIn';
+  dialect: string;
+  hasReturningSupport: boolean;
+}
+
+export interface BulkBaseOptions {
+  chunkSize?: number;
+  concurrency?: BulkConcurrency;
+  transactional?: boolean;
+  timing?: boolean;
+  onChunkComplete?: (info: ChunkCompleteInfo) => void | Promise<void>;
+}
+
+export interface ChunkCompleteInfo {
+  chunkIndex: number;
+  totalChunks: number;
+  rowsInChunk: number;
+  elapsedMs: number;
+}
+
+export type InsertRow = Record<string, ValueOperandInput>;
+
+export interface BulkInsertOptions extends BulkBaseOptions {
+  returning?: boolean | ColumnDef[];
+  onConflict?: UpsertClause;
+}
+
+export interface BulkUpsertOptions extends BulkInsertOptions {
+  conflictColumns?: string[];
+  updateColumns?: string[];
+}
+
+export type UpdateRow = Record<string, ValueOperandInput>;
+
+export interface BulkUpdateOptions extends BulkBaseOptions {
+  by?: string | string[];
+  where?: ExpressionNode;
+  returning?: boolean | ColumnDef[];
+}
+
+export interface BulkDeleteOptions extends BulkBaseOptions {
+  by?: string;
+  where?: ExpressionNode;
+}
+
+export interface ChunkOutcome {
+  processedRows: number;
+  returning: Record<string, unknown>[];
+  elapsedMs: number;
+}

package/src/bulk/bulk-update-executor.ts

@@ -0,0 +1,192 @@
+import { UpdateQueryBuilder } from '../query-builder/update.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import { eq, and, inList } from '../core/ast/expression-builders.js';
+import type { TableDef } from '../schema/table.js';
+import type { OrmSession } from '../orm/orm-session.js';
+import type { BulkUpdateOptions, ChunkOutcome, UpdateRow } from './bulk-types.js';
+import type { ValueOperandInput } from '../core/ast/expression.js';
+import type { ExpressionNode } from '../core/ast/expression-nodes.js';
+import { BulkBaseExecutor, type BulkExecutorOptions } from './bulk-executor.base.js';
+import { resolveReturningColumns, flattenQueryResults, executeCompiled, createBulkExecutionContext } from './bulk-context.js';
+import { splitIntoChunks, runWithConcurrency, runChunk, maybeTransaction, aggregateOutcomes, aggregateOutcomesWithTimings } from './bulk-utils.js';
+
+interface UpdateExecutorOptions extends BulkExecutorOptions {
+  by?: string | string[];
+  where?: ExpressionNode;
+  returning?: boolean | import('../schema/column-types.js').ColumnDef[];
+}
+
+function resolveByColumns(table: TableDef, by: string | string[] | undefined): string[] {
+  if (!by) return [findPrimaryKey(table)];
+  return Array.isArray(by) ? by : [by];
+}
+
+export class BulkUpdateExecutor extends BulkBaseExecutor<UpdateExecutorOptions> {
+  private readonly byColumns: string[];
+
+  constructor(
+    session: OrmSession,
+    table: TableDef,
+    rows: UpdateRow[],
+    options: BulkUpdateOptions = {}
+  ) {
+    super(session, table, rows, options);
+    this.byColumns = resolveByColumns(table, options.by);
+  }
+
+  protected async executeChunk(chunk: UpdateRow[], chunkIndex: number): Promise<ChunkOutcome> {
+    const allReturning: Record<string, unknown>[] = [];
+    const returningColumns = resolveReturningColumns(this.ctx, this.table, this.options.returning);
+    const extraWhere = this.options.where;
+
+    for (const row of chunk) {
+      const predicates = this.byColumns.map(colName => {
+        const col = this.table.columns[colName];
+        if (!col) {
+          throw new Error(
+            `bulkUpdate: column "${colName}" not found in table "${this.table.name}"`
+          );
+        }
+        const val = row[colName];
+        if (val === undefined) {
+          throw new Error(
+            `bulkUpdate: row is missing the identity column "${colName}" required by the "by" option`
+          );
+        }
+        return eq(col, val as ValueOperandInput);
+      });
+
+      const whereExpr: ExpressionNode =
+        predicates.length === 1
+          ? predicates[0]
+          : predicates.reduce((acc, p) => and(acc, p) as ExpressionNode, predicates[0]);
+
+      const finalWhere = extraWhere ? and(whereExpr, extraWhere) as ExpressionNode : whereExpr;
+
+      const bySet = new Set(this.byColumns);
+      const setPayload: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(row)) {
+        if (!bySet.has(key) && key in this.table.columns) {
+          setPayload[key] = val;
+        }
+      }
+
+      if (!Object.keys(setPayload).length) continue;
+
+      let builder = new UpdateQueryBuilder(this.table).set(setPayload).where(finalWhere);
+
+      if (returningColumns?.length) {
+        builder = builder.returning(...returningColumns);
+      }
+
+      const compiled = builder.compile(this.ctx.dialect);
+      const resultSets = await executeCompiled(this.ctx, compiled);
+
+      if (returningColumns) {
+        allReturning.push(...flattenQueryResults(resultSets));
+      }
+    }
+
+    return {
+      processedRows: chunk.length,
+      returning: allReturning,
+      elapsedMs: 0,
+    };
+  }
+}
+
+export async function bulkUpdate<TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  rows: UpdateRow[],
+  options: BulkUpdateOptions = {}
+): Promise<import('./bulk-types.js').BulkResult> {
+  if (!rows.length) {
+    return { processedRows: 0, chunksExecuted: 0, returning: [] };
+  }
+
+  const executor = new BulkUpdateExecutor(session, table, rows, options);
+  return executor.execute();
+}
+
+const DEFAULT_BULK_UPDATE_WHERE_CHUNK_SIZE = 500;
+
+export async function bulkUpdateWhere<TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  ids: ValueOperandInput[],
+  set: Record<string, ValueOperandInput>,
+  options: Omit<BulkUpdateOptions, 'by' | 'returning'> & {
+    by?: string;
+    returning?: boolean | import('../schema/column-types.js').ColumnDef[];
+  } = {}
+): Promise<import('./bulk-types.js').BulkResult> {
+  if (!ids.length) {
+    return { processedRows: 0, chunksExecuted: 0, returning: [] };
+  }
+
+  const {
+    chunkSize = DEFAULT_BULK_UPDATE_WHERE_CHUNK_SIZE,
+    concurrency = 'sequential',
+    transactional = true,
+    timing = false,
+    onChunkComplete,
+    by,
+    where: extraWhere,
+    returning,
+  } = options;
+
+  const ctx = createBulkExecutionContext(session);
+  const byColumnName = by ?? findPrimaryKey(table);
+  const byColumn = table.columns[byColumnName];
+  if (!byColumn) {
+    throw new Error(
+      `bulkUpdateWhere: column "${byColumnName}" not found in table "${table.name}"`
+    );
+  }
+
+  const returningColumns = resolveReturningColumns(ctx, table, returning);
+  const chunks = splitIntoChunks(ids, chunkSize);
+  const totalChunks = chunks.length;
+
+  const buildTask = (chunk: ValueOperandInput[], chunkIndex: number) => async (): Promise<ChunkOutcome> => {
+    return runChunk(
+      async () => {
+        const inExpr = inList(byColumn, chunk as any);
+        const finalWhere = extraWhere ? and(inExpr, extraWhere) : inExpr;
+
+        let builder = new UpdateQueryBuilder(table).set(set as Record<string, unknown>).where(finalWhere);
+
+        if (returningColumns?.length) {
+          builder = builder.returning(...returningColumns);
+        }
+
+        const compiled = builder.compile(ctx.dialect);
+        const resultSets = await executeCompiled(ctx, compiled);
+
+        return {
+          processedRows: chunk.length,
+          returning: returningColumns ? flattenQueryResults(resultSets) : [],
+          elapsedMs: 0,
+        };
+      },
+      chunkIndex,
+      totalChunks,
+      chunk.length,
+      timing,
+      onChunkComplete
+    );
+  };
+
+  const tasks = chunks.map((chunk, i) => buildTask(chunk, i));
+
+  const outcomes = await maybeTransaction(
+    session,
+    transactional,
+    () => runWithConcurrency(tasks, concurrency)
+  );
+
+  return timing
+    ? aggregateOutcomesWithTimings(outcomes)
+    : aggregateOutcomes(outcomes);
+}