@unlaxer/tramli 1.13.0 → 1.15.0

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

@@ -68,7 +68,10 @@ export declare class FromBuilder<S extends string> {
     private readonly fromState;
     constructor(builder: Builder<S>, fromState: S);
     auto(to: S, processor: StateProcessor<S>): Builder<S>;
-    external(to: S, guard: TransitionGuard<S>, processor?: StateProcessor<S>): Builder<S>;
+    external(to: S, guard: TransitionGuard<S>, processorOrOptions?: StateProcessor<S> | {
+        processor?: StateProcessor<S>;
+        timeout?: number;
+    }): Builder<S>;
     branch(branch: BranchProcessor<S>): BranchBuilder<S>;
     subFlow(subFlowDef: FlowDefinition<any>): SubFlowBuilder<S>;
 }

package/dist/cjs/flow-definition.js

@@ -434,10 +434,20 @@ class FromBuilder {
         });
         return this.builder;
     }
-    external(to, guard, processor) {
+    external(to, guard, processorOrOptions) {
+        let processor;
+        let timeout;
+        if (processorOrOptions && 'process' in processorOrOptions) {
+            processor = processorOrOptions;
+        }
+        else if (processorOrOptions) {
+            const opts = processorOrOptions;
+            processor = opts.processor;
+            timeout = opts.timeout;
+        }
         this.builder.addTransition({
             from: this.fromState, to, type: 'external', processor,
-            guard, branch: undefined, branchTargets: new Map(),
+            guard, branch: undefined, branchTargets: new Map(), timeout,
         });
         return this.builder;
     }

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

@@ -1,6 +1,8 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+/** Default max auto-chain depth. Override via constructor options. */
+export declare const DEFAULT_MAX_CHAIN_DEPTH = 10;
 /** Log entry types for tramli's pluggable logger API. */
 export interface TransitionLogEntry {
     flowId: string;
@@ -24,11 +26,13 @@ export interface ErrorLogEntry {
 export declare class FlowEngine {
     private readonly store;
     private readonly strictMode;
+    private readonly maxChainDepth;
     private transitionLogger?;
     private stateLogger?;
     private errorLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
+        maxChainDepth?: number;
     });
     setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
     setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;

package/dist/cjs/flow-engine.js

@@ -1,19 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlowEngine = void 0;
+exports.FlowEngine = exports.DEFAULT_MAX_CHAIN_DEPTH = void 0;
 const flow_context_js_1 = require("./flow-context");
 const flow_instance_js_1 = require("./flow-instance");
 const flow_error_js_1 = require("./flow-error");
-const MAX_CHAIN_DEPTH = 10;
+/** Default max auto-chain depth. Override via constructor options. */
+exports.DEFAULT_MAX_CHAIN_DEPTH = 10;
 class FlowEngine {
     store;
     strictMode;
+    maxChainDepth;
     transitionLogger;
     stateLogger;
     errorLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
+        this.maxChainDepth = options?.maxChainDepth ?? exports.DEFAULT_MAX_CHAIN_DEPTH;
     }
     setTransitionLogger(logger) {
         this.transitionLogger = logger ?? undefined;
@@ -65,6 +68,15 @@ class FlowEngine {
         const transition = definition.externalFrom(currentState);
         if (!transition)
             throw flow_error_js_1.FlowError.invalidTransition(currentState, currentState);
+        // Per-state timeout check
+        if (transition.timeout != null) {
+            const deadline = new Date(flow.stateEnteredAt.getTime() + transition.timeout);
+            if (new Date() > deadline) {
+                flow.complete('EXPIRED');
+                this.store.save(flow);
+                return flow;
+            }
+        }
         const guard = transition.guard;
         if (guard) {
             const output = await guard.validate(flow.context);
@@ -116,7 +128,7 @@ class FlowEngine {
     }
     async executeAutoChain(flow) {
         let depth = 0;
-        while (depth < MAX_CHAIN_DEPTH) {
+        while (depth < this.maxChainDepth) {
             const current = flow.currentState;
             if (flow.definition.stateConfig[current].terminal) {
                 flow.complete(current);
@@ -168,7 +180,7 @@ class FlowEngine {
             }
             depth++;
         }
-        if (depth >= MAX_CHAIN_DEPTH)
+        if (depth >= this.maxChainDepth)
             throw flow_error_js_1.FlowError.maxChainDepth();
     }
     async executeSubFlow(parentFlow, subFlowTransition) {

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

@@ -1,10 +1,15 @@
+export type FlowErrorType = 'BUSINESS' | 'SYSTEM' | 'RETRYABLE' | 'FATAL';
 export declare class FlowError extends Error {
     readonly code: string;
+    /** Error type classification for retry/recovery strategy. */
+    errorType?: FlowErrorType;
     /** Types that were available in context when the error occurred. */
     availableTypes?: Set<string>;
     /** Types that were expected but missing (if applicable). */
     missingTypes?: Set<string>;
     constructor(code: string, message: string);
+    /** Attach error type classification. */
+    withErrorType(type: FlowErrorType): this;
     /** Attach context snapshot to this error. */
     withContextSnapshot(available: Set<string>, missing: Set<string>): this;
     static invalidTransition(from: string, to: string): FlowError;

package/dist/cjs/flow-error.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowError = void 0;
 class FlowError extends Error {
     code;
+    /** Error type classification for retry/recovery strategy. */
+    errorType;
     /** Types that were available in context when the error occurred. */
     availableTypes;
     /** Types that were expected but missing (if applicable). */
@@ -12,6 +14,11 @@ class FlowError extends Error {
         this.code = code;
         this.name = 'FlowError';
     }
+    /** Attach error type classification. */
+    withErrorType(type) {
+        this.errorType = type;
+        return this;
+    }
     /** Attach context snapshot to this error. */
     withContextSnapshot(available, missing) {
         this.availableTypes = available;

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

@@ -13,6 +13,7 @@ export declare class FlowInstance<S extends string> {
     private _exitState;
     private _activeSubFlow;
     private _lastError;
+    private _stateEnteredAt;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -39,6 +40,7 @@ export declare class FlowInstance<S extends string> {
     waitingFor(): string[];
     /** Return a copy with the given version. For FlowStore optimistic locking. */
     withVersion(newVersion: number): FlowInstance<S>;
+    get stateEnteredAt(): Date;
     /** @internal */ transitionTo(state: S): void;
     /** @internal */ incrementGuardFailure(): void;
     /** @internal */ complete(exitState: string): void;

package/dist/cjs/flow-instance.js

@@ -14,6 +14,7 @@ class FlowInstance {
     _exitState;
     _activeSubFlow = null;
     _lastError = null;
+    _stateEnteredAt = new Date();
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -98,7 +99,8 @@ class FlowInstance {
         copy.setActiveSubFlow(this._activeSubFlow);
         return copy;
     }
-    /** @internal */ transitionTo(state) { this._currentState = state; }
+    get stateEnteredAt() { return this._stateEnteredAt; }
+    /** @internal */ transitionTo(state) { this._currentState = state; this._stateEnteredAt = new Date(); }
     /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }

package/dist/cjs/types.d.ts

@@ -28,6 +28,8 @@ export interface Transition<S extends string> {
     branchTargets: Map<string, S>;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
+    /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */
+    timeout?: number;
 }
 /**
  * Processes a state transition.

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

@@ -68,7 +68,10 @@ export declare class FromBuilder<S extends string> {
     private readonly fromState;
     constructor(builder: Builder<S>, fromState: S);
     auto(to: S, processor: StateProcessor<S>): Builder<S>;
-    external(to: S, guard: TransitionGuard<S>, processor?: StateProcessor<S>): Builder<S>;
+    external(to: S, guard: TransitionGuard<S>, processorOrOptions?: StateProcessor<S> | {
+        processor?: StateProcessor<S>;
+        timeout?: number;
+    }): Builder<S>;
     branch(branch: BranchProcessor<S>): BranchBuilder<S>;
     subFlow(subFlowDef: FlowDefinition<any>): SubFlowBuilder<S>;
 }

package/dist/esm/flow-definition.js

@@ -429,10 +429,20 @@ export class FromBuilder {
         });
         return this.builder;
     }
-    external(to, guard, processor) {
+    external(to, guard, processorOrOptions) {
+        let processor;
+        let timeout;
+        if (processorOrOptions && 'process' in processorOrOptions) {
+            processor = processorOrOptions;
+        }
+        else if (processorOrOptions) {
+            const opts = processorOrOptions;
+            processor = opts.processor;
+            timeout = opts.timeout;
+        }
         this.builder.addTransition({
             from: this.fromState, to, type: 'external', processor,
-            guard, branch: undefined, branchTargets: new Map(),
+            guard, branch: undefined, branchTargets: new Map(), timeout,
         });
         return this.builder;
     }

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

@@ -1,6 +1,8 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+/** Default max auto-chain depth. Override via constructor options. */
+export declare const DEFAULT_MAX_CHAIN_DEPTH = 10;
 /** Log entry types for tramli's pluggable logger API. */
 export interface TransitionLogEntry {
     flowId: string;
@@ -24,11 +26,13 @@ export interface ErrorLogEntry {
 export declare class FlowEngine {
     private readonly store;
     private readonly strictMode;
+    private readonly maxChainDepth;
     private transitionLogger?;
     private stateLogger?;
     private errorLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
+        maxChainDepth?: number;
     });
     setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
     setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;

package/dist/esm/flow-engine.js

@@ -1,16 +1,19 @@
 import { FlowContext } from './flow-context.js';
 import { FlowInstance } from './flow-instance.js';
 import { FlowError } from './flow-error.js';
-const MAX_CHAIN_DEPTH = 10;
+/** Default max auto-chain depth. Override via constructor options. */
+export const DEFAULT_MAX_CHAIN_DEPTH = 10;
 export class FlowEngine {
     store;
     strictMode;
+    maxChainDepth;
     transitionLogger;
     stateLogger;
     errorLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
+        this.maxChainDepth = options?.maxChainDepth ?? DEFAULT_MAX_CHAIN_DEPTH;
     }
     setTransitionLogger(logger) {
         this.transitionLogger = logger ?? undefined;
@@ -62,6 +65,15 @@ export class FlowEngine {
         const transition = definition.externalFrom(currentState);
         if (!transition)
             throw FlowError.invalidTransition(currentState, currentState);
+        // Per-state timeout check
+        if (transition.timeout != null) {
+            const deadline = new Date(flow.stateEnteredAt.getTime() + transition.timeout);
+            if (new Date() > deadline) {
+                flow.complete('EXPIRED');
+                this.store.save(flow);
+                return flow;
+            }
+        }
         const guard = transition.guard;
         if (guard) {
             const output = await guard.validate(flow.context);
@@ -113,7 +125,7 @@ export class FlowEngine {
     }
     async executeAutoChain(flow) {
         let depth = 0;
-        while (depth < MAX_CHAIN_DEPTH) {
+        while (depth < this.maxChainDepth) {
             const current = flow.currentState;
             if (flow.definition.stateConfig[current].terminal) {
                 flow.complete(current);
@@ -165,7 +177,7 @@ export class FlowEngine {
             }
             depth++;
         }
-        if (depth >= MAX_CHAIN_DEPTH)
+        if (depth >= this.maxChainDepth)
             throw FlowError.maxChainDepth();
     }
     async executeSubFlow(parentFlow, subFlowTransition) {

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

@@ -1,10 +1,15 @@
+export type FlowErrorType = 'BUSINESS' | 'SYSTEM' | 'RETRYABLE' | 'FATAL';
 export declare class FlowError extends Error {
     readonly code: string;
+    /** Error type classification for retry/recovery strategy. */
+    errorType?: FlowErrorType;
     /** Types that were available in context when the error occurred. */
     availableTypes?: Set<string>;
     /** Types that were expected but missing (if applicable). */
     missingTypes?: Set<string>;
     constructor(code: string, message: string);
+    /** Attach error type classification. */
+    withErrorType(type: FlowErrorType): this;
     /** Attach context snapshot to this error. */
     withContextSnapshot(available: Set<string>, missing: Set<string>): this;
     static invalidTransition(from: string, to: string): FlowError;

package/dist/esm/flow-error.js

@@ -1,5 +1,7 @@
 export class FlowError extends Error {
     code;
+    /** Error type classification for retry/recovery strategy. */
+    errorType;
     /** Types that were available in context when the error occurred. */
     availableTypes;
     /** Types that were expected but missing (if applicable). */
@@ -9,6 +11,11 @@ export class FlowError extends Error {
         this.code = code;
         this.name = 'FlowError';
     }
+    /** Attach error type classification. */
+    withErrorType(type) {
+        this.errorType = type;
+        return this;
+    }
     /** Attach context snapshot to this error. */
     withContextSnapshot(available, missing) {
         this.availableTypes = available;

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

@@ -13,6 +13,7 @@ export declare class FlowInstance<S extends string> {
     private _exitState;
     private _activeSubFlow;
     private _lastError;
+    private _stateEnteredAt;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -39,6 +40,7 @@ export declare class FlowInstance<S extends string> {
     waitingFor(): string[];
     /** Return a copy with the given version. For FlowStore optimistic locking. */
     withVersion(newVersion: number): FlowInstance<S>;
+    get stateEnteredAt(): Date;
     /** @internal */ transitionTo(state: S): void;
     /** @internal */ incrementGuardFailure(): void;
     /** @internal */ complete(exitState: string): void;

package/dist/esm/flow-instance.js

@@ -11,6 +11,7 @@ export class FlowInstance {
     _exitState;
     _activeSubFlow = null;
     _lastError = null;
+    _stateEnteredAt = new Date();
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -95,7 +96,8 @@ export class FlowInstance {
         copy.setActiveSubFlow(this._activeSubFlow);
         return copy;
     }
-    /** @internal */ transitionTo(state) { this._currentState = state; }
+    get stateEnteredAt() { return this._stateEnteredAt; }
+    /** @internal */ transitionTo(state) { this._currentState = state; this._stateEnteredAt = new Date(); }
     /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }

package/dist/esm/types.d.ts

@@ -28,6 +28,8 @@ export interface Transition<S extends string> {
     branchTargets: Map<string, S>;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
+    /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */
+    timeout?: number;
 }
 /**
  * Processes a state transition.

package/package.json

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