@unlaxer/tramli 1.1.0 → 1.2.1

package/dist/flow-definition.d.ts

@@ -47,6 +47,9 @@ export declare class Builder<S extends string> {
     private checkRequiresProducesFrom;
     private checkAutoExternalConflict;
     private checkTerminalNoOutgoing;
+    private checkSubFlowNestingDepth;
+    private checkSubFlowCircularRef;
+    private checkSubFlowExitCompleteness;
 }
 export declare class FromBuilder<S extends string> {
     private readonly builder;
@@ -55,6 +58,16 @@ export declare class FromBuilder<S extends string> {
     auto(to: S, processor: StateProcessor<S>): Builder<S>;
     external(to: S, guard: TransitionGuard<S>, processor?: StateProcessor<S>): Builder<S>;
     branch(branch: BranchProcessor<S>): BranchBuilder<S>;
+    subFlow(subFlowDef: FlowDefinition<any>): SubFlowBuilder<S>;
+}
+export declare class SubFlowBuilder<S extends string> {
+    private readonly builder;
+    private readonly fromState;
+    private readonly subFlowDef;
+    private readonly exitMap;
+    constructor(builder: Builder<S>, fromState: S, subFlowDef: FlowDefinition<any>);
+    onExit(terminalName: string, parentState: S): this;
+    endSubFlow(): Builder<S>;
 }
 export declare class BranchBuilder<S extends string> {
     private readonly builder;

package/dist/flow-definition.js

@@ -118,6 +118,9 @@ export class Builder {
         this.checkRequiresProduces(def, errors);
         this.checkAutoExternalConflict(def, errors);
         this.checkTerminalNoOutgoing(def, errors);
+        this.checkSubFlowExitCompleteness(def, errors);
+        this.checkSubFlowNestingDepth(def, errors, 0);
+        this.checkSubFlowCircularRef(def, errors, new Set());
         if (errors.length > 0) {
             throw new FlowError('INVALID_FLOW_DEFINITION', `Flow '${this.name}' has ${errors.length} validation error(s):\n  - ${errors.join('\n  - ')}`);
         }
@@ -131,6 +134,15 @@ export class Builder {
         while (queue.length > 0) {
             const current = queue.shift();
             for (const t of def.transitionsFrom(current)) {
+                if (t.type === 'sub_flow' && t.exitMappings) {
+                    for (const target of t.exitMappings.values()) {
+                        if (!visited.has(target)) {
+                            visited.add(target);
+                            queue.push(target);
+                        }
+                    }
+                    continue;
+                }
                 if (!visited.has(t.to)) {
                     visited.add(t.to);
                     queue.push(t.to);
@@ -163,6 +175,13 @@ export class Builder {
             return false;
         visited.add(state);
         for (const t of def.transitionsFrom(state)) {
+            if (t.type === 'sub_flow' && t.exitMappings) {
+                for (const target of t.exitMappings.values()) {
+                    if (this.canReachTerminal(def, target, visited))
+                        return true;
+                }
+                continue;
+            }
             if (this.canReachTerminal(def, t.to, visited))
                 return true;
         }
@@ -300,11 +319,46 @@ export class Builder {
     }
     checkTerminalNoOutgoing(def, errors) {
         for (const t of def.transitions) {
-            if (def.stateConfig[t.from].terminal) {
+            if (def.stateConfig[t.from].terminal && t.type !== 'sub_flow') {
                 errors.push(`Terminal state ${t.from} has an outgoing transition to ${t.to}`);
             }
         }
     }
+    checkSubFlowNestingDepth(def, errors, depth) {
+        if (depth > 3) {
+            errors.push(`SubFlow nesting depth exceeds maximum of 3 (flow: ${def.name})`);
+            return;
+        }
+        for (const t of def.transitions) {
+            if (t.type === 'sub_flow' && t.subFlowDefinition) {
+                this.checkSubFlowNestingDepth(t.subFlowDefinition, errors, depth + 1);
+            }
+        }
+    }
+    checkSubFlowCircularRef(def, errors, visited) {
+        if (visited.has(def.name)) {
+            errors.push(`Circular sub-flow reference detected: ${[...visited].join(' -> ')} -> ${def.name}`);
+            return;
+        }
+        visited.add(def.name);
+        for (const t of def.transitions) {
+            if (t.type === 'sub_flow' && t.subFlowDefinition) {
+                this.checkSubFlowCircularRef(t.subFlowDefinition, errors, new Set(visited));
+            }
+        }
+    }
+    checkSubFlowExitCompleteness(def, errors) {
+        for (const t of def.transitions) {
+            if (t.type !== 'sub_flow' || !t.subFlowDefinition)
+                continue;
+            const subDef = t.subFlowDefinition;
+            for (const terminal of subDef.terminalStates) {
+                if (!t.exitMappings?.has(terminal)) {
+                    errors.push(`SubFlow '${subDef.name}' at ${t.from} has terminal state ${terminal} with no onExit mapping`);
+                }
+            }
+        }
+    }
 }
 export class FromBuilder {
     builder;
@@ -330,6 +384,34 @@ export class FromBuilder {
     branch(branch) {
         return new BranchBuilder(this.builder, this.fromState, branch);
     }
+    subFlow(subFlowDef) {
+        return new SubFlowBuilder(this.builder, this.fromState, subFlowDef);
+    }
+}
+export class SubFlowBuilder {
+    builder;
+    fromState;
+    subFlowDef;
+    exitMap = new Map();
+    constructor(builder, fromState, subFlowDef) {
+        this.builder = builder;
+        this.fromState = fromState;
+        this.subFlowDef = subFlowDef;
+    }
+    onExit(terminalName, parentState) {
+        this.exitMap.set(terminalName, parentState);
+        return this;
+    }
+    endSubFlow() {
+        this.builder.addTransition({
+            from: this.fromState, to: this.fromState, type: 'sub_flow',
+            processor: undefined, guard: undefined, branch: undefined,
+            branchTargets: new Map(),
+            subFlowDefinition: this.subFlowDef,
+            exitMappings: new Map(this.exitMap),
+        });
+        return this.builder;
+    }
 }
 export class BranchBuilder {
     builder;

package/dist/flow-engine.d.ts

@@ -1,22 +1,13 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
-/**
- * Generic engine that drives all flow state machines.
- *
- * Exceptions:
- * - FLOW_NOT_FOUND: resumeAndExecute with unknown or completed flowId
- * - INVALID_TRANSITION: resumeAndExecute when no external transition exists
- * - MAX_CHAIN_DEPTH: auto-chain exceeded 10 steps
- * - EXPIRED: flow TTL exceeded at resumeAndExecute entry
- *
- * Processor and branch exceptions are caught and routed to error transitions.
- */
 export declare class FlowEngine {
     private readonly store;
     constructor(store: InMemoryFlowStore);
     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 handleError;
 }

package/dist/flow-engine.js

@@ -2,17 +2,6 @@ import { FlowContext } from './flow-context.js';
 import { FlowInstance } from './flow-instance.js';
 import { FlowError } from './flow-error.js';
 const MAX_CHAIN_DEPTH = 10;
-/**
- * Generic engine that drives all flow state machines.
- *
- * Exceptions:
- * - FLOW_NOT_FOUND: resumeAndExecute with unknown or completed flowId
- * - INVALID_TRANSITION: resumeAndExecute when no external transition exists
- * - MAX_CHAIN_DEPTH: auto-chain exceeded 10 steps
- * - EXPIRED: flow TTL exceeded at resumeAndExecute entry
- *
- * Processor and branch exceptions are caught and routed to error transitions.
- */
 export class FlowEngine {
     store;
     constructor(store) {
@@ -46,6 +35,10 @@ export class FlowEngine {
             this.store.save(flow);
             return flow;
         }
+        // If actively in a sub-flow, delegate resume
+        if (flow.activeSubFlow) {
+            return this.resumeSubFlow(flow, definition);
+        }
         const currentState = flow.currentState;
         const transition = definition.externalFrom(currentState);
         if (!transition)
@@ -108,6 +101,15 @@ export class FlowEngine {
                 break;
             }
             const transitions = flow.definition.transitionsFrom(current);
+            // Check for sub-flow transition
+            const subFlowT = transitions.find(t => t.type === 'sub_flow');
+            if (subFlowT) {
+                const advanced = await this.executeSubFlow(flow, subFlowT);
+                depth += advanced;
+                if (advanced === 0)
+                    break; // sub-flow stopped at external
+                continue;
+            }
             const autoOrBranch = transitions.find(t => t.type === 'auto' || t.type === 'branch');
             if (!autoOrBranch)
                 break;
@@ -145,6 +147,81 @@ export class FlowEngine {
         if (depth >= MAX_CHAIN_DEPTH)
             throw FlowError.maxChainDepth();
     }
+    async executeSubFlow(parentFlow, subFlowTransition) {
+        const subDef = subFlowTransition.subFlowDefinition;
+        const exitMappings = subFlowTransition.exitMappings;
+        const subInitial = subDef.initialState;
+        const subFlow = new FlowInstance(parentFlow.id, parentFlow.sessionId, subDef, parentFlow.context, subInitial, parentFlow.expiresAt);
+        parentFlow.setActiveSubFlow(subFlow);
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const target = exitMappings.get(subFlow.exitState);
+            if (target) {
+                const from = parentFlow.currentState;
+                parentFlow.transitionTo(target);
+                this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                return 1;
+            }
+            // Error bubbling: no exit mapping → fall back to parent's error transitions
+            this.handleError(parentFlow, parentFlow.currentState);
+            return 1;
+        }
+        return 0; // sub-flow stopped at external
+    }
+    async resumeSubFlow(parentFlow, parentDef) {
+        const subFlow = parentFlow.activeSubFlow;
+        const subDef = subFlow.definition;
+        const transition = subDef.externalFrom(subFlow.currentState);
+        if (!transition) {
+            throw new FlowError('INVALID_TRANSITION', `No external transition from sub-flow state ${subFlow.currentState}`);
+        }
+        const guard = transition.guard;
+        if (guard) {
+            const output = await guard.validate(parentFlow.context);
+            if (output.type === 'accepted') {
+                if (output.data) {
+                    for (const [key, value] of output.data)
+                        parentFlow.context.put(key, value);
+                }
+                subFlow.transitionTo(transition.to);
+                this.store.recordTransition(parentFlow.id, subFlow.currentState, transition.to, guard.name, parentFlow.context);
+            }
+            else if (output.type === 'rejected') {
+                subFlow.incrementGuardFailure();
+                if (subFlow.guardFailureCount >= subDef.maxGuardRetries) {
+                    subFlow.complete('ERROR');
+                }
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+            else {
+                parentFlow.complete('EXPIRED');
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+        }
+        else {
+            subFlow.transitionTo(transition.to);
+        }
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const subFlowT = parentDef.transitionsFrom(parentFlow.currentState)
+                .find(t => t.type === 'sub_flow');
+            if (subFlowT?.exitMappings) {
+                const target = subFlowT.exitMappings.get(subFlow.exitState);
+                if (target) {
+                    const from = parentFlow.currentState;
+                    parentFlow.transitionTo(target);
+                    this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                    await this.executeAutoChain(parentFlow);
+                }
+            }
+        }
+        this.store.save(parentFlow);
+        return parentFlow;
+    }
     handleError(flow, fromState) {
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {

package/dist/flow-instance.d.ts

@@ -11,6 +11,7 @@ export declare class FlowInstance<S extends string> {
     readonly createdAt: Date;
     readonly expiresAt: Date;
     private _exitState;
+    private _activeSubFlow;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -22,8 +23,10 @@ export declare class FlowInstance<S extends string> {
     get version(): number;
     get exitState(): string | null;
     get isCompleted(): boolean;
+    get activeSubFlow(): FlowInstance<any> | null;
     /** @internal */ transitionTo(state: S): void;
     /** @internal */ incrementGuardFailure(): void;
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
+    /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;
 }

package/dist/flow-instance.js

@@ -9,6 +9,7 @@ export class FlowInstance {
     createdAt;
     expiresAt;
     _exitState;
+    _activeSubFlow = null;
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -45,8 +46,10 @@ export class FlowInstance {
     get version() { return this._version; }
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
+    get activeSubFlow() { return this._activeSubFlow; }
     /** @internal */ transitionTo(state) { this._currentState = state; }
     /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
+    /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
-export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-definition.js';
+export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export type { TransitionRecord } from './in-memory-flow-store.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
-export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-definition.js';
+export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';

package/dist/types.d.ts

@@ -16,7 +16,7 @@ export type GuardOutput = {
     type: 'expired';
 };
 /** Transition types. */
-export type TransitionType = 'auto' | 'external' | 'branch';
+export type TransitionType = 'auto' | 'external' | 'branch' | 'sub_flow';
 /** A single transition in the flow definition. */
 export interface Transition<S extends string> {
     from: S;
@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
+    exitMappings?: Map<string, S>;
 }
 /**
  * Processes a state transition.

package/package.json

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