@duraflows/nestjs 3.1.0 → 4.0.1

package/dist/cjs/filters/workflow-exception.filter.js

@@ -36,6 +36,14 @@ let WorkflowExceptionFilter = WorkflowExceptionFilter_1 = class WorkflowExceptio
             });
             return;
         }
+        if (exception instanceof core_1.InvalidArgumentError) {
+            response.status(common_1.HttpStatus.BAD_REQUEST).send({
+                statusCode: common_1.HttpStatus.BAD_REQUEST,
+                error: "Bad Request",
+                message: exception.message,
+            });
+            return;
+        }
         // The response body is sanitized, so log the real cause here — otherwise
         // unmapped domain errors (e.g. optimistic-locking conflicts under
         // concurrency) become undiagnosable silent 500s. `WorkflowError` wraps the

package/dist/cjs/providers/injection-tokens.d.ts

@@ -6,4 +6,11 @@ export declare const WORKFLOW_DEFINITION_REGISTRY: unique symbol;
 export declare const WORKFLOW_TRANSACTION_RUNNER: unique symbol;
 export declare const WORKFLOW_CLOCK: unique symbol;
 export declare const WORKFLOW_GUARD_REGISTRY: unique symbol;
+/**
+ * The resolved module configuration. Deliberately not re-exported from the
+ * package barrel: it exists so `forRoot` and `forRootAsync` can publish their
+ * config under one token and share a single provider graph, not as a supported
+ * extension point.
+ */
+export declare const WORKFLOW_MODULE_OPTIONS: unique symbol;
 //# sourceMappingURL=injection-tokens.d.ts.map

package/dist/cjs/providers/injection-tokens.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORKFLOW_GUARD_REGISTRY = exports.WORKFLOW_CLOCK = exports.WORKFLOW_TRANSACTION_RUNNER = exports.WORKFLOW_DEFINITION_REGISTRY = exports.WORKFLOW_COMMAND_REGISTRY = exports.WORKFLOW_HISTORY_STORE = exports.WORKFLOW_INSTANCE_STORE = exports.WORKFLOW_RUNTIME = void 0;
+exports.WORKFLOW_MODULE_OPTIONS = exports.WORKFLOW_GUARD_REGISTRY = exports.WORKFLOW_CLOCK = exports.WORKFLOW_TRANSACTION_RUNNER = exports.WORKFLOW_DEFINITION_REGISTRY = exports.WORKFLOW_COMMAND_REGISTRY = exports.WORKFLOW_HISTORY_STORE = exports.WORKFLOW_INSTANCE_STORE = exports.WORKFLOW_RUNTIME = void 0;
 exports.WORKFLOW_RUNTIME = Symbol("WORKFLOW_RUNTIME");
 exports.WORKFLOW_INSTANCE_STORE = Symbol("WORKFLOW_INSTANCE_STORE");
 exports.WORKFLOW_HISTORY_STORE = Symbol("WORKFLOW_HISTORY_STORE");
@@ -9,4 +9,11 @@ exports.WORKFLOW_DEFINITION_REGISTRY = Symbol("WORKFLOW_DEFINITION_REGISTRY");
 exports.WORKFLOW_TRANSACTION_RUNNER = Symbol("WORKFLOW_TRANSACTION_RUNNER");
 exports.WORKFLOW_CLOCK = Symbol("WORKFLOW_CLOCK");
 exports.WORKFLOW_GUARD_REGISTRY = Symbol("WORKFLOW_GUARD_REGISTRY");
+/**
+ * The resolved module configuration. Deliberately not re-exported from the
+ * package barrel: it exists so `forRoot` and `forRootAsync` can publish their
+ * config under one token and share a single provider graph, not as a supported
+ * extension point.
+ */
+exports.WORKFLOW_MODULE_OPTIONS = Symbol("WORKFLOW_MODULE_OPTIONS");
 //# sourceMappingURL=injection-tokens.js.map

package/dist/cjs/services/workflow.service.js

@@ -56,9 +56,9 @@ let WorkflowService = class WorkflowService {
      * upstream when the instance was created via `createInstanceFor`).
      */
     async triggerEventFor(definition, input) {
-        // `definition` is consumed at type-level only; the runtime resolves
-        // the instance by uuid and reads its workflowName from the live row.
-        void definition;
+        // `definition` is consumed at type level only -- it is what infers TState.
+        // The runtime resolves the instance by uuid and reads its workflowName from
+        // the live row, so there is nothing to do with the value at runtime.
         const result = await this.runtime.triggerEvent(input);
         return result;
     }

package/dist/cjs/workflow.module.js

@@ -38,227 +38,161 @@ const EXPORTED_TOKENS = [
     injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
     injection_tokens_js_1.WORKFLOW_CLOCK,
 ];
+const CONTROLLERS = [
+    workflow_instance_controller_js_1.WorkflowInstanceController,
+    workflow_event_controller_js_1.WorkflowEventController,
+    workflow_query_controller_js_1.WorkflowQueryController,
+    workflow_timeout_controller_js_1.WorkflowTimeoutController,
+];
+/**
+ * `guards` and `guardRegistry` are mutually exclusive: with a custom registry
+ * duraflows cannot enumerate guard names, so it can neither merge the array in
+ * nor validate definition refs against it.
+ *
+ * forRoot calls this eagerly, so the error surfaces at module definition.
+ * forRootAsync only learns its config once the factory resolves, so it calls
+ * this from inside the guard-registry provider instead. Same message, and each
+ * entry point keeps the failure timing it has always had.
+ */
+function assertGuardConfigExclusive(config) {
+    if (config.guardRegistry && config.guards && config.guards.length > 0) {
+        throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
+    }
+}
+/**
+ * The provider graph shared by both entry points. Every factory reads its
+ * configuration from WORKFLOW_MODULE_OPTIONS — supplied as a value by forRoot
+ * and as the caller's factory by forRootAsync — so the wiring downstream is
+ * identical and cannot drift between the sync and async paths.
+ */
+function buildWorkflowProviders(explicitCommands) {
+    return [
+        ...explicitCommands.map((c) => c.useClass),
+        {
+            provide: injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
+            useFactory: (moduleRef, discoveryService) => {
+                const discovered = (0, command_discovery_js_1.discoverDecoratedCommands)(discoveryService);
+                const merged = (0, command_discovery_js_1.mergeCommandRegistrations)(explicitCommands, discovered);
+                return new nest_command_registry_js_1.NestCommandRegistry(moduleRef, merged);
+            },
+            inject: [core_1.ModuleRef, core_1.DiscoveryService],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
+            useFactory: (config) => {
+                // Redundant on the forRoot path, which already threw at module
+                // definition, but this is forRootAsync's only opportunity to check.
+                assertGuardConfigExclusive(config);
+                if (config.guardRegistry)
+                    return config.guardRegistry;
+                const registry = new core_2.InMemoryGuardRegistry();
+                for (const guard of config.guards ?? []) {
+                    registry.register(guard.name, guard);
+                }
+                return registry;
+            },
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
+            useFactory: (config, commandRegistry) => {
+                const knownCommandNames = commandRegistry.getRegisteredNames();
+                // Validate guard refs only when we own the registry (built-in path).
+                // With a custom guardRegistry we can't enumerate names, so skip;
+                // unresolved refs surface at runtime as WorkflowError.
+                const knownGuardNames = config.guardRegistry !== undefined ? undefined : new Set((config.guards ?? []).map((g) => g.name));
+                const registry = new core_2.InMemoryDefinitionRegistry({
+                    validator: new core_2.WorkflowValidator(),
+                    compiler: new core_2.WorkflowCompiler(),
+                    validationOptions: { knownCommandNames, knownGuardNames },
+                    onValidationWarning: logValidationWarning,
+                });
+                for (const workflow of config.workflows) {
+                    registry.register(workflow);
+                }
+                return registry;
+            },
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS, injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
+            useFactory: (config) => config.persistence.instanceStore,
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
+            useFactory: (config) => config.persistence.historyStore,
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
+            useFactory: (config) => config.persistence.transactionRunner,
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_CLOCK,
+            useFactory: (config) => config.clock ?? { now: () => new Date() },
+            inject: [injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: injection_tokens_js_1.WORKFLOW_RUNTIME,
+            useFactory: (config, definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, clock) => new core_2.WorkflowRuntime({
+                definitionRegistry,
+                commandRegistry,
+                guardRegistry,
+                instanceStore,
+                historyStore,
+                transactionRunner,
+                clock,
+                observers: config.observers,
+                onObserverError: config.onObserverError,
+            }),
+            inject: [
+                injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS,
+                injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
+                injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
+                injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
+                injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
+                injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
+                injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
+                injection_tokens_js_1.WORKFLOW_CLOCK,
+            ],
+        },
+        workflow_service_js_1.WorkflowService,
+        workflow_timeout_service_js_1.WorkflowTimeoutService,
+    ];
+}
 let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
     static forRoot(options) {
-        if (options.guardRegistry && options.guards && options.guards.length > 0) {
-            throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
-        }
-        const controllers = options.enableControllers
-            ? [workflow_instance_controller_js_1.WorkflowInstanceController, workflow_event_controller_js_1.WorkflowEventController, workflow_query_controller_js_1.WorkflowQueryController, workflow_timeout_controller_js_1.WorkflowTimeoutController]
-            : [];
-        const explicitCommands = options.commands ?? [];
-        const commandClasses = explicitCommands.map((c) => c.useClass);
-        const clock = options.clock ?? { now: () => new Date() };
-        const providers = [
-            ...commandClasses,
-            {
-                provide: injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
-                useFactory: (moduleRef, discoveryService) => {
-                    const discovered = (0, command_discovery_js_1.discoverDecoratedCommands)(discoveryService);
-                    const merged = (0, command_discovery_js_1.mergeCommandRegistrations)(explicitCommands, discovered);
-                    return new nest_command_registry_js_1.NestCommandRegistry(moduleRef, merged);
-                },
-                inject: [core_1.ModuleRef, core_1.DiscoveryService],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
-                // guards/guardRegistry mutual exclusion is enforced synchronously at
-                // the top of forRoot, before this factory can ever run.
-                useFactory: () => {
-                    if (options.guardRegistry)
-                        return options.guardRegistry;
-                    const registry = new core_2.InMemoryGuardRegistry();
-                    for (const guard of options.guards ?? []) {
-                        registry.register(guard.name, guard);
-                    }
-                    return registry;
-                },
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
-                useFactory: (commandRegistry) => {
-                    const knownCommandNames = commandRegistry.getRegisteredNames();
-                    // Validate guard refs only when we own the registry (built-in path).
-                    // With a custom guardRegistry we can't enumerate names, so skip;
-                    // unresolved refs surface at runtime as WorkflowError.
-                    const knownGuardNames = options.guardRegistry !== undefined ? undefined : new Set((options.guards ?? []).map((g) => g.name));
-                    const registry = new core_2.InMemoryDefinitionRegistry({
-                        validator: new core_2.WorkflowValidator(),
-                        compiler: new core_2.WorkflowCompiler(),
-                        validationOptions: { knownCommandNames, knownGuardNames },
-                        onValidationWarning: logValidationWarning,
-                    });
-                    for (const workflow of options.workflows) {
-                        registry.register(workflow);
-                    }
-                    return registry;
-                },
-                inject: [injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
-                useValue: options.persistence.instanceStore,
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
-                useValue: options.persistence.historyStore,
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
-                useValue: options.persistence.transactionRunner,
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_CLOCK,
-                useValue: clock,
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_RUNTIME,
-                useFactory: (definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, wfClock) => new core_2.WorkflowRuntime({
-                    definitionRegistry,
-                    commandRegistry,
-                    guardRegistry,
-                    instanceStore,
-                    historyStore,
-                    transactionRunner,
-                    clock: wfClock,
-                    observers: options.observers,
-                    onObserverError: options.onObserverError,
-                }),
-                inject: [
-                    injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
-                    injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
-                    injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
-                    injection_tokens_js_1.WORKFLOW_CLOCK,
-                ],
-            },
-            workflow_service_js_1.WorkflowService,
-            workflow_timeout_service_js_1.WorkflowTimeoutService,
-        ];
+        // Eager, so a misconfiguration fails where it was written rather than at
+        // container bootstrap.
+        assertGuardConfigExclusive(options);
         return {
             module: WorkflowModule_1,
             global: true, // allow downstream feature modules to inject WorkflowService without re-importing forRoot
             imports: [core_1.DiscoveryModule],
-            controllers,
-            providers,
+            controllers: options.enableControllers ? [...CONTROLLERS] : [],
+            providers: [
+                { provide: injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS, useValue: options },
+                ...buildWorkflowProviders(options.commands ?? []),
+            ],
             exports: EXPORTED_TOKENS,
         };
     }
     static forRootAsync(options) {
-        const controllers = options.enableControllers
-            ? [workflow_instance_controller_js_1.WorkflowInstanceController, workflow_event_controller_js_1.WorkflowEventController, workflow_query_controller_js_1.WorkflowQueryController, workflow_timeout_controller_js_1.WorkflowTimeoutController]
-            : [];
-        const explicitCommands = options.commands ?? [];
-        const commandClasses = explicitCommands.map((c) => c.useClass);
-        const configProvider = {
-            provide: "WORKFLOW_MODULE_OPTIONS",
-            useFactory: options.useFactory,
-            inject: (options.inject ?? []),
-        };
-        const providers = [
-            configProvider,
-            ...commandClasses,
-            {
-                provide: injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
-                useFactory: (moduleRef, discoveryService) => {
-                    const discovered = (0, command_discovery_js_1.discoverDecoratedCommands)(discoveryService);
-                    const merged = (0, command_discovery_js_1.mergeCommandRegistrations)(explicitCommands, discovered);
-                    return new nest_command_registry_js_1.NestCommandRegistry(moduleRef, merged);
-                },
-                inject: [core_1.ModuleRef, core_1.DiscoveryService],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
-                useFactory: (config) => {
-                    if (config.guardRegistry && config.guards && config.guards.length > 0) {
-                        throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
-                    }
-                    if (config.guardRegistry)
-                        return config.guardRegistry;
-                    const registry = new core_2.InMemoryGuardRegistry();
-                    for (const guard of config.guards ?? []) {
-                        registry.register(guard.name, guard);
-                    }
-                    return registry;
-                },
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
-                useFactory: (config, commandRegistry) => {
-                    const knownCommandNames = commandRegistry.getRegisteredNames();
-                    // Validate guard refs only when we own the registry (built-in path).
-                    // With a custom guardRegistry we can't enumerate names, so skip;
-                    // unresolved refs surface at runtime as WorkflowError.
-                    const knownGuardNames = config.guardRegistry !== undefined ? undefined : new Set((config.guards ?? []).map((g) => g.name));
-                    const registry = new core_2.InMemoryDefinitionRegistry({
-                        validator: new core_2.WorkflowValidator(),
-                        compiler: new core_2.WorkflowCompiler(),
-                        validationOptions: { knownCommandNames, knownGuardNames },
-                        onValidationWarning: logValidationWarning,
-                    });
-                    for (const workflow of config.workflows) {
-                        registry.register(workflow);
-                    }
-                    return registry;
-                },
-                inject: ["WORKFLOW_MODULE_OPTIONS", injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
-                useFactory: (config) => config.persistence.instanceStore,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
-                useFactory: (config) => config.persistence.historyStore,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
-                useFactory: (config) => config.persistence.transactionRunner,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_CLOCK,
-                useFactory: (config) => config.clock ?? { now: () => new Date() },
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: injection_tokens_js_1.WORKFLOW_RUNTIME,
-                useFactory: (config, definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, clock) => new core_2.WorkflowRuntime({
-                    definitionRegistry,
-                    commandRegistry,
-                    guardRegistry,
-                    instanceStore,
-                    historyStore,
-                    transactionRunner,
-                    clock,
-                    observers: config.observers,
-                    onObserverError: config.onObserverError,
-                }),
-                inject: [
-                    "WORKFLOW_MODULE_OPTIONS",
-                    injection_tokens_js_1.WORKFLOW_DEFINITION_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_COMMAND_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_GUARD_REGISTRY,
-                    injection_tokens_js_1.WORKFLOW_INSTANCE_STORE,
-                    injection_tokens_js_1.WORKFLOW_HISTORY_STORE,
-                    injection_tokens_js_1.WORKFLOW_TRANSACTION_RUNNER,
-                    injection_tokens_js_1.WORKFLOW_CLOCK,
-                ],
-            },
-            workflow_service_js_1.WorkflowService,
-            workflow_timeout_service_js_1.WorkflowTimeoutService,
-        ];
         return {
             module: WorkflowModule_1,
             global: true, // allow downstream feature modules to inject WorkflowService without re-importing forRootAsync
             imports: [core_1.DiscoveryModule, ...(options.imports ?? [])],
-            controllers,
-            providers,
+            controllers: options.enableControllers ? [...CONTROLLERS] : [],
+            providers: [
+                {
+                    provide: injection_tokens_js_1.WORKFLOW_MODULE_OPTIONS,
+                    useFactory: options.useFactory,
+                    inject: (options.inject ?? []),
+                },
+                ...buildWorkflowProviders(options.commands ?? []),
+            ],
             exports: EXPORTED_TOKENS,
         };
     }

package/dist/filters/workflow-exception.filter.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var WorkflowExceptionFilter_1;
 import { Catch, HttpStatus, Logger } from "@nestjs/common";
-import { WorkflowError, WorkflowInstanceNotFoundError, InvalidEventError } from "@duraflows/core";
+import { WorkflowError, WorkflowInstanceNotFoundError, InvalidEventError, InvalidArgumentError } from "@duraflows/core";
 /**
  * Maps duraflows domain errors to HTTP statuses for the optional REST
  * controllers. Without this filter, a missing instance or an event invalid
@@ -33,6 +33,14 @@ let WorkflowExceptionFilter = WorkflowExceptionFilter_1 = class WorkflowExceptio
             });
             return;
         }
+        if (exception instanceof InvalidArgumentError) {
+            response.status(HttpStatus.BAD_REQUEST).send({
+                statusCode: HttpStatus.BAD_REQUEST,
+                error: "Bad Request",
+                message: exception.message,
+            });
+            return;
+        }
         // The response body is sanitized, so log the real cause here — otherwise
         // unmapped domain errors (e.g. optimistic-locking conflicts under
         // concurrency) become undiagnosable silent 500s. `WorkflowError` wraps the

package/dist/providers/injection-tokens.d.ts

@@ -6,4 +6,11 @@ export declare const WORKFLOW_DEFINITION_REGISTRY: unique symbol;
 export declare const WORKFLOW_TRANSACTION_RUNNER: unique symbol;
 export declare const WORKFLOW_CLOCK: unique symbol;
 export declare const WORKFLOW_GUARD_REGISTRY: unique symbol;
+/**
+ * The resolved module configuration. Deliberately not re-exported from the
+ * package barrel: it exists so `forRoot` and `forRootAsync` can publish their
+ * config under one token and share a single provider graph, not as a supported
+ * extension point.
+ */
+export declare const WORKFLOW_MODULE_OPTIONS: unique symbol;
 //# sourceMappingURL=injection-tokens.d.ts.map

package/dist/providers/injection-tokens.js

@@ -6,4 +6,11 @@ export const WORKFLOW_DEFINITION_REGISTRY = Symbol("WORKFLOW_DEFINITION_REGISTRY
 export const WORKFLOW_TRANSACTION_RUNNER = Symbol("WORKFLOW_TRANSACTION_RUNNER");
 export const WORKFLOW_CLOCK = Symbol("WORKFLOW_CLOCK");
 export const WORKFLOW_GUARD_REGISTRY = Symbol("WORKFLOW_GUARD_REGISTRY");
+/**
+ * The resolved module configuration. Deliberately not re-exported from the
+ * package barrel: it exists so `forRoot` and `forRootAsync` can publish their
+ * config under one token and share a single provider graph, not as a supported
+ * extension point.
+ */
+export const WORKFLOW_MODULE_OPTIONS = Symbol("WORKFLOW_MODULE_OPTIONS");
 //# sourceMappingURL=injection-tokens.js.map

package/dist/services/workflow.service.js

@@ -53,9 +53,9 @@ let WorkflowService = class WorkflowService {
      * upstream when the instance was created via `createInstanceFor`).
      */
     async triggerEventFor(definition, input) {
-        // `definition` is consumed at type-level only; the runtime resolves
-        // the instance by uuid and reads its workflowName from the live row.
-        void definition;
+        // `definition` is consumed at type level only -- it is what infers TState.
+        // The runtime resolves the instance by uuid and reads its workflowName from
+        // the live row, so there is nothing to do with the value at runtime.
         const result = await this.runtime.triggerEvent(input);
         return result;
     }

package/dist/workflow.module.js

@@ -10,7 +10,7 @@ import { DiscoveryModule, DiscoveryService, ModuleRef } from "@nestjs/core";
 import { InMemoryDefinitionRegistry, WorkflowRuntime, WorkflowValidator, WorkflowCompiler, InMemoryGuardRegistry, } from "@duraflows/core";
 import { NestCommandRegistry } from "./providers/nest-command-registry.js";
 import { discoverDecoratedCommands, mergeCommandRegistrations } from "./providers/command-discovery.js";
-import { WORKFLOW_RUNTIME, WORKFLOW_INSTANCE_STORE, WORKFLOW_HISTORY_STORE, WORKFLOW_COMMAND_REGISTRY, WORKFLOW_DEFINITION_REGISTRY, WORKFLOW_TRANSACTION_RUNNER, WORKFLOW_CLOCK, WORKFLOW_GUARD_REGISTRY, } from "./providers/injection-tokens.js";
+import { WORKFLOW_RUNTIME, WORKFLOW_INSTANCE_STORE, WORKFLOW_HISTORY_STORE, WORKFLOW_COMMAND_REGISTRY, WORKFLOW_DEFINITION_REGISTRY, WORKFLOW_TRANSACTION_RUNNER, WORKFLOW_CLOCK, WORKFLOW_GUARD_REGISTRY, WORKFLOW_MODULE_OPTIONS, } from "./providers/injection-tokens.js";
 import { WorkflowService } from "./services/workflow.service.js";
 import { WorkflowTimeoutService } from "./services/workflow-timeout.service.js";
 import { WorkflowEventController } from "./controllers/workflow-event.controller.js";
@@ -35,227 +35,161 @@ const EXPORTED_TOKENS = [
     WORKFLOW_TRANSACTION_RUNNER,
     WORKFLOW_CLOCK,
 ];
+const CONTROLLERS = [
+    WorkflowInstanceController,
+    WorkflowEventController,
+    WorkflowQueryController,
+    WorkflowTimeoutController,
+];
+/**
+ * `guards` and `guardRegistry` are mutually exclusive: with a custom registry
+ * duraflows cannot enumerate guard names, so it can neither merge the array in
+ * nor validate definition refs against it.
+ *
+ * forRoot calls this eagerly, so the error surfaces at module definition.
+ * forRootAsync only learns its config once the factory resolves, so it calls
+ * this from inside the guard-registry provider instead. Same message, and each
+ * entry point keeps the failure timing it has always had.
+ */
+function assertGuardConfigExclusive(config) {
+    if (config.guardRegistry && config.guards && config.guards.length > 0) {
+        throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
+    }
+}
+/**
+ * The provider graph shared by both entry points. Every factory reads its
+ * configuration from WORKFLOW_MODULE_OPTIONS — supplied as a value by forRoot
+ * and as the caller's factory by forRootAsync — so the wiring downstream is
+ * identical and cannot drift between the sync and async paths.
+ */
+function buildWorkflowProviders(explicitCommands) {
+    return [
+        ...explicitCommands.map((c) => c.useClass),
+        {
+            provide: WORKFLOW_COMMAND_REGISTRY,
+            useFactory: (moduleRef, discoveryService) => {
+                const discovered = discoverDecoratedCommands(discoveryService);
+                const merged = mergeCommandRegistrations(explicitCommands, discovered);
+                return new NestCommandRegistry(moduleRef, merged);
+            },
+            inject: [ModuleRef, DiscoveryService],
+        },
+        {
+            provide: WORKFLOW_GUARD_REGISTRY,
+            useFactory: (config) => {
+                // Redundant on the forRoot path, which already threw at module
+                // definition, but this is forRootAsync's only opportunity to check.
+                assertGuardConfigExclusive(config);
+                if (config.guardRegistry)
+                    return config.guardRegistry;
+                const registry = new InMemoryGuardRegistry();
+                for (const guard of config.guards ?? []) {
+                    registry.register(guard.name, guard);
+                }
+                return registry;
+            },
+            inject: [WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: WORKFLOW_DEFINITION_REGISTRY,
+            useFactory: (config, commandRegistry) => {
+                const knownCommandNames = commandRegistry.getRegisteredNames();
+                // Validate guard refs only when we own the registry (built-in path).
+                // With a custom guardRegistry we can't enumerate names, so skip;
+                // unresolved refs surface at runtime as WorkflowError.
+                const knownGuardNames = config.guardRegistry !== undefined ? undefined : new Set((config.guards ?? []).map((g) => g.name));
+                const registry = new InMemoryDefinitionRegistry({
+                    validator: new WorkflowValidator(),
+                    compiler: new WorkflowCompiler(),
+                    validationOptions: { knownCommandNames, knownGuardNames },
+                    onValidationWarning: logValidationWarning,
+                });
+                for (const workflow of config.workflows) {
+                    registry.register(workflow);
+                }
+                return registry;
+            },
+            inject: [WORKFLOW_MODULE_OPTIONS, WORKFLOW_COMMAND_REGISTRY],
+        },
+        {
+            provide: WORKFLOW_INSTANCE_STORE,
+            useFactory: (config) => config.persistence.instanceStore,
+            inject: [WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: WORKFLOW_HISTORY_STORE,
+            useFactory: (config) => config.persistence.historyStore,
+            inject: [WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: WORKFLOW_TRANSACTION_RUNNER,
+            useFactory: (config) => config.persistence.transactionRunner,
+            inject: [WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: WORKFLOW_CLOCK,
+            useFactory: (config) => config.clock ?? { now: () => new Date() },
+            inject: [WORKFLOW_MODULE_OPTIONS],
+        },
+        {
+            provide: WORKFLOW_RUNTIME,
+            useFactory: (config, definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, clock) => new WorkflowRuntime({
+                definitionRegistry,
+                commandRegistry,
+                guardRegistry,
+                instanceStore,
+                historyStore,
+                transactionRunner,
+                clock,
+                observers: config.observers,
+                onObserverError: config.onObserverError,
+            }),
+            inject: [
+                WORKFLOW_MODULE_OPTIONS,
+                WORKFLOW_DEFINITION_REGISTRY,
+                WORKFLOW_COMMAND_REGISTRY,
+                WORKFLOW_GUARD_REGISTRY,
+                WORKFLOW_INSTANCE_STORE,
+                WORKFLOW_HISTORY_STORE,
+                WORKFLOW_TRANSACTION_RUNNER,
+                WORKFLOW_CLOCK,
+            ],
+        },
+        WorkflowService,
+        WorkflowTimeoutService,
+    ];
+}
 let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
     static forRoot(options) {
-        if (options.guardRegistry && options.guards && options.guards.length > 0) {
-            throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
-        }
-        const controllers = options.enableControllers
-            ? [WorkflowInstanceController, WorkflowEventController, WorkflowQueryController, WorkflowTimeoutController]
-            : [];
-        const explicitCommands = options.commands ?? [];
-        const commandClasses = explicitCommands.map((c) => c.useClass);
-        const clock = options.clock ?? { now: () => new Date() };
-        const providers = [
-            ...commandClasses,
-            {
-                provide: WORKFLOW_COMMAND_REGISTRY,
-                useFactory: (moduleRef, discoveryService) => {
-                    const discovered = discoverDecoratedCommands(discoveryService);
-                    const merged = mergeCommandRegistrations(explicitCommands, discovered);
-                    return new NestCommandRegistry(moduleRef, merged);
-                },
-                inject: [ModuleRef, DiscoveryService],
-            },
-            {
-                provide: WORKFLOW_GUARD_REGISTRY,
-                // guards/guardRegistry mutual exclusion is enforced synchronously at
-                // the top of forRoot, before this factory can ever run.
-                useFactory: () => {
-                    if (options.guardRegistry)
-                        return options.guardRegistry;
-                    const registry = new InMemoryGuardRegistry();
-                    for (const guard of options.guards ?? []) {
-                        registry.register(guard.name, guard);
-                    }
-                    return registry;
-                },
-            },
-            {
-                provide: WORKFLOW_DEFINITION_REGISTRY,
-                useFactory: (commandRegistry) => {
-                    const knownCommandNames = commandRegistry.getRegisteredNames();
-                    // Validate guard refs only when we own the registry (built-in path).
-                    // With a custom guardRegistry we can't enumerate names, so skip;
-                    // unresolved refs surface at runtime as WorkflowError.
-                    const knownGuardNames = options.guardRegistry !== undefined ? undefined : new Set((options.guards ?? []).map((g) => g.name));
-                    const registry = new InMemoryDefinitionRegistry({
-                        validator: new WorkflowValidator(),
-                        compiler: new WorkflowCompiler(),
-                        validationOptions: { knownCommandNames, knownGuardNames },
-                        onValidationWarning: logValidationWarning,
-                    });
-                    for (const workflow of options.workflows) {
-                        registry.register(workflow);
-                    }
-                    return registry;
-                },
-                inject: [WORKFLOW_COMMAND_REGISTRY],
-            },
-            {
-                provide: WORKFLOW_INSTANCE_STORE,
-                useValue: options.persistence.instanceStore,
-            },
-            {
-                provide: WORKFLOW_HISTORY_STORE,
-                useValue: options.persistence.historyStore,
-            },
-            {
-                provide: WORKFLOW_TRANSACTION_RUNNER,
-                useValue: options.persistence.transactionRunner,
-            },
-            {
-                provide: WORKFLOW_CLOCK,
-                useValue: clock,
-            },
-            {
-                provide: WORKFLOW_RUNTIME,
-                useFactory: (definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, wfClock) => new WorkflowRuntime({
-                    definitionRegistry,
-                    commandRegistry,
-                    guardRegistry,
-                    instanceStore,
-                    historyStore,
-                    transactionRunner,
-                    clock: wfClock,
-                    observers: options.observers,
-                    onObserverError: options.onObserverError,
-                }),
-                inject: [
-                    WORKFLOW_DEFINITION_REGISTRY,
-                    WORKFLOW_COMMAND_REGISTRY,
-                    WORKFLOW_GUARD_REGISTRY,
-                    WORKFLOW_INSTANCE_STORE,
-                    WORKFLOW_HISTORY_STORE,
-                    WORKFLOW_TRANSACTION_RUNNER,
-                    WORKFLOW_CLOCK,
-                ],
-            },
-            WorkflowService,
-            WorkflowTimeoutService,
-        ];
+        // Eager, so a misconfiguration fails where it was written rather than at
+        // container bootstrap.
+        assertGuardConfigExclusive(options);
         return {
             module: WorkflowModule_1,
             global: true, // allow downstream feature modules to inject WorkflowService without re-importing forRoot
             imports: [DiscoveryModule],
-            controllers,
-            providers,
+            controllers: options.enableControllers ? [...CONTROLLERS] : [],
+            providers: [
+                { provide: WORKFLOW_MODULE_OPTIONS, useValue: options },
+                ...buildWorkflowProviders(options.commands ?? []),
+            ],
             exports: EXPORTED_TOKENS,
         };
     }
     static forRootAsync(options) {
-        const controllers = options.enableControllers
-            ? [WorkflowInstanceController, WorkflowEventController, WorkflowQueryController, WorkflowTimeoutController]
-            : [];
-        const explicitCommands = options.commands ?? [];
-        const commandClasses = explicitCommands.map((c) => c.useClass);
-        const configProvider = {
-            provide: "WORKFLOW_MODULE_OPTIONS",
-            useFactory: options.useFactory,
-            inject: (options.inject ?? []),
-        };
-        const providers = [
-            configProvider,
-            ...commandClasses,
-            {
-                provide: WORKFLOW_COMMAND_REGISTRY,
-                useFactory: (moduleRef, discoveryService) => {
-                    const discovered = discoverDecoratedCommands(discoveryService);
-                    const merged = mergeCommandRegistrations(explicitCommands, discovered);
-                    return new NestCommandRegistry(moduleRef, merged);
-                },
-                inject: [ModuleRef, DiscoveryService],
-            },
-            {
-                provide: WORKFLOW_GUARD_REGISTRY,
-                useFactory: (config) => {
-                    if (config.guardRegistry && config.guards && config.guards.length > 0) {
-                        throw new Error("WorkflowModule: cannot supply both `guards` and `guardRegistry` — they are mutually exclusive. Pass guards or a custom registry, not both.");
-                    }
-                    if (config.guardRegistry)
-                        return config.guardRegistry;
-                    const registry = new InMemoryGuardRegistry();
-                    for (const guard of config.guards ?? []) {
-                        registry.register(guard.name, guard);
-                    }
-                    return registry;
-                },
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: WORKFLOW_DEFINITION_REGISTRY,
-                useFactory: (config, commandRegistry) => {
-                    const knownCommandNames = commandRegistry.getRegisteredNames();
-                    // Validate guard refs only when we own the registry (built-in path).
-                    // With a custom guardRegistry we can't enumerate names, so skip;
-                    // unresolved refs surface at runtime as WorkflowError.
-                    const knownGuardNames = config.guardRegistry !== undefined ? undefined : new Set((config.guards ?? []).map((g) => g.name));
-                    const registry = new InMemoryDefinitionRegistry({
-                        validator: new WorkflowValidator(),
-                        compiler: new WorkflowCompiler(),
-                        validationOptions: { knownCommandNames, knownGuardNames },
-                        onValidationWarning: logValidationWarning,
-                    });
-                    for (const workflow of config.workflows) {
-                        registry.register(workflow);
-                    }
-                    return registry;
-                },
-                inject: ["WORKFLOW_MODULE_OPTIONS", WORKFLOW_COMMAND_REGISTRY],
-            },
-            {
-                provide: WORKFLOW_INSTANCE_STORE,
-                useFactory: (config) => config.persistence.instanceStore,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: WORKFLOW_HISTORY_STORE,
-                useFactory: (config) => config.persistence.historyStore,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: WORKFLOW_TRANSACTION_RUNNER,
-                useFactory: (config) => config.persistence.transactionRunner,
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: WORKFLOW_CLOCK,
-                useFactory: (config) => config.clock ?? { now: () => new Date() },
-                inject: ["WORKFLOW_MODULE_OPTIONS"],
-            },
-            {
-                provide: WORKFLOW_RUNTIME,
-                useFactory: (config, definitionRegistry, commandRegistry, guardRegistry, instanceStore, historyStore, transactionRunner, clock) => new WorkflowRuntime({
-                    definitionRegistry,
-                    commandRegistry,
-                    guardRegistry,
-                    instanceStore,
-                    historyStore,
-                    transactionRunner,
-                    clock,
-                    observers: config.observers,
-                    onObserverError: config.onObserverError,
-                }),
-                inject: [
-                    "WORKFLOW_MODULE_OPTIONS",
-                    WORKFLOW_DEFINITION_REGISTRY,
-                    WORKFLOW_COMMAND_REGISTRY,
-                    WORKFLOW_GUARD_REGISTRY,
-                    WORKFLOW_INSTANCE_STORE,
-                    WORKFLOW_HISTORY_STORE,
-                    WORKFLOW_TRANSACTION_RUNNER,
-                    WORKFLOW_CLOCK,
-                ],
-            },
-            WorkflowService,
-            WorkflowTimeoutService,
-        ];
         return {
             module: WorkflowModule_1,
             global: true, // allow downstream feature modules to inject WorkflowService without re-importing forRootAsync
             imports: [DiscoveryModule, ...(options.imports ?? [])],
-            controllers,
-            providers,
+            controllers: options.enableControllers ? [...CONTROLLERS] : [],
+            providers: [
+                {
+                    provide: WORKFLOW_MODULE_OPTIONS,
+                    useFactory: options.useFactory,
+                    inject: (options.inject ?? []),
+                },
+                ...buildWorkflowProviders(options.commands ?? []),
+            ],
             exports: EXPORTED_TOKENS,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duraflows/nestjs",
-  "version": "3.1.0",
+  "version": "4.0.1",
   "description": "NestJS integration for duraflows: dependency injection, services, optional REST controllers, and @WorkflowCommand decorator for DI-backed command handlers.",
   "keywords": [
     "duraflows",
@@ -54,17 +54,17 @@
     "class-validator": "^0.15.1"
   },
   "peerDependencies": {
-    "@duraflows/core": "^3.1.0",
+    "@duraflows/core": "^4.0.1",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.0.0"
   },
   "devDependencies": {
-    "@nestjs/common": "^11.1.24",
-    "@nestjs/core": "^11.1.24",
-    "@nestjs/testing": "^11.1.24",
-    "@duraflows/core": "3.1.0"
+    "@nestjs/common": "^11.1.28",
+    "@nestjs/core": "^11.1.28",
+    "@nestjs/testing": "^11.1.28",
+    "@duraflows/core": "4.0.1"
   },
   "scripts": {
     "build": "tsc --build"