@dudousxd/nestjs-durable 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -1,8 +1,417 @@
-export * from './context-accessor';
-export * from './decorators';
-export * from './durable.module';
-export * from './entity';
-export * from './step-interceptor';
-export * from './tokens';
-export * from './workflow.service';
-//# sourceMappingURL=index.d.ts.map
+import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
+import { DynamicModule, InjectionToken } from '@nestjs/common';
+
+/**
+ * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
+ * (`packages/core/src/accessor.ts`).
+ *
+ * We deliberately do NOT import nestjs-context (it is an OPTIONAL peer). Instead
+ * we declare the same shape here and inject it via the shared
+ * {@link CONTEXT_ACCESSOR} token with `@Optional()`. Any object that structurally
+ * satisfies this interface — including nestjs-context's real accessor — works.
+ *
+ * Kept byte-aligned with nestjs-context's `ContextAccessor` (and the identical
+ * mirror in `@dudousxd/nestjs-authz`): `traceId()` / `tenantId()` are REQUIRED
+ * (the real accessor always provides them) and `get()` is included, so the
+ * structural match stays exact when DurableModule auto-feeds the carrier.
+ */
+interface UserRef {
+    type: string;
+    id: string | number;
+}
+/** Opaque shape of the context store. durable never reads it; mirrors the upstream surface. */
+type ContextStore = Record<string, unknown>;
+interface ContextAccessor {
+    /** Trace id for the current request, or `undefined` when unavailable. */
+    traceId(): string | undefined;
+    /** Current tenant id, or `undefined` when no multi-tenant context is populated. */
+    tenantId(): string | undefined;
+    /** Reference to the current user, or `undefined` when unauthenticated. */
+    userRef(): UserRef | undefined;
+    /** The raw context store for the current request, or `undefined`. */
+    get(): ContextStore | undefined;
+}
+
+declare const WORKFLOW_METADATA: unique symbol;
+interface WorkflowMeta {
+    name: string;
+    version: string;
+    /** The workflow this workflow's dead runs route to (a name or a class). See `WorkflowOptions`. */
+    deadLetterWorkflow?: WorkflowRef | undefined;
+    /** Static searchable labels stamped on every run of this workflow. See `WorkflowOptions`. */
+    tags?: string[] | undefined;
+    /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
+    singleton?: SingletonConfig | undefined;
+    /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
+    executionTimeout?: string | number | undefined;
+    /** class-validator DTO validated at start. See `WorkflowOptions`. */
+    inputSchema?: (new (...args: any[]) => object) | undefined;
+    /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
+    validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+    /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
+    onEvent?: string[] | undefined;
+    /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
+    debounce?: string | number | undefined;
+    /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
+    batch?: {
+        maxSize: number;
+        within: string | number;
+    } | undefined;
+}
+interface WorkflowOptions {
+    name: string;
+    version?: string;
+    /**
+     * Route this workflow's dead-lettered runs to another **registered** workflow — by class
+     * (`deadLetterWorkflow: CheckoutDlqWorkflow`, refactor-safe) or by name for a cross-runtime
+     * handler. For a handler co-located on the same class, prefer an inline `@DeadLetter()` method
+     * instead — it takes precedence, and declaring both is a boot-time error. The handler receives a
+     * {@link DeadLetter} payload, idempotent by a `dlq:<runId>` id.
+     */
+    deadLetterWorkflow?: WorkflowRef;
+    /**
+     * Static labels stamped on **every run** of this workflow (e.g. `tags: ['etl', 'critical']`) and
+     * merged with any per-run tags passed to `start`. Searchable/filterable in the dashboard.
+     */
+    tags?: string[];
+    /**
+     * Serialize runs of this workflow that share a key — a durable FIFO mutex. e.g.
+     * `singleton: { key: (input) => `base:${input.baseId}` }` runs at most one pipeline per base at a
+     * time; same-key runs queue (suspended) and admit in creation order as slots free. `limit` (default
+     * 1) raises the concurrency.
+     */
+    singleton?: SingletonConfig;
+    /**
+     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
+     * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
+     * runs that get stuck or loop forever. Omit for no limit.
+     */
+    executionTimeout?: string | number;
+    /**
+     * Validate the workflow input at `start` against a **class-validator DTO** (the same
+     * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
+     * run is created. Needs the optional peers `class-validator` + `class-transformer`.
+     * `@Workflow({ inputSchema: CheckoutInput })`.
+     */
+    inputSchema?: new (...args: any[]) => object;
+    /**
+     * Custom input validator (throws on invalid) — an escape hatch for zod/yup/etc. instead of
+     * `inputSchema`. Takes precedence over `inputSchema` if both are set.
+     */
+    validateInput?: (input: unknown) => void | Promise<void>;
+    /**
+     * Start a fresh run of this workflow whenever any of these events is published via
+     * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
+     * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
+     * the `@OnEvent(...)` class decorator; the two are merged.
+     */
+    onEvent?: string[];
+    /**
+     * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
+     * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
+     */
+    debounce?: string | number;
+    /**
+     * Coalesce `onEvent` triggers by **batching** — start one run with all payloads (`{ events: [...] }`)
+     * once `maxSize` is reached or `within` elapses from the first event. e.g.
+     * `batch: { maxSize: 100, within: '10s' }`.
+     */
+    batch?: {
+        maxSize: number;
+        within: string | number;
+    };
+}
+/**
+ * Marks a provider class as a durable workflow. Its `run(ctx, input)` method becomes the
+ * workflow function the engine executes and replays.
+ */
+declare function Workflow(options: WorkflowOptions): ClassDecorator;
+declare function getWorkflowMeta(target: Function): WorkflowMeta | undefined;
+declare const DURABLE_STEP_METADATA: unique symbol;
+interface DurableStepMeta {
+    name: string;
+}
+/**
+ * Marks a provider method as the handler for a remote step `name`. An in-process transport
+ * (e.g. the event-emitter transport) routes dispatched tasks to it. The method's single
+ * argument is the step input; its return value is the step output.
+ */
+declare function DurableStep(name: string): MethodDecorator;
+declare function getDurableStepMeta(method: Function): DurableStepMeta | undefined;
+declare const DEAD_LETTER_METADATA: unique symbol;
+/**
+ * The payload a dead-letter handler receives: the dead run's id, its workflow, the input it was
+ * started with (typed via `TInput`), and the failure that killed it.
+ */
+interface DeadLetter<TInput = unknown> {
+    /** Id of the run that was dead-lettered (inspectable + retriable in the dashboard). */
+    deadRunId: string;
+    /** Name of the workflow whose run died. */
+    workflow: string;
+    /** The original input the dead run was started with. */
+    input: TInput;
+    /** The structured error that moved the run to `dead`, when known. */
+    error?: StepError;
+}
+/**
+ * Marks a method on a `@Workflow` class as that workflow's **inline dead-letter handler**. When a
+ * run of the workflow is moved to `dead` (exceeded `maxRecoveryAttempts`), this method runs — as a
+ * durable workflow itself, auto-registered as `<workflow>.dlq` with a `dlq:<runId>` id — receiving a
+ * {@link DeadLetter} payload. It shares the class's injected dependencies, so the handler lives in
+ * the same file as the workflow it protects.
+ *
+ * Takes precedence over `@Workflow({ deadLetterWorkflow })` and the module-level `deadLetterWorkflow`
+ * default. The method signature is `(ctx, dead)` — the same `ctx` a workflow `run` gets.
+ */
+declare function DeadLetter(): MethodDecorator;
+declare function isDeadLetterHandler(method: Function): boolean;
+declare const ON_EVENT_METADATA: unique symbol;
+/**
+ * Subscribe a `@Workflow` class to one or more events: when any of them is published via
+ * `publishEvent(name, payload)`, a fresh run of the workflow starts with the payload as input.
+ * Equivalent to `@Workflow({ onEvent })` — use whichever reads better; multiple `@OnEvent(...)`
+ * decorators and the option are all merged.
+ */
+declare function OnEvent(...events: string[]): ClassDecorator;
+/** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnEvent`. */
+declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
+
+interface DurableModuleOptions {
+    store: StateStore;
+    transport?: Transport;
+    /**
+     * An ordered pool of named transports for failover / multi-broker setups. The engine dispatches on
+     * the first and fails over to the next; a step pins one via `ctx.call(step, input, { transport })`.
+     * Use instead of `transport`.
+     */
+    transports?: NamedTransport[];
+    /**
+     * Cross-instance broadcast pub/sub (lifecycle events + cancellation). Defaults to the (first)
+     * transport when it can broadcast (event-emitter, BullMQ); set explicitly to use a dedicated one.
+     */
+    controlPlane?: ControlPlane;
+    /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. */
+    timerPollMs?: number;
+    /**
+     * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
+     * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
+     */
+    autoSchema?: boolean;
+    /**
+     * Multi-instance recovery lease, in ms — how long an instance owns a run it picked up before
+     * another may take over. Defaults to 30000. Set above your longest synchronous run.
+     */
+    leaseMs?: number;
+    /** Unique id for this instance (for leases). Defaults to a random id. */
+    instanceId?: string;
+    /**
+     * Cap recovery attempts before a still-`running` run is moved to the `dead` dead-letter state
+     * (a poison pill that crashes the process every boot). Omit for unlimited.
+     */
+    maxRecoveryAttempts?: number;
+    /**
+     * The **default** workflow to route dead-lettered runs to, for workflows that don't declare their
+     * own. When a run is moved to `dead` (exceeded `maxRecoveryAttempts`), the started handler gets a
+     * `DeadLetter` payload `{ deadRunId, workflow, input, error }` (idempotent by a `dlq:<runId>` id) —
+     * it can alert, compensate, or queue for review. Resolution per dead run: the workflow's inline
+     * `@DeadLetter()` method → its `@Workflow({ deadLetterWorkflow })` reference → this default. Omit
+     * everything to just leave dead runs parked (inspectable + retriable from the dashboard). Accepts a
+     * workflow class (refactor-safe) or a name (cross-runtime).
+     */
+    deadLetterWorkflow?: WorkflowRef;
+    /**
+     * Whether this instance plays the **worker** role: register `@DurableStep` handlers (consume the
+     * transport), recover incomplete runs on boot, and poll due timers. Defaults to `true`. Set
+     * `false` for a **dashboard/dispatch-only** instance (e.g. an API pod) that mounts the control
+     * plane and reads the store but must not process or recover workflows — leave that to the workers.
+     */
+    worker?: boolean;
+    /** Max ms to wait for in-flight runs on shutdown before exiting. Defaults to 10000. */
+    shutdownTimeoutMs?: number;
+    /**
+     * Recurring workflows to start on a schedule (fixed interval or cron). The timer poller fires
+     * them each tick on **worker** instances only; `engine.start` is idempotent by the schedule's
+     * time-bucket run id, so racing instances start each window exactly once. Cron schedules need the
+     * optional `cron-parser` peer dependency.
+     */
+    schedules?: ScheduledWorkflow[];
+    /**
+     * Build the public callback URL for a `ctx.webhook()` token, e.g.
+     * ``(t) => `https://api.example.com/durable/api/webhooks/${t}` ``. Populates `DurableWebhook.url`
+     * so a step can hand the URL to a third party. The dashboard's `POST webhooks/:token` receives the
+     * callback. Omit to build URLs yourself from the token.
+     */
+    webhookUrl?: (token: string) => string;
+    /**
+     * Flow-control queues for remote steps, registered on the engine at startup. Reference one from a
+     * workflow with `ctx.call(step, input, { queue: name })` to cap its concurrency / admission rate.
+     */
+    queues?: QueueConfig[];
+    /**
+     * Admission backend for the flow-control `queues`. Defaults to in-process (per-instance) caps. Pass
+     * a `RedisAdmissionBackend` (from `@dudousxd/nestjs-durable-admission-redis`) to make concurrency /
+     * rate-limit / priority ordering GLOBAL across every engine replica.
+     */
+    admission?: AdmissionBackend;
+    /**
+     * Provide the current W3C `traceparent` to stamp on dispatched remote tasks, so workers continue
+     * the distributed trace. Pass `otelTraceparent` from `@dudousxd/nestjs-durable-otel`.
+     */
+    traceparent?: () => string | undefined;
+    /**
+     * Provide an opaque context carrier (tenant / user / correlation ids) to stamp on dispatched remote
+     * tasks, so workers re-expose it to the step handler alongside the `traceparent`. The engine never
+     * inspects its shape.
+     *
+     * **Auto-feed**: if you omit this AND `@dudousxd/nestjs-context` is installed (its accessor is bound
+     * to the shared `CONTEXT_ACCESSOR` token), DurableModule defaults this to a reader that builds
+     * `{ traceId, tenantId, userRef }` from the accessor — so a workflow dispatched within a request
+     * automatically carries the originating context across process boundaries. Pass your own reader to
+     * override the auto-feed; with neither, the carrier is omitted (unchanged behavior).
+     *
+     * Re-evaluated at each (re)dispatch — including a retry or a crash/scale-down resume that the engine
+     * drives OUTSIDE the originating request scope, where this reader may return empty or stale values.
+     * Treat the carrier as best-effort correlation/propagation metadata only — do NOT treat it as an
+     * authorization boundary.
+     */
+    context?: () => Record<string, unknown> | undefined;
+    /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos. */
+    compensationRetries?: number;
+}
+interface DurableModuleAsyncOptions {
+    useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
+    inject?: InjectionToken[];
+}
+declare class DurableModule {
+    static forRoot(options: DurableModuleOptions): DynamicModule;
+    static forRootAsync(options: DurableModuleAsyncOptions): DynamicModule;
+    private static build;
+}
+
+declare const ENTITY_METADATA: unique symbol;
+declare const ENTITY_ON_METADATA: unique symbol;
+/**
+ * Marks an `@Injectable()` class as a **durable entity** (a virtual object): its `@On(op)` methods run
+ * serialized per key over the instance's fields as durable state. e.g.
+ *
+ * ```ts
+ * @Entity({ name: 'cart' }) @Injectable()
+ * class Cart { items: Item[] = []; @On('add') add(i: Item) { this.items.push(i); } @On('list') list() { return this.items; } }
+ * ```
+ *
+ * The class must be **constructible with no arguments** (a fresh instance is the initial state per key)
+ * — keep entities pure state, no DI. Drive them with `EntityService` or `ctx.signalEntity`/`callEntity`.
+ */
+declare function Entity(options: {
+    name: string;
+}): ClassDecorator;
+/** Marks an entity method as the handler for operation `op`. */
+declare function On(op: string): MethodDecorator;
+declare function getEntityMeta(target: Function): {
+    name: string;
+} | undefined;
+/**
+ * Build the engine `EntityConfig` for a discovered `@Entity` class: a fresh instance per key, and
+ * handlers that rehydrate the class prototype onto the (serialized) state before dispatching the op,
+ * so methods work after replay.
+ */
+declare function entityConfigFor(ctor: Function): {
+    initialState: () => object;
+    handlers: Record<string, EntityHandler>;
+};
+/** Inject this to drive durable entities from outside a workflow. */
+declare class EntityService {
+    private readonly engine;
+    constructor(engine: WorkflowEngine);
+    /** Send an operation to an entity (fire-and-forget; ordered + exactly-once per key). */
+    signal(name: string, key: string, op: string, arg?: unknown): Promise<void>;
+    /** Read an entity's current durable state (or undefined if it has none yet). */
+    getState<S = unknown>(name: string, key: string): Promise<S | undefined>;
+}
+
+declare const STEP_INTERCEPTOR_METADATA: unique symbol;
+/**
+ * The shape a `@StepInterceptor()` provider must implement: `intercept(invocation, next)` wraps the
+ * real execution of every local `ctx.step` (call `next()` to run the step body / next interceptor,
+ * and return — or transform — its result). The engine-level {@link StepInterceptor} primitive, with
+ * NestJS dependency injection.
+ */
+interface DurableStepInterceptor {
+    intercept(invocation: StepInvocation, next: () => Promise<unknown>): Promise<unknown>;
+}
+/**
+ * Marks an `@Injectable()` class as a durable step interceptor. The module discovers it on boot and
+ * registers its `intercept` method with the engine (so it can inject loggers/tracers/etc.). First
+ * declared is outermost. Interceptors fire only when a step actually executes, never on replay.
+ */
+declare function StepInterceptor(): ClassDecorator;
+declare function isStepInterceptor(target: Function): boolean;
+
+/**
+ * Cross-lib injection token for the current-request context accessor, owned by
+ * `@dudousxd/nestjs-context`. We do NOT import nestjs-context (it is an OPTIONAL
+ * peer dependency) — instead we share its well-known token by value so DI
+ * resolves the same provider when nestjs-context is installed and present.
+ *
+ * `Symbol.for(key)` uses the global symbol registry, so this resolves to the
+ * SAME symbol instance as nestjs-context's `tokens.ts` (and the identical token
+ * declared by `@dudousxd/nestjs-authz`) without any import. The key MUST stay
+ * byte-identical with nestjs-context's export.
+ */
+declare const CONTEXT_ACCESSOR: unique symbol;
+
+/** Public entry point for starting and resuming workflow runs. */
+declare class WorkflowService {
+    private readonly engine;
+    constructor(engine: WorkflowEngine);
+    /**
+     * Enqueue a workflow run — it creates the run (`pending`) and returns `{ runId, status: 'pending' }`
+     * immediately; a worker executes the body (so the caller never blocks on workflow logic). Use
+     * {@link waitForRun} when you need the outcome. Pass the workflow's **class**
+     * (`start(CheckoutWorkflow, input)`) for a typed input + refactor-safety, or a **name** string for a
+     * cross-runtime workflow. `runId` defaults to a random id; pass your own to make the start idempotent
+     * (a redelivery returns the existing run). `opts.tags` are merged with the workflow's static
+     * `@Workflow({ tags })`; `opts.searchAttributes` stamp typed, queryable run data.
+     */
+    start<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, runId?: string, opts?: StartOptions): Promise<RunResult>;
+    start(workflow: string, input: unknown, runId?: string, opts?: StartOptions): Promise<RunResult>;
+    resume(runId: string): Promise<RunResult>;
+    /**
+     * Resolve once a run settles — terminal (completed/failed/cancelled/dead) or suspended. `start`
+     * only enqueues (a worker runs the body), so pair them when a request needs the outcome:
+     * `const { runId } = await svc.start(...); const result = await svc.waitForRun(runId)`.
+     */
+    waitForRun(runId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+    /** Deliver an external signal (e.g. from a webhook) to the run waiting on `token`. */
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
+    /**
+     * Ensure a run exists for `runId`, then deliver a signal to it — race-free (the signal is buffered
+     * until the run reaches its `waitForSignal`). The durable-entity / accumulator pattern: one
+     * long-lived run per key fed events by many calls. See {@link WorkflowEngine.signalWithStart}.
+     */
+    signalWithStart<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }, opts?: StartOptions): Promise<{
+        runId: string;
+    }>;
+    signalWithStart(workflow: string, input: unknown, runId: string, signal: {
+        token: string;
+        payload?: unknown;
+    }, opts?: StartOptions): Promise<{
+        runId: string;
+    }>;
+    /**
+     * Publish a named event. Resumes runs waiting on it via `ctx.waitForEvent(name, { match })` and
+     * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnEvent` (the
+     * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
+     * touched (resumed + started).
+     */
+    publishEvent(name: string, payload: unknown, opts?: {
+        id?: string;
+    }): Promise<number>;
+}
+
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, ON_EVENT_METADATA, On, OnEvent, STEP_INTERCEPTOR_METADATA, StepInterceptor, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, isDeadLetterHandler, isStepInterceptor };