Simple Flow Machine

A lightweight, TypeScript-based workflow engine for building and executing complex flow-based applications with conditional branching, loops, and parallel execution.

Features

• Graph-based Flow Execution - Define workflows as directed graphs with nodes and edges
• Conditional Branching - Use json-rules-engine for powerful condition evaluation
• Task Handlers - Register custom task handlers for different node types
• Execution Tracing - Track node executions, edge traversals, and execution metrics
• Parallel Execution - Support for parallel branches in workflows
• Loop Support - Handle cyclic flows with exit conditions
• TypeScript Support - Fully typed API for better developer experience

Installation

npm install simple-flow-machine

Or with pnpm:

pnpm add simple-flow-machine

Or with yarn:

yarn add simple-flow-machine

Quick Start

import { FlowMachine } from 'simple-flow-machine';

// Create a new flow machine
const flowMachine = new FlowMachine();

// Register task handlers
flowMachine.handlers.registerHandler('greet', async (inputs) => ({
  message: `Hello, ${inputs.name}!`
}));

flowMachine.handlers.registerHandler('log', async (inputs) => {
  console.log(inputs.message);
  return { logged: true };
});

// Define the flow
const flowDefinition = {
  nodes: [
    { id: 'start', type: 'start', inputs: {}, outputs: {} },
    { id: 'greet', type: 'greet', inputs: { name: 'World' }, outputs: {} },
    { id: 'log', type: 'log', inputs: {}, outputs: {} },
    { id: 'end', type: 'end', inputs: {}, outputs: {} }
  ],
  edges: [
    { id: 'e1', source: 'start', target: 'greet', conditions: {} },
    { id: 'e2', source: 'greet', target: 'log', conditions: {} },
    { id: 'e3', source: 'log', target: 'end', conditions: {} }
  ]
};

// Load and run the flow
flowMachine.loadFlow(flowDefinition);
await flowMachine.run();

// Get the result
const result = flowMachine.getResult();
console.log(result); // { logged: true }

Conditional Branching

Use json-rules-engine syntax for conditions:

const flowDefinition = {
  nodes: [
    { id: 'start', type: 'start', inputs: {}, outputs: {} },
    { id: 'check', type: 'checkValue', inputs: {}, outputs: {} },
    { id: 'pathA', type: 'handleA', inputs: {}, outputs: {} },
    { id: 'pathB', type: 'handleB', inputs: {}, outputs: {} },
    { id: 'end', type: 'end', inputs: {}, outputs: {} }
  ],
  edges: [
    { id: 'e1', source: 'start', target: 'check', conditions: {} },
    {
      id: 'e2',
      source: 'check',
      target: 'pathA',
      conditions: {
        all: [{ fact: 'value', operator: 'greaterThan', value: 10 }]
      }
    },
    {
      id: 'e3',
      source: 'check',
      target: 'pathB',
      conditions: {
        all: [{ fact: 'value', operator: 'lessThanInclusive', value: 10 }]
      }
    },
    { id: 'e4', source: 'pathA', target: 'end', conditions: {} },
    { id: 'e5', source: 'pathB', target: 'end', conditions: {} }
  ]
};

API Reference

FlowMachine

The main class for creating and running workflows.

Methods

• loadFlow(definition: { nodes: Node[], edges: Edge[] }) - Load a flow definition
• run() - Execute the flow
• getResult() - Get the final result from the end node
• getNodeResult(nodeId: string) - Get the result from a specific node
• getExecutionTrace() - Get the complete execution trace
• getExecutionMetrics() - Get execution metrics (timing, node count, etc.)

Node

interface Node {
  id: string;
  type: string;
  inputs: Record<string, unknown>;
  outputs: Record<string, unknown>;
}

Edge

interface Edge {
  id: string;
  source: string;
  target: string;
  conditions: Record<string, unknown>;
}

Handler Registration

flowMachine.handlers.registerHandler('taskType', async (inputs) => {
  // Process inputs
  return {
    // Output data
  };
});

Development

Setup

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

Running Tests

pnpm test

All tests should pass with 100% coverage of core functionality.

License

MIT - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

https://github.com/AndreasCaldewei/simple-flow-machine