@dudousxd/nestjs-durable 0.18.1 → 0.20.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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';
+import { RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
+import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
 /**
  * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
@@ -176,6 +178,96 @@ 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[];
 
+/**
+ * Options for a **store-less thin worker** process: where to consume (`connection`/`prefix`) and
+ * which worker `groups` this process serves. There is deliberately NO `store`, `transport`, engine,
+ * dashboard, recovery, or timer config — a thin worker only registers `@Workflow`/`@DurableStep`
+ * handlers and runs the BullMQ consumer (see {@link DurableWorkerModule}).
+ */
+interface DurableWorkerModuleOptions {
+    /** ioredis connection (string or options), as `runRedisWorker` / `BullMQTransport` accept. */
+    connection: string | Record<string, unknown>;
+    /** The worker groups this process serves — one BullMQ consumer is started per group. */
+    groups: string[];
+    /** Key prefix namespacing the durable queues. Defaults to `durable` (matches the transport). */
+    prefix?: string;
+    /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
+    instanceId?: string;
+}
+interface DurableWorkerModuleAsyncOptions {
+    useFactory: (...args: never[]) => DurableWorkerModuleOptions | Promise<DurableWorkerModuleOptions>;
+    inject?: InjectionToken[];
+}
+/** The resolved {@link DurableWorkerModuleOptions} (canonical token). */
+declare const DURABLE_WORKER_OPTIONS: unique symbol;
+/**
+ * The `runRedisWorker` function the module uses to start each group's BullMQ consumer. Defaults to
+ * the real one from `@dudousxd/durable-worker`; tests `overrideProvider` it with a fake so no real
+ * Redis is needed.
+ */
+declare const RUN_REDIS_WORKER: unique symbol;
+/** The list of started {@link RunningWorker} handles (one per group), closed on shutdown. */
+declare const DURABLE_WORKER_RUNNERS: unique symbol;
+/** The signature of `runRedisWorker` — injected behind {@link RUN_REDIS_WORKER}. */
+type RunRedisWorkerFn = (opts: RunRedisWorkerOptions) => Promise<RunningWorker>;
+/**
+ * Discovers every provider carrying `@Workflow` metadata and registers its `run(ctx, input)` on the
+ * thin {@link DurableWorkerRuntime}. Mirrors the engine-side `WorkflowRegistrar`, but registers on
+ * the runner-core runtime instead of a `WorkflowEngine` — the runtime drives `run` with the thin
+ * `WorkflowContext` (which `implements WorkflowCtx`), so the body runs unchanged. NO store/engine.
+ */
+declare class ThinWorkflowRegistrar implements OnModuleInit {
+    private readonly discovery;
+    private readonly runtime;
+    constructor(discovery: DiscoveryService, runtime: DurableWorkerRuntime);
+    onModuleInit(): void;
+}
+/**
+ * Discovers every `@DurableStep` method and registers it as a step handler on the thin
+ * {@link DurableWorkerRuntime}. Mirrors the engine-side `DurableStepRegistrar`, but always registers
+ * on the runtime (a thin worker IS the consumer — there is no in-process-vs-queue branch).
+ */
+declare class ThinStepRegistrar implements OnModuleInit {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly runtime;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, runtime: DurableWorkerRuntime);
+    onModuleInit(): void;
+}
+/**
+ * Starts one BullMQ consumer per configured group on bootstrap (after both registrars have run, so
+ * every handler is registered before any task is consumed) and closes them on shutdown. The only
+ * runtime side effect of a thin worker: register handlers, run the consumer. No engine, no store,
+ * no recovery, no timers, no dispatch.
+ *
+ * For the shutdown close to fire, enable Nest's shutdown hooks: `app.enableShutdownHooks()`.
+ */
+declare class ThinWorkerBootstrap implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly runtime;
+    private readonly options;
+    private readonly runRedisWorker;
+    private readonly runnersSink;
+    private readonly runners;
+    constructor(runtime: DurableWorkerRuntime, options: DurableWorkerModuleOptions, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+/**
+ * A NestJS dynamic module that turns an app into a **PURE durable worker**: it discovers
+ * `@Workflow`/`@DurableStep` providers, registers them on the thin {@link DurableWorkerRuntime}, and
+ * runs one BullMQ consumer per group via `runRedisWorker`. It is **control-plane-less** — it binds
+ * NO `WorkflowEngine`, NO store/ORM, NO dashboard, NO timer poller, NO recovery, and NO run dispatch.
+ * Use it for a worker pod that only executes work an engine elsewhere coordinates.
+ *
+ * Contrast with `DurableModule` (`worker: true`), which is a full control plane WITH a store: this
+ * module is the store-less half. A workflow body runs identically on either (conformance-tested).
+ */
+declare class DurableWorkerModule {
+    static forRoot(options: DurableWorkerModuleOptions): DynamicModule;
+    static forRootAsync(options: DurableWorkerModuleAsyncOptions): DynamicModule;
+    private static build;
+}
+
 interface DurableModuleOptions {
     store: StateStore;
     transport?: Transport;
@@ -209,6 +301,14 @@ interface DurableModuleOptions {
      * (a poison pill that crashes the process every boot). Omit for unlimited.
      */
     maxRecoveryAttempts?: number;
+    /**
+     * Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
+     * returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
+     * and lets recovery re-drive; each heartbeat rearms the window so a slow-but-alive worker is never
+     * re-driven. Pair with a worker SDK that emits run-scoped heartbeats (`@dudousxd/durable-worker` ≥ the
+     * release that ships them, and the Python `durable-worker`). Omit for the prior unbounded await.
+     */
+    remoteAdvanceSilenceMs?: 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
@@ -414,4 +514,4 @@ declare class WorkflowService {
     }): 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 };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, ON_EVENT_METADATA, On, OnEvent, RUN_REDIS_WORKER, type RunRedisWorkerFn, STEP_INTERCEPTOR_METADATA, StepInterceptor, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, isDeadLetterHandler, isStepInterceptor };