@unlaxer/tramli 1.14.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.js

@@ -68,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);

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.js

@@ -65,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);

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.14.0",
+  "version": "1.15.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {