@proteinjs/db 1.41.0 → 1.42.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.42.0](https://github.com/proteinjs/db/compare/@proteinjs/db@1.41.0...@proteinjs/db@1.42.0) (2026-09-02)
+
+
+### Features
+
+* **db:** DetachedDbOps — THE named detachment idiom for deliberately fire-and-forget db work (one owner). Under node's default unhandled-rejection policy (node 24 in production) a detached db operation that rejects — e.g. a write tripping the driver's 60s op deadline — killed the whole process (observed live: a detached write past the deadline aborted the server). DetachedDbOps.run(description, work, context?) invokes the work, terminally catches (synchronous throws included), and logs the failure WITH the caller's context — never process death, never a silent swallow; returns void by design so a detached outcome cannot be accidentally consumed. Exported from the package root for every consumer's deliberate detached DML. The repo's own deliberate detached call sites route through it: SpannerLivenessMonitor's two detached verifyLiveness dispatches (pool-error listener + driver-reported error); the client-recycle oldDb.close stays on its existing terminal catch (its silent swallow is a named decision — the channel is believed dead). No half-existing db-layer idiom found to extend: the service layer's doNotAwait observer (ServiceExecutor) covers only service-dispatched work. RED RUN stated: DetachedDbOps.test red at the absent module (the simulated 60s-deadline driver rejection is the suite's first pin); green wired 4/4. Bites verified: terminal catch dropped -> the 2 rejection pins red; sync containment dropped -> the sync-throw pin red alone; restored green. Suites: packages/db 16 suites / 134 tests green (130 pre-existing + 4 new); drivers/spanner Liveness 1/1 green on a dedicated emulator (:9040) — the routed pool-error path exercised live; driver tsc clean (the one build red was the cloned stale db-query dist, cleared by rebuilding query from main source). ([3b92847](https://github.com/proteinjs/db/commit/3b92847355b23db7013fb9bf11fd1b6e7e879b72))
+
+
+
+
+
 # [1.41.0](https://github.com/proteinjs/db/compare/@proteinjs/db@1.40.0...@proteinjs/db@1.41.0) (2026-09-01)
 
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './src/Db';
+export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAI9C,OAAO,EAAE,kBAAkB,IAAI,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC/F,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,6CAA6C,CAAC;AAE5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAE1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iDAAiD,CAAC;AAEhE,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AAExD,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAI9C,OAAO,EAAE,kBAAkB,IAAI,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC/F,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,6CAA6C,CAAC;AAE5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAE1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iDAAiD,CAAC;AAEhE,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AAExD,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SourceRecordSyncRunner = void 0;
 __exportStar(require("./src/Db"), exports);
+__exportStar(require("./src/DetachedDbOps"), exports);
 __exportStar(require("./src/Table"), exports);
 __exportStar(require("./src/RecordAccessError"), exports);
 __exportStar(require("./src/auth/TableAuth"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B;AAC5B,0DAAwC;AACxC,uDAAqC;AACrC,8DAA4C;AAC5C,gDAA8B;AAC9B,+CAA6B;AAC7B,iEAA+C;AAC/C,qEAAmD;AACnD,4DAA0C;AAC1C,yDAAuC;AACvC,iEAA+C;AAC/C,uDAAqC;AACrC,0DAAwC;AACxC,4DAA0C;AAC1C,gEAA8C;AAC9C,+FAA+F;AAC/F,+FAA+F;AAC/F,gFAAgF;AAChF,sEAA+F;AAAtF,4HAAA,kBAAkB,OAA0B;AACrD,wDAAsC;AACtC,4DAA0C;AAC1C,qDAAmC;AACnC,gEAA8C;AAC9C,sEAAoD;AACpD,8EAA4D;AAE5D,gEAA8C;AAC9C,8DAA4C;AAC5C,4DAA0C;AAE1C,qEAAmD;AACnD,6EAA2D;AAC3D,sEAAoD;AACpD,0EAAwD;AACxD,gEAA8C;AAC9C,sEAAoD;AACpD,mEAAiD;AACjD,oEAAkD;AAClD,6EAA2D;AAC3D,iFAA+D;AAC/D,oEAAkD;AAClD,yEAAuD;AACvD,8EAA4D;AAC5D,6EAA2D;AAC3D,kFAAgE;AAEhE,sDAAoC;AACpC,8DAA4C;AAE5C,2DAAyC;AACzC,wEAAsD;AACtD,0EAAwD;AAExD,sDAAoC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,sDAAoC;AACpC,8CAA4B;AAC5B,0DAAwC;AACxC,uDAAqC;AACrC,8DAA4C;AAC5C,gDAA8B;AAC9B,+CAA6B;AAC7B,iEAA+C;AAC/C,qEAAmD;AACnD,4DAA0C;AAC1C,yDAAuC;AACvC,iEAA+C;AAC/C,uDAAqC;AACrC,0DAAwC;AACxC,4DAA0C;AAC1C,gEAA8C;AAC9C,+FAA+F;AAC/F,+FAA+F;AAC/F,gFAAgF;AAChF,sEAA+F;AAAtF,4HAAA,kBAAkB,OAA0B;AACrD,wDAAsC;AACtC,4DAA0C;AAC1C,qDAAmC;AACnC,gEAA8C;AAC9C,sEAAoD;AACpD,8EAA4D;AAE5D,gEAA8C;AAC9C,8DAA4C;AAC5C,4DAA0C;AAE1C,qEAAmD;AACnD,6EAA2D;AAC3D,sEAAoD;AACpD,0EAAwD;AACxD,gEAA8C;AAC9C,sEAAoD;AACpD,mEAAiD;AACjD,oEAAkD;AAClD,6EAA2D;AAC3D,iFAA+D;AAC/D,oEAAkD;AAClD,yEAAuD;AACvD,8EAA4D;AAC5D,6EAA2D;AAC3D,kFAAgE;AAEhE,sDAAoC;AACpC,8DAA4C;AAE5C,2DAAyC;AACzC,wEAAsD;AACtD,0EAAwD;AAExD,sDAAoC"}

package/dist/src/DetachedDbOps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * THE detachment idiom for deliberately fire-and-forget db work — one owner.
+ *
+ * Under node's default unhandled-rejection policy (node 15+ `--unhandled-rejections=throw`;
+ * node 24 in production), a detached db operation that REJECTS — e.g. a write that trips the
+ * driver's op deadline (`SpannerConfig.opDeadlineMs`, default 60s) — is an unhandled rejection
+ * that KILLS THE PROCESS (observed live: a detached write past the 60s driver deadline aborted
+ * the server). Detaching is a legitimate, named decision — the caller does not need the outcome
+ * to proceed — but the rejection still needs a terminal observer. This class is that observer:
+ * every deliberately un-awaited db operation routes through `run`, which invokes the work,
+ * terminally catches (synchronous throws included), and logs the failure WITH the caller's
+ * context — never process death, never a silent swallow.
+ *
+ * NOT for outcomes the caller depends on: work whose failure must alter behavior is awaited at
+ * the call site. `run` returns void by design, so a detached result cannot be accidentally
+ * consumed.
+ */
+export declare class DetachedDbOps {
+    private static logger;
+    /**
+     * Run `work` detached. Failures — a rejected promise or a synchronous throw — are terminally
+     * logged under `description` with `context`, never rethrown and never left unhandled.
+     */
+    static run(description: string, work: () => Promise<unknown>, context?: Record<string, unknown>): void;
+    private static observe;
+}
+//# sourceMappingURL=DetachedDbOps.d.ts.map

package/dist/src/DetachedDbOps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DetachedDbOps.d.ts","sourceRoot":"","sources":["../../src/DetachedDbOps.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAyC;IAE9D;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAatG,OAAO,CAAC,MAAM,CAAC,OAAO;CAOvB"}

package/dist/src/DetachedDbOps.js

@@ -0,0 +1,60 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetachedDbOps = void 0;
+var logger_1 = require("@proteinjs/logger");
+/**
+ * THE detachment idiom for deliberately fire-and-forget db work — one owner.
+ *
+ * Under node's default unhandled-rejection policy (node 15+ `--unhandled-rejections=throw`;
+ * node 24 in production), a detached db operation that REJECTS — e.g. a write that trips the
+ * driver's op deadline (`SpannerConfig.opDeadlineMs`, default 60s) — is an unhandled rejection
+ * that KILLS THE PROCESS (observed live: a detached write past the 60s driver deadline aborted
+ * the server). Detaching is a legitimate, named decision — the caller does not need the outcome
+ * to proceed — but the rejection still needs a terminal observer. This class is that observer:
+ * every deliberately un-awaited db operation routes through `run`, which invokes the work,
+ * terminally catches (synchronous throws included), and logs the failure WITH the caller's
+ * context — never process death, never a silent swallow.
+ *
+ * NOT for outcomes the caller depends on: work whose failure must alter behavior is awaited at
+ * the call site. `run` returns void by design, so a detached result cannot be accidentally
+ * consumed.
+ */
+var DetachedDbOps = /** @class */ (function () {
+    function DetachedDbOps() {
+    }
+    /**
+     * Run `work` detached. Failures — a rejected promise or a synchronous throw — are terminally
+     * logged under `description` with `context`, never rethrown and never left unhandled.
+     */
+    DetachedDbOps.run = function (description, work, context) {
+        var _this = this;
+        var result;
+        try {
+            result = work();
+        }
+        catch (error) {
+            this.observe(description, error, context);
+            return;
+        }
+        result.catch(function (error) { return _this.observe(description, error, context); });
+    };
+    // --- helpers last ---
+    DetachedDbOps.observe = function (description, error, context) {
+        this.logger.error(__assign({ message: "Detached db operation failed: ".concat(description), error: error }, (context ? { obj: context } : {})));
+    };
+    DetachedDbOps.logger = new logger_1.Logger({ name: 'DetachedDbOps' });
+    return DetachedDbOps;
+}());
+exports.DetachedDbOps = DetachedDbOps;
+//# sourceMappingURL=DetachedDbOps.js.map

package/dist/src/DetachedDbOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DetachedDbOps.js","sourceRoot":"","sources":["../../src/DetachedDbOps.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,4CAA2C;AAE3C;;;;;;;;;;;;;;;;GAgBG;AACH;IAAA;IA2BA,CAAC;IAxBC;;;OAGG;IACI,iBAAG,GAAV,UAAW,WAAmB,EAAE,IAA4B,EAAE,OAAiC;QAA/F,iBASC;QARC,IAAI,MAAwB,CAAC;QAC7B,IAAI;YACF,MAAM,GAAG,IAAI,EAAE,CAAC;SACjB;QAAC,OAAO,KAAK,EAAE;YACd,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YAC1C,OAAO;SACR;QACD,MAAM,CAAC,KAAK,CAAC,UAAC,KAAK,IAAK,OAAA,KAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,EAAzC,CAAyC,CAAC,CAAC;IACrE,CAAC;IAED,uBAAuB;IAER,qBAAO,GAAtB,UAAuB,WAAmB,EAAE,KAAc,EAAE,OAAiC;QAC3F,IAAI,CAAC,MAAM,CAAC,KAAK,YACf,OAAO,EAAE,wCAAiC,WAAW,CAAE,EACvD,KAAK,OAAA,IACF,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACpC,CAAC;IACL,CAAC;IAzBc,oBAAM,GAAG,IAAI,eAAM,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;IA0BhE,oBAAC;CAAA,AA3BD,IA2BC;AA3BY,sCAAa"}

package/dist/test/DetachedDbOps.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DetachedDbOps.test.d.ts.map

package/dist/test/DetachedDbOps.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DetachedDbOps.test.d.ts","sourceRoot":"","sources":["../../test/DetachedDbOps.test.ts"],"names":[],"mappings":""}

package/dist/test/DetachedDbOps.test.js

@@ -0,0 +1,158 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var logger_1 = require("@proteinjs/logger");
+var DetachedDbOps_1 = require("../src/DetachedDbOps");
+/**
+ * The detachment idiom's contract (the node-24 crash class): a deliberately fire-and-forget db
+ * operation that REJECTS — e.g. a write that trips the driver's 60s op deadline — must be
+ * terminally observed (logged with the caller's context), never left as an unhandled rejection
+ * for node's default policy to kill the process over. These tests run with no emulator: the
+ * simulated driver rejection IS the deadline failure's shape.
+ *
+ * Note: jest itself surfaces unhandled rejections as failures — so each green run here doubles
+ * as the no-escape assertion (a dropped catch turns the log pins red AND leaks the rejection).
+ */
+var flushDetached = function () { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: 
+            // The terminal catch attaches synchronously; the rejection lands on the microtask queue.
+            return [4 /*yield*/, Promise.resolve()];
+            case 1:
+                // The terminal catch attaches synchronously; the rejection lands on the microtask queue.
+                _a.sent();
+                return [4 /*yield*/, new Promise(function (resolve) { return setImmediate(resolve); })];
+            case 2:
+                _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); };
+describe('DetachedDbOps', function () {
+    var errorLogs;
+    var errorSpy;
+    beforeEach(function () {
+        errorLogs = [];
+        errorSpy = jest.spyOn(logger_1.Logger.prototype, 'error').mockImplementation(function (log) {
+            errorLogs.push(log);
+        });
+    });
+    afterEach(function () {
+        errorSpy.mockRestore();
+    });
+    test('a rejecting detached operation is terminally observed — logged with the caller context, no escaping rejection', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var deadlineRejection;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    deadlineRejection = new Error('4 DEADLINE_EXCEEDED: spanner dml transaction (runTransactionAsync) exceeded the 60000ms op deadline');
+                    DetachedDbOps_1.DetachedDbOps.run('write flow-run heartbeat', function () { return Promise.reject(deadlineRejection); }, {
+                        flowRunId: 'run-1',
+                        table: 'flow_run',
+                    });
+                    return [4 /*yield*/, flushDetached()];
+                case 1:
+                    _a.sent();
+                    expect(errorLogs).toHaveLength(1);
+                    expect(errorLogs[0].message).toContain('Detached db operation failed');
+                    expect(errorLogs[0].message).toContain('write flow-run heartbeat');
+                    expect(errorLogs[0].obj).toEqual({ flowRunId: 'run-1', table: 'flow_run' });
+                    expect(errorLogs[0].error).toBe(deadlineRejection);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('a synchronously-throwing work function is contained the same way — the caller never sees the throw', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var boom;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    boom = new Error('driver construction failed before any promise existed');
+                    expect(function () {
+                        return DetachedDbOps_1.DetachedDbOps.run('sync-throwing detached op', function () {
+                            throw boom;
+                        }, { site: 'test' });
+                    }).not.toThrow();
+                    return [4 /*yield*/, flushDetached()];
+                case 1:
+                    _a.sent();
+                    expect(errorLogs).toHaveLength(1);
+                    expect(errorLogs[0].message).toContain('sync-throwing detached op');
+                    expect(errorLogs[0].error).toBe(boom);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('a resolving detached operation logs nothing', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var ran;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    ran = false;
+                    DetachedDbOps_1.DetachedDbOps.run('healthy detached op', function () { return __awaiter(void 0, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            ran = true;
+                            return [2 /*return*/, 'ok'];
+                        });
+                    }); });
+                    return [4 /*yield*/, flushDetached()];
+                case 1:
+                    _a.sent();
+                    expect(ran).toBe(true);
+                    expect(errorLogs).toHaveLength(0);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('context is optional — a rejection without context still logs the description', function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    DetachedDbOps_1.DetachedDbOps.run('context-free detached op', function () { return Promise.reject(new Error('deadline')); });
+                    return [4 /*yield*/, flushDetached()];
+                case 1:
+                    _a.sent();
+                    expect(errorLogs).toHaveLength(1);
+                    expect(errorLogs[0].message).toContain('context-free detached op');
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+//# sourceMappingURL=DetachedDbOps.test.js.map

package/dist/test/DetachedDbOps.test.js.map

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

package/index.ts

@@ -1,4 +1,5 @@
 export * from './src/Db';
+export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.41.0",
+  "version": "1.42.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": "149e538c8a05858b6eb7d3a2dc362e5ff196caf9"
+  "gitHead": "bbbbd77251d6c48bd4dd31331c2bbb8113337597"
 }

package/src/DetachedDbOps.ts

@@ -0,0 +1,47 @@
+import { Logger } from '@proteinjs/logger';
+
+/**
+ * THE detachment idiom for deliberately fire-and-forget db work — one owner.
+ *
+ * Under node's default unhandled-rejection policy (node 15+ `--unhandled-rejections=throw`;
+ * node 24 in production), a detached db operation that REJECTS — e.g. a write that trips the
+ * driver's op deadline (`SpannerConfig.opDeadlineMs`, default 60s) — is an unhandled rejection
+ * that KILLS THE PROCESS (observed live: a detached write past the 60s driver deadline aborted
+ * the server). Detaching is a legitimate, named decision — the caller does not need the outcome
+ * to proceed — but the rejection still needs a terminal observer. This class is that observer:
+ * every deliberately un-awaited db operation routes through `run`, which invokes the work,
+ * terminally catches (synchronous throws included), and logs the failure WITH the caller's
+ * context — never process death, never a silent swallow.
+ *
+ * NOT for outcomes the caller depends on: work whose failure must alter behavior is awaited at
+ * the call site. `run` returns void by design, so a detached result cannot be accidentally
+ * consumed.
+ */
+export class DetachedDbOps {
+  private static logger = new Logger({ name: 'DetachedDbOps' });
+
+  /**
+   * Run `work` detached. Failures — a rejected promise or a synchronous throw — are terminally
+   * logged under `description` with `context`, never rethrown and never left unhandled.
+   */
+  static run(description: string, work: () => Promise<unknown>, context?: Record<string, unknown>): void {
+    let result: Promise<unknown>;
+    try {
+      result = work();
+    } catch (error) {
+      this.observe(description, error, context);
+      return;
+    }
+    result.catch((error) => this.observe(description, error, context));
+  }
+
+  // --- helpers last ---
+
+  private static observe(description: string, error: unknown, context?: Record<string, unknown>): void {
+    this.logger.error({
+      message: `Detached db operation failed: ${description}`,
+      error,
+      ...(context ? { obj: context } : {}),
+    });
+  }
+}

package/test/DetachedDbOps.test.ts

@@ -0,0 +1,90 @@
+import { Logger } from '@proteinjs/logger';
+import { DetachedDbOps } from '../src/DetachedDbOps';
+
+/**
+ * The detachment idiom's contract (the node-24 crash class): a deliberately fire-and-forget db
+ * operation that REJECTS — e.g. a write that trips the driver's 60s op deadline — must be
+ * terminally observed (logged with the caller's context), never left as an unhandled rejection
+ * for node's default policy to kill the process over. These tests run with no emulator: the
+ * simulated driver rejection IS the deadline failure's shape.
+ *
+ * Note: jest itself surfaces unhandled rejections as failures — so each green run here doubles
+ * as the no-escape assertion (a dropped catch turns the log pins red AND leaks the rejection).
+ */
+
+const flushDetached = async () => {
+  // The terminal catch attaches synchronously; the rejection lands on the microtask queue.
+  await Promise.resolve();
+  await new Promise((resolve) => setImmediate(resolve));
+};
+
+describe('DetachedDbOps', () => {
+  let errorLogs: Array<{ message: string; obj?: Record<string, unknown>; error?: unknown }>;
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    errorLogs = [];
+    errorSpy = jest.spyOn(Logger.prototype, 'error').mockImplementation(function (log: any) {
+      errorLogs.push(log);
+    });
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  test('a rejecting detached operation is terminally observed — logged with the caller context, no escaping rejection', async () => {
+    const deadlineRejection = new Error(
+      '4 DEADLINE_EXCEEDED: spanner dml transaction (runTransactionAsync) exceeded the 60000ms op deadline'
+    );
+    DetachedDbOps.run('write flow-run heartbeat', () => Promise.reject(deadlineRejection), {
+      flowRunId: 'run-1',
+      table: 'flow_run',
+    });
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('Detached db operation failed');
+    expect(errorLogs[0].message).toContain('write flow-run heartbeat');
+    expect(errorLogs[0].obj).toEqual({ flowRunId: 'run-1', table: 'flow_run' });
+    expect(errorLogs[0].error).toBe(deadlineRejection);
+  });
+
+  test('a synchronously-throwing work function is contained the same way — the caller never sees the throw', async () => {
+    const boom = new Error('driver construction failed before any promise existed');
+    expect(() =>
+      DetachedDbOps.run(
+        'sync-throwing detached op',
+        () => {
+          throw boom;
+        },
+        { site: 'test' }
+      )
+    ).not.toThrow();
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('sync-throwing detached op');
+    expect(errorLogs[0].error).toBe(boom);
+  });
+
+  test('a resolving detached operation logs nothing', async () => {
+    let ran = false;
+    DetachedDbOps.run('healthy detached op', async () => {
+      ran = true;
+      return 'ok';
+    });
+    await flushDetached();
+
+    expect(ran).toBe(true);
+    expect(errorLogs).toHaveLength(0);
+  });
+
+  test('context is optional — a rejection without context still logs the description', async () => {
+    DetachedDbOps.run('context-free detached op', () => Promise.reject(new Error('deadline')));
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('context-free detached op');
+  });
+});