@proteinjs/db-driver-knex 1.15.0 → 1.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db-driver-knex",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,10 +41,10 @@
     "test": "jest --runInBand --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db": "^1.48.0",
+    "@proteinjs/db": "^1.49.0",
     "@proteinjs/db-query": "^1.10.1",
-    "@proteinjs/db-transaction-context": "^0.5.36",
-    "@proteinjs/logger": "^1.0.21",
+    "@proteinjs/db-transaction-context": "^0.5.37",
+    "@proteinjs/logger": "^1.2.0",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/util": "^1.6.1",
     "knex": "0.21.5",
@@ -67,5 +67,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "ec3fd54430dde18afd406ec70eccd857492272a0"
+  "gitHead": "5ef7c5a2f3eb6ef3b774aa93cc74cc1754cfa011"
 }

package/src/KnexDriver.ts

@@ -10,6 +10,7 @@ import {
 } from '@proteinjs/db';
 import { KnexConfig } from './KnexConfig';
 import { KnexLogValues } from './KnexLogValues';
+import { KnexFailureLine } from './KnexFailureLine';
 import { Logger } from '@proteinjs/logger';
 import { Statement } from '@proteinjs/db-query';
 import { KnexSchemaOperations } from './KnexSchemaOperations';
@@ -24,9 +25,6 @@ type ParamDescription = { type: string; length?: number; null?: true };
  */
 type ParamsDescription = ParamDescription[] | { [name: string]: ParamDescription } | 'unreadable';
 
-/** A failure as the log line carries it: the error's name, the vendor's codes and the server's own message. */
-type FailureCauseSummary = { name?: string; code?: string; errno?: number; sqlState?: string; sqlMessage?: string };
-
 /**
  * Knex driver (configured for MariaDb) for ProteinJs Db
  */
@@ -177,6 +175,8 @@ export class KnexDriver implements DbDriver {
       // returns 2 arrays, first is records, second is metadata per record
       return (await runner.raw(sql, params as any).timeout(this.getOperationDeadlineMs(), { cancel: true }))[0];
     } catch (error: unknown) {
+      // Rethrown as it is; marked, so no line about it — this driver's or a caller's — prints its text.
+      KnexFailureLine.mark(error, 'Failed when executing sql');
       this.logFailure(sql, params, error);
       throw error;
     }
@@ -196,10 +196,25 @@ export class KnexDriver implements DbDriver {
    * @returns the return value of the `fn`
    */
   async runTransaction<T>(fn: (transaction: Transaction) => Promise<T>): Promise<T> {
-    return await this.getKnex().transaction(async (trx) => {
-      const result = await fn(trx);
-      return result;
-    });
+    const bodyErrors = new Set<unknown>();
+    try {
+      return await this.getKnex().transaction(async (trx) => {
+        try {
+          return await fn(trx);
+        } catch (error: unknown) {
+          bodyErrors.add(error);
+          throw error;
+        }
+      });
+    } catch (error: unknown) {
+      // What the BODY threw is the caller's own error, or a failure already marked at the
+      // statement's door. Anything else was raised around the body — beginning, committing —
+      // and words itself as the vendor did. Rethrown as it is, either way.
+      if (!bodyErrors.has(error)) {
+        KnexFailureLine.mark(error, 'Transaction failed');
+      }
+      throw error;
+    }
   }
 
   /**
@@ -238,7 +253,7 @@ export class KnexDriver implements DbDriver {
           sql,
           params: this.describeParams(params),
           ...KnexLogValues.ofStatement(params),
-          cause: this.causeSummary(error),
+          cause: KnexFailureLine.causeOf(error),
         },
         ...KnexLogValues.ofFailure(error),
       })
@@ -267,25 +282,6 @@ export class KnexDriver implements DbDriver {
     }
   }
 
-  /**
-   * The name, codes and server message of any thrown value — never the query layer's rewritten
-   * `message` or `sql`. Total: a fact that cannot be read (vendorFact) is left out.
-   */
-  private causeSummary(error: unknown): FailureCauseSummary {
-    const name = this.vendorFact(error, 'name');
-    const code = this.vendorFact(error, 'code');
-    const errno = this.vendorFact(error, 'errno');
-    const sqlState = this.vendorFact(error, 'sqlState');
-    const sqlMessage = this.vendorFact(error, 'sqlMessage');
-    return {
-      ...(typeof name === 'string' ? { name } : {}),
-      ...(typeof code === 'string' ? { code } : {}),
-      ...(typeof errno === 'number' ? { errno } : {}),
-      ...(typeof sqlState === 'string' ? { sqlState } : {}),
-      ...(typeof sqlMessage === 'string' ? { sqlMessage } : {}),
-    };
-  }
-
   /**
    * A statement's bound parameters as a LOG LINE carries them — the one owner of that form: by
    * position, the KIND of each value and, for strings, arrays and bytes, its LENGTH. Never a
@@ -377,13 +373,4 @@ export class KnexDriver implements DbDriver {
     const prototype = Object.getPrototypeOf(params);
     return prototype === null || Object.getPrototypeOf(prototype) === null;
   }
-
-  /** One fact of a thrown value, or nothing when it cannot be read (nothing thrown, a scalar, a throwing accessor). */
-  private vendorFact(error: unknown, fact: keyof FailureCauseSummary): unknown {
-    try {
-      return (error as { [fact: string]: unknown } | null | undefined)?.[fact];
-    } catch {
-      return undefined;
-    }
-  }
 }

package/src/KnexFailureLine.ts

@@ -0,0 +1,127 @@
+import { ErrorLine, LogLineErrors } from '@proteinjs/logger';
+import { KnexLogValues } from './KnexLogValues';
+
+/**
+ * A failure as the driver's own line carries it under `cause`: the error's name, the vendor's
+ * codes and, as `message`, the driver's sentence — the field a reader of any driver's line parses.
+ */
+export type FailureCause = {
+  name?: string;
+  code?: string;
+  errno?: number;
+  sqlState?: string;
+  message: string;
+  /** The server's own message — behind the dev-only values switch, never otherwise. */
+  sqlMessage?: string;
+};
+
+/**
+ * The ONE owner of how a failure of the database reads on a LOG LINE: the vendor's codes and a
+ * sentence of the driver's own — never the vendor's text.
+ *
+ * What the driver THROWS is the vendor's error itself, untouched, and it is not safe to print:
+ * the query layer rewrites its `message` to the SQL with every binding INTERPOLATED, the client
+ * library carries the same text as `sql`, and the server's own message (`sqlMessage`) quotes the
+ * value it refused (`Duplicate entry '<key>' for key 'PRIMARY'`). The driver's own line never
+ * carried the first two; a CALLER's line about the error it caught carried all three. So every
+ * failure that leaves the driver is marked with the logger (`mark`), which never touches the
+ * error; from then on any line about it, the driver's or a caller's, carries the codes and the
+ * sentence in place of the error's own text.
+ *
+ * The vendor's text rides a line only behind the dev-only values switch (KnexLogValues): with
+ * both gates open a marked error prints as it is, and `causeOf` adds the server's message.
+ * Asked at each line, like the switch itself.
+ */
+export class KnexFailureLine {
+  private static readonly UNNAMED = 'the database refused the statement';
+  private static readonly UNREACHABLE = 'the database could not be reached';
+  private static readonly SENTENCES: { [code: string]: string } = {
+    ER_DUP_ENTRY: 'a row with that key already exists',
+    ER_NO_SUCH_TABLE: 'a table the statement names does not exist',
+    ER_BAD_FIELD_ERROR: 'a column the statement names does not exist',
+    ER_PARSE_ERROR: 'the statement does not parse',
+    ER_LOCK_DEADLOCK: 'the transaction was chosen as a deadlock victim',
+    ER_LOCK_WAIT_TIMEOUT: 'a lock wait timed out',
+    ER_DATA_TOO_LONG: 'a value is longer than its column',
+    ER_TRUNCATED_WRONG_VALUE: 'a value does not convert to the type of its column',
+    ER_TRUNCATED_WRONG_VALUE_FOR_FIELD: 'a value does not convert to the type of its column',
+    ER_WARN_DATA_OUT_OF_RANGE: 'a value is out of range for its column',
+    ER_BAD_NULL_ERROR: 'a column that cannot be null was given null',
+    ER_NO_REFERENCED_ROW_2: 'a foreign key refused the statement',
+    ER_ROW_IS_REFERENCED_2: 'a foreign key refused the statement',
+    ER_ACCESS_DENIED_ERROR: 'the credentials of the caller were not accepted',
+    ER_NET_PACKET_TOO_LARGE: 'the statement is larger than the server accepts',
+    ECONNREFUSED: KnexFailureLine.UNREACHABLE,
+    ECONNRESET: KnexFailureLine.UNREACHABLE,
+    ETIMEDOUT: KnexFailureLine.UNREACHABLE,
+    PROTOCOL_CONNECTION_LOST: KnexFailureLine.UNREACHABLE,
+  };
+  /**
+   * The failures the query layer raises itself, which carry no vendor code — by the error's name.
+   * Its timeout is one error for the statement's operation deadline and for the wait for a free
+   * connection; either way it carries the statement's bindings, so it is marked like any other.
+   */
+  private static readonly SENTENCES_BY_NAME: { [name: string]: string } = {
+    KnexTimeoutError: 'the statement or its wait for a connection timed out',
+  };
+
+  /**
+   * Marks `error` — whatever the client library or the query layer rejected with — as never
+   * printing its own text, and answers the same error. `what` is the driver's words for what
+   * failed. An error already marked keeps its line.
+   */
+  static mark<T>(error: T, what: string): T {
+    if (!LogLineErrors.isMarked(error)) {
+      LogLineErrors.mark(error, () => (KnexLogValues.enabled() ? undefined : KnexFailureLine.lineOf(error, what)));
+    }
+    return error;
+  }
+
+  /**
+   * The failure as the driver's own line carries it under `cause` — never the query layer's
+   * rewritten `message` or `sql`, and the server's own message only behind the values switch.
+   * Total: a fact that cannot be read is left out.
+   */
+  static causeOf(error: unknown): FailureCause {
+    const name = KnexFailureLine.vendorFact(error, 'name');
+    const code = KnexFailureLine.vendorFact(error, 'code');
+    const errno = KnexFailureLine.vendorFact(error, 'errno');
+    const sqlState = KnexFailureLine.vendorFact(error, 'sqlState');
+    const sqlMessage = KnexLogValues.enabled() ? KnexFailureLine.vendorFact(error, 'sqlMessage') : undefined;
+    return {
+      ...(typeof name === 'string' ? { name } : {}),
+      ...(typeof code === 'string' ? { code } : {}),
+      ...(typeof errno === 'number' ? { errno } : {}),
+      ...(typeof sqlState === 'string' ? { sqlState } : {}),
+      message: KnexFailureLine.sentenceOf(code, name),
+      ...(typeof sqlMessage === 'string' ? { sqlMessage } : {}),
+    };
+  }
+
+  private static lineOf(error: unknown, what: string): ErrorLine {
+    const { name: _name, message, sqlMessage: _sqlMessage, ...codes } = KnexFailureLine.causeOf(error);
+    const named = [codes.code, codes.errno !== undefined ? `errno ${codes.errno}` : undefined].filter(Boolean);
+    return {
+      ...(codes.code !== undefined ? { code: codes.code } : {}),
+      sentence: `${what}${named.length ? ` (${named.join(', ')})` : ''}: ${message}`,
+      facts: codes,
+    };
+  }
+
+  private static sentenceOf(code: unknown, name: unknown): string {
+    return (
+      (typeof code === 'string' ? KnexFailureLine.SENTENCES[code] : undefined) ??
+      (typeof name === 'string' ? KnexFailureLine.SENTENCES_BY_NAME[name] : undefined) ??
+      KnexFailureLine.UNNAMED
+    );
+  }
+
+  /** One fact of a thrown value, or nothing when it cannot be read (nothing thrown, a scalar, a throwing accessor). */
+  private static vendorFact(error: unknown, fact: string): unknown {
+    try {
+      return (error as { [fact: string]: unknown } | null | undefined)?.[fact];
+    } catch {
+      return undefined;
+    }
+  }
+}

package/test/LogValuesSwitch.test.ts

@@ -141,12 +141,14 @@ describe('the dev-only values switch: real values ride the driver`s failure line
     expect(facts(caught)).toEqual(baseline);
     // The description and the summary ride the line at every gate.
     expect(failure.obj.params).toEqual([{ type: 'string', length: VALUE.length }, { type: 'number' }]);
+    // The server's own message rides the summary only behind the switch.
     expect(failure.obj.cause).toEqual({
       name: 'Error',
       code: 'ER_NO_SUCH_TABLE',
       errno: 1146,
       sqlState: '42S02',
-      sqlMessage: `Table 'test.credential' doesn't exist`,
+      message: 'a table the statement names does not exist',
+      ...(on ? { sqlMessage: `Table 'test.credential' doesn't exist` } : {}),
     });
     if (!on) {
       for (const log of captured) {

package/test/StatementLogNeverThrows.test.ts

@@ -1,6 +1,6 @@
 import knex from 'knex';
 import { inspect } from 'util';
-import { KnexDriver } from '@proteinjs/db-driver-knex';
+import { KnexDriver, KnexFailureLine } from '@proteinjs/db-driver-knex';
 import { Logger } from '@proteinjs/logger';
 import { CapturedLog, lineOf } from './util/printedLine';
 
@@ -12,7 +12,7 @@ import { CapturedLog, lineOf } from './util/printedLine';
  *
  * Two layers hold that, and this suite holds both:
  *
- *  - the helpers that build the line (`describeParams`, `causeSummary`) are TOTAL: whatever they
+ *  - the helpers that build the line (`describeParams`, `KnexFailureLine.causeOf`) are TOTAL: whatever they
  *    are handed — positional bindings, a bindings dictionary, nothing, null, a scalar, a Map, a
  *    value whose accessor or `toJSON` throws, a proxy that refuses everything — they return a
  *    description and never a value;
@@ -34,7 +34,6 @@ type ParamsDescription = ParamDescription[] | { [name: string]: ParamDescription
 type DriverInternals = {
   logger: Logger;
   describeParams: (params?: unknown) => ParamsDescription | undefined;
-  causeSummary: (error: unknown) => { [fact: string]: unknown };
 };
 type DriverStatics = { KNEX?: unknown };
 
@@ -164,13 +163,8 @@ describe('describeParams is total: any bindings, a description, never a value',
   });
 });
 
-describe('causeSummary is total: anything thrown, a summary of codes, never the rewritten message', () => {
-  const internals = new KnexDriver({
-    host: 'localhost',
-    user: 'root',
-    password: '',
-    dbName: 'test',
-  }) as unknown as DriverInternals;
+describe('KnexFailureLine.causeOf is total: anything thrown, a summary of codes and the driver`s sentence, never the vendor`s text', () => {
+  const UNNAMED = 'the database refused the statement';
   const vendorFacts = {
     code: 'ER_NO_SUCH_TABLE',
     errno: 1146,
@@ -182,27 +176,37 @@ describe('causeSummary is total: anything thrown, a summary of codes, never the
     [
       'a vendor error whose message and sql carry the bindings',
       () => Object.assign(new Error(`insert ... '${CANARY}'`), vendorFacts, { sql: `insert ... '${CANARY}'` }),
-      { name: 'Error', ...vendorFacts },
+      {
+        name: 'Error',
+        code: 'ER_NO_SUCH_TABLE',
+        errno: 1146,
+        sqlState: '42S02',
+        message: 'a table the statement names does not exist',
+      },
+    ],
+    ['nothing', () => undefined, { message: UNNAMED }],
+    ['null', () => null, { message: UNNAMED }],
+    ['a thrown string', () => CANARY, { message: UNNAMED }],
+    ['a thrown number', () => 1146, { message: UNNAMED }],
+    [
+      'facts of the wrong kind',
+      () => ({ name: 5, code: 1146, errno: '1146', sqlState: null, sqlMessage: {} }),
+      { message: UNNAMED },
     ],
-    ['nothing', () => undefined, {}],
-    ['null', () => null, {}],
-    ['a thrown string', () => CANARY, {}],
-    ['a thrown number', () => 1146, {}],
-    ['facts of the wrong kind', () => ({ name: 5, code: 1146, errno: '1146', sqlState: null, sqlMessage: {} }), {}],
     [
       'an error with a fact whose accessor throws',
       () => throwingEntry(Object.assign(new Error(CANARY), vendorFacts), 'code'),
-      { name: 'Error', errno: 1146, sqlState: '42S02', sqlMessage: vendorFacts.sqlMessage },
+      { name: 'Error', errno: 1146, sqlState: '42S02', message: UNNAMED },
     ],
-    ['an error that refuses every read', () => refusesEverything(new Error(CANARY)), {}],
-    ['a revoked error', () => revoked(new Error(CANARY)), {}],
+    ['an error that refuses every read', () => refusesEverything(new Error(CANARY)), { message: UNNAMED }],
+    ['a revoked error', () => revoked(new Error(CANARY)), { message: UNNAMED }],
   ];
 
   test.each(THROWN)('%s', (_shape, thrown, expected) => {
     let summary: { [fact: string]: unknown } | undefined;
 
     expect(() => {
-      summary = internals.causeSummary(thrown());
+      summary = KnexFailureLine.causeOf(thrown());
     }).not.toThrow();
 
     expect(summary).toEqual(expected);

package/test/StatementParamLogging.test.ts

@@ -14,8 +14,8 @@ import { CapturedLog, lineOf } from './util/printedLine';
  * The contract: the failure line carries the SQL text (placeholders only), the parameters
  * DESCRIBED — each one's position, the kind of its value and, for strings, arrays and bytes, its
  * length; one private helper (`describeParams`) owns that form — and a summary of the failure (the
- * error's name, the vendor's codes, the server's own message). The vendor error itself no longer
- * rides the line. (The dev-only switch that adds the values back is LogValuesSwitch.test.ts; it is
+ * error's name, the vendor's codes, the driver's own sentence — KnexFailureLine). The vendor error
+ * itself no longer rides the line. (The dev-only switch that adds the values back is LogValuesSwitch.test.ts; it is
  * off here.) A statement's bindings are typed as an array, but the query layer also accepts a
  * bindings DICTIONARY (`:name` placeholders) and the driver forwards what it was handed: a
  * dictionary is described by entry name. (Every other shape the driver can be handed, and a log
@@ -26,13 +26,10 @@ import { CapturedLog, lineOf } from './util/printedLine';
  * that prints what it catches still prints the interpolated SQL; that is the query layer's
  * behaviour and this contract does not change it.
  *
- * SCOPE, by name: this suite holds what the DRIVER prints of the parameters it was handed. It does
- * NOT hold the vendor-echo class — the server's own message can quote a bound value (`Duplicate
- * entry '…' for key 'PRIMARY'`), and that text reaches the line's cause summary and the thrown
- * error exactly as it did before. Closing that class means changing what the driver throws; that
- * work is parked on the branch `fix/driver-logs-never-carry-param-values`, pending a decision. So
- * the canaries below are bound to parameters the server does not echo, and the one value it does
- * echo — the colliding key — is left out of the assertions on purpose.
+ * SCOPE, by name: this suite holds what the DRIVER prints of the parameters it was handed. The
+ * vendor-echo class — the server's own message quoting a bound value (`Duplicate entry '…' for key
+ * 'PRIMARY'`) — is VendorTextNeverOnALine.test.ts: no line carries the server's message, and a
+ * caller's line about the error it caught carries the driver's sentence in its place.
  *
  * No server is needed: the REAL query layer and dialect run over a stub connection that rejects
  * the way the client library does (its own `format` builds the interpolated `sql`), so the
@@ -140,11 +137,10 @@ describe('The driver never prints a bound value; what it throws is the vendor`s
 
     const failures = captured.filter((log) => log.logLevel === 'error' && log.message === 'Failed when executing sql');
     expect(failures).toHaveLength(1);
-    // (`ECHOED_KEY` is NOT asserted: the server quotes the colliding key in its own message — the
-    // vendor-echo class this suite leaves out by name; see the header.)
     for (const log of captured) {
       expect(lineOf(log)).not.toContain(SECRET_TOKEN);
       expect(lineOf(log)).not.toContain(SECRET_EMAIL);
+      expect(lineOf(log)).not.toContain(ECHOED_KEY);
     }
     const [failure] = failures;
     expect(failure.obj.sql).toBe(INSERT);
@@ -160,7 +156,7 @@ describe('The driver never prints a bound value; what it throws is the vendor`s
       code: 'ER_DUP_ENTRY',
       errno: 1062,
       sqlState: '23000',
-      sqlMessage: `Duplicate entry '${ECHOED_KEY}' for key 'PRIMARY'`,
+      message: 'a row with that key already exists',
     });
     expect(Object.keys(failure.obj)).not.toContain('paramValues');
     // The vendor error itself — the carrier of the interpolated SQL — is not on the line.
@@ -188,11 +184,10 @@ describe('The driver never prints a bound value; what it throws is the vendor`s
     const failures = captured.filter((log) => log.logLevel === 'error');
     expect(failures).toHaveLength(1);
     expect(failures[0].obj.params).toEqual([{ type: 'string', length: SECRET_TOKEN.length }]);
-    // This statement's first binding IS the token, so the stub server echoes it: the summary's
-    // `sqlMessage` is the vendor-echo class. Everything else on the line is the driver's.
-    const { sqlMessage, ...ownFacts } = failures[0].obj.cause;
-    expect(sqlMessage).toContain(SECRET_TOKEN);
-    expect(lineOf({ ...failures[0], obj: { ...failures[0].obj, cause: ownFacts } })).not.toContain(SECRET_TOKEN);
+    // This statement's first binding IS the token, so the stub server echoes it in its own
+    // message — which no line carries.
+    expect(Object.keys(failures[0].obj.cause)).not.toContain('sqlMessage');
+    expect(lineOf(failures[0])).not.toContain(SECRET_TOKEN);
   });
 
   test('a failed statement inside a transaction: the same line, and the transaction rejects with the vendor`s error itself', async () => {