@unlaxer/tramli 3.3.0 → 3.4.0

package/dist/cjs/data-flow-graph.d.ts

@@ -88,5 +88,5 @@ export declare class DataFlowGraph<S extends string> {
     private static collectEdges;
     /** Version compatibility: check if v1 instances can resume on v2 definition. */
     static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
-    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[], externallyProvided?: string[]): DataFlowGraph<S>;
 }

package/dist/cjs/data-flow-graph.js

@@ -370,14 +370,15 @@ class DataFlowGraph {
         return issues;
     }
     // ─── Builder ─────────────────────────────────────────────
-    static build(def, initiallyAvailable) {
+    static build(def, initiallyAvailable, externallyProvided = []) {
         const stateAvail = new Map();
         const producers = new Map();
         const consumers = new Map();
         const allProduced = new Set(initiallyAvailable);
         const allConsumed = new Set();
+        const extSet = new Set(externallyProvided);
         if (def.initialState) {
-            traverse(def, def.initialState, new Set(initiallyAvailable), stateAvail, producers, consumers, allProduced, allConsumed);
+            traverse(def, def.initialState, new Set(initiallyAvailable), extSet, stateAvail, producers, consumers, allProduced, allConsumed);
             // Mark initially available types as produced by "initial"
             for (const key of initiallyAvailable) {
                 if (!producers.has(key))
@@ -391,7 +392,7 @@ class DataFlowGraph {
     }
 }
 exports.DataFlowGraph = DataFlowGraph;
-function traverse(def, state, available, stateAvail, producers, consumers, allProduced, allConsumed) {
+function traverse(def, state, available, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed) {
     if (stateAvail.has(state)) {
         const existing = stateAvail.get(state);
         let isSubset = true;
@@ -413,6 +414,10 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
     }
     for (const t of def.transitionsFrom(state)) {
         const newAvail = new Set(stateAvail.get(state));
+        if (t.type === 'external') {
+            for (const k of externallyProvided)
+                newAvail.add(k);
+        }
         if (t.guard) {
             for (const req of t.guard.requires) {
                 addTo(consumers, req, { name: t.guard.name, fromState: t.from, toState: t.to, kind: 'guard' });
@@ -441,7 +446,7 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
                 newAvail.add(prod);
             }
         }
-        traverse(def, t.to, newAvail, stateAvail, producers, consumers, allProduced, allConsumed);
+        traverse(def, t.to, newAvail, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
 function addTo(map, key, info) {

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

@@ -45,9 +45,12 @@ export declare class Builder<S extends string> {
     private readonly _enterActions;
     private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private readonly externallyProvidedKeys;
     private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;

package/dist/cjs/flow-definition.js

@@ -113,6 +113,7 @@ class Builder {
     _enterActions = new Map();
     _exitActions = new Map();
     initiallyAvailableKeys = [];
+    externallyProvidedKeys = [];
     _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
@@ -123,6 +124,12 @@ class Builder {
             this.initiallyAvailableKeys.push(k);
         return this;
     }
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys) {
+        for (const k of keys)
+            this.externallyProvidedKeys.push(k);
+        return this;
+    }
     setTtl(ms) { this.ttl = ms; return this; }
     setMaxGuardRetries(max) { this.maxGuardRetries = max; return this; }
     from(state) {
@@ -185,7 +192,7 @@ class Builder {
         result.terminalStates = terminals;
         result.dataFlowGraph = null;
         this.validate(result);
-        result.dataFlowGraph = data_flow_graph_js_1.DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        result.dataFlowGraph = data_flow_graph_js_1.DataFlowGraph.build(result, this.initiallyAvailableKeys, this.externallyProvidedKeys);
         // Build warnings
         const warnings = [];
         const perpetual = terminals.size === 0;
@@ -354,6 +361,10 @@ class Builder {
         }
         for (const t of def.transitionsFrom(state)) {
             const newAvailable = new Set(stateAvailable.get(state));
+            if (t.type === 'external') {
+                for (const k of this.externallyProvidedKeys)
+                    newAvailable.add(k);
+            }
             if (t.guard) {
                 for (const req of t.guard.requires) {
                     if (!newAvailable.has(req))
@@ -534,6 +545,7 @@ class BranchBuilder {
                 processor: this.processors.get(label),
                 guard: undefined, branch: this.branch,
                 branchTargets: new Map(this.targets),
+                branchLabel: label,
             });
         }
         return this.builder;

package/dist/cjs/flow-engine.js

@@ -201,7 +201,7 @@ class FlowEngine {
                     if (!target) {
                         throw new flow_error_js_1.FlowError('UNKNOWN_BRANCH', `Branch '${branch.name}' returned unknown label: ${label}`);
                     }
-                    const specific = transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
+                    const specific = transitions.find(t => t.type === 'branch' && t.branchLabel === label) ?? transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;

package/dist/cjs/types.d.ts

@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    /** Label assigned by builder .to(target, label, processor). Used for branch label-specific processor matching. */
+    branchLabel?: string;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
     /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */

package/dist/esm/data-flow-graph.d.ts

@@ -88,5 +88,5 @@ export declare class DataFlowGraph<S extends string> {
     private static collectEdges;
     /** Version compatibility: check if v1 instances can resume on v2 definition. */
     static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
-    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[], externallyProvided?: string[]): DataFlowGraph<S>;
 }

package/dist/esm/data-flow-graph.js

@@ -367,14 +367,15 @@ export class DataFlowGraph {
         return issues;
     }
     // ─── Builder ─────────────────────────────────────────────
-    static build(def, initiallyAvailable) {
+    static build(def, initiallyAvailable, externallyProvided = []) {
         const stateAvail = new Map();
         const producers = new Map();
         const consumers = new Map();
         const allProduced = new Set(initiallyAvailable);
         const allConsumed = new Set();
+        const extSet = new Set(externallyProvided);
         if (def.initialState) {
-            traverse(def, def.initialState, new Set(initiallyAvailable), stateAvail, producers, consumers, allProduced, allConsumed);
+            traverse(def, def.initialState, new Set(initiallyAvailable), extSet, stateAvail, producers, consumers, allProduced, allConsumed);
             // Mark initially available types as produced by "initial"
             for (const key of initiallyAvailable) {
                 if (!producers.has(key))
@@ -387,7 +388,7 @@ export class DataFlowGraph {
         return new DataFlowGraph(stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
-function traverse(def, state, available, stateAvail, producers, consumers, allProduced, allConsumed) {
+function traverse(def, state, available, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed) {
     if (stateAvail.has(state)) {
         const existing = stateAvail.get(state);
         let isSubset = true;
@@ -409,6 +410,10 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
     }
     for (const t of def.transitionsFrom(state)) {
         const newAvail = new Set(stateAvail.get(state));
+        if (t.type === 'external') {
+            for (const k of externallyProvided)
+                newAvail.add(k);
+        }
         if (t.guard) {
             for (const req of t.guard.requires) {
                 addTo(consumers, req, { name: t.guard.name, fromState: t.from, toState: t.to, kind: 'guard' });
@@ -437,7 +442,7 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
                 newAvail.add(prod);
             }
         }
-        traverse(def, t.to, newAvail, stateAvail, producers, consumers, allProduced, allConsumed);
+        traverse(def, t.to, newAvail, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
 function addTo(map, key, info) {

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

@@ -45,9 +45,12 @@ export declare class Builder<S extends string> {
     private readonly _enterActions;
     private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private readonly externallyProvidedKeys;
     private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;

package/dist/esm/flow-definition.js

@@ -109,6 +109,7 @@ export class Builder {
     _enterActions = new Map();
     _exitActions = new Map();
     initiallyAvailableKeys = [];
+    externallyProvidedKeys = [];
     _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
@@ -119,6 +120,12 @@ export class Builder {
             this.initiallyAvailableKeys.push(k);
         return this;
     }
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys) {
+        for (const k of keys)
+            this.externallyProvidedKeys.push(k);
+        return this;
+    }
     setTtl(ms) { this.ttl = ms; return this; }
     setMaxGuardRetries(max) { this.maxGuardRetries = max; return this; }
     from(state) {
@@ -181,7 +188,7 @@ export class Builder {
         result.terminalStates = terminals;
         result.dataFlowGraph = null;
         this.validate(result);
-        result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys, this.externallyProvidedKeys);
         // Build warnings
         const warnings = [];
         const perpetual = terminals.size === 0;
@@ -350,6 +357,10 @@ export class Builder {
         }
         for (const t of def.transitionsFrom(state)) {
             const newAvailable = new Set(stateAvailable.get(state));
+            if (t.type === 'external') {
+                for (const k of this.externallyProvidedKeys)
+                    newAvailable.add(k);
+            }
             if (t.guard) {
                 for (const req of t.guard.requires) {
                     if (!newAvailable.has(req))
@@ -527,6 +538,7 @@ export class BranchBuilder {
                 processor: this.processors.get(label),
                 guard: undefined, branch: this.branch,
                 branchTargets: new Map(this.targets),
+                branchLabel: label,
             });
         }
         return this.builder;

package/dist/esm/flow-engine.js

@@ -198,7 +198,7 @@ export class FlowEngine {
                     if (!target) {
                         throw new FlowError('UNKNOWN_BRANCH', `Branch '${branch.name}' returned unknown label: ${label}`);
                     }
-                    const specific = transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
+                    const specific = transitions.find(t => t.type === 'branch' && t.branchLabel === label) ?? transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;

package/dist/esm/types.d.ts

@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    /** Label assigned by builder .to(target, label, processor). Used for branch label-specific processor matching. */
+    branchLabel?: string;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
     /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */

package/package.json

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