Getting Started

Installation #

Install the package using your preferred package manager. Symbiote Engine requires Node.js version 18 or higher.

npm install symbiote-engine

Since the library is published as a pure ES Module (ESM), ensure your project is configured to support ESM. You can do this by setting "type": "module" in your project's package.json file:

{
  "name": "your-project",
  "type": "module"
}

Your First Graph #

The following executable example shows how to import the required classes, register custom node types, build a simple math pipeline (with nodes that generate and double a value), and execute the graph to yield 42.

import { Graph, Executor, registerNodeType } from 'symbiote-engine/browser';

registerNodeType({
  type: 'docs/source',
  driver: {
    inputs: [],
    outputs: [{ name: 'value', type: 'number' }],
  },
  process: (_inputs, { value }) => ({ value }),
});

registerNodeType({
  type: 'docs/double',
  driver: {
    inputs: [{ name: 'value', type: 'number' }],
    outputs: [{ name: 'result', type: 'number' }],
  },
  process: ({ value }) => ({ result: value * 2 }),
});

const graph = new Graph();
const source = graph.addNode('docs/source', { value: 21 });
const double = graph.addNode('docs/double');

graph.connect(source, 'value', double, 'value');

const result = await new Executor().run(graph);
console.log(result.outputs[double].result); // 42

Node Registration #

Custom node definitions are registered globally via registerNodeType. Node registrations dictate the interface (or driver contract) for custom nodes:

• type: A unique string identifier representing the node type (e.g., 'math/add').
• driver: Specifies the inputs and outputs, along with their names and expected types.
• process: The processing function that executes when the node runs. It receives inputs (from connections) and static parameters. If no process function is defined on a generic node definition, the Executor projects static parameters combined with current inputs to the outputs. This generic projection belongs only to node definitions, never to providers, which require executable functions.

Execution Pipeline #

The Executor runs the DAG sequentially. Here are the key execution steps:

• Topological Sorting: Execution follows Kahn's algorithm, ordering nodes according to their directed connections so that a node's dependencies run before it does.
• Orphan Nodes: Isolated or orphan nodes with no connections are omitted during execution.
• Socket Matching: Graph connection validation verifies socket compatibility only when both node definitions and their named sockets exist in the registry. No cyclic checking is performed during connection.