@proteinjs/db 1.51.0 → 1.53.0

package/index.ts

@@ -2,6 +2,7 @@ export * from './src/Db';
 export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
+export * from './src/DuplicateKeyError';
 export * from './src/auth/TableAuth';
 export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,7 +41,7 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.10.2",
+    "@proteinjs/db-query": "^1.11.0",
     "@proteinjs/logger": "^1.2.0",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "1128b1e6374c7f52cd5de172620b619b8f92e119"
+  "gitHead": "480320d415088dd0d378bd0e9863dc70353fa92f"
 }

package/src/Db.ts

@@ -32,6 +32,7 @@ import { ReferenceArray } from './reference/ReferenceArray';
 import { ReferenceCache } from './reference/ReferenceCache';
 import { ArrayMembershipUpdate, applyArrayMembershipOps } from './reference/ArrayMembershipOps';
 import { PreservedPath, overlayPreservedPaths } from './UpdatePreserving';
+import { DuplicateKeyError } from './DuplicateKeyError';
 
 /** get `Db` if on server, and `DbService` if on browser */
 export const getDb = <R extends Record = Record>() =>
@@ -104,6 +105,21 @@ export interface DbDriver {
    * configured its database to tolerate rather than a number of its own.
    */
   getOperationDeadlineMs(): number;
+  /**
+   * The most bound parameters one statement may carry on this driver's backend, when the backend
+   * bounds it — `Db.insertMany` sizes its multi-row statements by it (`columns × rows` parameters
+   * each), so a batch wider than the bound goes as the fewest statements that fit instead of one
+   * the backend refuses. A driver whose backend declares no such bound leaves this undeclared,
+   * and a batch on it is always one statement.
+   */
+  getStatementParameterLimit?(): number;
+  /**
+   * Whether `error` — what this driver's `runDml` threw — is the backend refusing a row because a
+   * row with the same key is already there (the primary key, or a unique index). `Db.insert` and
+   * `Db.insertMany` rethrow such a refusal as the typed `DuplicateKeyError`, so a caller can take
+   * it by type. A driver that declares no classifier lets the backend's error through as it came.
+   */
+  isDuplicateKeyError?(error: unknown): boolean;
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {
@@ -211,7 +227,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
         serializedRecord as Partial<T>,
         this.statementConfigFactory.getStatementConfig(config)
       );
-    await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+    try {
+      await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+    } catch (error) {
+      throw this.insertFailure(table, error);
+    }
     if (encryptionContext) {
       // The same write that stored the ciphertext maintains its search tokens (rides the
       // ambient transaction when there is one).
@@ -228,6 +248,81 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return recordCopy as T;
   }
 
+  /**
+   * Insert `records` as ONE statement (a multi-row INSERT) instead of one statement per row,
+   * each row keeping every contract {@link insert} gives a single one: the table's default field
+   * values, the before-insert table watchers, the columns' before-insert hooks, the encryption
+   * context, then — after the statement — the search-token upkeep, the columns' after-insert
+   * hooks and the after-insert table watchers. Each phase runs per row, in the order given, and
+   * sees the row exactly as `insert` would; what differs from N single inserts is only that every
+   * row's before-phases precede the statement and every row's after-phases follow it.
+   *
+   * Atomic: inside a transaction the statement rides it; outside one this opens a transaction
+   * of its own around the batch, so a row the database refuses fails the whole batch and no row
+   * of it lands. A batch wider than the driver's statement parameter bound
+   * ({@link DbDriver.getStatementParameterLimit}) goes as the fewest statements that fit, in
+   * order, inside that same transaction.
+   *
+   * Returns the rows as inserted (defaults applied, watchers' changes carried), in order. An
+   * empty list inserts nothing and returns [].
+   */
+  async insertMany<T extends R>(table: Table<T>, records: Omit<T, keyof R>[]): Promise<T[]> {
+    if (!this.runAsSystem) {
+      this.auth.canInsert(table);
+    }
+    if (records.length === 0) {
+      return [];
+    }
+    if (!this.transactionContextFactory.getTransactionContext().currentTransaction) {
+      const db = this.newSelfWrapDb();
+      return await db.runTransaction(async () => await db.insertMany(table, records));
+    }
+
+    const prepared: {
+      recordCopy: any;
+      encryptionContext?: { keyOwner: string };
+      serializedRecord: SerializedRecord;
+    }[] = [];
+    for (const record of records) {
+      let recordCopy = Object.assign({}, record);
+      await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
+      recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy);
+      await this.addColumnInsertHooks(table, recordCopy);
+      const encryptionContext = await this.encryptionWriteContext(table, recordCopy);
+      const serializedRecord = await new RecordSerializer(table, encryptionContext).serialize(recordCopy);
+      prepared.push({ recordCopy, encryptionContext, serializedRecord });
+    }
+
+    for (const statementRows of this.chunkByParameterLimit(prepared.map((row) => row.serializedRecord))) {
+      const generateInsert = (config: DbDriverDmlStatementConfig) =>
+        new StatementFactory<T>().insertMany(
+          table.name,
+          statementRows as Partial<T>[],
+          this.statementConfigFactory.getStatementConfig(config)
+        );
+      try {
+        await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+      } catch (error) {
+        throw this.insertFailure(table, error);
+      }
+    }
+
+    for (const { recordCopy, encryptionContext } of prepared) {
+      if (encryptionContext) {
+        const { EncryptionTokenMaintenance } = await import('./encryption/EncryptionTokenMaintenance');
+        await new EncryptionTokenMaintenance().afterInsert(
+          table,
+          recordCopy,
+          encryptionContext.keyOwner,
+          this.newSystemDb()
+        );
+      }
+      await this.runColumnAfterInsertHooks(table, recordCopy);
+      await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
+    }
+    return prepared.map((row) => row.recordCopy as T);
+  }
+
   async update<T extends R>(table: Table<T>, record: Partial<T>, query?: Query<T>): Promise<number> {
     if (!this.runAsSystem) {
       this.auth.canUpdate(table);
@@ -941,6 +1036,15 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return { keyOwner: await new EncryptionRecordHooks().resolveKeyOwnerForWrite(table, record) };
   }
 
+  /**
+   * What an insert statement's failure becomes for the caller: the typed `DuplicateKeyError` when
+   * the driver classifies the backend's refusal as a row already there; any other failure as it
+   * came.
+   */
+  private insertFailure(table: Table<any>, error: unknown): unknown {
+    return this.dbDriver.isDuplicateKeyError?.(error) ? new DuplicateKeyError(table.name, error) : error;
+  }
+
   private async updateTouchesEncryptedColumns(table: Table<any>, record: any): Promise<boolean> {
     const { EncryptedColumns } = await import('./encryption/EncryptedColumns');
     const encryptedColumns = new EncryptedColumns();
@@ -1045,6 +1149,29 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return context.currentTransaction;
   }
 
+  /**
+   * The rows of one multi-row insert split into the fewest statements the driver's statement
+   * parameter bound admits (`insertMany`): each statement binds `columns × rows` parameters,
+   * the columns being the union over the whole batch (what `StatementFactory.insertMany` lists),
+   * so the split follows the batch's widest shape rather than the first statement's. One
+   * statement when the driver declares no bound.
+   */
+  private chunkByParameterLimit(rows: SerializedRecord[]): SerializedRecord[][] {
+    const limit = this.dbDriver.getStatementParameterLimit?.();
+    if (limit === undefined) {
+      return [rows];
+    }
+
+    const columns = new Set<string>();
+    for (const row of rows) {
+      for (const column of Object.keys(row)) {
+        columns.add(column);
+      }
+    }
+    const rowsPerStatement = Math.max(1, Math.floor(limit / Math.max(1, columns.size)));
+    return this.chunk(rows, rowsPerStatement);
+  }
+
   // Utility: simple chunker
   private chunk<T>(arr: T[], size: number): T[][] {
     if (size <= 0) {

package/src/DuplicateKeyError.ts

@@ -0,0 +1,26 @@
+/**
+ * An insert the database refused because a row with the same key is already there — the primary
+ * key, or any unique index the table declares. `Db.insert` and `Db.insertMany` throw it in place
+ * of the driver's own error (which rides as `cause`, never printed: the backend's words quote the
+ * colliding key), so a caller for whom "that row already exists" is a branch of its own — an
+ * insert-then-update that keeps one row per key under concurrent writers — takes it by type,
+ * never by the backend's message text. Which errors are this class is the driver's call
+ * (`DbDriver.isDuplicateKeyError`); a driver that declares no classifier lets the backend's error
+ * through as it came.
+ *
+ * Name-tagged rather than relying on `instanceof`: the prototype chain is unreliable across
+ * package compile targets (the same reason `RecordAccessError` checks `name`).
+ */
+export class DuplicateKeyError extends Error {
+  /** The driver's error — for callers in process; not enumerable, so a serialized error carries no row key. */
+  readonly cause: unknown;
+
+  constructor(tableName: string, cause: unknown) {
+    super(`(${tableName}) Insert refused: a row with the same key already exists`);
+    this.name = 'DuplicateKeyError';
+    Object.defineProperty(this, 'cause', { value: cause, enumerable: false, writable: false });
+  }
+}
+
+export const isDuplicateKeyError = (error: unknown): error is DuplicateKeyError =>
+  !!error && typeof error === 'object' && (error as { name?: string }).name === 'DuplicateKeyError';

package/test/DuplicateKeyError.test.ts

@@ -0,0 +1,179 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Statement } from '@proteinjs/db-query';
+import { Db, DbDriver, DbDriverDmlStatementConfig } from '../src/Db';
+import { DuplicateKeyError, isDuplicateKeyError } from '../src/DuplicateKeyError';
+import { Table } from '../src/Table';
+import { Record, withRecordColumns } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+
+/**
+ * What an insert's refusal becomes for the caller: a refusal the driver classifies as a duplicate
+ * key (a row with the same key already there — the primary key or a unique index) reaches the
+ * caller as the typed `DuplicateKeyError`, name-tagged, naming the table and carrying the driver's
+ * error as a cause that never prints; every other failure, and every failure on a driver that
+ * declares no classifier, reaches the caller exactly as the driver threw it. The same on
+ * `insertMany`. What the database itself refuses is the drivers' emulator suites' (the settings
+ * package's one-row-per-name suite proves the unique index's refusal end to end).
+ */
+
+interface Doc extends Record {
+  title: string;
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'duplicate_key_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** A driver whose every DML fails with the error it is handed, classifying `code === 6` as a duplicate key. */
+class RefusingDriver implements DbDriver {
+  constructor(private readonly refusal: unknown) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<never[]> {
+    return [];
+  }
+
+  async runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement): Promise<number> {
+    generateStatement({
+      useParams: true,
+      useNamedParams: true,
+      prefixTablesWithDb: false,
+      getDriverColumnType: () => 'STRING(MAX)',
+    });
+    throw this.refusal;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+
+  isDuplicateKeyError(error: unknown): boolean {
+    return (error as { code?: unknown } | null | undefined)?.code === 6;
+  }
+}
+
+/** The same driver with no classifier declared. */
+class UnclassifyingDriver extends RefusingDriver {
+  isDuplicateKeyError = undefined as unknown as (error: unknown) => boolean;
+}
+
+const dbOn = (driver: DbDriver) => new Db(driver, () => docTable, new TestTransactionContextFactory(), true);
+
+const failureOf = async (act: () => Promise<unknown>): Promise<unknown> => {
+  try {
+    await act();
+  } catch (error) {
+    return error;
+  }
+  throw new Error('the insert was expected to fail');
+};
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+
+describe('an insert the database refuses because the row is already there', () => {
+  const backendRefusal = Object.assign(new Error('Row {pk#id:"7f3"} in table duplicate_key_doc already exists'), {
+    code: 6,
+  });
+  let originalWatchers: unknown[] | undefined;
+
+  // No reflection graph in a unit test: the watcher registry is empty by declaration.
+  beforeAll(() => {
+    originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+    objectCache()['@proteinjs/db/TableWatcher'] = [];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  afterAll(() => {
+    if (originalWatchers) {
+      objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+    } else {
+      delete objectCache()['@proteinjs/db/TableWatcher'];
+    }
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  test('reaches the caller as the typed DuplicateKeyError, naming the table, carrying the cause unprinted', async () => {
+    const failure = await failureOf(() => dbOn(new RefusingDriver(backendRefusal)).insert(docTable, { title: 'a' }));
+    expect(isDuplicateKeyError(failure)).toBe(true);
+    const typed = failure as DuplicateKeyError;
+    expect(typed.name).toBe('DuplicateKeyError');
+    expect(typed.message).toBe('(duplicate_key_doc) Insert refused: a row with the same key already exists');
+    expect(typed.cause).toBe(backendRefusal);
+    // The backend's words quote the colliding key: they ride for callers in process only.
+    expect(Object.keys(typed)).not.toContain('cause');
+    expect(JSON.stringify(typed)).not.toContain('pk#id');
+  });
+
+  test('the same on insertMany', async () => {
+    const failure = await failureOf(() =>
+      dbOn(new RefusingDriver(backendRefusal)).insertMany(docTable, [{ title: 'a' }, { title: 'b' }])
+    );
+    expect(isDuplicateKeyError(failure)).toBe(true);
+    expect((failure as DuplicateKeyError).cause).toBe(backendRefusal);
+  });
+
+  test('any other refusal reaches the caller as the driver threw it', async () => {
+    const aborted = Object.assign(new Error('Transaction was aborted'), { code: 10 });
+    const failure = await failureOf(() => dbOn(new RefusingDriver(aborted)).insert(docTable, { title: 'a' }));
+    expect(failure).toBe(aborted);
+    expect(isDuplicateKeyError(failure)).toBe(false);
+  });
+
+  test('a driver that declares no classifier lets the refusal through as it came', async () => {
+    const failure = await failureOf(() =>
+      dbOn(new UnclassifyingDriver(backendRefusal)).insert(docTable, { title: 'a' })
+    );
+    expect(failure).toBe(backendRefusal);
+  });
+
+  test('the guard reads the name, not the prototype chain', () => {
+    expect(isDuplicateKeyError(Object.assign(new Error('x'), { name: 'DuplicateKeyError' }))).toBe(true);
+    expect(isDuplicateKeyError(new Error('DuplicateKeyError'))).toBe(false);
+    expect(isDuplicateKeyError(undefined)).toBe(false);
+    expect(isDuplicateKeyError('DuplicateKeyError')).toBe(false);
+  });
+});