Getting started

Core concepts

Engine state and subscriptions, worksheets, chart models and mounted chart views.

The engine

createEngine() returns an object with namespaces of operations (datasets, folders, worksheets, charts, view, mathChannels, live, io, data) and one immutable state snapshot. Operations replace the snapshot; they never mutate it.

TypeScript

const state = engine.getState()          // EngineState
const off = engine.subscribe(() => {     // once per effective change
  render(engine.getState())
})
engine.on('change', (state) => { /* same moment, with the state */ })

Because unchanged parts keep their identity (state.datasets is the same array until a dataset changes), comparing by reference is enough to skip work. Call engine.dispose() when you are done: it unmounts every chart, closes live connections and frees out-of-core datasets.

What the state holds

Field	Contents
`datasets`	Every loaded dataset: columns, row count, colour, offset, laps, selection state.
`selection`	The plotted ids: dataset ids, lap ids and live connection ids. Every chart draws the selection.
`worksheets`	Each with its charts, shared X key and linked zoom range.
`activeWorksheetId`	Which worksheet your UI shows. Charts of any worksheet can be mounted.
`mathChannels`	The formula channels (within the math-channel limit).
`live`	Live connections and their status.
`numericColumns`, `allColumns`, `columnUnits`	Columns across the plotted data, math channels included: feed your column pickers from these.
`hasData`, `importing`, `limits`	Whether anything is plotted, how many files are being imported, and the limits in force.

Worksheets

A worksheet is a set of charts that share one X column (xKey) and one zoom range: zooming one multi-band chart zooms its siblings. The engine starts with one empty worksheet. When data arrives and the worksheet’s X column is missing from it, the first numeric column becomes the X key; set it explicitly with engine.worksheets.setXKey().

Chart models and chart views

A chart exists twice, on purpose:

A model in the state (ChartModel): its kind, title, settings, background and a layout rectangle. engine.charts.add() creates one; charts.update() changes it. Models are what gets exported and imported.
A view in the page (ChartView): the plot drawn into an element of yours by engine.charts.mount(chartId, element). A view has no state of its own beyond the element; it re-renders whenever its model or the plotted data change, and reports its status and user gestures as events.

You can mount a model, destroy its view and mount it again later (for example when your UI switches worksheets), or mount the same model twice.

Failures

Every operation that can fail throws (or rejects with) a KymoscopeError with a code. Limits throw limit_reached and also emit a limit event, so one listener can open your upgrade dialog wherever the action came from. See Limits and errors.