npm package: @majdibo/flow-engine
Description: Pure TypeScript graph flow visualizer engine with timeline support
Author: majdibo
Latest version: 1.0.0

# Flow Engine

<p align="center">
  <img src="./logo.svg" alt="Flow Engine Logo" width="120" height="120">
</p>

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

```bash
npm install @majdibo/flow-engine
```

Or with yarn:

```bash
yarn add @majdibo/flow-engine
```

## Core Concepts

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

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

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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
// 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