@duraflows/nestjs 2.1.0 → 3.0.0

package/README.md

@@ -157,6 +157,8 @@ export class SendToWarehouseCommand implements IWorkflowCommand {
 
 When `enableControllers: true` is set, the following endpoints are registered:
 
+> **Security:** the generated controllers ship **without authentication**. They expose instance creation, arbitrary event triggering, full history reads, and `POST /workflows/timeouts/process` (an administrative bulk operation). Apply your own auth guards and rate limiting before enabling them in production — e.g. a global `APP_GUARD`, or guards bound per controller. Note also that `triggerEvent` responses include each command's `CommandResult` verbatim, so command authors must not place sensitive data in `CommandResult.error` / `message` if the controllers are enabled.
+
 | Controller                   | Endpoints                              |
 | ---------------------------- | -------------------------------------- |
 | `WorkflowInstanceController` | Create and retrieve workflow instances |

package/dist/cjs/controllers/dto/history-query.dto.d.ts

@@ -1,6 +1,6 @@
 export declare class HistoryQueryDto {
-    limit?: string;
-    offset?: string;
+    limit?: number;
+    offset?: number;
 }
 export declare class HistoryParamsDto {
     workflowInstanceUuid: string;

package/dist/cjs/controllers/dto/history-query.dto.js

@@ -10,6 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HistoryParamsDto = exports.HistoryQueryDto = void 0;
+const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 class HistoryQueryDto {
     limit;
@@ -18,13 +19,18 @@ class HistoryQueryDto {
 exports.HistoryQueryDto = HistoryQueryDto;
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsNumberString)(),
-    __metadata("design:type", String)
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(500),
+    __metadata("design:type", Number)
 ], HistoryQueryDto.prototype, "limit", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsNumberString)(),
-    __metadata("design:type", String)
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
 ], HistoryQueryDto.prototype, "offset", void 0);
 class HistoryParamsDto {
     workflowInstanceUuid;

package/dist/cjs/controllers/dto/timeout-process.dto.d.ts

@@ -1,4 +1,4 @@
 export declare class TimeoutProcessQueryDto {
-    limit?: string;
+    limit?: number;
 }
 //# sourceMappingURL=timeout-process.dto.d.ts.map

package/dist/cjs/controllers/dto/timeout-process.dto.js

@@ -10,6 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TimeoutProcessQueryDto = void 0;
+const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 class TimeoutProcessQueryDto {
     limit;
@@ -17,7 +18,10 @@ class TimeoutProcessQueryDto {
 exports.TimeoutProcessQueryDto = TimeoutProcessQueryDto;
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsNumberString)(),
-    __metadata("design:type", String)
+    (0, class_transformer_1.Type)(() => Number),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(1000),
+    __metadata("design:type", Number)
 ], TimeoutProcessQueryDto.prototype, "limit", void 0);
 //# sourceMappingURL=timeout-process.dto.js.map

package/dist/cjs/controllers/workflow-event.controller.js

@@ -16,6 +16,7 @@ exports.WorkflowEventController = void 0;
 const common_1 = require("@nestjs/common");
 const workflow_service_js_1 = require("../services/workflow.service.js");
 const index_js_1 = require("./dto/index.js");
+const workflow_exception_filter_js_1 = require("../filters/workflow-exception.filter.js");
 let WorkflowEventController = class WorkflowEventController {
     workflowService;
     constructor(workflowService) {
@@ -42,7 +43,8 @@ __decorate([
 ], WorkflowEventController.prototype, "triggerEvent", null);
 exports.WorkflowEventController = WorkflowEventController = __decorate([
     (0, common_1.Controller)("workflows"),
-    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true })),
+    (0, common_1.UseFilters)(workflow_exception_filter_js_1.WorkflowExceptionFilter),
+    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [workflow_service_js_1.WorkflowService])
 ], WorkflowEventController);
 //# sourceMappingURL=workflow-event.controller.js.map

package/dist/cjs/controllers/workflow-instance.controller.js

@@ -16,6 +16,7 @@ exports.WorkflowInstanceController = void 0;
 const common_1 = require("@nestjs/common");
 const workflow_service_js_1 = require("../services/workflow.service.js");
 const index_js_1 = require("./dto/index.js");
+const workflow_exception_filter_js_1 = require("../filters/workflow-exception.filter.js");
 let WorkflowInstanceController = class WorkflowInstanceController {
     workflowService;
     constructor(workflowService) {
@@ -54,7 +55,8 @@ __decorate([
 ], WorkflowInstanceController.prototype, "getInstance", null);
 exports.WorkflowInstanceController = WorkflowInstanceController = __decorate([
     (0, common_1.Controller)("workflows"),
-    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true })),
+    (0, common_1.UseFilters)(workflow_exception_filter_js_1.WorkflowExceptionFilter),
+    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [workflow_service_js_1.WorkflowService])
 ], WorkflowInstanceController);
 //# sourceMappingURL=workflow-instance.controller.js.map

package/dist/cjs/controllers/workflow-query.controller.js

@@ -16,6 +16,7 @@ exports.WorkflowQueryController = void 0;
 const common_1 = require("@nestjs/common");
 const workflow_service_js_1 = require("../services/workflow.service.js");
 const index_js_1 = require("./dto/index.js");
+const workflow_exception_filter_js_1 = require("../filters/workflow-exception.filter.js");
 let WorkflowQueryController = class WorkflowQueryController {
     workflowService;
     constructor(workflowService) {
@@ -28,8 +29,8 @@ let WorkflowQueryController = class WorkflowQueryController {
     }
     async getHistory(params, query) {
         return this.workflowService.getHistory(params.workflowInstanceUuid, {
-            limit: query.limit ? parseInt(query.limit, 10) : undefined,
-            offset: query.offset ? parseInt(query.offset, 10) : undefined,
+            limit: query.limit,
+            offset: query.offset,
         });
     }
 };
@@ -52,7 +53,8 @@ __decorate([
 ], WorkflowQueryController.prototype, "getHistory", null);
 exports.WorkflowQueryController = WorkflowQueryController = __decorate([
     (0, common_1.Controller)("workflows"),
-    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true })),
+    (0, common_1.UseFilters)(workflow_exception_filter_js_1.WorkflowExceptionFilter),
+    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [workflow_service_js_1.WorkflowService])
 ], WorkflowQueryController);
 //# sourceMappingURL=workflow-query.controller.js.map

package/dist/cjs/controllers/workflow-timeout.controller.js

@@ -16,13 +16,14 @@ exports.WorkflowTimeoutController = void 0;
 const common_1 = require("@nestjs/common");
 const workflow_timeout_service_js_1 = require("../services/workflow-timeout.service.js");
 const index_js_1 = require("./dto/index.js");
+const workflow_exception_filter_js_1 = require("../filters/workflow-exception.filter.js");
 let WorkflowTimeoutController = class WorkflowTimeoutController {
     timeoutService;
     constructor(timeoutService) {
         this.timeoutService = timeoutService;
     }
     async processExpired(query) {
-        return this.timeoutService.processExpiredWorkflows(query.limit ? parseInt(query.limit, 10) : undefined);
+        return this.timeoutService.processExpiredWorkflows(query.limit);
     }
 };
 exports.WorkflowTimeoutController = WorkflowTimeoutController;
@@ -35,7 +36,8 @@ __decorate([
 ], WorkflowTimeoutController.prototype, "processExpired", null);
 exports.WorkflowTimeoutController = WorkflowTimeoutController = __decorate([
     (0, common_1.Controller)("workflows/timeouts"),
-    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true })),
+    (0, common_1.UseFilters)(workflow_exception_filter_js_1.WorkflowExceptionFilter),
+    (0, common_1.UsePipes)(new common_1.ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [workflow_timeout_service_js_1.WorkflowTimeoutService])
 ], WorkflowTimeoutController);
 //# sourceMappingURL=workflow-timeout.controller.js.map

package/dist/cjs/filters/workflow-exception.filter.d.ts

@@ -0,0 +1,13 @@
+import { type ArgumentsHost, type ExceptionFilter } from "@nestjs/common";
+import { WorkflowError } 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
+ * for the current state surfaces as a generic 500 and leaks internal
+ * messages.
+ */
+export declare class WorkflowExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: WorkflowError, host: ArgumentsHost): void;
+}
+//# sourceMappingURL=workflow-exception.filter.d.ts.map

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

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var WorkflowExceptionFilter_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowExceptionFilter = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@duraflows/core");
+/**
+ * Maps duraflows domain errors to HTTP statuses for the optional REST
+ * controllers. Without this filter, a missing instance or an event invalid
+ * for the current state surfaces as a generic 500 and leaks internal
+ * messages.
+ */
+let WorkflowExceptionFilter = WorkflowExceptionFilter_1 = class WorkflowExceptionFilter {
+    logger = new common_1.Logger(WorkflowExceptionFilter_1.name);
+    catch(exception, host) {
+        const response = host.switchToHttp().getResponse();
+        if (exception instanceof core_1.WorkflowInstanceNotFoundError) {
+            response.status(common_1.HttpStatus.NOT_FOUND).send({
+                statusCode: common_1.HttpStatus.NOT_FOUND,
+                error: "Not Found",
+                message: exception.message,
+            });
+            return;
+        }
+        if (exception instanceof core_1.InvalidEventError) {
+            response.status(common_1.HttpStatus.CONFLICT).send({
+                statusCode: common_1.HttpStatus.CONFLICT,
+                error: "Conflict",
+                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
+        // originating DI/persistence failure as `cause` (e.g. NestCommandRegistry
+        // attaches the container error), so prefer the cause's message and stack —
+        // the wrapper alone hides the underlying failure from operators.
+        const cause = exception.cause instanceof Error ? exception.cause : undefined;
+        this.logger.error(cause ? `${exception.message} (cause: ${cause.message})` : exception.message, (cause ?? exception).stack);
+        response.status(common_1.HttpStatus.INTERNAL_SERVER_ERROR).send({
+            statusCode: common_1.HttpStatus.INTERNAL_SERVER_ERROR,
+            error: "Internal Server Error",
+            message: "Internal server error",
+        });
+    }
+};
+exports.WorkflowExceptionFilter = WorkflowExceptionFilter;
+exports.WorkflowExceptionFilter = WorkflowExceptionFilter = WorkflowExceptionFilter_1 = __decorate([
+    (0, common_1.Catch)(core_1.WorkflowError)
+], WorkflowExceptionFilter);
+//# sourceMappingURL=workflow-exception.filter.js.map

package/dist/cjs/index.d.ts

@@ -10,9 +10,10 @@ export { WorkflowInstanceController } from "./controllers/workflow-instance.cont
 export { WorkflowEventController } from "./controllers/workflow-event.controller.js";
 export { WorkflowQueryController } from "./controllers/workflow-query.controller.js";
 export { WorkflowTimeoutController } from "./controllers/workflow-timeout.controller.js";
+export { WorkflowExceptionFilter } from "./filters/workflow-exception.filter.js";
 export { TriggerEventDto, TriggerEventParamsDto, HistoryQueryDto, HistoryParamsDto, AvailableEventsParamsDto, TimeoutProcessQueryDto, CreateInstanceDto, } from "./controllers/dto/index.js";
 export type { WorkflowDefinition, WorkflowStateDefinition, WorkflowEventDefinition, WorkflowOnEnterDefinition, WorkflowCommandRef, WorkflowTimeoutDefinition, CommandResult, WorkflowExecutionContext, WorkflowInstance, WorkflowExecutionResult, AvailableWorkflowEvent, CreateWorkflowInstanceInput, TriggerWorkflowEventInput, ProcessExpiredWorkflowsInput, ProcessExpiredWorkflowsResult, GetAvailableEventsInput, WorkflowInstanceStore, WorkflowHistoryStore, WorkflowHistoryRecord, WorkflowTransactionRunner, WorkflowClock, WorkflowPersistenceProvider, WorkflowDefinitionRegistry, WorkflowCommandRegistry, ValidationResult, ValidationError, CompiledWorkflow, OnEnterChainResult, OnEnterHopResult, WorkflowRuntimeClient, } from "@duraflows/core";
-export { WorkflowError, WorkflowDefinitionError, InvalidEventError, CommandFailureError, OnEnterDepthExceededError, WorkflowValidator, WorkflowCompiler, CommandExecutor, EventExecutor, OnEnterExecutor, TimeoutResolver, WorkflowRuntime, WorkflowHandle, InMemoryDefinitionRegistry, InMemoryCommandRegistry, InMemoryGuardRegistry, } from "@duraflows/core";
+export { WorkflowError, WorkflowDefinitionError, WorkflowInstanceNotFoundError, InvalidEventError, CommandFailureError, OnEnterDepthExceededError, WorkflowValidator, WorkflowCompiler, CommandExecutor, EventExecutor, OnEnterExecutor, TimeoutResolver, WorkflowRuntime, WorkflowHandle, InMemoryDefinitionRegistry, InMemoryCommandRegistry, InMemoryGuardRegistry, } from "@duraflows/core";
 export type { WorkflowObserver, StateEnterEvent, ObserverErrorHandler } from "@duraflows/core";
 export type { WorkflowGuard, WorkflowGuardRef, WorkflowGuardRegistry } from "@duraflows/core";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryGuardRegistry = exports.InMemoryCommandRegistry = exports.InMemoryDefinitionRegistry = exports.WorkflowHandle = exports.WorkflowRuntime = exports.TimeoutResolver = exports.OnEnterExecutor = exports.EventExecutor = exports.CommandExecutor = exports.WorkflowCompiler = exports.WorkflowValidator = exports.OnEnterDepthExceededError = exports.CommandFailureError = exports.InvalidEventError = exports.WorkflowDefinitionError = exports.WorkflowError = exports.CreateInstanceDto = exports.TimeoutProcessQueryDto = exports.AvailableEventsParamsDto = exports.HistoryParamsDto = exports.HistoryQueryDto = exports.TriggerEventParamsDto = exports.TriggerEventDto = exports.WorkflowTimeoutController = exports.WorkflowQueryController = exports.WorkflowEventController = exports.WorkflowInstanceController = exports.WORKFLOW_COMMAND_METADATA_KEY = exports.WorkflowCommand = exports.NestCommandRegistry = exports.WORKFLOW_CLOCK = exports.WORKFLOW_TRANSACTION_RUNNER = exports.WORKFLOW_DEFINITION_REGISTRY = exports.WORKFLOW_GUARD_REGISTRY = exports.WORKFLOW_COMMAND_REGISTRY = exports.WORKFLOW_HISTORY_STORE = exports.WORKFLOW_INSTANCE_STORE = exports.WORKFLOW_RUNTIME = exports.WorkflowTimeoutService = exports.WorkflowService = exports.WorkflowModule = void 0;
+exports.InMemoryGuardRegistry = exports.InMemoryCommandRegistry = exports.InMemoryDefinitionRegistry = exports.WorkflowHandle = exports.WorkflowRuntime = exports.TimeoutResolver = exports.OnEnterExecutor = exports.EventExecutor = exports.CommandExecutor = exports.WorkflowCompiler = exports.WorkflowValidator = exports.OnEnterDepthExceededError = exports.CommandFailureError = exports.InvalidEventError = exports.WorkflowInstanceNotFoundError = exports.WorkflowDefinitionError = exports.WorkflowError = exports.CreateInstanceDto = exports.TimeoutProcessQueryDto = exports.AvailableEventsParamsDto = exports.HistoryParamsDto = exports.HistoryQueryDto = exports.TriggerEventParamsDto = exports.TriggerEventDto = exports.WorkflowExceptionFilter = exports.WorkflowTimeoutController = exports.WorkflowQueryController = exports.WorkflowEventController = exports.WorkflowInstanceController = exports.WORKFLOW_COMMAND_METADATA_KEY = exports.WorkflowCommand = exports.NestCommandRegistry = exports.WORKFLOW_CLOCK = exports.WORKFLOW_TRANSACTION_RUNNER = exports.WORKFLOW_DEFINITION_REGISTRY = exports.WORKFLOW_GUARD_REGISTRY = exports.WORKFLOW_COMMAND_REGISTRY = exports.WORKFLOW_HISTORY_STORE = exports.WORKFLOW_INSTANCE_STORE = exports.WORKFLOW_RUNTIME = exports.WorkflowTimeoutService = exports.WorkflowService = exports.WorkflowModule = void 0;
 // Module
 var workflow_module_js_1 = require("./workflow.module.js");
 Object.defineProperty(exports, "WorkflowModule", { enumerable: true, get: function () { return workflow_module_js_1.WorkflowModule; } });
@@ -34,6 +34,9 @@ var workflow_query_controller_js_1 = require("./controllers/workflow-query.contr
 Object.defineProperty(exports, "WorkflowQueryController", { enumerable: true, get: function () { return workflow_query_controller_js_1.WorkflowQueryController; } });
 var workflow_timeout_controller_js_1 = require("./controllers/workflow-timeout.controller.js");
 Object.defineProperty(exports, "WorkflowTimeoutController", { enumerable: true, get: function () { return workflow_timeout_controller_js_1.WorkflowTimeoutController; } });
+// Filters
+var workflow_exception_filter_js_1 = require("./filters/workflow-exception.filter.js");
+Object.defineProperty(exports, "WorkflowExceptionFilter", { enumerable: true, get: function () { return workflow_exception_filter_js_1.WorkflowExceptionFilter; } });
 // DTOs
 var index_js_1 = require("./controllers/dto/index.js");
 Object.defineProperty(exports, "TriggerEventDto", { enumerable: true, get: function () { return index_js_1.TriggerEventDto; } });
@@ -46,6 +49,7 @@ Object.defineProperty(exports, "CreateInstanceDto", { enumerable: true, get: fun
 var core_1 = require("@duraflows/core");
 Object.defineProperty(exports, "WorkflowError", { enumerable: true, get: function () { return core_1.WorkflowError; } });
 Object.defineProperty(exports, "WorkflowDefinitionError", { enumerable: true, get: function () { return core_1.WorkflowDefinitionError; } });
+Object.defineProperty(exports, "WorkflowInstanceNotFoundError", { enumerable: true, get: function () { return core_1.WorkflowInstanceNotFoundError; } });
 Object.defineProperty(exports, "InvalidEventError", { enumerable: true, get: function () { return core_1.InvalidEventError; } });
 Object.defineProperty(exports, "CommandFailureError", { enumerable: true, get: function () { return core_1.CommandFailureError; } });
 Object.defineProperty(exports, "OnEnterDepthExceededError", { enumerable: true, get: function () { return core_1.OnEnterDepthExceededError; } });

package/dist/cjs/providers/nest-command-registry.js

@@ -19,7 +19,24 @@ class NestCommandRegistry {
         if (!cls) {
             throw new core_1.WorkflowError(`Command "${name}" not found in registry`);
         }
-        return this.moduleRef.get(cls, { strict: false });
+        try {
+            return this.moduleRef.get(cls, { strict: false });
+        }
+        catch (error) {
+            // `ModuleRef.get()` fails for many reasons — a missing provider, a
+            // circular dependency, a throwing constructor — not only unsupported
+            // scopes. Wrap every failure with a generic resolution message and only
+            // add the singleton-scope hint when the underlying error is Nest's
+            // scoped-provider rejection, so the guidance is never misleading. The
+            // original error is attached as the cause either way.
+            let message = `Command "${name}" could not be resolved from the NestJS container.`;
+            if (isScopedProviderError(error)) {
+                message +=
+                    ` Workflow command providers must be singleton-scoped (the default); ` +
+                        `REQUEST- and TRANSIENT-scoped providers are not supported.`;
+            }
+            throw new core_1.WorkflowError(message, error);
+        }
     }
     has(name) {
         return this.registrations.has(name);
@@ -29,4 +46,16 @@ class NestCommandRegistry {
     }
 }
 exports.NestCommandRegistry = NestCommandRegistry;
+/**
+ * Nest throws `InvalidClassScopeException` (message: "... is marked as a scoped
+ * provider ...") when `get()` is called on a REQUEST/TRANSIENT provider. That
+ * class is not part of Nest's public API, so match on the constructor name with
+ * a message-content fallback to survive version drift.
+ */
+function isScopedProviderError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.constructor.name === "InvalidClassScopeException" || /scoped provider/i.test(error.message);
+}
 //# sourceMappingURL=nest-command-registry.js.map

package/dist/cjs/workflow.module.d.ts

@@ -1,4 +1,4 @@
-import { type DynamicModule, type Type, type InjectionToken } from "@nestjs/common";
+import { type DynamicModule, type Type, type InjectionToken, type OptionalFactoryDependency } from "@nestjs/common";
 import type { WorkflowDefinition, WorkflowClock, WorkflowPersistenceProvider, WorkflowObserver, ObserverErrorHandler, WorkflowGuard, WorkflowGuardRegistry } from "@duraflows/core";
 import { type WorkflowCommandRegistration } from "./providers/nest-command-registry.js";
 export interface WorkflowModuleOptions {
@@ -26,7 +26,14 @@ export interface WorkflowModuleAsyncOptions<TArgs extends unknown[] = unknown[]>
     commands?: WorkflowCommandRegistration[];
     enableControllers?: boolean;
     useFactory: (...args: TArgs) => Promise<WorkflowModuleFactoryConfig> | WorkflowModuleFactoryConfig;
-    inject?: InjectionToken[];
+    /**
+     * DI tokens resolved and passed to `useFactory`, positionally. The tuple
+     * length is type-checked against the factory's parameter list when `TArgs`
+     * is supplied (e.g. `forRootAsync<[Pool, AuditObserver]>({ ... })`).
+     */
+    inject?: {
+        [K in keyof TArgs]: InjectionToken | OptionalFactoryDependency;
+    };
 }
 export declare class WorkflowModule {
     static forRoot(options: WorkflowModuleOptions): DynamicModule;

package/dist/cjs/workflow.module.js

@@ -20,6 +20,12 @@ const workflow_event_controller_js_1 = require("./controllers/workflow-event.con
 const workflow_query_controller_js_1 = require("./controllers/workflow-query.controller.js");
 const workflow_timeout_controller_js_1 = require("./controllers/workflow-timeout.controller.js");
 const workflow_instance_controller_js_1 = require("./controllers/workflow-instance.controller.js");
+// Surfaces non-fatal definition warnings (e.g. unreachable states) that the
+// registry would otherwise compute and discard.
+const validationLogger = new common_1.Logger("WorkflowModule");
+const logValidationWarning = (workflowName, warning) => {
+    validationLogger.warn(`Workflow "${workflowName}": ${warning.message} (${warning.path})`);
+};
 const EXPORTED_TOKENS = [
     workflow_service_js_1.WorkflowService,
     workflow_timeout_service_js_1.WorkflowTimeoutService,
@@ -56,10 +62,9 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
             },
             {
                 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 && 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.");
-                    }
                     if (options.guardRegistry)
                         return options.guardRegistry;
                     const registry = new core_2.InMemoryGuardRegistry();
@@ -81,6 +86,7 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
                         validator: new core_2.WorkflowValidator(),
                         compiler: new core_2.WorkflowCompiler(),
                         validationOptions: { knownCommandNames, knownGuardNames },
+                        onValidationWarning: logValidationWarning,
                     });
                     for (const workflow of options.workflows) {
                         registry.register(workflow);
@@ -149,7 +155,7 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
         const configProvider = {
             provide: "WORKFLOW_MODULE_OPTIONS",
             useFactory: options.useFactory,
-            inject: options.inject ?? [],
+            inject: (options.inject ?? []),
         };
         const providers = [
             configProvider,
@@ -191,6 +197,7 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
                         validator: new core_2.WorkflowValidator(),
                         compiler: new core_2.WorkflowCompiler(),
                         validationOptions: { knownCommandNames, knownGuardNames },
+                        onValidationWarning: logValidationWarning,
                     });
                     for (const workflow of config.workflows) {
                         registry.register(workflow);

package/dist/controllers/dto/history-query.dto.d.ts

@@ -1,6 +1,6 @@
 export declare class HistoryQueryDto {
-    limit?: string;
-    offset?: string;
+    limit?: number;
+    offset?: number;
 }
 export declare class HistoryParamsDto {
     workflowInstanceUuid: string;

package/dist/controllers/dto/history-query.dto.js

@@ -7,20 +7,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { IsOptional, IsNumberString, IsUUID } from "class-validator";
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsUUID, Max, Min } from "class-validator";
 export class HistoryQueryDto {
     limit;
     offset;
 }
 __decorate([
     IsOptional(),
-    IsNumberString(),
-    __metadata("design:type", String)
+    Type(() => Number),
+    IsInt(),
+    Min(1),
+    Max(500),
+    __metadata("design:type", Number)
 ], HistoryQueryDto.prototype, "limit", void 0);
 __decorate([
     IsOptional(),
-    IsNumberString(),
-    __metadata("design:type", String)
+    Type(() => Number),
+    IsInt(),
+    Min(0),
+    __metadata("design:type", Number)
 ], HistoryQueryDto.prototype, "offset", void 0);
 export class HistoryParamsDto {
     workflowInstanceUuid;

package/dist/controllers/dto/timeout-process.dto.d.ts

@@ -1,4 +1,4 @@
 export declare class TimeoutProcessQueryDto {
-    limit?: string;
+    limit?: number;
 }
 //# sourceMappingURL=timeout-process.dto.d.ts.map

package/dist/controllers/dto/timeout-process.dto.js

@@ -7,13 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { IsOptional, IsNumberString } from "class-validator";
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, Max, Min } from "class-validator";
 export class TimeoutProcessQueryDto {
     limit;
 }
 __decorate([
     IsOptional(),
-    IsNumberString(),
-    __metadata("design:type", String)
+    Type(() => Number),
+    IsInt(),
+    Min(1),
+    Max(1000),
+    __metadata("design:type", Number)
 ], TimeoutProcessQueryDto.prototype, "limit", void 0);
 //# sourceMappingURL=timeout-process.dto.js.map

package/dist/controllers/workflow-event.controller.js

@@ -10,9 +10,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Post, Param, Body, UsePipes, ValidationPipe } from "@nestjs/common";
+import { Controller, Post, Param, Body, UsePipes, UseFilters, ValidationPipe } from "@nestjs/common";
 import { WorkflowService } from "../services/workflow.service.js";
 import { TriggerEventDto, TriggerEventParamsDto } from "./dto/index.js";
+import { WorkflowExceptionFilter } from "../filters/workflow-exception.filter.js";
 let WorkflowEventController = class WorkflowEventController {
     workflowService;
     constructor(workflowService) {
@@ -38,7 +39,8 @@ __decorate([
 ], WorkflowEventController.prototype, "triggerEvent", null);
 WorkflowEventController = __decorate([
     Controller("workflows"),
-    UsePipes(new ValidationPipe({ transform: true, whitelist: true })),
+    UseFilters(WorkflowExceptionFilter),
+    UsePipes(new ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [WorkflowService])
 ], WorkflowEventController);
 export { WorkflowEventController };

package/dist/controllers/workflow-instance.controller.js

@@ -10,9 +10,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Post, Get, Param, Body, UsePipes, ValidationPipe, NotFoundException, ParseUUIDPipe, } from "@nestjs/common";
+import { Controller, Post, Get, Param, Body, UsePipes, UseFilters, ValidationPipe, NotFoundException, ParseUUIDPipe, } from "@nestjs/common";
 import { WorkflowService } from "../services/workflow.service.js";
 import { CreateInstanceDto } from "./dto/index.js";
+import { WorkflowExceptionFilter } from "../filters/workflow-exception.filter.js";
 let WorkflowInstanceController = class WorkflowInstanceController {
     workflowService;
     constructor(workflowService) {
@@ -50,7 +51,8 @@ __decorate([
 ], WorkflowInstanceController.prototype, "getInstance", null);
 WorkflowInstanceController = __decorate([
     Controller("workflows"),
-    UsePipes(new ValidationPipe({ transform: true, whitelist: true })),
+    UseFilters(WorkflowExceptionFilter),
+    UsePipes(new ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [WorkflowService])
 ], WorkflowInstanceController);
 export { WorkflowInstanceController };

package/dist/controllers/workflow-query.controller.js

@@ -10,9 +10,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Get, Param, Query, UsePipes, ValidationPipe } from "@nestjs/common";
+import { Controller, Get, Param, Query, UsePipes, UseFilters, ValidationPipe } from "@nestjs/common";
 import { WorkflowService } from "../services/workflow.service.js";
 import { AvailableEventsParamsDto, HistoryQueryDto, HistoryParamsDto } from "./dto/index.js";
+import { WorkflowExceptionFilter } from "../filters/workflow-exception.filter.js";
 let WorkflowQueryController = class WorkflowQueryController {
     workflowService;
     constructor(workflowService) {
@@ -25,8 +26,8 @@ let WorkflowQueryController = class WorkflowQueryController {
     }
     async getHistory(params, query) {
         return this.workflowService.getHistory(params.workflowInstanceUuid, {
-            limit: query.limit ? parseInt(query.limit, 10) : undefined,
-            offset: query.offset ? parseInt(query.offset, 10) : undefined,
+            limit: query.limit,
+            offset: query.offset,
         });
     }
 };
@@ -48,7 +49,8 @@ __decorate([
 ], WorkflowQueryController.prototype, "getHistory", null);
 WorkflowQueryController = __decorate([
     Controller("workflows"),
-    UsePipes(new ValidationPipe({ transform: true, whitelist: true })),
+    UseFilters(WorkflowExceptionFilter),
+    UsePipes(new ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [WorkflowService])
 ], WorkflowQueryController);
 export { WorkflowQueryController };

package/dist/controllers/workflow-timeout.controller.js

@@ -10,16 +10,17 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Post, Query, UsePipes, ValidationPipe } from "@nestjs/common";
+import { Controller, Post, Query, UsePipes, UseFilters, ValidationPipe } from "@nestjs/common";
 import { WorkflowTimeoutService } from "../services/workflow-timeout.service.js";
 import { TimeoutProcessQueryDto } from "./dto/index.js";
+import { WorkflowExceptionFilter } from "../filters/workflow-exception.filter.js";
 let WorkflowTimeoutController = class WorkflowTimeoutController {
     timeoutService;
     constructor(timeoutService) {
         this.timeoutService = timeoutService;
     }
     async processExpired(query) {
-        return this.timeoutService.processExpiredWorkflows(query.limit ? parseInt(query.limit, 10) : undefined);
+        return this.timeoutService.processExpiredWorkflows(query.limit);
     }
 };
 __decorate([
@@ -31,7 +32,8 @@ __decorate([
 ], WorkflowTimeoutController.prototype, "processExpired", null);
 WorkflowTimeoutController = __decorate([
     Controller("workflows/timeouts"),
-    UsePipes(new ValidationPipe({ transform: true, whitelist: true })),
+    UseFilters(WorkflowExceptionFilter),
+    UsePipes(new ValidationPipe({ transform: true, whitelist: true, forbidNonWhitelisted: true })),
     __metadata("design:paramtypes", [WorkflowTimeoutService])
 ], WorkflowTimeoutController);
 export { WorkflowTimeoutController };

package/dist/filters/workflow-exception.filter.d.ts

@@ -0,0 +1,13 @@
+import { type ArgumentsHost, type ExceptionFilter } from "@nestjs/common";
+import { WorkflowError } 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
+ * for the current state surfaces as a generic 500 and leaks internal
+ * messages.
+ */
+export declare class WorkflowExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: WorkflowError, host: ArgumentsHost): void;
+}
+//# sourceMappingURL=workflow-exception.filter.d.ts.map