json-pipeline

3.12.3 verified Fri May 01 auth: no javascript

json-pipeline (v3.12.3) is a structure specification for designing flexible compilers with support for third-party optimization phases. It provides abstractions for sea-of-nodes (SoN), control flow graphs (CFG), static single assignment (SSA), dominator trees, and global code motion (GCM). The package is designed for Node.js and focuses on JSON-representable intermediate representations, making it suitable for compiler backends and JIT compilers. Release cadence is irregular; last major update was v3.0.0 with breaking changes in API. Key differentiators: modular architecture, JSON serialization, and emphasis on custom optimization phases.

Common errors

error TypeError: Pipeline is not a constructor ↓

cause Using named import instead of default import.

fix

Use import Pipeline from 'json-pipeline' (default import).

error Error: Node with id X not found ↓

cause Referencing a node that has not been added to the graph.

fix

Ensure nodes are created via graph.createNode() and added before using them as inputs.

error Cannot read property 'setInput' of undefined ↓

cause graph.setStart() or graph.setEnd() called before nodes are created.

fix

Create nodes first, then set start/end.

error AssertionError [ERR_ASSERTION]: Graph must have a start node ↓

cause Calling graph.toJSON() without setting a start node.

fix

Set the graph's start node using graph.setStart(node).

Warnings

breaking v3.0.0 changed the API: Pipeline constructor now requires options object. ↓

fix Update to `new Pipeline({ /* options */ })`.

gotcha Node.setInput(index, node) does not clone nodes; mutates the graph structure in-place. ↓

fix If you need immutability, clone the graph before modification.

deprecated pipeline.createGraph() is deprecated in favor of pipeline.createGraph(options). ↓

fix Use `pipeline.createGraph({ name: 'myGraph' })` instead.

gotcha Node types are not validated; invalid types may cause runtime errors. ↓

fix Ensure node types match expected schema from documentation.

breaking .toJSON() and .fromJSON() are not symmetric in v3.2.0 - due to internal ordering. ↓

fix Upgrade to v3.2.1 or later.

Install

npm install json-pipeline

yarn add json-pipeline

pnpm add json-pipeline

Imports

Pipeline

wrong

const { Pipeline } = require('json-pipeline')

correct

import Pipeline from 'json-pipeline'

Default export only; named import does not exist.

Node

wrong

import { Pipeline, Node } from 'json-pipeline'

correct

import Pipeline, { Node } from 'json-pipeline'

Node is a named export; Pipeline is default.

Graph

wrong

const Graph = require('json-pipeline').Graph

correct

import Pipeline, { Graph } from 'json-pipeline'

Graph is a named export; ensure ESM import syntax.

Quickstart

Create a pipeline, build a graph with two constant nodes feeding into an add node, serialize to JSON, and deserialize.

import Pipeline, { Node, Graph } from 'json-pipeline';

// Create a new pipeline
const pipeline = new Pipeline();

// Create a graph
const graph = pipeline.createGraph();

// Create nodes
const node1 = graph.createNode('add', { type: 'op' });
node1.setInput(0, graph.createNode('const', { value: 1 }));
node1.setInput(1, graph.createNode('const', { value: 2 }));

// Set start/end nodes
graph.setStart(node1);
graph.setEnd(node1);

// Serialize to JSON
const json = pipeline.toJSON();
console.log(JSON.stringify(json, null, 2));

// Deserialize
const restored = Pipeline.fromJSON(json);
console.log(restored.graphs[0].nodes.length);