@kronos-ts/knex 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { knexTransactionManager, type KnexInstanceLike, type KnexTransaction, } from "./knex-transaction-manager.js";
+export { knexTransactionManager, type KnexInstanceLike, type KnexTransaction, type KnexTransactionManagerOptions, } from "./knex-transaction-manager.js";
 export { knexTokenStore, type KnexQueryable, } from "./knex-token-store.js";
 export { knexDeadLetterQueue, type KnexDeadLetterQueueConfig, } from "./knex-dead-letter-queue.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAGvB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAIvB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAA"}

package/dist/knex-transaction-manager.d.ts

@@ -9,6 +9,26 @@ export interface KnexInstanceLike {
  * The Knex transaction object.
  */
 export type KnexTransaction = any;
+export interface KnexTransactionManagerOptions {
+    /**
+     * Runs once on every transaction, right after it opens and before the UoW
+     * gets the handle. This is where a Postgres-backed deployment arms session
+     * GUCs — chiefly `idle_in_transaction_session_timeout` — so a stalled UoW
+     * (e.g. a hung dead-letter drain whose replay never returns) is aborted by
+     * the database instead of pinning a connection indefinitely. The Postgres
+     * adapter does this for its own transactions; this hook is the equivalent
+     * seam for the (DB-agnostic) Knex/Drizzle path. No-op by default.
+     *
+     * Example (pg client):
+     * ```ts
+     * knexTransactionManager(knex, {
+     *   onBeginTransaction: (trx) => trx.raw(
+     *     "SET LOCAL idle_in_transaction_session_timeout = 30000"),
+     * })
+     * ```
+     */
+    readonly onBeginTransaction?: (tx: KnexTransaction) => Promise<void>;
+}
 /**
  * Creates a TransactionManager for Knex.
  *
@@ -27,5 +47,5 @@ export type KnexTransaction = any;
  * const txManager = knexTransactionManager(knex)
  * ```
  */
-export declare function knexTransactionManager(knex: KnexInstanceLike): TransactionManager<KnexTransaction>;
+export declare function knexTransactionManager(knex: KnexInstanceLike, options?: KnexTransactionManagerOptions): TransactionManager<KnexTransaction>;
 //# sourceMappingURL=knex-transaction-manager.d.ts.map

package/dist/knex-transaction-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knex-transaction-manager.d.ts","sourceRoot":"","sources":["../src/knex-transaction-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACzD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,GAAG,CAAA;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,GACrB,kBAAkB,CAAC,eAAe,CAAC,CA2CrC"}
+{"version":3,"file":"knex-transaction-manager.d.ts","sourceRoot":"","sources":["../src/knex-transaction-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACzD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,GAAG,CAAA;AAEjC,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACrE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,6BAAkC,GAC1C,kBAAkB,CAAC,eAAe,CAAC,CA4DrC"}

package/dist/knex-transaction-manager.js

@@ -16,23 +16,41 @@
  * const txManager = knexTransactionManager(knex)
  * ```
  */
-export function knexTransactionManager(knex) {
+export function knexTransactionManager(knex, options = {}) {
+    const { onBeginTransaction } = options;
     return {
         async begin() {
             let resolveTx;
+            let rejectTx;
             let resolveCompletion;
             let rejectCompletion;
-            const txReady = new Promise((resolve) => {
+            const txReady = new Promise((resolve, reject) => {
                 resolveTx = resolve;
+                rejectTx = reject;
             });
             const completionSignal = new Promise((resolve, reject) => {
                 resolveCompletion = resolve;
                 rejectCompletion = reject;
             });
             const txPromise = knex.transaction(async (trx) => {
+                // Arm session settings (e.g. idle-in-transaction timeout) before the
+                // UoW gets the handle, so begin() only resolves once the tx is bounded.
+                if (onBeginTransaction) {
+                    try {
+                        await onBeginTransaction(trx);
+                    }
+                    catch (err) {
+                        rejectTx(err);
+                        throw err;
+                    }
+                }
                 resolveTx(trx);
                 await completionSignal;
             });
+            // If knex.transaction() rejects before onBeginTransaction runs (e.g. the
+            // pool can't hand out a connection), make begin() reject instead of
+            // hanging on txReady forever.
+            txPromise.catch(rejectTx);
             const tx = await txReady;
             tx.__kronos_commit = resolveCompletion;
             tx.__kronos_rollback = rejectCompletion;

package/dist/knex-transaction-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"knex-transaction-manager.js","sourceRoot":"","sources":["../src/knex-transaction-manager.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAsB;IAEtB,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,SAAyC,CAAA;YAC7C,IAAI,iBAA8B,CAAA;YAClC,IAAI,gBAA2C,CAAA;YAE/C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,EAAE;gBACvD,SAAS,GAAG,OAAO,CAAA;YACrB,CAAC,CAAC,CAAA;YAEF,MAAM,gBAAgB,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC7D,iBAAiB,GAAG,OAAO,CAAA;gBAC3B,gBAAgB,GAAG,MAAM,CAAA;YAC3B,CAAC,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC/C,SAAS,CAAC,GAAG,CAAC,CAAA;gBACd,MAAM,gBAAgB,CAAA;YACxB,CAAC,CAAC,CAAA;YAEF,MAAM,EAAE,GAAG,MAAM,OAAO,CACvB;YAAC,EAAU,CAAC,eAAe,GAAG,iBAAiB,CAC/C;YAAC,EAAU,CAAC,iBAAiB,GAAG,gBAAgB,CAChD;YAAC,EAAU,CAAC,kBAAkB,GAAG,SAAS,CAAA;YAE3C,OAAO,EAAE,CAAA;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAmB;YAC9B,MAAM,MAAM,GAAI,EAAU,CAAC,eAA6B,CAAA;YACxD,MAAM,SAAS,GAAI,EAAU,CAAC,kBAAmC,CAAA;YACjE,MAAM,EAAE,CAAA;YACR,MAAM,SAAS,CAAA;QACjB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,EAAmB;YAChC,MAAM,QAAQ,GAAI,EAAU,CAAC,iBAA6C,CAAA;YAC1E,MAAM,SAAS,GAAI,EAAU,CAAC,kBAAmC,CAAA;YACjE,QAAQ,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;YAC9C,IAAI,CAAC;gBAAC,MAAM,SAAS,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;QAClD,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"knex-transaction-manager.js","sourceRoot":"","sources":["../src/knex-transaction-manager.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAsB,EACtB,UAAyC,EAAE;IAE3C,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAA;IACtC,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,SAAyC,CAAA;YAC7C,IAAI,QAAmC,CAAA;YACvC,IAAI,iBAA8B,CAAA;YAClC,IAAI,gBAA2C,CAAA;YAE/C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC/D,SAAS,GAAG,OAAO,CAAA;gBACnB,QAAQ,GAAG,MAAM,CAAA;YACnB,CAAC,CAAC,CAAA;YAEF,MAAM,gBAAgB,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC7D,iBAAiB,GAAG,OAAO,CAAA;gBAC3B,gBAAgB,GAAG,MAAM,CAAA;YAC3B,CAAC,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC/C,qEAAqE;gBACrE,wEAAwE;gBACxE,IAAI,kBAAkB,EAAE,CAAC;oBACvB,IAAI,CAAC;wBACH,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAA;oBAC/B,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,QAAQ,CAAC,GAAG,CAAC,CAAA;wBACb,MAAM,GAAG,CAAA;oBACX,CAAC;gBACH,CAAC;gBACD,SAAS,CAAC,GAAG,CAAC,CAAA;gBACd,MAAM,gBAAgB,CAAA;YACxB,CAAC,CAAC,CAAA;YACF,yEAAyE;YACzE,oEAAoE;YACpE,8BAA8B;YAC9B,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;YAEzB,MAAM,EAAE,GAAG,MAAM,OAAO,CACvB;YAAC,EAAU,CAAC,eAAe,GAAG,iBAAiB,CAC/C;YAAC,EAAU,CAAC,iBAAiB,GAAG,gBAAgB,CAChD;YAAC,EAAU,CAAC,kBAAkB,GAAG,SAAS,CAAA;YAE3C,OAAO,EAAE,CAAA;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAmB;YAC9B,MAAM,MAAM,GAAI,EAAU,CAAC,eAA6B,CAAA;YACxD,MAAM,SAAS,GAAI,EAAU,CAAC,kBAAmC,CAAA;YACjE,MAAM,EAAE,CAAA;YACR,MAAM,SAAS,CAAA;QACjB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,EAAmB;YAChC,MAAM,QAAQ,GAAI,EAAU,CAAC,iBAA6C,CAAA;YAC1E,MAAM,SAAS,GAAI,EAAU,CAAC,kBAAmC,CAAA;YACjE,QAAQ,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;YAC9C,IAAI,CAAC;gBAAC,MAAM,SAAS,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;QAClD,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/knex",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Knex extension for Kronos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@kronos-ts/common": "0.1.1",
-    "@kronos-ts/messaging": "0.6.0"
+    "@kronos-ts/messaging": "0.8.0"
   },
   "peerDependencies": {
     "knex": ">=3.0.0"

package/src/index.ts

@@ -2,6 +2,7 @@ export {
   knexTransactionManager,
   type KnexInstanceLike,
   type KnexTransaction,
+  type KnexTransactionManagerOptions,
 } from "./knex-transaction-manager.js"
 
 export {

package/src/knex-transaction-manager.ts

@@ -12,6 +12,27 @@ export interface KnexInstanceLike {
  */
 export type KnexTransaction = any
 
+export interface KnexTransactionManagerOptions {
+  /**
+   * Runs once on every transaction, right after it opens and before the UoW
+   * gets the handle. This is where a Postgres-backed deployment arms session
+   * GUCs — chiefly `idle_in_transaction_session_timeout` — so a stalled UoW
+   * (e.g. a hung dead-letter drain whose replay never returns) is aborted by
+   * the database instead of pinning a connection indefinitely. The Postgres
+   * adapter does this for its own transactions; this hook is the equivalent
+   * seam for the (DB-agnostic) Knex/Drizzle path. No-op by default.
+   *
+   * Example (pg client):
+   * ```ts
+   * knexTransactionManager(knex, {
+   *   onBeginTransaction: (trx) => trx.raw(
+   *     "SET LOCAL idle_in_transaction_session_timeout = 30000"),
+   * })
+   * ```
+   */
+  readonly onBeginTransaction?: (tx: KnexTransaction) => Promise<void>
+}
+
 /**
  * Creates a TransactionManager for Knex.
  *
@@ -32,15 +53,19 @@ export type KnexTransaction = any
  */
 export function knexTransactionManager(
   knex: KnexInstanceLike,
+  options: KnexTransactionManagerOptions = {},
 ): TransactionManager<KnexTransaction> {
+  const { onBeginTransaction } = options
   return {
     async begin(): Promise<KnexTransaction> {
       let resolveTx!: (tx: KnexTransaction) => void
+      let rejectTx!: (error: unknown) => void
       let resolveCompletion!: () => void
       let rejectCompletion!: (error: unknown) => void
 
-      const txReady = new Promise<KnexTransaction>((resolve) => {
+      const txReady = new Promise<KnexTransaction>((resolve, reject) => {
         resolveTx = resolve
+        rejectTx = reject
       })
 
       const completionSignal = new Promise<void>((resolve, reject) => {
@@ -49,9 +74,23 @@ export function knexTransactionManager(
       })
 
       const txPromise = knex.transaction(async (trx) => {
+        // Arm session settings (e.g. idle-in-transaction timeout) before the
+        // UoW gets the handle, so begin() only resolves once the tx is bounded.
+        if (onBeginTransaction) {
+          try {
+            await onBeginTransaction(trx)
+          } catch (err) {
+            rejectTx(err)
+            throw err
+          }
+        }
         resolveTx(trx)
         await completionSignal
       })
+      // If knex.transaction() rejects before onBeginTransaction runs (e.g. the
+      // pool can't hand out a connection), make begin() reject instead of
+      // hanging on txReady forever.
+      txPromise.catch(rejectTx)
 
       const tx = await txReady
       ;(tx as any).__kronos_commit = resolveCompletion