@dudousxd/nestjs-durable-testing 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { AdmissionBackend, StateStore, RunStatus, WorkflowEngine, InMemoryStateStore, InMemoryTransport, RunResult, WorkflowRef, StartOptions, WorkflowRun, StepCheckpoint, Transport } from '@dudousxd/nestjs-durable-core';
2
+ export { RUN_HISTORY_FIXTURE_VERSION } from '@dudousxd/nestjs-durable-core';
2
3
 
3
4
  /**
4
5
  * Builds an {@link AdmissionBackend} bound to the given test clock. Implementations that hold their
@@ -184,6 +185,34 @@ interface RunHistory {
184
185
  run: WorkflowRun;
185
186
  checkpoints: StepCheckpoint[];
186
187
  }
188
+
189
+ /**
190
+ * Capture a run's replayable history (the run row + its full checkpoint timeline) from anything with
191
+ * the read API: a `WorkflowEngine`, or a bare `StateStore` (the CLI's `durable export` uses the
192
+ * store). The fixture half of the {@link assertReplayable} loop: capture a representative run,
193
+ * commit it with {@link serializeRunHistory}, and assert it in CI via {@link parseRunHistory}.
194
+ * Returns `null` for an unknown run.
195
+ */
196
+ declare function captureHistory(source: {
197
+ getRun(runId: string): Promise<WorkflowRun | null | undefined>;
198
+ listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
199
+ }, runId: string): Promise<RunHistory | null>;
200
+ /**
201
+ * Serialize a captured history as a pretty-printed JSON fixture (with a trailing newline, so it
202
+ * commits cleanly). Read it back with {@link parseRunHistory}.
203
+ */
204
+ declare function serializeRunHistory(history: RunHistory): string;
205
+ /**
206
+ * Parse a committed fixture (what {@link serializeRunHistory} / `durable export` writes) back into a
207
+ * {@link RunHistory}, reviving the `Date` fields JSON flattened to ISO strings, so
208
+ * `assertReplayable(register, parseRunHistory(readFileSync('fixture.json', 'utf8')))` just works.
209
+ *
210
+ * Throws on a fixture whose `version` is not {@link RUN_HISTORY_FIXTURE_VERSION}: a fixture written
211
+ * in another format would otherwise replay against the wrong shape. A fixture with NO `version` (a
212
+ * hand-built `{ run, checkpoints }`, the shape these docs showed before the marker existed) is read
213
+ * as version 1.
214
+ */
215
+ declare function parseRunHistory(json: string): RunHistory;
187
216
  /**
188
217
  * Replay a recorded run's history against the CURRENT workflow code and throw if they diverged.
189
218
  *
@@ -288,4 +317,37 @@ declare function aggregationFixture(): StepCheckpoint[];
288
317
  */
289
318
  declare function registerCheckpointAggregationCases(t: (label: string, fn: () => Promise<void>) => void, getStore: () => StateStore, run: (over?: Partial<WorkflowRun>) => WorkflowRun): void;
290
319
 
291
- export { type AdmissionBackendFactory, DURABLE_CANONICAL_COLUMNS, type DurableColumnMap, type DurableColumnMismatch, type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, aggregationFixture, assertDurableColumns, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, createTestEngine, failOnce, failTimes, preserveColumnExpectation, recordedSteps, registerCheckpointAggregationCases, runAdmissionBackendContract, runStateStoreContract };
320
+ /**
321
+ * Two transports on one broker (two instances of one deployment), isolated from every other case:
322
+ * a fresh prefix, table or queue per call. Both carry a run queue
323
+ * ({@link Transport.dispatchRuns} + {@link Transport.onDispatchedRun}).
324
+ */
325
+ interface RunDispatchHarness {
326
+ pair(): Promise<[Transport, Transport]>;
327
+ }
328
+ /**
329
+ * Builds the harness once per case, or returns a string: the reason the backend is unavailable
330
+ * (no Docker, say), which skips the case.
331
+ */
332
+ type RunDispatchHarnessFactory = () => Promise<RunDispatchHarness | string>;
333
+ interface RunDispatchContractOptions {
334
+ /** Per-case budget; a polling transport needs more. Default 30s. */
335
+ timeoutMs?: number;
336
+ /** Children in the fan cases. Default 300. */
337
+ fanSize?: number;
338
+ /**
339
+ * Whether a run already waiting in the queue is not queued a second time. Default true. False for
340
+ * an at-least-once queue without deduplication (an SQS standard queue): the contract then checks
341
+ * that a run received twice still runs one turn.
342
+ */
343
+ dedupesWaitingRuns?: boolean;
344
+ }
345
+ /**
346
+ * The contract of a transport's run queue: what `ctx.all` children, starts, re-dispatches and due
347
+ * timers rely on to spread over every instance of a deployment instead of executing on the one that
348
+ * triggered them. Registered as a vitest `describe`; every transport that carries a run queue runs
349
+ * it against its real backend.
350
+ */
351
+ declare function runRunDispatchContract(name: string, makeHarness: RunDispatchHarnessFactory, options?: RunDispatchContractOptions): void;
352
+
353
+ export { type AdmissionBackendFactory, DURABLE_CANONICAL_COLUMNS, type DurableColumnMap, type DurableColumnMismatch, type HandleableTransport, MutableClock, type RunDispatchContractOptions, type RunDispatchHarness, type RunDispatchHarnessFactory, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, aggregationFixture, assertDurableColumns, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, captureHistory, createTestEngine, failOnce, failTimes, parseRunHistory, preserveColumnExpectation, recordedSteps, registerCheckpointAggregationCases, runAdmissionBackendContract, runRunDispatchContract, runStateStoreContract, serializeRunHistory };