@unlaxer/tramli 1.5.3 → 1.7.0

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

@@ -3,11 +3,15 @@ import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
 export declare class FlowEngine {
     private readonly store;
-    constructor(store: InMemoryFlowStore);
+    private readonly strictMode;
+    constructor(store: InMemoryFlowStore, options?: {
+        strictMode?: boolean;
+    });
     startFlow<S extends string>(definition: FlowDefinition<S>, sessionId: string, initialData: Map<string, unknown>): Promise<FlowInstance<S>>;
     resumeAndExecute<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData?: Map<string, unknown>): Promise<FlowInstance<S>>;
     private executeAutoChain;
     private executeSubFlow;
     private resumeSubFlow;
+    private verifyProduces;
     private handleError;
 }

package/dist/cjs/flow-engine.js

@@ -7,8 +7,10 @@ const flow_error_js_1 = require("./flow-error");
 const MAX_CHAIN_DEPTH = 10;
 class FlowEngine {
     store;
-    constructor(store) {
+    strictMode;
+    constructor(store, options) {
         this.store = store;
+        this.strictMode = options?.strictMode ?? false;
     }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
@@ -26,7 +28,7 @@ class FlowEngine {
         return flow;
     }
     async resumeAndExecute(flowId, definition, externalData) {
-        const flow = this.store.loadForUpdate(flowId);
+        const flow = this.store.loadForUpdate(flowId, definition);
         if (!flow)
             throw new flow_error_js_1.FlowError('FLOW_NOT_FOUND', `Flow ${flowId} not found or already completed`);
         if (externalData) {
@@ -63,9 +65,9 @@ class FlowEngine {
                         flow.transitionTo(transition.to);
                         this.store.recordTransition(flow.id, from, transition.to, guard.name, flow.context);
                     }
-                    catch {
+                    catch (e) {
                         flow.context.restoreFrom(backup);
-                        this.handleError(flow, currentState);
+                        this.handleError(flow, currentState, e instanceof Error ? e : new Error(String(e)));
                         this.store.save(flow);
                         return flow;
                     }
@@ -119,8 +121,10 @@ class FlowEngine {
             const backup = flow.context.snapshot();
             try {
                 if (autoOrBranch.type === 'auto') {
-                    if (autoOrBranch.processor)
+                    if (autoOrBranch.processor) {
                         await autoOrBranch.processor.process(flow.context);
+                        this.verifyProduces(autoOrBranch.processor, flow.context);
+                    }
                     const from = flow.currentState;
                     flow.transitionTo(autoOrBranch.to);
                     this.store.recordTransition(flow.id, from, autoOrBranch.to, autoOrBranch.processor?.name ?? 'auto', flow.context);
@@ -140,9 +144,9 @@ class FlowEngine {
                     this.store.recordTransition(flow.id, from, target, `${branch.name}:${label}`, flow.context);
                 }
             }
-            catch {
+            catch (e) {
                 flow.context.restoreFrom(backup);
-                this.handleError(flow, flow.currentState);
+                this.handleError(flow, flow.currentState, e instanceof Error ? e : new Error(String(e)));
                 return;
             }
             depth++;
@@ -225,7 +229,18 @@ class FlowEngine {
         this.store.save(parentFlow);
         return parentFlow;
     }
-    handleError(flow, fromState) {
+    verifyProduces(processor, ctx) {
+        if (!this.strictMode)
+            return;
+        for (const prod of processor.produces) {
+            if (!ctx.has(prod)) {
+                throw new flow_error_js_1.FlowError('PRODUCES_VIOLATION', `Processor '${processor.name}' declares produces ${prod} but did not put it in context (strictMode)`);
+            }
+        }
+    }
+    handleError(flow, fromState, cause) {
+        if (cause)
+            flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

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

@@ -12,6 +12,7 @@ export declare class FlowInstance<S extends string> {
     readonly expiresAt: Date;
     private _exitState;
     private _activeSubFlow;
+    private _lastError;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -24,6 +25,8 @@ export declare class FlowInstance<S extends string> {
     get exitState(): string | null;
     get isCompleted(): boolean;
     get activeSubFlow(): FlowInstance<any> | null;
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError(): string | null;
     /** State path from root to deepest active sub-flow. */
     statePath(): string[];
     /** State path as slash-separated string. */
@@ -41,4 +44,5 @@ export declare class FlowInstance<S extends string> {
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
     /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;
+    /** @internal */ setLastError(error: string | null): void;
 }

package/dist/cjs/flow-instance.js

@@ -13,6 +13,7 @@ class FlowInstance {
     expiresAt;
     _exitState;
     _activeSubFlow = null;
+    _lastError = null;
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -50,6 +51,8 @@ class FlowInstance {
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
     get activeSubFlow() { return this._activeSubFlow; }
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError() { return this._lastError; }
     /** State path from root to deepest active sub-flow. */
     statePath() {
         const path = [this._currentState];
@@ -100,5 +103,6 @@ class FlowInstance {
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
     /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }
+    /** @internal */ setLastError(error) { this._lastError = error; }
 }
 exports.FlowInstance = FlowInstance;

package/dist/cjs/in-memory-flow-store.d.ts

@@ -12,7 +12,7 @@ export declare class InMemoryFlowStore {
     private flows;
     private _transitionLog;
     create(flow: FlowInstance<any>): void;
-    loadForUpdate<S extends string>(flowId: string): FlowInstance<S> | undefined;
+    loadForUpdate<S extends string>(flowId: string, _definition?: any): FlowInstance<S> | undefined;
     save(flow: FlowInstance<any>): void;
     recordTransition(flowId: string, from: string | null, to: string, trigger: string, _ctx: FlowContext): void;
     get transitionLog(): readonly TransitionRecord[];

package/dist/cjs/in-memory-flow-store.js

@@ -7,7 +7,7 @@ class InMemoryFlowStore {
     create(flow) {
         this.flows.set(flow.id, flow);
     }
-    loadForUpdate(flowId) {
+    loadForUpdate(flowId, _definition) {
         const flow = this.flows.get(flowId);
         if (!flow || flow.isCompleted)
             return undefined;

package/dist/cjs/tramli.d.ts

@@ -4,5 +4,7 @@ import { FlowEngine } from './flow-engine.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
 export declare class Tramli {
     static define<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
-    static engine(store: InMemoryFlowStore): FlowEngine;
+    static engine(store: InMemoryFlowStore, options?: {
+        strictMode?: boolean;
+    }): FlowEngine;
 }

package/dist/cjs/tramli.js

@@ -7,8 +7,8 @@ class Tramli {
     static define(name, stateConfig) {
         return new flow_definition_js_1.Builder(name, stateConfig);
     }
-    static engine(store) {
-        return new flow_engine_js_1.FlowEngine(store);
+    static engine(store, options) {
+        return new flow_engine_js_1.FlowEngine(store, options);
     }
 }
 exports.Tramli = Tramli;

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

@@ -3,11 +3,15 @@ import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
 export declare class FlowEngine {
     private readonly store;
-    constructor(store: InMemoryFlowStore);
+    private readonly strictMode;
+    constructor(store: InMemoryFlowStore, options?: {
+        strictMode?: boolean;
+    });
     startFlow<S extends string>(definition: FlowDefinition<S>, sessionId: string, initialData: Map<string, unknown>): Promise<FlowInstance<S>>;
     resumeAndExecute<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData?: Map<string, unknown>): Promise<FlowInstance<S>>;
     private executeAutoChain;
     private executeSubFlow;
     private resumeSubFlow;
+    private verifyProduces;
     private handleError;
 }

package/dist/esm/flow-engine.js

@@ -4,8 +4,10 @@ import { FlowError } from './flow-error.js';
 const MAX_CHAIN_DEPTH = 10;
 export class FlowEngine {
     store;
-    constructor(store) {
+    strictMode;
+    constructor(store, options) {
         this.store = store;
+        this.strictMode = options?.strictMode ?? false;
     }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
@@ -23,7 +25,7 @@ export class FlowEngine {
         return flow;
     }
     async resumeAndExecute(flowId, definition, externalData) {
-        const flow = this.store.loadForUpdate(flowId);
+        const flow = this.store.loadForUpdate(flowId, definition);
         if (!flow)
             throw new FlowError('FLOW_NOT_FOUND', `Flow ${flowId} not found or already completed`);
         if (externalData) {
@@ -60,9 +62,9 @@ export class FlowEngine {
                         flow.transitionTo(transition.to);
                         this.store.recordTransition(flow.id, from, transition.to, guard.name, flow.context);
                     }
-                    catch {
+                    catch (e) {
                         flow.context.restoreFrom(backup);
-                        this.handleError(flow, currentState);
+                        this.handleError(flow, currentState, e instanceof Error ? e : new Error(String(e)));
                         this.store.save(flow);
                         return flow;
                     }
@@ -116,8 +118,10 @@ export class FlowEngine {
             const backup = flow.context.snapshot();
             try {
                 if (autoOrBranch.type === 'auto') {
-                    if (autoOrBranch.processor)
+                    if (autoOrBranch.processor) {
                         await autoOrBranch.processor.process(flow.context);
+                        this.verifyProduces(autoOrBranch.processor, flow.context);
+                    }
                     const from = flow.currentState;
                     flow.transitionTo(autoOrBranch.to);
                     this.store.recordTransition(flow.id, from, autoOrBranch.to, autoOrBranch.processor?.name ?? 'auto', flow.context);
@@ -137,9 +141,9 @@ export class FlowEngine {
                     this.store.recordTransition(flow.id, from, target, `${branch.name}:${label}`, flow.context);
                 }
             }
-            catch {
+            catch (e) {
                 flow.context.restoreFrom(backup);
-                this.handleError(flow, flow.currentState);
+                this.handleError(flow, flow.currentState, e instanceof Error ? e : new Error(String(e)));
                 return;
             }
             depth++;
@@ -222,7 +226,18 @@ export class FlowEngine {
         this.store.save(parentFlow);
         return parentFlow;
     }
-    handleError(flow, fromState) {
+    verifyProduces(processor, ctx) {
+        if (!this.strictMode)
+            return;
+        for (const prod of processor.produces) {
+            if (!ctx.has(prod)) {
+                throw new FlowError('PRODUCES_VIOLATION', `Processor '${processor.name}' declares produces ${prod} but did not put it in context (strictMode)`);
+            }
+        }
+    }
+    handleError(flow, fromState, cause) {
+        if (cause)
+            flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

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

@@ -12,6 +12,7 @@ export declare class FlowInstance<S extends string> {
     readonly expiresAt: Date;
     private _exitState;
     private _activeSubFlow;
+    private _lastError;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -24,6 +25,8 @@ export declare class FlowInstance<S extends string> {
     get exitState(): string | null;
     get isCompleted(): boolean;
     get activeSubFlow(): FlowInstance<any> | null;
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError(): string | null;
     /** State path from root to deepest active sub-flow. */
     statePath(): string[];
     /** State path as slash-separated string. */
@@ -41,4 +44,5 @@ export declare class FlowInstance<S extends string> {
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
     /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;
+    /** @internal */ setLastError(error: string | null): void;
 }

package/dist/esm/flow-instance.js

@@ -10,6 +10,7 @@ export class FlowInstance {
     expiresAt;
     _exitState;
     _activeSubFlow = null;
+    _lastError = null;
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -47,6 +48,8 @@ export class FlowInstance {
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
     get activeSubFlow() { return this._activeSubFlow; }
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError() { return this._lastError; }
     /** State path from root to deepest active sub-flow. */
     statePath() {
         const path = [this._currentState];
@@ -97,4 +100,5 @@ export class FlowInstance {
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
     /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }
+    /** @internal */ setLastError(error) { this._lastError = error; }
 }

package/dist/esm/in-memory-flow-store.d.ts

@@ -12,7 +12,7 @@ export declare class InMemoryFlowStore {
     private flows;
     private _transitionLog;
     create(flow: FlowInstance<any>): void;
-    loadForUpdate<S extends string>(flowId: string): FlowInstance<S> | undefined;
+    loadForUpdate<S extends string>(flowId: string, _definition?: any): FlowInstance<S> | undefined;
     save(flow: FlowInstance<any>): void;
     recordTransition(flowId: string, from: string | null, to: string, trigger: string, _ctx: FlowContext): void;
     get transitionLog(): readonly TransitionRecord[];

package/dist/esm/in-memory-flow-store.js

@@ -4,7 +4,7 @@ export class InMemoryFlowStore {
     create(flow) {
         this.flows.set(flow.id, flow);
     }
-    loadForUpdate(flowId) {
+    loadForUpdate(flowId, _definition) {
         const flow = this.flows.get(flowId);
         if (!flow || flow.isCompleted)
             return undefined;

package/dist/esm/tramli.d.ts

@@ -4,5 +4,7 @@ import { FlowEngine } from './flow-engine.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
 export declare class Tramli {
     static define<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
-    static engine(store: InMemoryFlowStore): FlowEngine;
+    static engine(store: InMemoryFlowStore, options?: {
+        strictMode?: boolean;
+    }): FlowEngine;
 }

package/dist/esm/tramli.js

@@ -4,7 +4,7 @@ export class Tramli {
     static define(name, stateConfig) {
         return new Builder(name, stateConfig);
     }
-    static engine(store) {
-        return new FlowEngine(store);
+    static engine(store, options) {
+        return new FlowEngine(store, options);
     }
 }

package/package.json

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