@memberjunction/generic-database-provider 6.1.2 → 6.1.3

package/dist/TransactionFrameTracker.d.ts

@@ -0,0 +1,72 @@
+import type { PostCommitToken } from '@memberjunction/core';
+/** How a settled outermost transaction ended. */
+export type TransactionEpochOutcome = 'committed' | 'rolledBack';
+/**
+ * What to do with a post-commit task registered with a {@link PostCommitToken}.
+ * - `run` — the token's transaction committed; run the task now.
+ * - `queue` — the token's transaction is still open; queue at `Depth` (the deepest captured frame
+ *   that is still open — a released savepoint's work belongs to its enclosing frame).
+ * - `drop` — the work was rolled back, or the token cannot be matched to known state.
+ */
+export type PostCommitTokenResolution = {
+    Kind: 'run';
+} | {
+    Kind: 'queue';
+    Depth: number;
+}
+/** `Unknown` marks a drop that is NOT a known rollback — the caller should log it louder. */
+ | {
+    Kind: 'drop';
+    Reason: string;
+    Unknown?: boolean;
+};
+/**
+ * Gives every transaction frame on one provider an identity, so work captured inside a frame can be
+ * matched to that frame's fate after the fact.
+ *
+ * - An **epoch** is one outermost transaction. Epoch and frame ids come from process-wide counters,
+ *   so a token from a different provider instance never matches this one's state by accident.
+ * - The **frame stack** mirrors the provider's transaction depth: index 0 is the outermost
+ *   transaction, each later entry a savepoint.
+ * - Savepoint frames rolled back in the open epoch are remembered until the epoch ends.
+ * - The outcomes of the last {@link SettledEpochLimit} epochs are remembered; older ones are
+ *   forgotten, and a token naming one is treated as unknown (dropped).
+ *
+ * The owner must call the mutators in step with its own depth changes. Not thread-safe beyond what
+ * the owner's transaction lock provides; {@link Capture} and {@link Resolve} are synchronous.
+ */
+export declare class TransactionFrameTracker {
+    /** How many settled epochs are remembered. */
+    static readonly SettledEpochLimit = 1000;
+    private static _lastEpoch;
+    private static _lastFrameId;
+    private _openEpoch;
+    private _frames;
+    private readonly _rolledBackFrames;
+    private readonly _settledEpochs;
+    /** Number of open frames. */
+    get Depth(): number;
+    /** A frame was begun. The first frame opens a new epoch. */
+    PushFrame(): void;
+    /** The innermost frame ended without undoing its work (savepoint released, or never created). */
+    ReleaseFrame(): void;
+    /** The innermost frame's work was undone (savepoint rolled back, or its frame dropped as doomed). */
+    RollBackFrame(): void;
+    /** The outermost transaction settled. No-op when no epoch is open. */
+    EndEpoch(outcome: TransactionEpochOutcome): void;
+    /**
+     * Snapshot of the open frames. Outside a transaction this returns a token with a `null` epoch
+     * rather than `undefined`: the work is already durable, and saying so is what stops a later
+     * registration from being attached to an unrelated transaction that opened in the meantime.
+     */
+    Capture(): PostCommitToken;
+    /**
+     * Decide what a task registered with `token` should do now.
+     * @param doomed Whether the owner's open transaction can no longer commit.
+     */
+    Resolve(token: PostCommitToken, doomed: boolean): PostCommitTokenResolution;
+    private rolledBackFrame;
+    private resolveOpenEpoch;
+    private evictOldEpochs;
+}
+//# sourceMappingURL=TransactionFrameTracker.d.ts.map

package/dist/TransactionFrameTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionFrameTracker.d.ts","sourceRoot":"","sources":["../src/TransactionFrameTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,iDAAiD;AACjD,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,YAAY,CAAC;AAYjE;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAC/B;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAClC,6FAA6F;GAC3F;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAuB;IAChC,8CAA8C;IAC9C,gBAAuB,iBAAiB,QAAQ;IAEhD,OAAO,CAAC,MAAM,CAAC,UAAU,CAAK;IAC9B,OAAO,CAAC,MAAM,CAAC,YAAY,CAAK;IAEhC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmC;IAElE,6BAA6B;IAC7B,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED,4DAA4D;IACrD,SAAS,IAAI,IAAI;IASxB,iGAAiG;IAC1F,YAAY,IAAI,IAAI;IAI3B,qGAAqG;IAC9F,aAAa,IAAI,IAAI;IAO5B,sEAAsE;IAC/D,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAWvD;;;;OAIG;IACI,OAAO,IAAI,eAAe;IAOjC;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,GAAG,yBAAyB;IA0BlF,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,cAAc;CASzB"}

package/dist/TransactionFrameTracker.js

@@ -0,0 +1,130 @@
+/**
+ * Gives every transaction frame on one provider an identity, so work captured inside a frame can be
+ * matched to that frame's fate after the fact.
+ *
+ * - An **epoch** is one outermost transaction. Epoch and frame ids come from process-wide counters,
+ *   so a token from a different provider instance never matches this one's state by accident.
+ * - The **frame stack** mirrors the provider's transaction depth: index 0 is the outermost
+ *   transaction, each later entry a savepoint.
+ * - Savepoint frames rolled back in the open epoch are remembered until the epoch ends.
+ * - The outcomes of the last {@link SettledEpochLimit} epochs are remembered; older ones are
+ *   forgotten, and a token naming one is treated as unknown (dropped).
+ *
+ * The owner must call the mutators in step with its own depth changes. Not thread-safe beyond what
+ * the owner's transaction lock provides; {@link Capture} and {@link Resolve} are synchronous.
+ */
+export class TransactionFrameTracker {
+    constructor() {
+        this._openEpoch = null;
+        this._frames = [];
+        this._rolledBackFrames = new Set();
+        this._settledEpochs = new Map();
+    }
+    /** How many settled epochs are remembered. */
+    static { this.SettledEpochLimit = 1000; }
+    static { this._lastEpoch = 0; }
+    static { this._lastFrameId = 0; }
+    /** Number of open frames. */
+    get Depth() {
+        return this._frames.length;
+    }
+    /** A frame was begun. The first frame opens a new epoch. */
+    PushFrame() {
+        if (this._frames.length === 0) {
+            // An epoch with no frames left is one whose begin failed; it never committed.
+            this.EndEpoch('rolledBack');
+            this._openEpoch = ++TransactionFrameTracker._lastEpoch;
+        }
+        this._frames.push(++TransactionFrameTracker._lastFrameId);
+    }
+    /** The innermost frame ended without undoing its work (savepoint released, or never created). */
+    ReleaseFrame() {
+        this._frames.pop();
+    }
+    /** The innermost frame's work was undone (savepoint rolled back, or its frame dropped as doomed). */
+    RollBackFrame() {
+        const id = this._frames.pop();
+        if (id !== undefined) {
+            this._rolledBackFrames.add(id);
+        }
+    }
+    /** The outermost transaction settled. No-op when no epoch is open. */
+    EndEpoch(outcome) {
+        if (this._openEpoch === null) {
+            return;
+        }
+        this._settledEpochs.set(this._openEpoch, { Outcome: outcome, RolledBackFrames: new Set(this._rolledBackFrames) });
+        this.evictOldEpochs();
+        this._openEpoch = null;
+        this._frames = [];
+        this._rolledBackFrames.clear();
+    }
+    /**
+     * Snapshot of the open frames. Outside a transaction this returns a token with a `null` epoch
+     * rather than `undefined`: the work is already durable, and saying so is what stops a later
+     * registration from being attached to an unrelated transaction that opened in the meantime.
+     */
+    Capture() {
+        if (this._openEpoch === null || this._frames.length === 0) {
+            return { Epoch: null, FrameIds: [] };
+        }
+        return { Epoch: this._openEpoch, FrameIds: [...this._frames] };
+    }
+    /**
+     * Decide what a task registered with `token` should do now.
+     * @param doomed Whether the owner's open transaction can no longer commit.
+     */
+    Resolve(token, doomed) {
+        if (token.Epoch === null) {
+            // Caused outside any transaction: already durable, so nothing to wait for or be undone by.
+            return { Kind: 'run' };
+        }
+        if (token.Epoch === this._openEpoch) {
+            return this.resolveOpenEpoch(token, doomed);
+        }
+        const settled = this._settledEpochs.get(token.Epoch);
+        if (settled?.Outcome === 'committed') {
+            // The outer transaction committing does not resurrect a savepoint that rolled back
+            // inside it, so the captured frames still decide.
+            return this.rolledBackFrame(token, settled.RolledBackFrames)
+                ? { Kind: 'drop', Reason: 'the savepoint it was registered in rolled back' }
+                : { Kind: 'run' };
+        }
+        if (settled?.Outcome === 'rolledBack') {
+            return { Kind: 'drop', Reason: 'the transaction it was registered in rolled back' };
+        }
+        return {
+            Kind: 'drop',
+            Unknown: true,
+            Reason: `transaction ${token.Epoch} is unknown to this provider (another instance's, or older than the last ${TransactionFrameTracker.SettledEpochLimit} transactions)`,
+        };
+    }
+    rolledBackFrame(token, rolledBack) {
+        return token.FrameIds.some((id) => rolledBack.has(id));
+    }
+    resolveOpenEpoch(token, doomed) {
+        if (doomed) {
+            return { Kind: 'drop', Reason: 'the transaction it was registered in was abandoned' };
+        }
+        if (this.rolledBackFrame(token, this._rolledBackFrames)) {
+            return { Kind: 'drop', Reason: 'the savepoint it was registered in rolled back' };
+        }
+        for (let i = token.FrameIds.length - 1; i >= 0; i--) {
+            const index = this._frames.indexOf(token.FrameIds[i]);
+            if (index >= 0) {
+                return { Kind: 'queue', Depth: index + 1 };
+            }
+        }
+        return { Kind: 'drop', Reason: 'none of the frames it was registered in is still open' };
+    }
+    evictOldEpochs() {
+        while (this._settledEpochs.size > TransactionFrameTracker.SettledEpochLimit) {
+            const oldest = this._settledEpochs.keys().next();
+            if (oldest.done) {
+                return;
+            }
+            this._settledEpochs.delete(oldest.value);
+        }
+    }
+}
+//# sourceMappingURL=TransactionFrameTracker.js.map

package/dist/TransactionFrameTracker.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/generic-database-provider",
   "type": "module",
-  "version": "6.1.2",
+  "version": "6.1.3",
   "description": "Shared database provider logic for MemberJunction — intermediate base class between DatabaseProviderBase and platform-specific providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,19 +16,19 @@
     "vitest": "^3.1.1"
   },
   "dependencies": {
-    "@memberjunction/actions": "6.1.2",
-    "@memberjunction/actions-base": "6.1.2",
-    "@memberjunction/ai-vectors-memory": "6.1.2",
-    "@memberjunction/aiengine": "6.1.2",
-    "@memberjunction/core": "6.1.2",
-    "@memberjunction/core-entities": "6.1.2",
-    "@memberjunction/encryption": "6.1.2",
-    "@memberjunction/geo-core": "6.1.2",
-    "@memberjunction/global": "6.1.2",
-    "@memberjunction/query-processor": "6.1.2",
-    "@memberjunction/sql-dialect": "6.1.2",
-    "@memberjunction/sql-parser": "6.1.2",
-    "@memberjunction/queue": "6.1.2",
+    "@memberjunction/actions": "6.1.3",
+    "@memberjunction/actions-base": "6.1.3",
+    "@memberjunction/ai-vectors-memory": "6.1.3",
+    "@memberjunction/aiengine": "6.1.3",
+    "@memberjunction/core": "6.1.3",
+    "@memberjunction/core-entities": "6.1.3",
+    "@memberjunction/encryption": "6.1.3",
+    "@memberjunction/geo-core": "6.1.3",
+    "@memberjunction/global": "6.1.3",
+    "@memberjunction/query-processor": "6.1.3",
+    "@memberjunction/sql-dialect": "6.1.3",
+    "@memberjunction/sql-parser": "6.1.3",
+    "@memberjunction/queue": "6.1.3",
     "sql-formatter": "^15.7.0",
     "uuid": "^13.0.0"
   },