@duraflows/nestjs 2.0.0 → 3.0.0

package/README.md

@@ -7,7 +7,9 @@ Part of the [duraflows](https://github.com/camcima/duraflows) monorepo.
 ## Features
 
 - Dynamic NestJS module with `forRoot()` and `forRootAsync()` configuration
+- Registered as a **global module** -- feature modules can inject `WorkflowService` without re-importing `WorkflowModule.forRoot()`
 - `WorkflowService` for creating instances, triggering events, and querying state
+- Type-safe `createInstanceFor()` / `triggerEventFor()` variants that narrow `currentState` / `fromState` / `toState` to the state union of a `WorkflowDefinition<TState>`
 - `WorkflowTimeoutService` for processing expired workflows
 - Optional REST controllers for full HTTP API
 - `@WorkflowCommand` decorator with automatic discovery
@@ -98,6 +100,40 @@ export class OrderService {
 }
 ```
 
+### Type-Safe Variants
+
+When you have a typed `WorkflowDefinition<TState>` in hand, use `createInstanceFor` / `triggerEventFor` to narrow `currentState`, `fromState`, and `toState` to the state union instead of `string`:
+
+```ts
+import type { WorkflowDefinition } from "@duraflows/nestjs";
+
+type OrderState = "new" | "paid" | "shipped" | "cancelled";
+
+const orderWorkflow: WorkflowDefinition<OrderState> = {
+  name: "order",
+  initialState: "new",
+  states: {
+    new: { events: { PaymentReceived: { targetState: "paid" }, Cancel: { targetState: "cancelled" } } },
+    paid: { events: { Ship: { targetState: "shipped" } } },
+    shipped: {},
+    cancelled: {},
+  },
+};
+
+// `instance.currentState` is typed as OrderState, not string
+const instance = await workflowService.createInstanceFor(orderWorkflow, {
+  metadata: { orderId: "abc" },
+});
+
+// `result.fromState` / `result.toState` are typed as OrderState
+const result = await workflowService.triggerEventFor(orderWorkflow, {
+  workflowInstanceUuid: instance.uuid,
+  eventName: "PaymentReceived",
+});
+```
+
+`triggerEventFor` does not verify at runtime that the instance belongs to the supplied definition -- the type narrowing is the caller's contract. Pair it with `createInstanceFor` to keep that invariant.
+
 ### @WorkflowCommand Decorator
 
 Mark command handlers for automatic discovery:
@@ -121,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/services/workflow.service.d.ts

@@ -1,10 +1,31 @@
 import { WorkflowHandle } from "@duraflows/core";
-import type { WorkflowRuntime, CreateWorkflowInstanceInput, TriggerWorkflowEventInput, GetAvailableEventsInput, WorkflowInstance, WorkflowExecutionResult, AvailableWorkflowEvent, WorkflowHistoryRecord } from "@duraflows/core";
+import type { WorkflowRuntime, CreateWorkflowInstanceInput, TriggerWorkflowEventInput, GetAvailableEventsInput, WorkflowDefinition, WorkflowInstance, WorkflowExecutionResult, AvailableWorkflowEvent, WorkflowHistoryRecord } from "@duraflows/core";
 export declare class WorkflowService {
     private readonly runtime;
     constructor(runtime: WorkflowRuntime);
     createInstance(input: CreateWorkflowInstanceInput): Promise<WorkflowInstance>;
+    /**
+     * Type-safe variant of {@link createInstance} that binds the resulting
+     * instance's `currentState` to the state union of the supplied
+     * `WorkflowDefinition`. Use when the caller has a typed definition in
+     * hand and wants to avoid widening `currentState` to `string`.
+     *
+     * The `workflowName` is read from the definition; callers pass only the
+     * non-name portion of `CreateWorkflowInstanceInput`.
+     */
+    createInstanceFor<TState extends string>(definition: WorkflowDefinition<TState>, input?: Omit<CreateWorkflowInstanceInput, "workflowName">): Promise<WorkflowInstance<TState>>;
     triggerEvent(input: TriggerWorkflowEventInput): Promise<WorkflowExecutionResult>;
+    /**
+     * Type-safe variant of {@link triggerEvent} that narrows the resulting
+     * `fromState`/`toState` to the state union of the supplied
+     * `WorkflowDefinition`. Use when the caller has a typed definition in
+     * hand and wants to avoid widening to `string`.
+     *
+     * Does not validate at runtime that the instance belongs to the given
+     * definition — that is the caller's responsibility (typically enforced
+     * upstream when the instance was created via `createInstanceFor`).
+     */
+    triggerEventFor<TState extends string>(definition: WorkflowDefinition<TState>, input: TriggerWorkflowEventInput): Promise<WorkflowExecutionResult<TState>>;
     getAvailableEvents(input: GetAvailableEventsInput): Promise<AvailableWorkflowEvent[]>;
     getInstance(uuid: string): Promise<WorkflowInstance | null>;
     getHistory(workflowInstanceUuid: string, options?: {

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

@@ -24,9 +24,44 @@ let WorkflowService = class WorkflowService {
     async createInstance(input) {
         return this.runtime.createInstance(input);
     }
+    /**
+     * Type-safe variant of {@link createInstance} that binds the resulting
+     * instance's `currentState` to the state union of the supplied
+     * `WorkflowDefinition`. Use when the caller has a typed definition in
+     * hand and wants to avoid widening `currentState` to `string`.
+     *
+     * The `workflowName` is read from the definition; callers pass only the
+     * non-name portion of `CreateWorkflowInstanceInput`.
+     */
+    async createInstanceFor(definition, input = {}) {
+        const instance = await this.runtime.createInstance({
+            ...input,
+            workflowName: definition.name,
+        });
+        // The runtime initialises `currentState` from `definition.initialState`,
+        // which is `TState`. Narrowing here is justified by that invariant.
+        return instance;
+    }
     async triggerEvent(input) {
         return this.runtime.triggerEvent(input);
     }
+    /**
+     * Type-safe variant of {@link triggerEvent} that narrows the resulting
+     * `fromState`/`toState` to the state union of the supplied
+     * `WorkflowDefinition`. Use when the caller has a typed definition in
+     * hand and wants to avoid widening to `string`.
+     *
+     * Does not validate at runtime that the instance belongs to the given
+     * definition — that is the caller's responsibility (typically enforced
+     * 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;
+        const result = await this.runtime.triggerEvent(input);
+        return result;
+    }
     async getAvailableEvents(input) {
         return this.runtime.getAvailableEvents(input);
     }

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);
@@ -133,6 +139,7 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
         ];
         return {
             module: WorkflowModule_1,
+            global: true, // allow downstream feature modules to inject WorkflowService without re-importing forRoot
             imports: [core_1.DiscoveryModule],
             controllers,
             providers,
@@ -148,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,
@@ -190,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);
@@ -247,6 +255,7 @@ let WorkflowModule = WorkflowModule_1 = class WorkflowModule {
         ];
         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,

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