@dudousxd/nestjs-durable-core 0.35.0 → 0.36.0

package/dist/index.d.cts

@@ -417,6 +417,15 @@ interface StateStore {
      * No-op if the run doesn't exist. (Token-keyed buffered signals are transient and left alone.)
      */
     deleteRun(runId: string): Promise<void>;
+    /**
+     * Hard-delete up to `limit` terminal runs that fall OUTSIDE `policy` (oldest / over the count cap
+     * first), cascading to their child rows exactly like {@link deleteRun}. Returns how many runs were
+     * deleted — call again while it returns `limit` to drain a large backlog in bounded batches.
+     *
+     * Optional: only adapters that implement a bulk prune provide it; the retention poller no-ops with a
+     * warning when the configured store omits it. See {@link RetentionPolicy} for the keep/prune rule.
+     */
+    pruneTerminalRuns?(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -491,6 +500,26 @@ interface StateStore {
      */
     listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
+/** The terminal run statuses — a run in one of these is finished and will never change on its own.
+ *  Only these are eligible for retention pruning (a {@link RetentionPolicy} targeting a non-terminal
+ *  status would race the engine and delete live work). */
+declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+/**
+ * One retention rule for hard-pruning terminal run history. Within `statuses` (terminal only), a run
+ * is KEPT only if it satisfies EVERY bound you set, and pruned the moment it violates any:
+ *  - `maxAgeMs` — prune runs whose `updatedAt` (≈ the time they reached terminal) is older than
+ *    `now - maxAgeMs`.
+ *  - `maxCount` — keep only the `maxCount` most-recent (by `updatedAt`) runs in the status set; prune
+ *    everything past that.
+ *
+ * Set one or both (both = the most-restrictive wins: capped at `maxCount` rows AND nothing older than
+ * `maxAgeMs`). Statuses not named by any policy are never pruned.
+ */
+interface RetentionPolicy {
+    statuses: RunStatus[];
+    maxAgeMs?: number;
+    maxCount?: number;
+}
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
 type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
@@ -2359,4 +2388,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };

package/dist/index.d.ts

@@ -417,6 +417,15 @@ interface StateStore {
      * No-op if the run doesn't exist. (Token-keyed buffered signals are transient and left alone.)
      */
     deleteRun(runId: string): Promise<void>;
+    /**
+     * Hard-delete up to `limit` terminal runs that fall OUTSIDE `policy` (oldest / over the count cap
+     * first), cascading to their child rows exactly like {@link deleteRun}. Returns how many runs were
+     * deleted — call again while it returns `limit` to drain a large backlog in bounded batches.
+     *
+     * Optional: only adapters that implement a bulk prune provide it; the retention poller no-ops with a
+     * warning when the configured store omits it. See {@link RetentionPolicy} for the keep/prune rule.
+     */
+    pruneTerminalRuns?(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -491,6 +500,26 @@ interface StateStore {
      */
     listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
+/** The terminal run statuses — a run in one of these is finished and will never change on its own.
+ *  Only these are eligible for retention pruning (a {@link RetentionPolicy} targeting a non-terminal
+ *  status would race the engine and delete live work). */
+declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+/**
+ * One retention rule for hard-pruning terminal run history. Within `statuses` (terminal only), a run
+ * is KEPT only if it satisfies EVERY bound you set, and pruned the moment it violates any:
+ *  - `maxAgeMs` — prune runs whose `updatedAt` (≈ the time they reached terminal) is older than
+ *    `now - maxAgeMs`.
+ *  - `maxCount` — keep only the `maxCount` most-recent (by `updatedAt`) runs in the status set; prune
+ *    everything past that.
+ *
+ * Set one or both (both = the most-restrictive wins: capped at `maxCount` rows AND nothing older than
+ * `maxAgeMs`). Statuses not named by any policy are never pruned.
+ */
+interface RetentionPolicy {
+    statuses: RunStatus[];
+    maxAgeMs?: number;
+    maxCount?: number;
+}
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
 type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
@@ -2359,4 +2388,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };

package/dist/index.js

@@ -3413,6 +3413,14 @@ var RemoteStepError = class extends Error {
   }
 };
 
+// src/interfaces.ts
+var TERMINAL_RUN_STATUSES = [
+  "completed",
+  "failed",
+  "cancelled",
+  "dead"
+];
+
 // src/remote-step-factory.ts
 function remoteStep(config) {
   return {
@@ -4225,6 +4233,7 @@ export {
   STATE_STORE_CANONICAL,
   SignalTimeoutError,
   SingletonQueueFullError,
+  TERMINAL_RUN_STATUSES,
   TRANSPORT,
   TRANSPORT_CANONICAL,
   WORKFLOW_NAME_KEY,