Flow Engine

A framework-agnostic TypeScript library for building and managing execution flow graphs from traces.

Overview

Flow Engine provides the core primitives for:

• Building flow graphs from execution traces
• Managing timelines and visual states
• Computing node and edge states during execution
• Validating graph structures

This package is completely framework-agnostic and can be used with any UI library or even server-side.

Installation

npm install @majdibo/flow-engine

Or with yarn:

yarn add @majdibo/flow-engine

Core Concepts

FlowGraph

A directed graph representing the execution flow with nodes (steps) and edges (transitions).

interface FlowGraph {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

Timeline

A sequence of step names representing the execution order. Just use standard arrays:

const timeline: string[] = ['start', 'process', 'end'];

VisualState

Computed state showing which nodes and edges are active, traversed, or untraversed at a given timeline position.

Usage

Building a Graph from Traces

import { buildGraphFromTraces } from '@majdibo/flow-engine';

const traces = [
  { step: 'start', nodeType: 'action', data: {}, timestamp: Date.now() },
  { step: 'process', nodeType: 'action', data: {}, timestamp: Date.now() },
  { step: 'end', nodeType: 'action', data: {}, timestamp: Date.now() }
];

const graph = buildGraphFromTraces(traces);

Computing Visual State

import { computeVisualState } from '@majdibo/flow-engine';

const timeline = traces.map(t => t.step);
const currentIndex = 1;

const visualState = computeVisualState(
  graph,
  timeline,
  currentIndex
);

console.log(visualState.nodeStates); // { start: 'traversed', process: 'current', end: 'untraversed' }
console.log(visualState.edgeStates); // { 'e1': 'traversed', 'e2': 'current', ... }

Using Initial Graph Templates

const initialGraph = {
  nodes: [
    { id: 'start', type: 'action', label: 'Start' },
    { id: 'process', type: 'action', label: 'Process' },
    { id: 'end', type: 'action', label: 'End' }
  ],
  edges: [
    { id: 'e1', from: 'start', to: 'process' },
    { id: 'e2', from: 'process', to: 'end' }
  ]
};

const graph = buildGraphFromTraces(traces, {
  initialGraph // Extends with new nodes from traces
});

Working with Timelines

Timelines are just arrays of step names. Use standard array methods:

// Create timeline from traces
const timeline = traces.map(t => t.step);

// Append a step
const newTimeline = [...timeline, 'newStep'];

// Check if visited
const visited = timeline.includes('process');

// Count visits
const visitCount = timeline.filter(step => step === 'process').length;

// Get last position
const lastIndex = timeline.lastIndexOf('process');

API Reference

buildGraphFromTraces(traces, options?)

Builds a flow graph from execution traces.

Parameters:

• traces: Array of trace objects with step and nodeType properties
• options.initialGraph: Optional starting graph structure to extend

Returns: FlowGraph

computeVisualState(graph, timeline, currentIndex)

Computes the visual state at a specific timeline position.

Parameters:

• graph: The flow graph
• timeline: Array of step names
• currentIndex: Current position in timeline

Returns: VisualState with nodeStates, edgeStates, and helper sets

validateGraph(graph)

Validates graph structure and returns any errors.

Parameters:

• graph: The graph to validate

Returns: ValidationResult with valid boolean and optional error message

Features

• Minimal API Surface: Only exports what's truly needed - three core functions and essential types
• Standard Library First: Uses native array methods instead of custom wrappers
• Zero Dependencies: Pure TypeScript with no runtime dependencies
• Framework Agnostic: Works with React, Vue, Angular, or vanilla JS
• Type Safe: Full TypeScript support with exported types

License

MIT