@unlaxer/tramli 1.10.0 → 1.12.0

package/dist/cjs/flow-definition.d.ts

@@ -11,6 +11,11 @@ export declare class FlowDefinition<S extends string> {
     readonly initialState: S | null;
     readonly terminalStates: Set<S>;
     readonly dataFlowGraph: DataFlowGraph<S> | null;
+    readonly warnings: string[];
+    readonly exceptionRoutes: Map<S, Array<{
+        errorClass: new (...args: any[]) => Error;
+        target: S;
+    }>>;
     private constructor();
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;
@@ -28,6 +33,7 @@ export declare class Builder<S extends string> {
     private maxGuardRetries;
     private readonly transitions;
     private readonly errorTransitions;
+    private readonly _exceptionRoutes;
     private readonly initiallyAvailableKeys;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
@@ -35,6 +41,8 @@ export declare class Builder<S extends string> {
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;
     onError(from: S, to: S): this;
+    /** Route specific error types to specific states. Checked before onError. */
+    onStepError(from: S, errorClass: new (...args: any[]) => Error, to: S): this;
     onAnyError(errorState: S): this;
     /** @internal */
     addTransition(t: Transition<S>): void;

package/dist/cjs/flow-definition.js

@@ -13,6 +13,8 @@ class FlowDefinition {
     initialState;
     terminalStates;
     dataFlowGraph;
+    warnings;
+    exceptionRoutes;
     constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -89,6 +91,7 @@ class Builder {
     maxGuardRetries = 3;
     transitions = [];
     errorTransitions = new Map();
+    _exceptionRoutes = new Map();
     initiallyAvailableKeys = [];
     constructor(name, stateConfig) {
         this.name = name;
@@ -108,6 +111,13 @@ class Builder {
         this.errorTransitions.set(from, to);
         return this;
     }
+    /** Route specific error types to specific states. Checked before onError. */
+    onStepError(from, errorClass, to) {
+        if (!this._exceptionRoutes.has(from))
+            this._exceptionRoutes.set(from, []);
+        this._exceptionRoutes.get(from).push({ errorClass, target: to });
+        return this;
+    }
     onAnyError(errorState) {
         for (const s of Object.keys(this.stateConfig)) {
             if (!this.stateConfig[s].terminal)
@@ -143,6 +153,15 @@ class Builder {
         result.dataFlowGraph = null;
         this.validate(result);
         result.dataFlowGraph = data_flow_graph_js_1.DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        // Build warnings
+        const warnings = [];
+        const perpetual = terminals.size === 0;
+        const hasExternal = this.transitions.some(t => t.type === 'external');
+        if (perpetual && hasExternal) {
+            warnings.push(`Perpetual flow '${this.name}' has External transitions — ensure events are always delivered to avoid deadlock (liveness risk)`);
+        }
+        result.warnings = warnings;
+        result.exceptionRoutes = new Map(this._exceptionRoutes);
         return result;
     }
     validate(def) {

package/dist/cjs/flow-engine.js

@@ -266,6 +266,23 @@ class FlowEngine {
             }
         }
         this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
+        // 1. Try exception-typed routes first (onStepError)
+        if (cause && flow.definition.exceptionRoutes) {
+            const routes = flow.definition.exceptionRoutes.get(fromState);
+            if (routes) {
+                for (const route of routes) {
+                    if (cause instanceof route.errorClass) {
+                        const from = flow.currentState;
+                        flow.transitionTo(route.target);
+                        this.store.recordTransition(flow.id, from, route.target, `error:${cause.constructor.name}`, flow.context);
+                        if (flow.definition.stateConfig[route.target].terminal)
+                            flow.complete(route.target);
+                        return;
+                    }
+                }
+            }
+        }
+        // 2. Fall back to state-based error transition (onError)
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

package/dist/esm/flow-definition.d.ts

@@ -11,6 +11,11 @@ export declare class FlowDefinition<S extends string> {
     readonly initialState: S | null;
     readonly terminalStates: Set<S>;
     readonly dataFlowGraph: DataFlowGraph<S> | null;
+    readonly warnings: string[];
+    readonly exceptionRoutes: Map<S, Array<{
+        errorClass: new (...args: any[]) => Error;
+        target: S;
+    }>>;
     private constructor();
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;
@@ -28,6 +33,7 @@ export declare class Builder<S extends string> {
     private maxGuardRetries;
     private readonly transitions;
     private readonly errorTransitions;
+    private readonly _exceptionRoutes;
     private readonly initiallyAvailableKeys;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
@@ -35,6 +41,8 @@ export declare class Builder<S extends string> {
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;
     onError(from: S, to: S): this;
+    /** Route specific error types to specific states. Checked before onError. */
+    onStepError(from: S, errorClass: new (...args: any[]) => Error, to: S): this;
     onAnyError(errorState: S): this;
     /** @internal */
     addTransition(t: Transition<S>): void;

package/dist/esm/flow-definition.js

@@ -10,6 +10,8 @@ export class FlowDefinition {
     initialState;
     terminalStates;
     dataFlowGraph;
+    warnings;
+    exceptionRoutes;
     constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -85,6 +87,7 @@ export class Builder {
     maxGuardRetries = 3;
     transitions = [];
     errorTransitions = new Map();
+    _exceptionRoutes = new Map();
     initiallyAvailableKeys = [];
     constructor(name, stateConfig) {
         this.name = name;
@@ -104,6 +107,13 @@ export class Builder {
         this.errorTransitions.set(from, to);
         return this;
     }
+    /** Route specific error types to specific states. Checked before onError. */
+    onStepError(from, errorClass, to) {
+        if (!this._exceptionRoutes.has(from))
+            this._exceptionRoutes.set(from, []);
+        this._exceptionRoutes.get(from).push({ errorClass, target: to });
+        return this;
+    }
     onAnyError(errorState) {
         for (const s of Object.keys(this.stateConfig)) {
             if (!this.stateConfig[s].terminal)
@@ -139,6 +149,15 @@ export class Builder {
         result.dataFlowGraph = null;
         this.validate(result);
         result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        // Build warnings
+        const warnings = [];
+        const perpetual = terminals.size === 0;
+        const hasExternal = this.transitions.some(t => t.type === 'external');
+        if (perpetual && hasExternal) {
+            warnings.push(`Perpetual flow '${this.name}' has External transitions — ensure events are always delivered to avoid deadlock (liveness risk)`);
+        }
+        result.warnings = warnings;
+        result.exceptionRoutes = new Map(this._exceptionRoutes);
         return result;
     }
     validate(def) {

package/dist/esm/flow-engine.js

@@ -263,6 +263,23 @@ export class FlowEngine {
             }
         }
         this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
+        // 1. Try exception-typed routes first (onStepError)
+        if (cause && flow.definition.exceptionRoutes) {
+            const routes = flow.definition.exceptionRoutes.get(fromState);
+            if (routes) {
+                for (const route of routes) {
+                    if (cause instanceof route.errorClass) {
+                        const from = flow.currentState;
+                        flow.transitionTo(route.target);
+                        this.store.recordTransition(flow.id, from, route.target, `error:${cause.constructor.name}`, flow.context);
+                        if (flow.definition.stateConfig[route.target].terminal)
+                            flow.complete(route.target);
+                        return;
+                    }
+                }
+            }
+        }
+        // 2. Fall back to state-based error transition (onError)
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {