@dudousxd/nestjs-durable-core 0.29.0 → 0.30.0

package/dist/index.d.cts

@@ -226,6 +226,14 @@ interface StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * Hard-delete a run and all of its rows — the run plus its checkpoints, signal waiters, and
+     * normalized search-attribute rows. Unlike a cancelled run (which stays as terminal history), a
+     * deleted run is GONE: it no longer appears in {@link getRun} or {@link listRuns}. This removes
+     * exactly the one run — the engine's {@link WorkflowEngine.deleteRun} handles the child cascade.
+     * No-op if the run doesn't exist. (Token-keyed buffered signals are transient and left alone.)
+     */
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -1232,6 +1240,8 @@ declare class WorkflowEngine {
     private readonly trackStepStart;
     /** Where a freshly-started run executes — in-process by default (see {@link RunDispatcher}). */
     private readonly runDispatcher;
+    /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
+    private readonly singletons;
     /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
     private readonly workflows;
     /** The newest registered version per workflow name — used to `start` new runs. */
@@ -1499,6 +1509,17 @@ declare class WorkflowEngine {
     cancelWhere(filter: Omit<RunQuery, 'limit' | 'offset'>, opts?: {
         compensate?: boolean;
     }): Promise<RunResult[]>;
+    /**
+     * Hard-delete a run and its entire subtree. Unlike {@link cancel} (which marks a run `cancelled`
+     * but keeps it as history), delete REMOVES the run and all its rows (checkpoints, signal waiters,
+     * search-attribute rows) — it vanishes from {@link getRun} and {@link listRuns}. Use it to purge a
+     * finished run whose data is being deleted (e.g. a pipeline run whose result rows are cleared).
+     *
+     * Cascades depth-first via {@link getRunChildren} so children are gone before the parent (no
+     * orphaned child runs). Prefer {@link cancel} first for a live run — deleting one mid-flight orphans
+     * its worker (its next checkpoint write fails). Returns the number of runs deleted (0 if absent).
+     */
+    deleteRun(runId: string): Promise<number>;
     /**
      * Cascade cancellation to a run's children — both awaited (`ctx.child`, found via its live
      * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
@@ -1552,21 +1573,6 @@ declare class WorkflowEngine {
     private completeStep;
     /** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
     private failStep;
-    /**
-     * Whether `run` may run now under its singleton key: it's among the `limit` oldest in-flight runs
-     * (running or suspended) sharing the key, by `(createdAt, id)` order. A consistent store gives every
-     * instance the same ordering, so admission is race-free + FIFO.
-     */
-    private admitSingleton;
-    /**
-     * Notify-on-release: a singleton run just settled (freeing a slot), so wake the gated waiters that
-     * can now be admitted — immediately, instead of letting them sleep until their ~1s retry timer.
-     * Dispatches up to `limit` of the oldest gated (`suspended` + same singleton tag) waiters by
-     * `(createdAt, id)`; each re-checks admission in `runExecution` and runs only if it actually wins a
-     * slot, so this never breaks the FIFO + race-free guarantees (the durable timer remains the
-     * cross-instance / crash fallback — this just removes the poll latency on the happy path).
-     */
-    private wakeNextSingletons;
     private execute;
     /**
      * Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
@@ -1574,6 +1580,14 @@ declare class WorkflowEngine {
      * {@link runExecution}'s settle/suspend; the lease is held by {@link execute}. The result that lands
      * us back here (a remote step finished, a timer fired) goes through `resume` like any TS workflow.
      */
+    /**
+     * Apply a terminal/suspended transition once: persist the new run status, emit the matching
+     * lifecycle event, and (on completion/failure) wake a waiting parent. Both the TS and remote
+     * executors funnel their completed/failed/suspended outcomes through here so a status update can
+     * never drift from its event or `notifyParent` call. Does NOT touch the run lock — each executor
+     * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
+     */
+    private settleRun;
     private runRemoteExecution;
     /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
     private remoteHistory;
@@ -1794,6 +1808,7 @@ declare class CodecStateStore implements StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     transaction<T>(work: (tx: {
@@ -2030,6 +2045,7 @@ declare class InMemoryStateStore implements StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     listIncompleteRuns(): Promise<WorkflowRun[]>;

package/dist/index.d.ts

@@ -226,6 +226,14 @@ interface StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * Hard-delete a run and all of its rows — the run plus its checkpoints, signal waiters, and
+     * normalized search-attribute rows. Unlike a cancelled run (which stays as terminal history), a
+     * deleted run is GONE: it no longer appears in {@link getRun} or {@link listRuns}. This removes
+     * exactly the one run — the engine's {@link WorkflowEngine.deleteRun} handles the child cascade.
+     * No-op if the run doesn't exist. (Token-keyed buffered signals are transient and left alone.)
+     */
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -1232,6 +1240,8 @@ declare class WorkflowEngine {
     private readonly trackStepStart;
     /** Where a freshly-started run executes — in-process by default (see {@link RunDispatcher}). */
     private readonly runDispatcher;
+    /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
+    private readonly singletons;
     /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
     private readonly workflows;
     /** The newest registered version per workflow name — used to `start` new runs. */
@@ -1499,6 +1509,17 @@ declare class WorkflowEngine {
     cancelWhere(filter: Omit<RunQuery, 'limit' | 'offset'>, opts?: {
         compensate?: boolean;
     }): Promise<RunResult[]>;
+    /**
+     * Hard-delete a run and its entire subtree. Unlike {@link cancel} (which marks a run `cancelled`
+     * but keeps it as history), delete REMOVES the run and all its rows (checkpoints, signal waiters,
+     * search-attribute rows) — it vanishes from {@link getRun} and {@link listRuns}. Use it to purge a
+     * finished run whose data is being deleted (e.g. a pipeline run whose result rows are cleared).
+     *
+     * Cascades depth-first via {@link getRunChildren} so children are gone before the parent (no
+     * orphaned child runs). Prefer {@link cancel} first for a live run — deleting one mid-flight orphans
+     * its worker (its next checkpoint write fails). Returns the number of runs deleted (0 if absent).
+     */
+    deleteRun(runId: string): Promise<number>;
     /**
      * Cascade cancellation to a run's children — both awaited (`ctx.child`, found via its live
      * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
@@ -1552,21 +1573,6 @@ declare class WorkflowEngine {
     private completeStep;
     /** Checkpoint a step that failed terminally, so the failure point is visible (not just the run). */
     private failStep;
-    /**
-     * Whether `run` may run now under its singleton key: it's among the `limit` oldest in-flight runs
-     * (running or suspended) sharing the key, by `(createdAt, id)` order. A consistent store gives every
-     * instance the same ordering, so admission is race-free + FIFO.
-     */
-    private admitSingleton;
-    /**
-     * Notify-on-release: a singleton run just settled (freeing a slot), so wake the gated waiters that
-     * can now be admitted — immediately, instead of letting them sleep until their ~1s retry timer.
-     * Dispatches up to `limit` of the oldest gated (`suspended` + same singleton tag) waiters by
-     * `(createdAt, id)`; each re-checks admission in `runExecution` and runs only if it actually wins a
-     * slot, so this never breaks the FIFO + race-free guarantees (the durable timer remains the
-     * cross-instance / crash fallback — this just removes the poll latency on the happy path).
-     */
-    private wakeNextSingletons;
     private execute;
     /**
      * Advance a remote (cross-SDK) workflow one turn: hand its history to the executor (which dispatches
@@ -1574,6 +1580,14 @@ declare class WorkflowEngine {
      * {@link runExecution}'s settle/suspend; the lease is held by {@link execute}. The result that lands
      * us back here (a remote step finished, a timer fired) goes through `resume` like any TS workflow.
      */
+    /**
+     * Apply a terminal/suspended transition once: persist the new run status, emit the matching
+     * lifecycle event, and (on completion/failure) wake a waiting parent. Both the TS and remote
+     * executors funnel their completed/failed/suspended outcomes through here so a status update can
+     * never drift from its event or `notifyParent` call. Does NOT touch the run lock — each executor
+     * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
+     */
+    private settleRun;
     private runRemoteExecution;
     /** The run's resolved durable ops as replay inputs: completed/failed steps + elapsed timers. */
     private remoteHistory;
@@ -1794,6 +1808,7 @@ declare class CodecStateStore implements StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     transaction<T>(work: (tx: {
@@ -2030,6 +2045,7 @@ declare class InMemoryStateStore implements StateStore {
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
+    deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     listIncompleteRuns(): Promise<WorkflowRun[]>;