@dudousxd/nestjs-durable-testing 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './assertions';
 export * from './harness';
+export * from './replay';
 export * from './steps';
 export * from './transport-conformance';
 //# 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,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./assertions"), exports);
 __exportStar(require("./harness"), exports);
+__exportStar(require("./replay"), exports);
 __exportStar(require("./steps"), exports);
 __exportStar(require("./transport-conformance"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,4CAA0B;AAC1B,0CAAwB;AACxB,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,4CAA0B;AAC1B,2CAAyB;AACzB,0CAAwB;AACxB,0DAAwC"}

package/dist/replay.d.ts

@@ -0,0 +1,22 @@
+import { type StepCheckpoint, WorkflowEngine, type WorkflowRun } from '@dudousxd/nestjs-durable-core';
+export interface RunHistory {
+    run: WorkflowRun;
+    checkpoints: StepCheckpoint[];
+}
+/**
+ * Replay a recorded run's history against the CURRENT workflow code and throw if they diverged.
+ *
+ * Capture a real (ideally in-flight or representative) run from production —
+ * `{ run: await store.getRun(id), checkpoints: await store.listCheckpoints(id) }` — commit it as a
+ * fixture, and assert here in CI. If a code change renamed/reordered/removed a step at a position the
+ * history already recorded, the engine raises a `NonDeterminismError` on replay and this rethrows it,
+ * catching the break *before* it reaches an in-flight run on deploy (the moment you'd otherwise
+ * silently replay the wrong checkpoint into the wrong step). Register the workflow exactly as the app
+ * does:
+ *
+ * ```ts
+ * await assertReplayable((engine) => engine.register('pipeline', '1', pipeline.run), fixture);
+ * ```
+ */
+export declare function assertReplayable(register: (engine: WorkflowEngine) => void, history: RunHistory): Promise<void>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,WAAW,CAAC;IACjB,WAAW,EAAE,cAAc,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,EAC1C,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/replay.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertReplayable = assertReplayable;
+const nestjs_durable_core_1 = require("@dudousxd/nestjs-durable-core");
+/**
+ * Replay a recorded run's history against the CURRENT workflow code and throw if they diverged.
+ *
+ * Capture a real (ideally in-flight or representative) run from production —
+ * `{ run: await store.getRun(id), checkpoints: await store.listCheckpoints(id) }` — commit it as a
+ * fixture, and assert here in CI. If a code change renamed/reordered/removed a step at a position the
+ * history already recorded, the engine raises a `NonDeterminismError` on replay and this rethrows it,
+ * catching the break *before* it reaches an in-flight run on deploy (the moment you'd otherwise
+ * silently replay the wrong checkpoint into the wrong step). Register the workflow exactly as the app
+ * does:
+ *
+ * ```ts
+ * await assertReplayable((engine) => engine.register('pipeline', '1', pipeline.run), fixture);
+ * ```
+ */
+async function assertReplayable(register, history) {
+    const store = new nestjs_durable_core_1.InMemoryStateStore();
+    // Seed as a suspended run with no lock so resume() replays the body against the recorded
+    // checkpoints — no transport is wired, so nothing new is dispatched.
+    await store.createRun({
+        ...history.run,
+        status: 'suspended',
+        lockedBy: undefined,
+        lockedUntil: undefined,
+    });
+    for (const cp of history.checkpoints)
+        await store.saveCheckpoint(cp);
+    const engine = new nestjs_durable_core_1.WorkflowEngine({ store });
+    register(engine);
+    const result = await engine.resume(history.run.id);
+    if (result.status === 'failed' && result.error?.message?.startsWith('non-determinism')) {
+        const err = new Error(result.error.message);
+        err.name = 'NonDeterminismError';
+        throw err;
+    }
+}
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":";;AA2BA,4CAuBC;AAlDD,uEAKuC;AAOvC;;;;;;;;;;;;;;GAcG;AACI,KAAK,UAAU,gBAAgB,CACpC,QAA0C,EAC1C,OAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,wCAAkB,EAAE,CAAC;IACvC,yFAAyF;IACzF,qEAAqE;IACrE,MAAM,KAAK,CAAC,SAAS,CAAC;QACpB,GAAG,OAAO,CAAC,GAAG;QACd,MAAM,EAAE,WAAW;QACnB,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,SAAS;KACvB,CAAC,CAAC;IACH,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,WAAW;QAAE,MAAM,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;IAErE,MAAM,MAAM,GAAG,IAAI,oCAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACvF,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5C,GAAG,CAAC,IAAI,GAAG,qBAAqB,CAAC;QACjC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/transport-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-conformance.d.ts","sourceRoot":"","sources":["../src/transport-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,+BAA+B,CAAC;AAGvC,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACrE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAUF;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CA2Bf"}
+{"version":3,"file":"transport-conformance.d.ts","sourceRoot":"","sources":["../src/transport-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,+BAA+B,CAAC;AAGvC,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACrE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAyBF;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/transport-conformance.js

@@ -10,6 +10,21 @@ const echo = {
     output: zod_1.z.object({ doubled: zod_1.z.number() }),
     __remote: true,
 };
+/**
+ * A durable `ctx.call` suspends the run; the worker result resumes it asynchronously (on whatever
+ * tick/poll the transport delivers on). Poll the store until the run reaches a terminal state —
+ * with a generous budget so a poll-based transport (DB/SQS) has time to round-trip.
+ */
+async function settle(store, runId, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const run = await store.getRun(runId);
+        if (run && run.status !== 'running' && run.status !== 'suspended')
+            return run;
+        await new Promise((r) => setTimeout(r, 25));
+    }
+    throw new Error(`run ${runId} did not settle within ${timeoutMs}ms`);
+}
 /**
  * The contract every `Transport` must satisfy: a remote step dispatched through it round-trips to a
  * worker and back (success), and a throwing handler surfaces as a failed run (failure). Point it at
@@ -20,24 +35,27 @@ const echo = {
  */
 async function assertTransportConformance(transport, idPrefix = 'conf') {
     try {
+        // One engine/store/transport — a durable remote step routes its result back to this engine,
+        // which resumes the run. (Two engines on one transport would fight over the result stream.)
+        const store = new nestjs_durable_core_1.InMemoryStateStore();
+        const engine = new nestjs_durable_core_1.WorkflowEngine({ store, transport });
+        engine.register('conf-ok', '1', async (ctx) => (await ctx.call(echo, { n: 21 })).doubled);
+        engine.register('conf-fail', '1', async (ctx) => ctx.call(echo, { n: 1 }));
         // success: the worker doubles the input
         transport.handle('conformance.echo', async (input) => ({
             doubled: input.n * 2,
         }));
-        const engine = new nestjs_durable_core_1.WorkflowEngine({ store: new nestjs_durable_core_1.InMemoryStateStore(), transport });
-        engine.register('conf-ok', '1', async (ctx) => (await ctx.call(echo, { n: 21 })).doubled);
-        const ok = await engine.start('conf-ok', {}, `${idPrefix}-ok`);
+        await engine.start('conf-ok', {}, `${idPrefix}-ok`);
+        const ok = await settle(store, `${idPrefix}-ok`);
         if (ok.status !== 'completed' || ok.output !== 42) {
             throw new Error(`expected completed/42, got ${JSON.stringify(ok)}`);
         }
-        // failure: a throwing handler fails the run
-        const failTransport = transport; // same instance, re-register the handler to throw
-        failTransport.handle('conformance.echo', async () => {
+        // failure: a throwing handler surfaces as a failed run (re-register the same step to throw)
+        transport.handle('conformance.echo', async () => {
             throw new Error('handler boom');
         });
-        const failEngine = new nestjs_durable_core_1.WorkflowEngine({ store: new nestjs_durable_core_1.InMemoryStateStore(), transport });
-        failEngine.register('conf-fail', '1', async (ctx) => ctx.call(echo, { n: 1 }));
-        const failed = await failEngine.start('conf-fail', {}, `${idPrefix}-fail`);
+        await engine.start('conf-fail', {}, `${idPrefix}-fail`);
+        const failed = await settle(store, `${idPrefix}-fail`);
         if (failed.status !== 'failed') {
             throw new Error(`expected failed, got ${JSON.stringify(failed)}`);
         }

package/dist/transport-conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport-conformance.js","sourceRoot":"","sources":["../src/transport-conformance.ts"],"names":[],"mappings":";;AA8BA,gEA8BC;AA5DD,uEAKuC;AACvC,6BAAwB;AAQxB,MAAM,IAAI,GAAsD;IAC9D,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,aAAa;IACpB,KAAK,EAAE,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAClC,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACzC,QAAQ,EAAE,IAAI;CACf,CAAC;AAEF;;;;;;;GAOG;AACI,KAAK,UAAU,0BAA0B,CAC9C,SAA8B,EAC9B,QAAQ,GAAG,MAAM;IAEjB,IAAI,CAAC;QACH,wCAAwC;QACxC,SAAS,CAAC,MAAM,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACrD,OAAO,EAAG,KAAuB,CAAC,CAAC,GAAG,CAAC;SACxC,CAAC,CAAC,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,oCAAc,CAAC,EAAE,KAAK,EAAE,IAAI,wCAAkB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAClF,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC1F,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,GAAG,QAAQ,KAAK,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,MAAM,KAAK,WAAW,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,4CAA4C;QAC5C,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,kDAAkD;QACnF,aAAa,CAAC,MAAM,CAAC,kBAAkB,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,oCAAc,CAAC,EAAE,KAAK,EAAE,IAAI,wCAAkB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACtF,UAAU,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/E,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;QAC3E,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"transport-conformance.js","sourceRoot":"","sources":["../src/transport-conformance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-durable-testing",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Testing utilities for nestjs-durable — a test engine harness, crash/flaky-step injection, and replay assertions",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "typescript": "5.9.3",
-    "@dudousxd/nestjs-durable-core": "^0.1.0"
+    "@dudousxd/nestjs-durable-core": "^0.4.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",