@dudousxd/nestjs-durable 0.22.1 → 0.24.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
+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 { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
 /**
@@ -268,6 +268,73 @@ declare class DurableWorkerModule {
     private static build;
 }
 
+/**
+ * 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`
+ * 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
+ * transport round-trip even though the worker is the same process. Requires a transport that carries
+ * workflow tasks (BullMQ); an in-process-only transport cannot dispatch a {@link WorkflowExecutor}.
+ */
+interface DurableInAppWorkerOptions {
+    /** The default group this app dispatches its `@Workflow` turns to AND consumes as a worker. */
+    group: string;
+    /** ioredis connection (string or options) for the co-located worker consumer (`runRedisWorker`). */
+    connection: string | Record<string, unknown>;
+    /** 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;
+}
+/** The resolved {@link DurableInAppWorkerOptions} or `null` when the app didn't opt in. */
+declare const IN_APP_WORKER_OPTIONS: unique symbol;
+/**
+ * The group-served binding the {@link import('./workflow.registrar').WorkflowRegistrar} applies to every
+ * discovered `@Workflow`: `{ group, executor }` when the app opted into an in-app worker, else `null`
+ * (workflows register inline — the unchanged default). The executor is a {@link RemoteWorkflowExecutor}
+ * over the engine's own transport, so a group-served turn is dispatched to `group` and the co-located
+ * worker (below) advances it.
+ */
+declare const IN_APP_WORKER_BINDING: unique symbol;
+/** The co-located worker's {@link DurableWorkerRuntime} (the consumer half). */
+declare const IN_APP_WORKER_RUNTIME: unique symbol;
+/** `runRedisWorker`, injected so tests can substitute a fake (no real Redis). Defaults to the real one. */
+declare const IN_APP_RUN_REDIS_WORKER: unique symbol;
+/** Started {@link RunningWorker} handles for the in-app group(s), closed on shutdown. */
+declare const IN_APP_WORKER_RUNNERS: unique symbol;
+/** The group-served binding shape resolved behind {@link IN_APP_WORKER_BINDING}. */
+interface InAppWorkerBinding {
+    group: string;
+    executor: WorkflowExecutor;
+}
+/**
+ * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@DurableStep`
+ * 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},
+ * but co-located with a full engine.
+ */
+declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly options;
+    private readonly runtime;
+    private readonly runRedisWorker;
+    private readonly runnersSink;
+    private readonly runners;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, options: DurableInAppWorkerOptions | null, runtime: DurableWorkerRuntime, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
+    onModuleInit(): void;
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+/**
+ * The providers that stand up an in-app worker, added to {@link import('./durable.module').DurableModule}.
+ * All are inert when `inAppWorker` is unset (the binding resolves to `null`, the bootstrap no-ops), so a
+ * plain `DurableModule` is byte-for-byte unchanged.
+ */
+declare function inAppWorkerProviders(): Provider[];
+
 /**
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
  * (status sets must be disjoint — validated at boot), swept together on a shared interval.
@@ -315,6 +382,12 @@ interface DurableModuleOptions {
      * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
      */
     autoSchema?: boolean;
+    /**
+     * Worker-pool partition for this instance (forwarded to the engine). Default `'default'`. Set a
+     * distinct value to share ONE state store across non-interchangeable pools — e.g. a developer's
+     * local instance vs the deployed cluster. See `WorkflowEngineDeps.namespace`.
+     */
+    namespace?: string;
     /**
      * 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.
@@ -411,6 +484,15 @@ interface DurableModuleOptions {
     context?: () => Record<string, unknown> | undefined;
     /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos. */
     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
+     * 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
+     * {@link DurableInAppWorkerOptions}.
+     */
+    inAppWorker?: DurableInAppWorkerOptions;
 }
 interface DurableModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
@@ -548,4 +630,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, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, 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 };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowEngine, EntityHandler, StepInvocation, WorkflowClass, WorkflowInputOf, StartOptions, RunResult } from '@dudousxd/nestjs-durable-core';
+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 { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
 /**
@@ -268,6 +268,73 @@ declare class DurableWorkerModule {
     private static build;
 }
 
+/**
+ * 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`
+ * 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
+ * transport round-trip even though the worker is the same process. Requires a transport that carries
+ * workflow tasks (BullMQ); an in-process-only transport cannot dispatch a {@link WorkflowExecutor}.
+ */
+interface DurableInAppWorkerOptions {
+    /** The default group this app dispatches its `@Workflow` turns to AND consumes as a worker. */
+    group: string;
+    /** ioredis connection (string or options) for the co-located worker consumer (`runRedisWorker`). */
+    connection: string | Record<string, unknown>;
+    /** 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;
+}
+/** The resolved {@link DurableInAppWorkerOptions} or `null` when the app didn't opt in. */
+declare const IN_APP_WORKER_OPTIONS: unique symbol;
+/**
+ * The group-served binding the {@link import('./workflow.registrar').WorkflowRegistrar} applies to every
+ * discovered `@Workflow`: `{ group, executor }` when the app opted into an in-app worker, else `null`
+ * (workflows register inline — the unchanged default). The executor is a {@link RemoteWorkflowExecutor}
+ * over the engine's own transport, so a group-served turn is dispatched to `group` and the co-located
+ * worker (below) advances it.
+ */
+declare const IN_APP_WORKER_BINDING: unique symbol;
+/** The co-located worker's {@link DurableWorkerRuntime} (the consumer half). */
+declare const IN_APP_WORKER_RUNTIME: unique symbol;
+/** `runRedisWorker`, injected so tests can substitute a fake (no real Redis). Defaults to the real one. */
+declare const IN_APP_RUN_REDIS_WORKER: unique symbol;
+/** Started {@link RunningWorker} handles for the in-app group(s), closed on shutdown. */
+declare const IN_APP_WORKER_RUNNERS: unique symbol;
+/** The group-served binding shape resolved behind {@link IN_APP_WORKER_BINDING}. */
+interface InAppWorkerBinding {
+    group: string;
+    executor: WorkflowExecutor;
+}
+/**
+ * The consumer half of the in-app worker: on init it registers every discovered `@Workflow`/`@DurableStep`
+ * 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},
+ * but co-located with a full engine.
+ */
+declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly options;
+    private readonly runtime;
+    private readonly runRedisWorker;
+    private readonly runnersSink;
+    private readonly runners;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, options: DurableInAppWorkerOptions | null, runtime: DurableWorkerRuntime, runRedisWorker: RunRedisWorkerFn, runnersSink: RunningWorker[]);
+    onModuleInit(): void;
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+/**
+ * The providers that stand up an in-app worker, added to {@link import('./durable.module').DurableModule}.
+ * All are inert when `inAppWorker` is unset (the binding resolves to `null`, the bootstrap no-ops), so a
+ * plain `DurableModule` is byte-for-byte unchanged.
+ */
+declare function inAppWorkerProviders(): Provider[];
+
 /**
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
  * (status sets must be disjoint — validated at boot), swept together on a shared interval.
@@ -315,6 +382,12 @@ interface DurableModuleOptions {
      * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
      */
     autoSchema?: boolean;
+    /**
+     * Worker-pool partition for this instance (forwarded to the engine). Default `'default'`. Set a
+     * distinct value to share ONE state store across non-interchangeable pools — e.g. a developer's
+     * local instance vs the deployed cluster. See `WorkflowEngineDeps.namespace`.
+     */
+    namespace?: string;
     /**
      * 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.
@@ -411,6 +484,15 @@ interface DurableModuleOptions {
     context?: () => Record<string, unknown> | undefined;
     /** Attempts for each saga compensation when a run fails. Default 1 (no retry). Idempotent undos. */
     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
+     * 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
+     * {@link DurableInAppWorkerOptions}.
+     */
+    inAppWorker?: DurableInAppWorkerOptions;
 }
 interface DurableModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
@@ -548,4 +630,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, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, 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 };
+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 };