@unlaxer/tramli 0.1.0 → 0.2.0

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

@@ -0,0 +1,33 @@
+import type { FlowDefinition } from './flow-definition.js';
+import type { FlowKey } from './flow-key.js';
+export interface NodeInfo<S extends string> {
+    name: string;
+    fromState: S;
+    toState: S;
+    kind: 'processor' | 'guard' | 'branch' | 'initial';
+}
+/**
+ * Bipartite graph of data types (FlowKey) and processors/guards.
+ * Built automatically during FlowDefinition.build().
+ */
+export declare class DataFlowGraph<S extends string> {
+    private readonly _availableAtState;
+    private readonly _producers;
+    private readonly _consumers;
+    private readonly _allProduced;
+    private readonly _allConsumed;
+    private constructor();
+    /** Data types available in context when the flow reaches the given state. */
+    availableAt(state: S): Set<string>;
+    /** Processors/guards that produce the given type. */
+    producersOf(key: FlowKey<unknown>): NodeInfo<S>[];
+    /** Processors/guards that consume (require) the given type. */
+    consumersOf(key: FlowKey<unknown>): NodeInfo<S>[];
+    /** Types produced but never required by any downstream processor/guard. */
+    deadData(): Set<string>;
+    /** All type nodes in the graph. */
+    allTypes(): Set<string>;
+    /** Generate Mermaid data-flow diagram. */
+    toMermaid(): string;
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+}

package/dist/data-flow-graph.js

@@ -0,0 +1,146 @@
+/**
+ * Bipartite graph of data types (FlowKey) and processors/guards.
+ * Built automatically during FlowDefinition.build().
+ */
+export class DataFlowGraph {
+    _availableAtState;
+    _producers;
+    _consumers;
+    _allProduced;
+    _allConsumed;
+    constructor(availableAtState, producers, consumers, allProduced, allConsumed) {
+        this._availableAtState = availableAtState;
+        this._producers = producers;
+        this._consumers = consumers;
+        this._allProduced = allProduced;
+        this._allConsumed = allConsumed;
+    }
+    /** Data types available in context when the flow reaches the given state. */
+    availableAt(state) {
+        return this._availableAtState.get(state) ?? new Set();
+    }
+    /** Processors/guards that produce the given type. */
+    producersOf(key) {
+        return this._producers.get(key) ?? [];
+    }
+    /** Processors/guards that consume (require) the given type. */
+    consumersOf(key) {
+        return this._consumers.get(key) ?? [];
+    }
+    /** Types produced but never required by any downstream processor/guard. */
+    deadData() {
+        const dead = new Set(this._allProduced);
+        for (const c of this._allConsumed)
+            dead.delete(c);
+        return dead;
+    }
+    /** All type nodes in the graph. */
+    allTypes() {
+        const types = new Set(this._allProduced);
+        for (const c of this._allConsumed)
+            types.add(c);
+        return types;
+    }
+    /** Generate Mermaid data-flow diagram. */
+    toMermaid() {
+        const lines = ['flowchart LR'];
+        const seen = new Set();
+        for (const [typeName, nodes] of this._producers) {
+            for (const node of nodes) {
+                const edge = `${node.name} -->|produces| ${typeName}`;
+                if (!seen.has(edge)) {
+                    seen.add(edge);
+                    lines.push(`    ${edge}`);
+                }
+            }
+        }
+        for (const [typeName, nodes] of this._consumers) {
+            for (const node of nodes) {
+                const edge = `${typeName} -->|requires| ${node.name}`;
+                if (!seen.has(edge)) {
+                    seen.add(edge);
+                    lines.push(`    ${edge}`);
+                }
+            }
+        }
+        return lines.join('\n') + '\n';
+    }
+    // ─── Builder ─────────────────────────────────────────────
+    static build(def, initiallyAvailable) {
+        const stateAvail = new Map();
+        const producers = new Map();
+        const consumers = new Map();
+        const allProduced = new Set(initiallyAvailable);
+        const allConsumed = new Set();
+        if (def.initialState) {
+            traverse(def, def.initialState, new Set(initiallyAvailable), stateAvail, producers, consumers, allProduced, allConsumed);
+            // Mark initially available types as produced by "initial"
+            for (const key of initiallyAvailable) {
+                if (!producers.has(key))
+                    producers.set(key, []);
+                producers.get(key).push({
+                    name: 'initial', fromState: def.initialState, toState: def.initialState, kind: 'initial',
+                });
+            }
+        }
+        return new DataFlowGraph(stateAvail, producers, consumers, allProduced, allConsumed);
+    }
+}
+function traverse(def, state, available, stateAvail, producers, consumers, allProduced, allConsumed) {
+    if (stateAvail.has(state)) {
+        const existing = stateAvail.get(state);
+        let isSubset = true;
+        for (const a of available) {
+            if (!existing.has(a)) {
+                isSubset = false;
+                break;
+            }
+        }
+        if (isSubset)
+            return;
+        for (const a of [...existing]) {
+            if (!available.has(a))
+                existing.delete(a);
+        }
+    }
+    else {
+        stateAvail.set(state, new Set(available));
+    }
+    for (const t of def.transitionsFrom(state)) {
+        const newAvail = new Set(stateAvail.get(state));
+        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' });
+                allConsumed.add(req);
+            }
+            for (const prod of t.guard.produces) {
+                addTo(producers, prod, { name: t.guard.name, fromState: t.from, toState: t.to, kind: 'guard' });
+                allProduced.add(prod);
+                newAvail.add(prod);
+            }
+        }
+        if (t.branch) {
+            for (const req of t.branch.requires) {
+                addTo(consumers, req, { name: t.branch.name, fromState: t.from, toState: t.to, kind: 'branch' });
+                allConsumed.add(req);
+            }
+        }
+        if (t.processor) {
+            for (const req of t.processor.requires) {
+                addTo(consumers, req, { name: t.processor.name, fromState: t.from, toState: t.to, kind: 'processor' });
+                allConsumed.add(req);
+            }
+            for (const prod of t.processor.produces) {
+                addTo(producers, prod, { name: t.processor.name, fromState: t.from, toState: t.to, kind: 'processor' });
+                allProduced.add(prod);
+                newAvail.add(prod);
+            }
+        }
+        traverse(def, t.to, newAvail, stateAvail, producers, consumers, allProduced, allConsumed);
+    }
+}
+function addTo(map, key, info) {
+    if (!map.has(key))
+        map.set(key, []);
+    map.get(key).push(info);
+}

package/dist/flow-definition.d.ts

@@ -1,5 +1,6 @@
 import type { FlowKey } from './flow-key.js';
 import type { StateConfig, Transition, StateProcessor, TransitionGuard, BranchProcessor } from './types.js';
+import { DataFlowGraph } from './data-flow-graph.js';
 export declare class FlowDefinition<S extends string> {
     readonly name: string;
     readonly stateConfig: Record<S, StateConfig>;
@@ -9,6 +10,7 @@ export declare class FlowDefinition<S extends string> {
     readonly errorTransitions: Map<S, S>;
     readonly initialState: S | null;
     readonly terminalStates: Set<S>;
+    readonly dataFlowGraph: DataFlowGraph<S> | null;
     private constructor();
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;

package/dist/flow-definition.js

@@ -1,4 +1,5 @@
 import { FlowError } from './flow-error.js';
+import { DataFlowGraph } from './data-flow-graph.js';
 export class FlowDefinition {
     name;
     stateConfig;
@@ -8,6 +9,7 @@ export class FlowDefinition {
     errorTransitions;
     initialState;
     terminalStates;
+    dataFlowGraph;
     constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -98,7 +100,9 @@ export class Builder {
         }
         result.initialState = initial;
         result.terminalStates = terminals;
+        result.dataFlowGraph = null;
         this.validate(result);
+        result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys);
         return result;
     }
     validate(def) {

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export type { TransitionRecord } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';
+export { DataFlowGraph } from './data-flow-graph.js';
+export type { NodeInfo } from './data-flow-graph.js';
 export { flowKey } from './flow-key.js';
 export type { FlowKey } from './flow-key.js';
 export type { StateConfig, GuardOutput, TransitionType, Transition, StateProcessor, TransitionGuard, BranchProcessor, } from './types.js';

package/dist/index.js

@@ -6,4 +6,5 @@ export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-defi
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';
+export { DataFlowGraph } from './data-flow-graph.js';
 export { flowKey } from './flow-key.js';

package/dist/mermaid-generator.d.ts

@@ -1,5 +1,7 @@
 import type { FlowDefinition } from './flow-definition.js';
 export declare class MermaidGenerator {
     static generate<S extends string>(def: FlowDefinition<S>): string;
+    /** Generate Mermaid data-flow diagram from requires/produces declarations. */
+    static generateDataFlow<S extends string>(def: FlowDefinition<S>): string;
     private static transitionLabel;
 }

package/dist/mermaid-generator.js

@@ -24,6 +24,10 @@ export class MermaidGenerator {
         }
         return lines.join('\n') + '\n';
     }
+    /** Generate Mermaid data-flow diagram from requires/produces declarations. */
+    static generateDataFlow(def) {
+        return def.dataFlowGraph?.toMermaid() ?? '';
+    }
     static transitionLabel(t) {
         if (t.type === 'auto')
             return t.processor?.name ?? '';

package/package.json

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