@proteinjs/db 1.52.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.52.0",
+  "version": "1.53.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "57c2ed1dca68a508bbd7b194ea7695ac4cf93344"
+  "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>() =>
@@ -112,6 +113,13 @@ export interface DbDriver {
    * 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> {
@@ -219,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).
@@ -288,7 +300,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
           statementRows 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);
+      }
     }
 
     for (const { recordCopy, encryptionContext } of prepared) {
@@ -1020,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();

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);
+  });
+});