@dudousxd/nestjs-durable 0.24.0 → 0.26.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { StepError, WorkflowRef, SingletonConfig, WorkflowExecutor, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
-import { RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
+import { ConcurrencyOption, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -138,7 +138,12 @@ interface DurableStepMeta {
  * (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 Step(name: string): MethodDecorator;
+/**
+ * @deprecated Use `@Step` instead. `@DurableStep` is a back-compat alias of {@link Step} and
+ * writes the same `DURABLE_STEP_METADATA`, so discovery/registrars treat them identically.
+ */
+declare const DurableStep: typeof Step;
 declare function getDurableStepMeta(method: Function): DurableStepMeta | undefined;
 declare const DEAD_LETTER_METADATA: unique symbol;
 /**
@@ -181,7 +186,7 @@ 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`
+ * dashboard, recovery, or timer config — a thin worker only registers `@Workflow`/`@Step`
  * handlers and runs the BullMQ consumer (see {@link DurableWorkerModule}).
  */
 interface DurableWorkerModuleOptions {
@@ -193,6 +198,18 @@ interface DurableWorkerModuleOptions {
     prefix?: string;
     /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
     instanceId?: string;
+    /**
+     * How many tasks each group's consumer runs concurrently (BullMQ Worker concurrency). Defaults to 1.
+     * Applies to every group unless overridden per-group by {@link concurrencyByGroup}. Raise it so a
+     * fanned-out batch (e.g. the N remote steps of a `gather`) runs in parallel instead of serially.
+     *
+     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let each consumer self-tune its concurrency
+     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
+     */
+    concurrency?: ConcurrencyOption;
+    /** Per-group concurrency override, keyed by group name. Falls back to {@link concurrency} (then 1).
+     *  Each value may itself be `'adaptive'` / `{ mode:'adaptive', ... }`. */
+    concurrencyByGroup?: Record<string, ConcurrencyOption>;
 }
 interface DurableWorkerModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableWorkerModuleOptions | Promise<DurableWorkerModuleOptions>;
@@ -223,7 +240,7 @@ declare class ThinWorkflowRegistrar implements OnModuleInit {
     onModuleInit(): void;
 }
 /**
- * Discovers every `@DurableStep` method and registers it as a step handler on the thin
+ * Discovers every `@Step` 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).
  */
@@ -254,7 +271,7 @@ declare class ThinWorkerBootstrap implements OnApplicationBootstrap, OnApplicati
 }
 /**
  * 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
+ * `@Workflow`/`@Step` 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.
@@ -270,7 +287,7 @@ declare class DurableWorkerModule {
 
 /**
  * Opt-in config for an **in-app worker**: the same NestJS process runs the engine AND serves its own
- * discovered `@Workflow`/`@DurableStep` on one default `group`. The engine registers each `@Workflow`
+ * discovered `@Workflow`/`@Step` on one default `group`. The engine registers each `@Workflow`
  * GROUP-SERVED (its turns are dispatched to `group` over the transport via a {@link RemoteWorkflowExecutor}
  * instead of run inline), and a co-located {@link DurableWorkerRuntime} consumes `group` and replays the
  * very same TS bodies. This is the uniform-dispatch "one app, both roles" shape — every turn pays a
@@ -286,6 +303,15 @@ interface DurableInAppWorkerOptions {
     prefix?: string;
     /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
     instanceId?: string;
+    /**
+     * How many tasks the co-located worker runs concurrently from its group's queue (BullMQ Worker
+     * concurrency). Defaults to 1. Raise it so a fanned-out batch (e.g. the N remote steps of a
+     * `gather`) runs in parallel. Per process; total parallelism is `concurrency × replicas`.
+     *
+     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let the worker self-tune its concurrency
+     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
+     */
+    concurrency?: ConcurrencyOption;
 }
 /** The resolved {@link DurableInAppWorkerOptions} or `null` when the app didn't opt in. */
 declare const IN_APP_WORKER_OPTIONS: unique symbol;
@@ -309,7 +335,7 @@ interface InAppWorkerBinding {
     executor: WorkflowExecutor;
 }
 /**
- * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@DurableStep`
+ * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@Step`
  * on a {@link DurableWorkerRuntime} (the SAME bodies the engine registered group-served), and on bootstrap
  * it starts one `runRedisWorker` consumer on the configured group, closing it on shutdown. A no-op when
  * the app didn't opt in. Mirrors the thin {@link import('./durable-worker.module').DurableWorkerModule},
@@ -419,7 +445,7 @@ interface DurableModuleOptions {
      */
     deadLetterWorkflow?: WorkflowRef;
     /**
-     * Whether this instance plays the **worker** role: register `@DurableStep` handlers (consume the
+     * Whether this instance plays the **worker** role: register `@Step` 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.
@@ -486,7 +512,7 @@ interface DurableModuleOptions {
     compensationRetries?: number;
     /**
      * Opt into an **in-app worker** (uniform dispatch): the same process runs the engine AND serves its
-     * own discovered `@Workflow`/`@DurableStep` on one default `group`. Each `@Workflow` is registered
+     * own discovered `@Workflow`/`@Step` on one default `group`. Each `@Workflow` is registered
      * GROUP-SERVED — its turns are dispatched to `group` over the transport and replayed by a co-located
      * worker consumer — instead of run inline. Requires a workflow-task transport (BullMQ). Omit (the
      * default) to keep every `@Workflow` on the inline fast path with zero dispatch round-trips. See
@@ -630,4 +656,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, type DurableInAppWorkerOptions, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_OPTIONS, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, 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, inAppWorkerProviders, isDeadLetterHandler, isStepInterceptor };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, type DurableInAppWorkerOptions, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_OPTIONS, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnEvent, RUN_REDIS_WORKER, type RunRedisWorkerFn, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isStepInterceptor };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { StepError, WorkflowRef, SingletonConfig, WorkflowExecutor, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
-import { RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
+import { ConcurrencyOption, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -138,7 +138,12 @@ interface DurableStepMeta {
  * (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 Step(name: string): MethodDecorator;
+/**
+ * @deprecated Use `@Step` instead. `@DurableStep` is a back-compat alias of {@link Step} and
+ * writes the same `DURABLE_STEP_METADATA`, so discovery/registrars treat them identically.
+ */
+declare const DurableStep: typeof Step;
 declare function getDurableStepMeta(method: Function): DurableStepMeta | undefined;
 declare const DEAD_LETTER_METADATA: unique symbol;
 /**
@@ -181,7 +186,7 @@ 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`
+ * dashboard, recovery, or timer config — a thin worker only registers `@Workflow`/`@Step`
  * handlers and runs the BullMQ consumer (see {@link DurableWorkerModule}).
  */
 interface DurableWorkerModuleOptions {
@@ -193,6 +198,18 @@ interface DurableWorkerModuleOptions {
     prefix?: string;
     /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
     instanceId?: string;
+    /**
+     * How many tasks each group's consumer runs concurrently (BullMQ Worker concurrency). Defaults to 1.
+     * Applies to every group unless overridden per-group by {@link concurrencyByGroup}. Raise it so a
+     * fanned-out batch (e.g. the N remote steps of a `gather`) runs in parallel instead of serially.
+     *
+     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let each consumer self-tune its concurrency
+     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
+     */
+    concurrency?: ConcurrencyOption;
+    /** Per-group concurrency override, keyed by group name. Falls back to {@link concurrency} (then 1).
+     *  Each value may itself be `'adaptive'` / `{ mode:'adaptive', ... }`. */
+    concurrencyByGroup?: Record<string, ConcurrencyOption>;
 }
 interface DurableWorkerModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableWorkerModuleOptions | Promise<DurableWorkerModuleOptions>;
@@ -223,7 +240,7 @@ declare class ThinWorkflowRegistrar implements OnModuleInit {
     onModuleInit(): void;
 }
 /**
- * Discovers every `@DurableStep` method and registers it as a step handler on the thin
+ * Discovers every `@Step` 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).
  */
@@ -254,7 +271,7 @@ declare class ThinWorkerBootstrap implements OnApplicationBootstrap, OnApplicati
 }
 /**
  * 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
+ * `@Workflow`/`@Step` 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.
@@ -270,7 +287,7 @@ declare class DurableWorkerModule {
 
 /**
  * Opt-in config for an **in-app worker**: the same NestJS process runs the engine AND serves its own
- * discovered `@Workflow`/`@DurableStep` on one default `group`. The engine registers each `@Workflow`
+ * discovered `@Workflow`/`@Step` on one default `group`. The engine registers each `@Workflow`
  * GROUP-SERVED (its turns are dispatched to `group` over the transport via a {@link RemoteWorkflowExecutor}
  * instead of run inline), and a co-located {@link DurableWorkerRuntime} consumes `group` and replays the
  * very same TS bodies. This is the uniform-dispatch "one app, both roles" shape — every turn pays a
@@ -286,6 +303,15 @@ interface DurableInAppWorkerOptions {
     prefix?: string;
     /** Stable id for this worker process in heartbeats/control. Defaults to a per-host/pid id. */
     instanceId?: string;
+    /**
+     * How many tasks the co-located worker runs concurrently from its group's queue (BullMQ Worker
+     * concurrency). Defaults to 1. Raise it so a fanned-out batch (e.g. the N remote steps of a
+     * `gather`) runs in parallel. Per process; total parallelism is `concurrency × replicas`.
+     *
+     * Pass `'adaptive'` (or `{ mode:'adaptive', ... }`) to let the worker self-tune its concurrency
+     * (latency gradient + RAM brake + backpressure) and publish a live status on its heartbeat.
+     */
+    concurrency?: ConcurrencyOption;
 }
 /** The resolved {@link DurableInAppWorkerOptions} or `null` when the app didn't opt in. */
 declare const IN_APP_WORKER_OPTIONS: unique symbol;
@@ -309,7 +335,7 @@ interface InAppWorkerBinding {
     executor: WorkflowExecutor;
 }
 /**
- * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@DurableStep`
+ * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@Step`
  * on a {@link DurableWorkerRuntime} (the SAME bodies the engine registered group-served), and on bootstrap
  * it starts one `runRedisWorker` consumer on the configured group, closing it on shutdown. A no-op when
  * the app didn't opt in. Mirrors the thin {@link import('./durable-worker.module').DurableWorkerModule},
@@ -419,7 +445,7 @@ interface DurableModuleOptions {
      */
     deadLetterWorkflow?: WorkflowRef;
     /**
-     * Whether this instance plays the **worker** role: register `@DurableStep` handlers (consume the
+     * Whether this instance plays the **worker** role: register `@Step` 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.
@@ -486,7 +512,7 @@ interface DurableModuleOptions {
     compensationRetries?: number;
     /**
      * Opt into an **in-app worker** (uniform dispatch): the same process runs the engine AND serves its
-     * own discovered `@Workflow`/`@DurableStep` on one default `group`. Each `@Workflow` is registered
+     * own discovered `@Workflow`/`@Step` on one default `group`. Each `@Workflow` is registered
      * GROUP-SERVED — its turns are dispatched to `group` over the transport and replayed by a co-located
      * worker consumer — instead of run inline. Requires a workflow-task transport (BullMQ). Omit (the
      * default) to keep every `@Workflow` on the inline fast path with zero dispatch round-trips. See
@@ -630,4 +656,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, type DurableInAppWorkerOptions, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_OPTIONS, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, 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, inAppWorkerProviders, isDeadLetterHandler, isStepInterceptor };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_OPTIONS, DURABLE_WORKER_RUNNERS, DeadLetter, type DurableInAppWorkerOptions, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStep, type DurableStepInterceptor, type DurableStepMeta, DurableWorkerModule, type DurableWorkerModuleAsyncOptions, type DurableWorkerModuleOptions, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_OPTIONS, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnEvent, RUN_REDIS_WORKER, type RunRedisWorkerFn, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isStepInterceptor };

package/dist/index.js

@@ -39,7 +39,7 @@ function getWorkflowMeta(target) {
 }
 __name(getWorkflowMeta, "getWorkflowMeta");
 var DURABLE_STEP_METADATA = Symbol("nestjs-durable:step-handler");
-function DurableStep(name) {
+function Step(name) {
   return (_target, _propertyKey, descriptor) => {
     const meta = {
       name
@@ -48,7 +48,8 @@ function DurableStep(name) {
     return descriptor;
   };
 }
-__name(DurableStep, "DurableStep");
+__name(Step, "Step");
+var DurableStep = Step;
 function getDurableStepMeta(method) {
   return Reflect.getMetadata(DURABLE_STEP_METADATA, method);
 }
@@ -218,6 +219,9 @@ var ThinWorkerBootstrap = class {
         } : {},
         ...this.options.instanceId !== void 0 ? {
           instanceId: this.options.instanceId
+        } : {},
+        ...(this.options.concurrencyByGroup?.[group] ?? this.options.concurrency) !== void 0 ? {
+          concurrency: this.options.concurrencyByGroup?.[group] ?? this.options.concurrency
         } : {}
       });
       this.runners.push(handle);
@@ -508,6 +512,9 @@ var InAppWorkerBootstrap = class {
       } : {},
       ...this.options.instanceId !== void 0 ? {
         instanceId: this.options.instanceId
+      } : {},
+      ...this.options.concurrency !== void 0 ? {
+        concurrency: this.options.concurrency
       } : {}
     });
     this.runners.push(handle);
@@ -1205,6 +1212,7 @@ export {
   OnEvent,
   RUN_REDIS_WORKER,
   STEP_INTERCEPTOR_METADATA,
+  Step,
   StepInterceptor,
   ThinStepRegistrar,
   ThinWorkerBootstrap,