@kronos-ts/knex 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { knexTransactionManager, type KnexInstanceLike, type KnexTransaction, } from "./knex-transaction-manager.js";
+export { knexTokenStore, type KnexQueryable, } from "./knex-token-store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { knexTransactionManager, } from "./knex-transaction-manager.js";
+export { knexTokenStore, } from "./knex-token-store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/knex-token-store.d.ts

@@ -0,0 +1,27 @@
+import type { TokenStore } from "@kronos-ts/messaging";
+/**
+ * A Knex instance or transaction with query builder methods.
+ */
+export interface KnexQueryable {
+    (tableName: string): any;
+    raw(sql: string, ...bindings: any[]): any;
+}
+/**
+ * Creates a TokenStore backed by Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexTokenStore } from "@kronos-ts/knex"
+ *
+ * // tokenStore wiring to a kronos() App is pending a typed `tokenStore` slot
+ * // (Phase 9). For now, construct the store and pass it directly to the
+ * // tracking processor that owns it:
+ * const tokenStore = knexTokenStore(knex)
+ * ```
+ */
+export declare function knexTokenStore(knex: KnexQueryable, options?: {
+    claimTimeoutMs?: number;
+    tableName?: string;
+}): TokenStore;
+//# sourceMappingURL=knex-token-store.d.ts.map

package/dist/knex-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knex-token-store.d.ts","sourceRoot":"","sources":["../src/knex-token-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,sBAAsB,CAAA;AAqBrE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAA;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;CAC1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,UAAU,CA+GZ"}

package/dist/knex-token-store.js

@@ -0,0 +1,124 @@
+import { getActiveTransaction, UnableToClaimTokenError, globalSequenceToken } from "@kronos-ts/messaging";
+function serializeToken(token) {
+    return {
+        token_type: "GlobalSequenceToken",
+        token: JSON.stringify({ position: token.position().toString() }),
+    };
+}
+function deserializeToken(tokenType, token) {
+    if (!token || !tokenType)
+        return undefined;
+    const data = JSON.parse(token);
+    return globalSequenceToken(BigInt(data.position));
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Creates a TokenStore backed by Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexTokenStore } from "@kronos-ts/knex"
+ *
+ * // tokenStore wiring to a kronos() App is pending a typed `tokenStore` slot
+ * // (Phase 9). For now, construct the store and pass it directly to the
+ * // tracking processor that owns it:
+ * const tokenStore = knexTokenStore(knex)
+ * ```
+ */
+export function knexTokenStore(knex, options) {
+    const claimTimeoutMs = options?.claimTimeoutMs ?? 10000;
+    const table = options?.tableName ?? "kronos_token_entries";
+    function getKnex() {
+        return getActiveTransaction() ?? knex;
+    }
+    return {
+        async store(processorName, segment, token) {
+            const k = getKnex();
+            const { token_type, token: tokenData } = serializeToken(token);
+            await k.raw(`INSERT INTO ?? (processor_name, segment, mask, token_type, token, timestamp, owner)
+         VALUES (?, ?, 0, ?, ?, ?, NULL)
+         ON CONFLICT (processor_name, segment) DO UPDATE SET token_type = ?, token = ?, timestamp = ?`, [table, processorName, segment, token_type, tokenData, nowIso(), token_type, tokenData, nowIso()]);
+        },
+        async get(processorName, segment) {
+            const k = getKnex();
+            const row = await k(table)
+                .where({ processor_name: processorName, segment })
+                .first();
+            if (!row)
+                return undefined;
+            return deserializeToken(row.token_type, row.token);
+        },
+        async initializeSegments(processorName, segmentCount) {
+            const k = getKnex();
+            for (let i = 0; i < segmentCount; i++) {
+                await k.raw(`INSERT INTO ?? (processor_name, segment, mask, token_type, token, timestamp, owner)
+           VALUES (?, ?, 0, NULL, NULL, NULL, NULL)
+           ON CONFLICT (processor_name, segment) DO NOTHING`, [table, processorName, i]);
+            }
+        },
+        async claimToken(processorName, segment, ownerId) {
+            const k = getKnex();
+            const row = await k(table)
+                .where({ processor_name: processorName, segment })
+                .first();
+            if (!row) {
+                await k(table).insert({
+                    processor_name: processorName, segment, mask: 0,
+                    token_type: null, token: null, timestamp: nowIso(), owner: ownerId,
+                });
+                return undefined;
+            }
+            const isExpired = !row.owner || !row.timestamp ||
+                (Date.now() - new Date(row.timestamp).getTime() > claimTimeoutMs);
+            if (row.owner === ownerId || isExpired) {
+                await k(table)
+                    .where({ processor_name: processorName, segment })
+                    .update({ owner: ownerId, timestamp: nowIso() });
+                return deserializeToken(row.token_type, row.token);
+            }
+            throw new UnableToClaimTokenError(processorName, segment);
+        },
+        async extendClaim(processorName, segment, ownerId) {
+            const k = getKnex();
+            await k(table)
+                .where({ processor_name: processorName, segment, owner: ownerId })
+                .update({ timestamp: nowIso() });
+        },
+        async releaseClaim(processorName, segment, ownerId) {
+            const k = getKnex();
+            await k(table)
+                .where({ processor_name: processorName, segment, owner: ownerId })
+                .update({ owner: null, timestamp: null });
+        },
+        async fetchSegments(processorName) {
+            const k = getKnex();
+            const rows = await k(table)
+                .where({ processor_name: processorName })
+                .select("segment")
+                .orderBy("segment", "asc");
+            return rows.map((r) => r.segment);
+        },
+        async fetchAvailableSegments(processorName) {
+            const k = getKnex();
+            const cutoff = new Date(Date.now() - claimTimeoutMs).toISOString();
+            const rows = await k(table)
+                .where({ processor_name: processorName })
+                .where(function () {
+                this.whereNull("owner").orWhere("timestamp", "<", cutoff);
+            })
+                .select("segment")
+                .orderBy("segment", "asc");
+            return rows.map((r) => r.segment);
+        },
+        async deleteToken(processorName, segment) {
+            const k = getKnex();
+            await k(table)
+                .where({ processor_name: processorName, segment })
+                .delete();
+        },
+    };
+}
+//# sourceMappingURL=knex-token-store.js.map

package/dist/knex-token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knex-token-store.js","sourceRoot":"","sources":["../src/knex-token-store.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,31 @@
+import type { TransactionManager } from "@kronos-ts/messaging";
+/**
+ * A Knex instance that supports transactions.
+ */
+export interface KnexInstanceLike {
+    transaction<T>(fn: (trx: any) => Promise<T>): Promise<T>;
+}
+/**
+ * The Knex transaction object.
+ */
+export type KnexTransaction = any;
+/**
+ * Creates a TransactionManager for Knex.
+ *
+ * Bridges Knex's `knex.transaction(fn)` callback to the framework's
+ * `begin/commit/rollback` lifecycle.
+ *
+ * ```typescript
+ * import Knex from "knex"
+ * import { knexTransactionManager } from "@kronos-ts/knex"
+ *
+ * const knex = Knex({ client: "pg", connection: "..." })
+ *
+ * // transactionManager wiring to a kronos() App is pending a typed
+ * // `transactionManager` slot (Phase 9). For now, construct the manager
+ * // and pass it directly into the unitOfWorkFactory composition:
+ * const txManager = knexTransactionManager(knex)
+ * ```
+ */
+export declare function knexTransactionManager(knex: KnexInstanceLike): TransactionManager<KnexTransaction>;
+//# sourceMappingURL=knex-transaction-manager.d.ts.map

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

@@ -0,0 +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"}

package/dist/knex-transaction-manager.js

@@ -0,0 +1,59 @@
+/**
+ * Creates a TransactionManager for Knex.
+ *
+ * Bridges Knex's `knex.transaction(fn)` callback to the framework's
+ * `begin/commit/rollback` lifecycle.
+ *
+ * ```typescript
+ * import Knex from "knex"
+ * import { knexTransactionManager } from "@kronos-ts/knex"
+ *
+ * const knex = Knex({ client: "pg", connection: "..." })
+ *
+ * // transactionManager wiring to a kronos() App is pending a typed
+ * // `transactionManager` slot (Phase 9). For now, construct the manager
+ * // and pass it directly into the unitOfWorkFactory composition:
+ * const txManager = knexTransactionManager(knex)
+ * ```
+ */
+export function knexTransactionManager(knex) {
+    return {
+        async begin() {
+            let resolveTx;
+            let resolveCompletion;
+            let rejectCompletion;
+            const txReady = new Promise((resolve) => {
+                resolveTx = resolve;
+            });
+            const completionSignal = new Promise((resolve, reject) => {
+                resolveCompletion = resolve;
+                rejectCompletion = reject;
+            });
+            const txPromise = knex.transaction(async (trx) => {
+                resolveTx(trx);
+                await completionSignal;
+            });
+            const tx = await txReady;
+            tx.__kronos_commit = resolveCompletion;
+            tx.__kronos_rollback = rejectCompletion;
+            tx.__kronos_txPromise = txPromise;
+            return tx;
+        },
+        async commit(tx) {
+            const commit = tx.__kronos_commit;
+            const txPromise = tx.__kronos_txPromise;
+            commit();
+            await txPromise;
+        },
+        async rollback(tx) {
+            const rollback = tx.__kronos_rollback;
+            const txPromise = tx.__kronos_txPromise;
+            rollback(new Error("Transaction rolled back"));
+            try {
+                await txPromise;
+            }
+            catch { /* expected */ }
+        },
+    };
+}
+//# sourceMappingURL=knex-transaction-manager.js.map

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

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kronos-ts/knex",
+  "version": "0.1.0",
+  "description": "Knex extension for Kronos.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Theo Emanuelsson",
+  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/extensions/knex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KronosDB/kronos-ts.git",
+    "directory": "packages/extensions/knex"
+  },
+  "bugs": {
+    "url": "https://github.com/KronosDB/kronos-ts/issues"
+  },
+  "keywords": [
+    "kronos",
+    "event-sourcing",
+    "cqrs",
+    "dcb",
+    "typescript",
+    "knex"
+  ],
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.bench.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@kronos-ts/common": "workspace:*",
+    "@kronos-ts/messaging": "workspace:*"
+  },
+  "peerDependencies": {
+    "knex": ">=3.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+  knexTransactionManager,
+  type KnexInstanceLike,
+  type KnexTransaction,
+} from "./knex-transaction-manager.js"
+
+export {
+  knexTokenStore,
+  type KnexQueryable,
+} from "./knex-token-store.js"

package/src/knex-token-store.ts

@@ -0,0 +1,158 @@
+import type { TokenStore, TrackingToken } from "@kronos-ts/messaging"
+import { getActiveTransaction, UnableToClaimTokenError, globalSequenceToken } from "@kronos-ts/messaging"
+import type { KnexTransaction } from "./knex-transaction-manager.js"
+
+function serializeToken(token: TrackingToken): { token_type: string; token: string } {
+  return {
+    token_type: "GlobalSequenceToken",
+    token: JSON.stringify({ position: token.position().toString() }),
+  }
+}
+
+function deserializeToken(tokenType: string | null, token: string | null): TrackingToken | undefined {
+  if (!token || !tokenType) return undefined
+  const data = JSON.parse(token)
+  return globalSequenceToken(BigInt(data.position))
+}
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+/**
+ * A Knex instance or transaction with query builder methods.
+ */
+export interface KnexQueryable {
+  (tableName: string): any
+  raw(sql: string, ...bindings: any[]): any
+}
+
+/**
+ * Creates a TokenStore backed by Knex.
+ *
+ * Participates in the active transaction via `getActiveTransaction()`.
+ *
+ * ```typescript
+ * import { knexTokenStore } from "@kronos-ts/knex"
+ *
+ * // tokenStore wiring to a kronos() App is pending a typed `tokenStore` slot
+ * // (Phase 9). For now, construct the store and pass it directly to the
+ * // tracking processor that owns it:
+ * const tokenStore = knexTokenStore(knex)
+ * ```
+ */
+export function knexTokenStore(
+  knex: KnexQueryable,
+  options?: { claimTimeoutMs?: number; tableName?: string },
+): TokenStore {
+  const claimTimeoutMs = options?.claimTimeoutMs ?? 10000
+  const table = options?.tableName ?? "kronos_token_entries"
+
+  function getKnex(): KnexQueryable {
+    return getActiveTransaction<KnexTransaction>() ?? knex
+  }
+
+  return {
+    async store(processorName, segment, token) {
+      const k = getKnex()
+      const { token_type, token: tokenData } = serializeToken(token)
+      await k.raw(
+        `INSERT INTO ?? (processor_name, segment, mask, token_type, token, timestamp, owner)
+         VALUES (?, ?, 0, ?, ?, ?, NULL)
+         ON CONFLICT (processor_name, segment) DO UPDATE SET token_type = ?, token = ?, timestamp = ?`,
+        [table, processorName, segment, token_type, tokenData, nowIso(), token_type, tokenData, nowIso()],
+      )
+    },
+
+    async get(processorName, segment) {
+      const k = getKnex()
+      const row = await k(table)
+        .where({ processor_name: processorName, segment })
+        .first()
+      if (!row) return undefined
+      return deserializeToken(row.token_type, row.token)
+    },
+
+    async initializeSegments(processorName, segmentCount) {
+      const k = getKnex()
+      for (let i = 0; i < segmentCount; i++) {
+        await k.raw(
+          `INSERT INTO ?? (processor_name, segment, mask, token_type, token, timestamp, owner)
+           VALUES (?, ?, 0, NULL, NULL, NULL, NULL)
+           ON CONFLICT (processor_name, segment) DO NOTHING`,
+          [table, processorName, i],
+        )
+      }
+    },
+
+    async claimToken(processorName, segment, ownerId) {
+      const k = getKnex()
+      const row = await k(table)
+        .where({ processor_name: processorName, segment })
+        .first()
+
+      if (!row) {
+        await k(table).insert({
+          processor_name: processorName, segment, mask: 0,
+          token_type: null, token: null, timestamp: nowIso(), owner: ownerId,
+        })
+        return undefined
+      }
+
+      const isExpired = !row.owner || !row.timestamp ||
+        (Date.now() - new Date(row.timestamp).getTime() > claimTimeoutMs)
+
+      if (row.owner === ownerId || isExpired) {
+        await k(table)
+          .where({ processor_name: processorName, segment })
+          .update({ owner: ownerId, timestamp: nowIso() })
+        return deserializeToken(row.token_type, row.token)
+      }
+
+      throw new UnableToClaimTokenError(processorName, segment)
+    },
+
+    async extendClaim(processorName, segment, ownerId) {
+      const k = getKnex()
+      await k(table)
+        .where({ processor_name: processorName, segment, owner: ownerId })
+        .update({ timestamp: nowIso() })
+    },
+
+    async releaseClaim(processorName, segment, ownerId) {
+      const k = getKnex()
+      await k(table)
+        .where({ processor_name: processorName, segment, owner: ownerId })
+        .update({ owner: null, timestamp: null })
+    },
+
+    async fetchSegments(processorName) {
+      const k = getKnex()
+      const rows = await k(table)
+        .where({ processor_name: processorName })
+        .select("segment")
+        .orderBy("segment", "asc")
+      return rows.map((r: any) => r.segment)
+    },
+
+    async fetchAvailableSegments(processorName) {
+      const k = getKnex()
+      const cutoff = new Date(Date.now() - claimTimeoutMs).toISOString()
+      const rows = await k(table)
+        .where({ processor_name: processorName })
+        .where(function (this: any) {
+          this.whereNull("owner").orWhere("timestamp", "<", cutoff)
+        })
+        .select("segment")
+        .orderBy("segment", "asc")
+      return rows.map((r: any) => r.segment)
+    },
+
+    async deleteToken(processorName, segment) {
+      const k = getKnex()
+      await k(table)
+        .where({ processor_name: processorName, segment })
+        .delete()
+    },
+  }
+}

package/src/knex-transaction-manager.ts

@@ -0,0 +1,78 @@
+import type { TransactionManager } from "@kronos-ts/messaging"
+
+/**
+ * A Knex instance that supports transactions.
+ */
+export interface KnexInstanceLike {
+  transaction<T>(fn: (trx: any) => Promise<T>): Promise<T>
+}
+
+/**
+ * The Knex transaction object.
+ */
+export type KnexTransaction = any
+
+/**
+ * Creates a TransactionManager for Knex.
+ *
+ * Bridges Knex's `knex.transaction(fn)` callback to the framework's
+ * `begin/commit/rollback` lifecycle.
+ *
+ * ```typescript
+ * import Knex from "knex"
+ * import { knexTransactionManager } from "@kronos-ts/knex"
+ *
+ * const knex = Knex({ client: "pg", connection: "..." })
+ *
+ * // transactionManager wiring to a kronos() App is pending a typed
+ * // `transactionManager` slot (Phase 9). For now, construct the manager
+ * // and pass it directly into the unitOfWorkFactory composition:
+ * const txManager = knexTransactionManager(knex)
+ * ```
+ */
+export function knexTransactionManager(
+  knex: KnexInstanceLike,
+): TransactionManager<KnexTransaction> {
+  return {
+    async begin(): Promise<KnexTransaction> {
+      let resolveTx!: (tx: KnexTransaction) => void
+      let resolveCompletion!: () => void
+      let rejectCompletion!: (error: unknown) => void
+
+      const txReady = new Promise<KnexTransaction>((resolve) => {
+        resolveTx = resolve
+      })
+
+      const completionSignal = new Promise<void>((resolve, reject) => {
+        resolveCompletion = resolve
+        rejectCompletion = reject
+      })
+
+      const txPromise = knex.transaction(async (trx) => {
+        resolveTx(trx)
+        await completionSignal
+      })
+
+      const tx = await txReady
+      ;(tx as any).__kronos_commit = resolveCompletion
+      ;(tx as any).__kronos_rollback = rejectCompletion
+      ;(tx as any).__kronos_txPromise = txPromise
+
+      return tx
+    },
+
+    async commit(tx: KnexTransaction): Promise<void> {
+      const commit = (tx as any).__kronos_commit as () => void
+      const txPromise = (tx as any).__kronos_txPromise as Promise<void>
+      commit()
+      await txPromise
+    },
+
+    async rollback(tx: KnexTransaction): Promise<void> {
+      const rollback = (tx as any).__kronos_rollback as (error: unknown) => void
+      const txPromise = (tx as any).__kronos_txPromise as Promise<void>
+      rollback(new Error("Transaction rolled back"))
+      try { await txPromise } catch { /* expected */ }
+    },
+  }
+}