A3S Flow Node.js SDK

Node.js bindings for the A3S Flow workflow engine, with full TypeScript support.

Installation

npm install @a3s-lab/flow

Quick Start

import { FlowEngine } from '@a3s-lab/flow';

// Create a flow engine
const engine = new FlowEngine();

// Define a simple workflow
const definition = {
  nodes: [
    { id: 'start', type: 'noop' },
    { id: 'process', type: 'noop' }
  ],
  edges: [
    { source: 'start', target: 'process' }
  ]
};

// Start the flow
const executionId = await engine.start(definition, {});

// Check the state
const state = await engine.state(executionId);
console.log(`Status: ${state.status}`);

// Pause and resume
await engine.pause(executionId);
await engine.resume(executionId);

// Terminate
await engine.terminate(executionId);

API Reference

FlowEngine

new FlowEngine()

Create a new flow engine with default built-in nodes.

start(definition: object, variables?: object): Promise<string>

Start a new flow execution.

• definition: Flow definition with nodes and edges
• variables: Initial variables (optional)
• Returns: Execution ID as a string

pause(executionId: string): Promise<void>

Pause a running flow execution.

resume(executionId: string): Promise<void>

Resume a paused flow execution.

terminate(executionId: string): Promise<void>

Terminate a running flow execution.

state(executionId: string): Promise<ExecutionState>

Get the current state of a flow execution.

nodeTypes(): string[]

List all registered node types.

ExecutionState

interface ExecutionState {
  status: 'running' | 'paused' | 'completed' | 'failed' | 'terminated';
  result?: FlowResult;  // present when status is "completed"
  error?: string;       // present when status is "failed"
}

FlowResult

interface FlowResult {
  executionId: string;
  outputs: Record<string, unknown>;
  completedNodes: string[];
  skippedNodes: string[];
  context: Record<string, unknown>;
}

FlowEvent

interface FlowEvent {
  eventType: 'flow_started' | 'node_started' | 'node_completed' | 'node_skipped' | 'node_failed' | 'flow_completed' | 'flow_failed' | 'flow_terminated';
  executionId: string;
  nodeId?: string;
  output?: unknown;
  error?: string;
}

Development

Build from source

cd sdk/node
npm install
npm run build:debug

Run tests

npm test

License

MIT