@proteinjs/db 1.52.0 → 1.54.0

package/index.ts

@@ -2,6 +2,8 @@ export * from './src/Db';
 export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
+export * from './src/DuplicateKeyError';
+export * from './src/TransactionRetryExhaustedError';
 export * from './src/auth/TableAuth';
 export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';
@@ -24,6 +26,7 @@ export * from './src/TableWatcher';
 export * from './src/transaction/Transaction';
 export * from './src/transaction/TransactionRunner';
 export * from './src/transaction/TransactionContextFactory';
+export * from './src/transaction/TransactionRetryPolicy';
 
 export * from './src/schema/SchemaOperations';
 export * from './src/schema/SchemaMetadata';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.52.0",
+  "version": "1.54.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": "856ac58e8bb61e5d46261ffb57434994fb808390"
 }

package/src/Db.ts

@@ -32,6 +32,8 @@ 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';
+import { TransactionOptions } from './transaction/TransactionRetryPolicy';
 
 /** get `Db` if on server, and `DbService` if on browser */
 export const getDb = <R extends Record = Record>() =>
@@ -93,8 +95,24 @@ export interface DbDriver {
     generateStatement: (config: DbDriverQueryStatementConfig) => Statement,
     transaction?: any
   ): Promise<SerializedRecord[]>;
-  runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement, transaction?: any): Promise<number>;
-  runTransaction<T>(fn: (transaction: any) => Promise<T>): Promise<T>;
+  /**
+   * Run one write statement. On `transaction` it rides that transaction; without one it is a
+   * transaction of its own, and `options.retry` (`TransactionRetryPolicy`) is how the driver
+   * re-runs it when the database aborts it — the driver's own road when omitted, else the bound
+   * named, past which the driver throws `TransactionRetryExhaustedError`. A driver that never
+   * re-runs an aborted statement (the abort reaches the caller at once) already satisfies every
+   * policy.
+   */
+  runDml(
+    generateStatement: (config: DbDriverDmlStatementConfig) => Statement,
+    transaction?: any,
+    options?: TransactionOptions
+  ): Promise<number>;
+  /**
+   * Run `fn` as one transaction. `options.retry` (`TransactionRetryPolicy`) is how the driver
+   * re-runs the whole body when the database aborts the transaction — see `runDml`.
+   */
+  runTransaction<T>(fn: (transaction: any) => Promise<T>, options?: TransactionOptions): Promise<T>;
   /**
    * The driver's per-operation deadline, in milliseconds: the longest one statement it runs may
    * take before the driver fails it — the bound the driver enforces, as configured. Not a whole
@@ -112,6 +130,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> {
@@ -201,10 +226,18 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return (await this.query(table, query, options))[0];
   }
 
-  async insert<T extends R>(table: Table<T>, record: Omit<T, keyof R>): Promise<T> {
+  /**
+   * Insert one row. Outside a transaction the insert is a transaction of its own, and
+   * `options.retry` names how it is re-run when the database aborts it (`TransactionRetryPolicy`:
+   * the driver's own road when omitted; a bounded policy for a best-effort write, past which the
+   * caller takes `TransactionRetryExhaustedError`). Inside a transaction the transaction's policy
+   * governs, and an insert naming one of its own is refused.
+   */
+  async insert<T extends R>(table: Table<T>, record: Omit<T, keyof R>, options?: TransactionOptions): Promise<T> {
     if (!this.runAsSystem) {
       this.auth.canInsert(table);
     }
+    const driverOptions = this.ownTransactionOptions(options);
 
     let recordCopy = Object.assign({}, record);
     await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
@@ -219,7 +252,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(), driverOptions);
+    } 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 +325,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) {
@@ -307,7 +348,20 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return prepared.map((row) => row.recordCopy as T);
   }
 
-  async update<T extends R>(table: Table<T>, record: Partial<T>, query?: Query<T>): Promise<number> {
+  /**
+   * Update the rows `query` selects (the one row `record.id` names when there is no query).
+   * Outside a transaction the update is a transaction of its own, and `options.retry` names how
+   * it is re-run when the database aborts it (`TransactionRetryPolicy`: the driver's own road when
+   * omitted; a bounded policy for a best-effort write — a live progress row the next step
+   * rewrites anyway — past which the caller takes `TransactionRetryExhaustedError`). Inside a
+   * transaction the transaction's policy governs, and an update naming one of its own is refused.
+   */
+  async update<T extends R>(
+    table: Table<T>,
+    record: Partial<T>,
+    query?: Query<T>,
+    options?: TransactionOptions
+  ): Promise<number> {
     if (!this.runAsSystem) {
       this.auth.canUpdate(table);
     }
@@ -315,6 +369,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     if (!query && !record.id) {
       throw new Error(`Update must be called with either a Query or a record with an id property`);
     }
+    const driverOptions = this.ownTransactionOptions(options);
 
     let recordCopy = Object.assign({}, record);
     // Immutable columns can never be rewritten through an update — strip them from the payload
@@ -337,7 +392,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     recordCopy = await this.tableWatcherRunner.runBeforeUpdateTableWatchers(table, recordCopy, qb);
     let recordUpdateCount: number;
     if (await this.updateTouchesEncryptedColumns(table, recordCopy)) {
-      recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb);
+      recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb, driverOptions);
     } else {
       const recordSerializer = new RecordSerializer<T>(table);
       const serializedRecord = await recordSerializer.serialize(recordCopy);
@@ -349,7 +404,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
           qb,
           this.statementConfigFactory.getStatementConfig(config)
         );
-      recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+      recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver(), driverOptions);
     }
     if (!this.runAsSystem && recordUpdateCount === 0) {
       const id = this.singleRowIdTarget(record, query);
@@ -912,6 +967,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
    *
    * Note: Nested transactions are not supported; will throw.
    *
+   * `options.retry` names how the driver re-runs the whole body when the database aborts the
+   * transaction (`TransactionRetryPolicy`: the driver's own road when omitted; a bounded policy
+   * for best-effort work, past which this throws `TransactionRetryExhaustedError`). Every write
+   * inside the body rides this policy; none may name one of its own.
+   *
    * Note: work spawned inside the body but NOT awaited by it escapes the transaction's
    * lifetime while still holding its context — such work fails loudly on its next db
    * operation (see TransactionContextData.ended). Await everything inside the body, or run
@@ -930,7 +990,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * });
    * ```
    */
-  async runTransaction<T>(fn: () => Promise<T>): Promise<T> {
+  async runTransaction<T>(fn: () => Promise<T>, options?: TransactionOptions): Promise<T> {
     if (this.transactionContextFactory.getTransactionContext().currentTransaction) {
       throw new Error(`Nested transactions are not supported. A transaction is already running in this context.`);
     }
@@ -953,7 +1013,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         // silent op on a finished transaction (see transactionForDriver).
         contextData.ended = true;
       }
-    });
+    }, options);
 
     // COMMIT BOUNDARY: the driver resolves only after the transaction is durably committed (and
     // rejects on rollback, in which case the queue above is never drained). Hook failures are
@@ -1020,6 +1080,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();
@@ -1037,7 +1106,8 @@ export class Db<R extends Record = Record> implements DbService<R> {
   private async updateEncrypted<T extends R>(
     table: Table<T>,
     recordCopy: Partial<T>,
-    qb: QueryBuilder<T>
+    qb: QueryBuilder<T>,
+    options?: TransactionOptions
   ): Promise<number> {
     const targetRows = await this._query(table, qb);
     if (targetRows.length === 0) {
@@ -1071,7 +1141,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
           groupQb,
           this.statementConfigFactory.getStatementConfig(config)
         );
-      recordUpdateCount += await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+      recordUpdateCount += await this.dbDriver.runDml(generateUpdate, this.transactionForDriver(), options);
       await tokenMaintenance.afterUpdate(table, ids, recordCopy, owner, this.newSystemDb());
     }
 
@@ -1124,6 +1194,22 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return context.currentTransaction;
   }
 
+  /**
+   * A write's transaction options as the driver takes them: its own, when the write runs outside
+   * any transaction and so is a transaction of its own. Inside a transaction the write rides the
+   * transaction, whose policy was named on `runTransaction`; a policy named on the write would be
+   * one nothing honours — refused by name, never dropped.
+   */
+  private ownTransactionOptions(options?: TransactionOptions): TransactionOptions | undefined {
+    if (options?.retry !== undefined && this.transactionContextFactory.getTransactionContext().currentTransaction) {
+      throw new Error(
+        `A write inside a transaction cannot name a retry policy of its own: the transaction's policy (runTransaction's options) governs every write in it`
+      );
+    }
+
+    return options;
+  }
+
   /**
    * 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,

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/src/TransactionRetryExhaustedError.ts

@@ -0,0 +1,37 @@
+/**
+ * A transaction the database aborted (a lock conflict it resolved against this transaction) that
+ * its caller's retry policy (`TransactionRetryPolicy`) did not allow to be re-run any further:
+ * every attempt the policy allowed was made, or its time budget was spent, and the last one was
+ * aborted too. The driver throws it in place of the database's own abort, so a caller that chose
+ * a bounded policy — a best-effort write that loses to the next write of its kind — takes the
+ * refusal by type and decides what to do with it: nothing was written by this transaction, and
+ * nothing was retried behind the caller's back.
+ *
+ * `attempts` is how many attempts were made in all; `elapsedMs` the wall-clock from the first
+ * attempt's start to the last abort; `cause` the abort that ended the last attempt (the driver's
+ * own error for it — for callers in process; not enumerable, so a serialized error carries none
+ * of the backend's words).
+ *
+ * Name-tagged rather than relying on `instanceof`: the prototype chain is unreliable across
+ * package compile targets (the same reason `DuplicateKeyError` checks `name`).
+ */
+export class TransactionRetryExhaustedError extends Error {
+  readonly cause: unknown;
+
+  constructor(
+    operation: string,
+    readonly attempts: number,
+    readonly elapsedMs: number,
+    cause: unknown
+  ) {
+    super(
+      `Transaction aborted and not retried further: its retry policy allowed ${attempts} attempt${attempts === 1 ? '' : 's'}, ` +
+        `made in ${Math.round(elapsedMs)}ms (${operation})`
+    );
+    this.name = 'TransactionRetryExhaustedError';
+    Object.defineProperty(this, 'cause', { value: cause, enumerable: false, writable: false });
+  }
+}
+
+export const isTransactionRetryExhaustedError = (error: unknown): error is TransactionRetryExhaustedError =>
+  !!error && typeof error === 'object' && (error as { name?: string }).name === 'TransactionRetryExhaustedError';

package/src/transaction/TransactionRetryPolicy.ts

@@ -0,0 +1,31 @@
+/**
+ * How a transaction is re-run when the database ABORTS it — a lock conflict the database
+ * resolves by aborting one of the transactions in it, delivered at that transaction's next
+ * statement or at its commit. The policy is the CALLER's, named at the call, never a default a
+ * caller cannot see:
+ *
+ * - Omitted: the driver's own road — the one right for a durable write, which must land however
+ *   long the conflict lasts (on Spanner, the client library's runner re-runs the body on its
+ *   backoff ladder inside the driver's configured budget).
+ * - `'none'`: one attempt. The abort reaches the caller at once, typed
+ *   (`TransactionRetryExhaustedError`).
+ * - `{ attempts, maxMs }`: at most `attempts` attempts in all (the first included), and no
+ *   attempt starts once `maxMs` milliseconds have passed since the first began; when either
+ *   bound is reached the last abort reaches the caller typed. `maxMs` omitted bounds by
+ *   attempts alone.
+ *
+ * A BEST-EFFORT write names a bounded policy: a write that the next write of its kind supersedes
+ * anyway (a live progress row rewritten at every step) must not be re-run for minutes against a
+ * conflict it will lose — it loses promptly, and the caller handles the typed refusal.
+ *
+ * The policy belongs to a transaction: a write issued outside any transaction is a transaction
+ * of its own and names it at the write (`Db.insert`, `Db.update`); a `Db.runTransaction` body
+ * names it on the transaction, and every write inside that body rides it — a write inside a
+ * transaction cannot name a policy of its own.
+ */
+export type TransactionRetryPolicy = 'none' | { attempts: number; maxMs?: number };
+
+/** The options of a transaction — a `Db.runTransaction` body's, or a write's own when it runs outside one. */
+export type TransactionOptions = {
+  retry?: TransactionRetryPolicy;
+};

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