@dudousxd/nestjs-durable-testing 0.15.0 → 0.16.1

package/dist/index.d.ts

@@ -208,6 +208,8 @@ declare function assertReplayable(register: (engine: WorkflowEngine) => void, hi
  */
 interface StateStoreContext {
     store: StateStore;
+    /** A second wrapper sharing the database/pool, used to exercise cross-instance claims. */
+    peerStore?: StateStore;
     cleanup: () => Promise<void>;
     /**
      * Whether the store's optional `transaction` can run an ASYNC work callback. Defaults to `true`.

package/dist/index.js

@@ -399,7 +399,7 @@ async function assertReplayable(register, history) {
 __name(assertReplayable, "assertReplayable");
 
 // src/state-store-conformance.ts
-import { WorkflowEngine as WorkflowEngine3 } from "@dudousxd/nestjs-durable-core";
+import { SINGLETON_ADMITTED_TAG, WorkflowEngine as WorkflowEngine3 } from "@dudousxd/nestjs-durable-core";
 import { beforeEach, describe as describe2, expect as expect2, it as it2 } from "vitest";
 var StateStoreUnavailableError = class extends Error {
   static {
@@ -449,6 +449,7 @@ var checkpoint = /* @__PURE__ */ __name((over = {}) => ({
 function runStateStoreContract(name, makeStore) {
   describe2(`StateStore contract: ${name}`, () => {
     let store;
+    let peerStore;
     let cleanup;
     let supportsAsyncTransaction = true;
     let supportsTagFilter = true;
@@ -458,6 +459,7 @@ function runStateStoreContract(name, makeStore) {
       try {
         const ctx = await makeStore();
         store = ctx.store;
+        peerStore = ctx.peerStore ?? ctx.store;
         cleanup = ctx.cleanup;
         supportsAsyncTransaction = ctx.supportsAsyncTransaction ?? true;
         supportsTagFilter = ctx.supportsTagFilter ?? true;
@@ -483,6 +485,197 @@ function runStateStoreContract(name, makeStore) {
         await fn();
       });
     }, "t");
+    t("atomically admits holders without displacement by later same-millisecond IDs", async () => {
+      expect2(store.tryAdmitSingleton).toBeTypeOf("function");
+      const claim = /* @__PURE__ */ __name((id, limit = 1) => store.tryAdmitSingleton?.(id, "singleton:k", "checkout", limit), "claim");
+      await store.createRun(run({
+        id: "z-holder",
+        tags: [
+          "singleton:k",
+          "user-tag"
+        ]
+      }));
+      expect2(await claim("z-holder")).toBe(true);
+      await store.updateRun("z-holder", {
+        status: "suspended",
+        wakeAt: 1e4
+      });
+      expect2(await claim("z-holder")).toBe(true);
+      await store.updateRun("z-holder", {
+        status: "blocked",
+        lockedBy: "expired",
+        lockedUntil: 0
+      });
+      await store.createRun(run({
+        id: "a-waiter",
+        tags: [
+          "singleton:k"
+        ]
+      }));
+      expect2(await claim("a-waiter")).toBe(false);
+      expect2(await claim("z-holder")).toBe(true);
+      await store.updateRun("z-holder", {
+        status: "cancelling"
+      });
+      expect2(await claim("a-waiter")).toBe(false);
+      await store.updateRun("z-holder", {
+        status: "completed"
+      });
+      expect2((await store.getRun("z-holder"))?.tags).toEqual([
+        "singleton:k",
+        "user-tag"
+      ]);
+      expect2(await claim("a-waiter")).toBe(true);
+      await store.updateRun("z-holder", {
+        status: "running"
+      });
+      expect2(await claim("z-holder")).toBe(false);
+      expect2(await claim("missing")).toBe(false);
+    });
+    t("singleton denial atomically parks waiters and preserves cancelling/terminal state", async () => {
+      await store.createRun(run({
+        id: "holder",
+        tags: [
+          "singleton:k"
+        ]
+      }));
+      expect2(await store.tryAdmitSingleton?.("holder", "singleton:k", "checkout", 1)).toBe(true);
+      await store.createRun(run({
+        id: "waiter",
+        tags: [
+          "singleton:k"
+        ]
+      }));
+      expect2(await peerStore.tryAdmitSingleton?.("waiter", "singleton:k", "checkout", 1, 12e3)).toBe(false);
+      expect2(await store.getRun("waiter")).toMatchObject({
+        status: "suspended",
+        wakeAt: 12e3
+      });
+      await store.updateRun("waiter", {
+        status: "cancelling",
+        wakeAt: void 0
+      });
+      expect2(await peerStore.tryAdmitSingleton?.("waiter", "singleton:k", "checkout", 1, 14e3)).toBe(false);
+      expect2(await store.getRun("waiter")).toMatchObject({
+        status: "cancelling"
+      });
+      expect2((await store.getRun("waiter"))?.wakeAt).toBeUndefined();
+      await store.updateRun("waiter", {
+        status: "cancelled"
+      });
+      expect2(await peerStore.tryAdmitSingleton?.("waiter", "singleton:k", "checkout", 1, 16e3)).toBe(false);
+      expect2((await store.getRun("waiter"))?.status).toBe("cancelled");
+      await store.updateRun("holder", {
+        status: "completed"
+      });
+      await store.createRun(run({
+        id: "cancelling",
+        status: "cancelling",
+        tags: [
+          "singleton:k"
+        ]
+      }));
+      expect2(await store.tryAdmitSingleton?.("cancelling", "singleton:k", "checkout", 1, 18e3)).toBe(false);
+      expect2((await store.getRun("cancelling"))?.tags).not.toContain(SINGLETON_ADMITTED_TAG);
+    });
+    t("competing store instances atomically claim an empty singleton slot", async () => {
+      for (const id of [
+        "a-first",
+        "b-second",
+        "c-third"
+      ]) {
+        await store.createRun(run({
+          id,
+          tags: [
+            "singleton:k"
+          ]
+        }));
+      }
+      const results = await Promise.all([
+        peerStore.tryAdmitSingleton?.("b-second", "singleton:k", "checkout", 1),
+        store.tryAdmitSingleton?.("a-first", "singleton:k", "checkout", 1),
+        peerStore.tryAdmitSingleton?.("c-third", "singleton:k", "checkout", 1)
+      ]);
+      expect2(results).toEqual([
+        false,
+        true,
+        false
+      ]);
+      expect2(await peerStore.tryAdmitSingleton?.("a-first", "singleton:k", "checkout", 1)).toBe(true);
+      expect2((await store.getRun("a-first"))?.tags).toContain(SINGLETON_ADMITTED_TAG);
+    });
+    t("concurrent singleton claims honor limits and independent keys/workflows", async () => {
+      const claim = /* @__PURE__ */ __name((id, tag = "singleton:k", workflow = "checkout") => store.tryAdmitSingleton?.(id, tag, workflow, 2), "claim");
+      for (const id of [
+        "z-holder",
+        "y-holder"
+      ]) {
+        await store.createRun(run({
+          id,
+          tags: [
+            "singleton:k"
+          ]
+        }));
+        expect2(await claim(id)).toBe(true);
+      }
+      for (const id of [
+        "a-waiter",
+        "b-waiter",
+        "c-waiter"
+      ]) {
+        await store.createRun(run({
+          id,
+          status: "pending",
+          tags: [
+            "singleton:k"
+          ]
+        }));
+      }
+      expect2(await Promise.all([
+        "a-waiter",
+        "b-waiter",
+        "c-waiter"
+      ].map((id) => claim(id)))).toEqual([
+        false,
+        false,
+        false
+      ]);
+      await store.updateRun("z-holder", {
+        status: "failed"
+      });
+      expect2(await Promise.all([
+        "c-waiter",
+        "b-waiter",
+        "a-waiter"
+      ].map((id) => claim(id)))).toEqual([
+        false,
+        false,
+        true
+      ]);
+      const active = await store.listRuns({
+        workflow: "checkout",
+        statuses: [
+          "running",
+          "pending"
+        ]
+      });
+      expect2(active.filter((r) => r.tags?.includes(SINGLETON_ADMITTED_TAG))).toHaveLength(2);
+      await store.createRun(run({
+        id: "other-key",
+        tags: [
+          "singleton:other"
+        ]
+      }));
+      expect2(await claim("other-key", "singleton:other")).toBe(true);
+      await store.createRun(run({
+        id: "other-workflow",
+        workflow: "other",
+        tags: [
+          "singleton:k"
+        ]
+      }));
+      expect2(await claim("other-workflow", "singleton:k", "other")).toBe(true);
+    });
     t("creates a run and reads it back with its JSON input", async () => {
       await store.createRun(run());
       const loaded = await store.getRun("r1");
@@ -856,6 +1049,42 @@ function runStateStoreContract(name, makeStore) {
       });
       expect2((await store.getRun("r1"))?.awaitingDecisionTaskId).toBeUndefined();
     });
+    t("saveCheckpointIfPending writes over a pending row only", async () => {
+      if (!store.saveCheckpointIfPending) return;
+      await store.createRun(run());
+      const pending = checkpoint({
+        status: "pending",
+        output: void 0
+      });
+      await store.saveCheckpoint(pending);
+      expect2(await store.saveCheckpointIfPending({
+        ...pending,
+        wakeAt: 5e3
+      })).toBe(true);
+      expect2((await store.getCheckpoint("r1", 0))?.wakeAt).toBe(5e3);
+      const done = {
+        ...pending,
+        status: "completed",
+        output: {
+          ok: true
+        }
+      };
+      expect2(await store.saveCheckpointIfPending(done)).toBe(true);
+      expect2(await store.saveCheckpointIfPending({
+        ...pending,
+        wakeAt: 9e3
+      })).toBe(false);
+      const after = await store.getCheckpoint("r1", 0);
+      expect2(after?.status).toBe("completed");
+      expect2(after?.output).toEqual({
+        ok: true
+      });
+      expect2(await store.saveCheckpointIfPending({
+        ...pending,
+        seq: 9
+      })).toBe(false);
+      expect2(await store.getCheckpoint("r1", 9)).toBeNull();
+    });
     t("upserts checkpoints, reads them by (runId, seq), and lists them ordered by seq", async () => {
       await store.createRun(run());
       await store.saveCheckpoint(checkpoint());
@@ -2439,6 +2668,184 @@ function runStateStoreContract(name, makeStore) {
       expect2((await store.takeSignalWaiter("child:r.child.0"))?.parallelGroup).toBe("gather:0");
       expect2((await store.takeSignalWaiter("child:r.child.9"))?.parallelGroup).toBeUndefined();
     });
+    t("registerChildWaits writes every waiter and placeholder, and upserts on repeat", async () => {
+      expect2(store.registerChildWaits).toBeTypeOf("function");
+      await store.createRun(run({
+        id: "p"
+      }));
+      const entry = /* @__PURE__ */ __name((i, status) => ({
+        waiter: {
+          token: `child:p.all.0.${i}`,
+          runId: "p",
+          seq: i,
+          parallelGroup: "all:0"
+        },
+        checkpoint: checkpoint({
+          runId: "p",
+          seq: i,
+          stepId: `p:${i}`,
+          name: `signal:child:p.all.0.${i}`,
+          kind: "signal",
+          status,
+          parallelGroup: "all:0"
+        })
+      }), "entry");
+      const entries = Array.from({
+        length: 250
+      }, (_, i) => entry(i, "running"));
+      await store.registerChildWaits?.(entries);
+      const waiters = await store.listSignalWaiters("child:p.all.0.");
+      expect2(waiters).toHaveLength(250);
+      expect2(waiters.find((w) => w.token === "child:p.all.0.7")).toEqual(entries[7]?.waiter);
+      const cps = await store.listCheckpoints("p");
+      expect2(cps).toHaveLength(250);
+      expect2(cps[7]).toMatchObject({
+        name: "signal:child:p.all.0.7",
+        status: "running"
+      });
+      expect2(cps[7]?.parallelGroup).toBe("all:0");
+      await store.registerChildWaits?.([
+        entry(7, "completed")
+      ]);
+      expect2((await store.getCheckpoint("p", 7))?.status).toBe("completed");
+      expect2(await store.listCheckpoints("p")).toHaveLength(250);
+      await expect2(store.registerChildWaits?.([])).resolves.toBeUndefined();
+    });
+    t("compactCheckpoints replaces a seq range with one checkpoint, atomically", async () => {
+      expect2(store.compactCheckpoints).toBeTypeOf("function");
+      await store.createRun(run({
+        id: "r"
+      }));
+      await store.createRun(run({
+        id: "other"
+      }));
+      for (let seq = 0; seq < 10; seq += 1) {
+        await store.saveCheckpoint(checkpoint({
+          runId: "r",
+          seq,
+          stepId: `r:${seq}`
+        }));
+      }
+      await store.saveCheckpoint(checkpoint({
+        runId: "other",
+        seq: 3,
+        stepId: "other:3"
+      }));
+      const into = checkpoint({
+        runId: "r",
+        seq: 2,
+        stepId: "r:2",
+        name: "fan:r.all.2.",
+        kind: "signal",
+        output: {
+          from: 0,
+          values: [
+            {
+              n: 1
+            },
+            "two",
+            null
+          ]
+        },
+        parallelGroup: "all:2"
+      });
+      await store.compactCheckpoints?.("r", 2, 7, into);
+      const left = await store.listCheckpoints("r");
+      expect2(left.map((cp) => cp.seq)).toEqual([
+        0,
+        1,
+        2,
+        8,
+        9
+      ]);
+      expect2(left[2]).toMatchObject({
+        name: "fan:r.all.2.",
+        parallelGroup: "all:2"
+      });
+      expect2(left[2]?.output).toEqual({
+        from: 0,
+        values: [
+          {
+            n: 1
+          },
+          "two",
+          null
+        ]
+      });
+      expect2(await store.listCheckpoints("other")).toHaveLength(1);
+    });
+    t("listSignalWaitersByRun returns only the given runs' waiters", async () => {
+      expect2(store.listSignalWaitersByRun).toBeTypeOf("function");
+      await store.putSignalWaiter({
+        token: "child:a.all.0.0",
+        runId: "a",
+        seq: 0,
+        parallelGroup: "all:0"
+      });
+      await store.putSignalWaiter({
+        token: "approve-a",
+        runId: "a",
+        seq: 1
+      });
+      await store.putSignalWaiter({
+        token: "approve-b",
+        runId: "b",
+        seq: 0
+      });
+      await store.putSignalWaiter({
+        token: "approve-c",
+        runId: "c",
+        seq: 0
+      });
+      const tokens = /* @__PURE__ */ __name(async (ids2) => (await store.listSignalWaitersByRun?.(ids2) ?? []).map((w) => w.token).sort(), "tokens");
+      expect2(await tokens([
+        "a",
+        "b"
+      ])).toEqual([
+        "approve-a",
+        "approve-b",
+        "child:a.all.0.0"
+      ]);
+      expect2(await tokens([
+        "missing"
+      ])).toEqual([]);
+      expect2(await tokens([])).toEqual([]);
+      expect2((await store.listSignalWaitersByRun?.([
+        "a"
+      ]))?.find((w) => w.seq === 0)).toEqual({
+        token: "child:a.all.0.0",
+        runId: "a",
+        seq: 0,
+        parallelGroup: "all:0"
+      });
+    });
+    t("hasSignalWaiter answers by run and exact token prefix", async () => {
+      expect2(store.hasSignalWaiter).toBeTypeOf("function");
+      const has = /* @__PURE__ */ __name((runId, prefix) => store.hasSignalWaiter?.(runId, prefix), "has");
+      await store.putSignalWaiter({
+        token: "child:p_1.all.3.0",
+        runId: "p_1",
+        seq: 3,
+        parallelGroup: "all:3"
+      });
+      await store.putSignalWaiter({
+        token: "child:p_1.all.4.0.all.0.0",
+        runId: "p_1.all.4.0",
+        seq: 0
+      });
+      await store.putSignalWaiter({
+        token: "child:pX1.all.3.0",
+        runId: "p_1",
+        seq: 9
+      });
+      expect2(await has("p_1", "child:p_1.all.3.")).toBe(true);
+      expect2(await has("p_1", "child:p_1.all.4.")).toBe(false);
+      expect2(await has("other", "child:p_1.all.3.")).toBe(false);
+      expect2(await has("p_1", "child:p%.all.3.")).toBe(false);
+      expect2(await has("p_1", "CHILD:p_1.all.3.")).toBe(false);
+      await store.takeSignalWaiter("child:p_1.all.3.0");
+      expect2(await has("p_1", "child:p_1.all.3.")).toBe(false);
+    });
     t("removeSignalWaiter deletes only the exact (token, runId, seq) row, never a different run's", async () => {
       await store.putSignalWaiter({
         token: "approve-1",