@dudousxd/nestjs-durable-testing 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -9,6 +9,94 @@ declare function assertStepsRan(store: StateStore, runId: string, names: string[
 /** Assert a step ran exactly the given number of attempts (e.g. to verify retries). */
 declare function assertStepAttempts(store: StateStore, runId: string, name: string, attempts: number): Promise<void>;
 
+/**
+ * The canonical physical column names for the durable tables, keyed by table → entity property →
+ * column. This is the cross-adapter contract: a run written by one store adapter must be readable by
+ * another, so EVERY adapter (TypeORM, MikroORM, Prisma, Drizzle) must map these properties to these
+ * exact columns. The canonical convention is `snake_case`.
+ *
+ * Each adapter has a spec that asserts its physical columns against this map (see `assertDurableColumns`).
+ * Without it, adapters silently diverge — one defaulting to its ORM's `snake_case` naming strategy,
+ * another keeping the verbatim camelCase property name — and a store swap fails against an existing
+ * table with "Unknown column" only at runtime. The map exists so that divergence is a failing unit
+ * test, not a production incident.
+ *
+ * The camelCase ("preserve") naming is simply the property names themselves (the object keys), so no
+ * separate map is needed for it.
+ */
+declare const DURABLE_CANONICAL_COLUMNS: {
+    readonly durable_workflow_runs: {
+        readonly id: "id";
+        readonly workflow: "workflow";
+        readonly workflowVersion: "workflow_version";
+        readonly status: "status";
+        readonly input: "input";
+        readonly output: "output";
+        readonly error: "error";
+        readonly wakeAt: "wake_at";
+        readonly lockedBy: "locked_by";
+        readonly lockedUntil: "locked_until";
+        readonly recoveryAttempts: "recovery_attempts";
+        readonly tags: "tags";
+        readonly searchAttributes: "search_attributes";
+        readonly createdAt: "created_at";
+        readonly updatedAt: "updated_at";
+    };
+    readonly durable_step_checkpoints: {
+        readonly runId: "run_id";
+        readonly seq: "seq";
+        readonly name: "name";
+        readonly kind: "kind";
+        readonly stepId: "step_id";
+        readonly status: "status";
+        readonly input: "input";
+        readonly output: "output";
+        readonly error: "error";
+        readonly events: "events";
+        readonly attempts: "attempts";
+        readonly workerGroup: "worker_group";
+        readonly wakeAt: "wake_at";
+        readonly enqueuedAt: "enqueued_at";
+        readonly startedAt: "started_at";
+        readonly finishedAt: "finished_at";
+    };
+    readonly durable_run_attributes: {
+        readonly runId: "run_id";
+        readonly key: "key";
+        readonly strValue: "str_value";
+        readonly numValue: "num_value";
+    };
+    readonly durable_signal_waiters: {
+        readonly token: "token";
+        readonly runId: "run_id";
+        readonly seq: "seq";
+    };
+    readonly durable_buffered_signals: {
+        readonly id: "id";
+        readonly token: "token";
+        readonly payload: "payload";
+    };
+};
+type DurableColumnMap = typeof DURABLE_CANONICAL_COLUMNS;
+/** A single column-name disagreement found by {@link assertDurableColumns}. */
+interface DurableColumnMismatch {
+    table: string;
+    property: string;
+    expected: string;
+    actual: string | undefined;
+}
+/**
+ * Walk every (table, property) in the canonical contract and compare it to what an adapter actually
+ * maps, via the supplied `resolve(table, property) => columnName`. Returns the list of mismatches
+ * (empty when the adapter is canonical) so a spec can `expect(assertDurableColumns(resolve)).toEqual([])`.
+ *
+ * Pass `expected = DURABLE_CANONICAL_COLUMNS` (default) for the snake_case contract, or a map of the
+ * property names to themselves to assert the camelCase ("preserve") naming.
+ */
+declare function assertDurableColumns(resolve: (table: string, property: string) => string | undefined, expected?: Record<string, Record<string, string>>): DurableColumnMismatch[];
+/** The "preserve" (camelCase) expectation: every property maps to a column of the same name. */
+declare function preserveColumnExpectation(): Record<string, Record<string, string>>;
+
 /** A clock you control, for testing durable sleeps without real time. */
 declare class MutableClock {
     private current;
@@ -127,4 +215,4 @@ type HandleableTransport = Transport & {
  */
 declare function assertTransportConformance(transport: HandleableTransport, idPrefix?: string): Promise<void>;
 
-export { type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, createTestEngine, failOnce, failTimes, recordedSteps, runStateStoreContract };
+export { DURABLE_CANONICAL_COLUMNS, type DurableColumnMap, type DurableColumnMismatch, type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, assertDurableColumns, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, createTestEngine, failOnce, failTimes, preserveColumnExpectation, recordedSteps, runStateStoreContract };

package/dist/index.js

@@ -48,6 +48,88 @@ async function assertStepAttempts(store, runId, name, attempts) {
 }
 __name(assertStepAttempts, "assertStepAttempts");
 
+// src/durable-columns.ts
+var DURABLE_CANONICAL_COLUMNS = {
+  durable_workflow_runs: {
+    id: "id",
+    workflow: "workflow",
+    workflowVersion: "workflow_version",
+    status: "status",
+    input: "input",
+    output: "output",
+    error: "error",
+    wakeAt: "wake_at",
+    lockedBy: "locked_by",
+    lockedUntil: "locked_until",
+    recoveryAttempts: "recovery_attempts",
+    tags: "tags",
+    searchAttributes: "search_attributes",
+    createdAt: "created_at",
+    updatedAt: "updated_at"
+  },
+  durable_step_checkpoints: {
+    runId: "run_id",
+    seq: "seq",
+    name: "name",
+    kind: "kind",
+    stepId: "step_id",
+    status: "status",
+    input: "input",
+    output: "output",
+    error: "error",
+    events: "events",
+    attempts: "attempts",
+    workerGroup: "worker_group",
+    wakeAt: "wake_at",
+    enqueuedAt: "enqueued_at",
+    startedAt: "started_at",
+    finishedAt: "finished_at"
+  },
+  durable_run_attributes: {
+    runId: "run_id",
+    key: "key",
+    strValue: "str_value",
+    numValue: "num_value"
+  },
+  durable_signal_waiters: {
+    token: "token",
+    runId: "run_id",
+    seq: "seq"
+  },
+  durable_buffered_signals: {
+    id: "id",
+    token: "token",
+    payload: "payload"
+  }
+};
+function assertDurableColumns(resolve, expected = DURABLE_CANONICAL_COLUMNS) {
+  const mismatches = [];
+  for (const [table, props] of Object.entries(expected)) {
+    for (const [property, column] of Object.entries(props)) {
+      const actual = resolve(table, property);
+      if (actual !== column) mismatches.push({
+        table,
+        property,
+        expected: column,
+        actual
+      });
+    }
+  }
+  return mismatches;
+}
+__name(assertDurableColumns, "assertDurableColumns");
+function preserveColumnExpectation() {
+  const out = {};
+  for (const [table, props] of Object.entries(DURABLE_CANONICAL_COLUMNS)) {
+    out[table] = Object.fromEntries(Object.keys(props).map((p) => [
+      p,
+      p
+    ]));
+  }
+  return out;
+}
+__name(preserveColumnExpectation, "preserveColumnExpectation");
+
 // src/harness.ts
 import { InMemoryStateStore, InMemoryTransport, WorkflowEngine } from "@dudousxd/nestjs-durable-core";
 var MutableClock = class {
@@ -235,6 +317,81 @@ function runStateStoreContract(name, makeStore) {
       expect(dead?.status).toBe("dead");
       expect(dead?.recoveryAttempts).toBe(4);
     });
+    t("deleteRun removes the run and all its rows (checkpoints, waiters, attributes)", async () => {
+      await store.createRun(run({
+        searchAttributes: {
+          tier: "pro"
+        }
+      }));
+      await store.saveCheckpoint(checkpoint());
+      await store.putSignalWaiter({
+        token: "approve-r1",
+        runId: "r1",
+        seq: 0
+      });
+      await store.deleteRun("r1");
+      expect(await store.getRun("r1")).toBeNull();
+      expect(await store.listCheckpoints("r1")).toEqual([]);
+      expect(await store.listSignalWaiters("approve-")).toEqual([]);
+      expect(await store.listRuns({
+        attributes: [
+          {
+            key: "tier",
+            op: "eq",
+            value: "pro"
+          }
+        ]
+      })).toEqual([]);
+    });
+    t("deleteRun is a no-op for a missing run", async () => {
+      await expect(store.deleteRun("nope")).resolves.toBeUndefined();
+    });
+    t("updateRun maps every patchable field \u2014 clears error and patches tags/lockedBy/input/timers", async () => {
+      await store.createRun(run({
+        status: "failed",
+        error: {
+          message: "boom"
+        },
+        tags: [
+          "old"
+        ],
+        lockedBy: "owner-1"
+      }));
+      await store.updateRun("r1", {
+        status: "completed",
+        output: {
+          ok: true
+        },
+        error: void 0,
+        input: {
+          orderId: "o2"
+        },
+        tags: [
+          "x",
+          "y"
+        ],
+        lockedBy: "owner-2",
+        wakeAt: 123456,
+        lockedUntil: 222222,
+        updatedAt: at
+      });
+      const r = await store.getRun("r1");
+      expect(r?.status).toBe("completed");
+      expect(r?.output).toEqual({
+        ok: true
+      });
+      expect(r?.error).toBeUndefined();
+      expect(r?.input).toEqual({
+        orderId: "o2"
+      });
+      expect(r?.tags).toEqual([
+        "x",
+        "y"
+      ]);
+      expect(r?.lockedBy).toBe("owner-2");
+      expect(r?.wakeAt).toBe(123456);
+      expect(r?.lockedUntil).toBe(222222);
+    });
     t("upserts checkpoints, reads them by (runId, seq), and lists them ordered by seq", async () => {
       await store.createRun(run());
       await store.saveCheckpoint(checkpoint());
@@ -5418,8 +5575,10 @@ async function assertTransportConformance(transport, idPrefix = "conf") {
 }
 __name(assertTransportConformance, "assertTransportConformance");
 export {
+  DURABLE_CANONICAL_COLUMNS,
   MutableClock,
   StateStoreUnavailableError,
+  assertDurableColumns,
   assertOutput,
   assertReplayable,
   assertRunStatus,
@@ -5429,6 +5588,7 @@ export {
   createTestEngine,
   failOnce,
   failTimes,
+  preserveColumnExpectation,
   recordedSteps,
   runStateStoreContract
 };