@adonis-agora/durable 0.1.0

package/dist/src/testing-kit/harness.d.ts

@@ -0,0 +1,28 @@
+import { InMemoryStateStore, InMemoryTransport, type RunResult, type StartOptions, WorkflowEngine, type WorkflowRef } from '../index.js';
+/** A clock you control, for testing durable sleeps without real time. */
+export declare class MutableClock {
+    private current;
+    constructor(current?: number);
+    readonly now: () => number;
+    set(ms: number): void;
+    advance(ms: number): void;
+}
+export interface TestEngine {
+    engine: WorkflowEngine;
+    store: InMemoryStateStore;
+    transport: InMemoryTransport;
+    clock: MutableClock;
+    /** Advance the clock by `ms` and resume any durable sleeps now due. */
+    tick(ms: number): Promise<RunResult[]>;
+    /**
+     * Enqueue a run and wait for it to settle (terminal or suspended). `engine.start` only enqueues
+     * now (dispatch model), so use this when a test needs the outcome synchronously.
+     */
+    run(workflow: WorkflowRef, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
+}
+/**
+ * A self-contained engine wired to in-memory store + transport and a controllable clock — run a
+ * whole workflow in a unit test, with no Postgres, no Redis, and no real time.
+ */
+export declare function createTestEngine(): TestEngine;
+//# sourceMappingURL=harness.d.ts.map

package/dist/src/testing-kit/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../src/testing-kit/harness.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,yEAAyE;AACzE,qBAAa,YAAY;IACX,OAAO,CAAC,OAAO;gBAAP,OAAO,SAAQ;IACnC,QAAQ,CAAC,GAAG,QAAO,MAAM,CAAiB;IAC1C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAGrB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAG1B;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,uEAAuE;IACvE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACvC;;;OAGG;IACH,GAAG,CACD,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAqB7C"}

package/dist/src/testing-kit/harness.js

@@ -0,0 +1,42 @@
+import { InMemoryStateStore, InMemoryTransport, WorkflowEngine, } from '../index.js';
+/** A clock you control, for testing durable sleeps without real time. */
+export class MutableClock {
+    current;
+    constructor(current = 1_000) {
+        this.current = current;
+    }
+    now = () => this.current;
+    set(ms) {
+        this.current = ms;
+    }
+    advance(ms) {
+        this.current += ms;
+    }
+}
+/**
+ * A self-contained engine wired to in-memory store + transport and a controllable clock — run a
+ * whole workflow in a unit test, with no Postgres, no Redis, and no real time.
+ */
+export function createTestEngine() {
+    const store = new InMemoryStateStore();
+    const transport = new InMemoryTransport();
+    const clock = new MutableClock();
+    const engine = new WorkflowEngine({ store, transport, clock: clock.now });
+    return {
+        engine,
+        store,
+        transport,
+        clock,
+        async tick(ms) {
+            clock.advance(ms);
+            return engine.resumeDueTimers(clock.now());
+        },
+        async run(workflow, input, runId, opts) {
+            // `start` is overloaded per ref kind; a `WorkflowRef` union fits neither overload directly, so
+            // resolve to the string overload (the engine accepts a class or name at runtime).
+            await engine.start(workflow, input, runId, opts);
+            return engine.waitForRun(runId);
+        },
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/src/testing-kit/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../../src/testing-kit/harness.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAGjB,cAAc,GAEf,MAAM,aAAa,CAAC;AAErB,yEAAyE;AACzE,MAAM,OAAO,YAAY;IACH;IAApB,YAAoB,UAAU,KAAK;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAC9B,GAAG,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC;IAC1C,GAAG,CAAC,EAAU;QACZ,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACrB,CAAC;CACF;AAqBD;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,KAAK,GAAG,IAAI,kBAAkB,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1E,OAAO;QACL,MAAM;QACN,KAAK;QACL,SAAS;QACT,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,EAAU;YACnB,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAClB,OAAO,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI;YACpC,+FAA+F;YAC/F,kFAAkF;YAClF,MAAM,MAAM,CAAC,KAAK,CAAC,QAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3D,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/testing-kit/index.d.ts

@@ -0,0 +1,8 @@
+export * from './admission-backend-conformance.js';
+export * from './assertions.js';
+export * from './harness.js';
+export * from './replay.js';
+export * from './state-store-conformance.js';
+export * from './steps.js';
+export * from './transport-conformance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/testing-kit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing-kit/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC"}

package/dist/src/testing-kit/index.js

@@ -0,0 +1,8 @@
+export * from './admission-backend-conformance.js';
+export * from './assertions.js';
+export * from './harness.js';
+export * from './replay.js';
+export * from './state-store-conformance.js';
+export * from './steps.js';
+export * from './transport-conformance.js';
+//# sourceMappingURL=index.js.map

package/dist/src/testing-kit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing-kit/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC"}

package/dist/src/testing-kit/replay.d.ts

@@ -0,0 +1,22 @@
+import { type StepCheckpoint, WorkflowEngine, type WorkflowRun } from '../index.js';
+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/src/testing-kit/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../src/testing-kit/replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,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/src/testing-kit/replay.js

@@ -0,0 +1,38 @@
+import { InMemoryStateStore, WorkflowEngine, } from '../index.js';
+/**
+ * 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 async function assertReplayable(register, history) {
+    const store = new 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 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/src/testing-kit/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../../src/testing-kit/replay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAElB,cAAc,GAEf,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAA0C,EAC1C,OAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,kBAAkB,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,cAAc,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/src/testing-kit/state-store-conformance.d.ts

@@ -0,0 +1,51 @@
+import { type StateStore } from '../index.js';
+/**
+ * A freshly provisioned, empty {@link StateStore} plus a `cleanup` to release its resources (close
+ * the connection, drop the schema, etc.). The conformance suite asks for one before each test so
+ * every case starts from a clean slate — exactly like the per-store specs that build a `:memory:` DB.
+ */
+export interface StateStoreContext {
+    store: StateStore;
+    cleanup: () => Promise<void>;
+    /**
+     * Whether the store's optional `transaction` can run an ASYNC work callback. Defaults to `true`.
+     * Set `false` only for a driver that genuinely can't — e.g. Drizzle on the SYNCHRONOUS
+     * `better-sqlite3` driver, whose `transaction()` rejects a promise-returning callback ("Transaction
+     * function cannot return a promise"). The same Drizzle adapter on an async driver (libSQL) works,
+     * and the contract still asserts `transaction` for every other store, so this never hides drift.
+     */
+    supportsAsyncTransaction?: boolean;
+    /**
+     * Whether the store can filter `listRuns({ tag })`. Defaults to `true`. Set `false` ONLY for
+     * Prisma-on-SQLite: the Prisma adapter filters tags with the `array_contains` JSON predicate, which
+     * Prisma supports on its real targets (Postgres + MySQL) but NOT on SQLite. SQLite is only the
+     * adapter's local TEST database, so the tag case is skipped there; every other store (and Prisma on
+     * a real engine) still asserts it, so this doesn't hide drift in the supported configurations.
+     */
+    supportsTagFilter?: boolean;
+}
+/** Builds a fresh, empty store for one test. Called once per `it` (in `beforeEach`). */
+export type StateStoreFactory = () => Promise<StateStoreContext>;
+/**
+ * Thrown by a {@link StateStoreFactory} to SKIP the contract for an unavailable backend instead of
+ * failing it — e.g. a testcontainers DB spec when Docker isn't running. Every contract case catches
+ * it, logs once, and returns (a no-op pass), so `pnpm test:db` is green-with-skips off a dev box
+ * without Docker rather than red.
+ */
+export declare class StateStoreUnavailableError extends Error {
+    readonly isStateStoreUnavailable = true;
+    constructor(message: string);
+}
+/**
+ * The SHARED behavioral contract every `StateStore` must satisfy — in-memory and each ORM adapter
+ * alike. Registered as a vitest `describe`; pass a `name` and a {@link StateStoreFactory} that builds
+ * a fresh, empty store. The same assertions run against SQLite/in-memory under `pnpm test` and
+ * against real Postgres/MySQL (via testcontainers) under `pnpm test:db`, so any drift between an
+ * adapter and the canonical (in-memory) semantics — especially the search-attribute side-table
+ * pushdown, which is implemented per-store — fails here instead of silently in production.
+ *
+ * Each adapter's own spec keeps its dialect-specific tests (DDL/longtext/EXISTS-SQL/JSON-tolerance);
+ * this suite owns the cross-store behavior so those never drift apart.
+ */
+export declare function runStateStoreContract(name: string, makeStore: StateStoreFactory): void;
+//# sourceMappingURL=state-store-conformance.d.ts.map

package/dist/src/testing-kit/state-store-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store-conformance.d.ts","sourceRoot":"","sources":["../../../src/testing-kit/state-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,UAAU,EAIhB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,uBAAuB,QAAQ;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAoftF"}