@gestaltbi/editor

The shape of it

import { readGraph, writeGraph } from '@gestaltbi/editor';

const graph = readGraph(processingJson);

graph.nodes     // placed at { depth, lane }, with a kind, a summary and an arity
graph.edges     // { from, to, socket }
graph.problems  // cycles, bad arity, requires that name nothing

// ...and back, without losing anything it did not model
const config = writeGraph(graph.nodes, processingJson);

Every node arrives with somewhere to be, so a host renders without solving layout — multiply by whatever spacing suits the surface and draw.

Positions are derived, never stored

Depth is the longest path from the raw frame, so a node always sits to the right of everything it reads. Lanes are ordered by the average position of each node's inputs, which keeps edges short without a full crossing-minimisation pass.

The point is what it means for a config nobody wrote in an editor. A processing.json written by hand, or generated by a build script — as the Kickstarter bundle is — opens as a readable picture straight away. Nothing has to be migrated to gain coordinates.

Nodes say what they are for

The op key tells you which class runs. kind tells you what it does to the data, which is what somebody reading a pipeline for the first time actually needs.

inputs carries the op's arity, so a canvas knows how many sockets to draw and a validator can catch a graph wired more ways than the op reads. A host with its own ops passes its own arities:

readGraph(config, { arity: { myop: 2 } });

A third of a config is not a stage

Entries named conf_* declare <code>"op": "noop"</code>, which is not a registered op. They never run; they exist so views can read their options — which measure a chart opens on, which columns a table shows, which currency a story uses.

They are left off the canvas by default, because a node that cannot run is noise among nodes that do — and put back untouched when the graph is written. Ask for them with includeSettings to show them somewhere they make sense, beside the view they configure.

Problems are reported, not thrown

A config with a cycle in it is exactly the config somebody needs to look at. Refusing to draw it hands them a stack trace instead of a picture of their mistake, so readGraph always returns a graph and lists what is wrong with it.

graph.problems
// [{ severity: 'error', code: 'cycle', node: 'a',
//    message: '"a" is part of a cycle: a -> b -> a' }]

The Studio

The node canvas this package exists for. Open a config repo by its org/repo slug, or a processing.json from disk, and the graph draws itself — then add stages from a palette grouped by what they do to the data, wire them by dragging between sockets, and copy the result back out.

It is a host, not a fork: every decision about what the graph means comes from this package, which is why the editor and the read-only view inside GestaltBI cannot disagree about a config. Sockets come from each op's declared arity; problems are listed as you work; the document is the source and the canvas redraws from it.

Opening a config that already exists

An editor that quietly drops what it did not understand is one nobody can safely open a real config with. writeGraph carries through the top-level keys, every option exactly as read, the settings carriers that were never on the canvas, and the original key order — so a diff shows what you changed and nothing else.