API Reference

This is a hand-written, conceptual reference for the Vela™ public surface — what each piece is for and how the pieces bind. A generated type reference (from the source declarations) may be added later; for now this prose is the source of truth.

The mental model

Vela™ is a small core plus three independently swappable layers — data providers, scripting engines, and renderers — each reached through a single narrow port.

The neutral model — bars, series, pane overlays, drawings, inputs, update patches — is the only thing that crosses a port. No backend-specific type ever leaks across. That opacity is what makes each layer swappable. What ships is the native renderer and the provider-backed, cache-wrapped data feed — both plain swappable defaults. No scripting engine ships at all: you install one (Pine Script: @luxalgo/vela-pinets) or write one against the port — see Scripting engines.

These snippets import from the npm package @luxalgo/vela (see Installation).

The higher-level shell is documented on its own page: the workspace (@luxalgo/vela/workspace — one chart with layout: false, or a multi-chart grid with one shared chrome and sync links). It exposes the state surface — getState() / applyState() / state:changed over one shared document format — which is also what its persist option writes.

class Vela(container, options?, deps?)

The public, imperative chart and the composition root — the one place that wires concrete backends.

• container — an HTMLElement or a CSS selector string. A missing selector throws.
• options — display, behavior, and market options. See Options.
• deps — the swap point for the three layers (see below).

Constructing a chart renders candles immediately. Scripting engines are opt-in.

Core methods

Because registerEngine returns the chart, you can wire an engine straight off construction:

const chart = new Vela('#chart', { data: myBars, timeframe: '1h' })
  .registerEngine('pine', new PineEngine());

Adding an indicator: sync handle, async data

addIndicator returns right away so you can wire up UI before any computation finishes. The script is prepared (its inputs are parsed) and then executed over the bar history; the plotted output appears when execution resolves. Listen on the handle's ready event (or chart.ready() for the whole chart) rather than assuming data is present on return. On a deep-history chart the indicator waits for the background backfill and then computes once over the full depth — its ready fires when that single run lands.

A minimal end-to-end setup — construct over data, register a scripting engine (here the Pine addon), add an indicator, then await the first render:

import { Vela } from '@luxalgo/vela';
import { PineEngine } from '@luxalgo/vela-pinets';

const chart = new Vela('#chart', { data: myBars, timeframe: '1h', theme: 'dark' });
chart.registerEngine('pine', new PineEngine());

// addIndicator returns synchronously — wire UI now; plotted values fill in later.
const rsi = chart.addIndicator(`//@version=5
indicator("RSI")
plot(ta.rsi(close, input.int(14, "Length")), "RSI", color.purple)`);
rsi.on('ready', () => console.log(rsi.title, 'has computed'));

await chart.ready(); // resolves once the chart is painted and interactive

IndicatorHandle

What addIndicator returns. Usable immediately.

The handle is usable the moment addIndicator returns; drive the indicator's lifecycle through its events and mutators:

const macd = chart.addIndicator(macdSource);

// React to the computation outcome.
macd.on('ready', () => console.log('inputs:', macd.inputs.map((i) => i.key)));
macd.on('error', ({ error }) => console.error('MACD failed:', error.message));

// Retune inputs — each change triggers a re-run.
macd.setInput('fast', 8);
macd.setInputs({ slow: 21, signal: 5 });

// Hiding suspends it (visuals dropped, computation stopped); showing re-runs it.
macd.setVisible(false);
console.log(macd.visible); // false

macd.remove(); // drop it from the chart

Capturing what a script computes

Two doors, one vocabulary. script:run reports every script the chart runs; runScript() executes one and hands you its first run. Both deliver the same ScriptRun object, so host code reads a manifest indicator, a console addIndicator, and an editor's script identically.

chart.on('script:run', (run) => {
    run.title;          // 'SMA cross' — the title the script DECLARED
    run.kind;           // 'indicator' | 'strategy'
    run.cause;          // why it computed (see below)
    run.bar;            // index of the last computed bar
    run.plots.fast;     // that plot's value at that bar
    run.vars.fastLen;   // the script's own variables, by their SOURCE names

    if (run.strategy) {
        run.strategy.position; // signed contracts held
        run.strategy.equity;
        run.strategy.openPnl;
        run.strategy.netPnl;
    }
});

The handle is already resolved and the data already extracted — there is nothing to look up and nothing to await.

Provisional vs final

cause is the field that decides whether a value can be trusted:

Anything that records, alerts, or exports should key off 'bar':

chart.on('script:run', (run) => {
    if (run.cause === 'bar') persist(run);  // a bar just closed — settled
    else updateDashboard(run);              // provisional
});

'tick' runs are throttled to ~1/s per indicator (a live stream re-executes the open candle several times a second, which no dashboard can use). Every other cause is emitted unconditionally — dropping a 'bar' run would break exactly the case above.

Two more flags round out the picture: forming is true while the run's last bar is still open (always so on a live chart, never on a static one), and complete is false only while an engine that computes progressively is still being fed a deep backfill.

What rides the run, and what you ask for

Flat and at the current bar → on the run. Historical and unbounded → an explicit call, so a per-tick listener never ships a ledger it will not read:

const trades = await run.trades();      // the strategy's round trips, closed then open
const history = await run.series('fast'); // one plot's full history

Executing a script and capturing its result

const result = await chart.runScript(source);
if (!result.ok) return console.error(result.error);

result.run.strategy.netPnl;
const off = result.onUpdate((run) => console.log(run.strategy.openPnl));
result.remove();                        // take it off the chart

runScript resolves on the first computed run, injects the script only if it runs (a failure removes it again — no dead legend row), and never rejects.

Across a grid

@luxalgo/vela/workspace relays the same event with the cell it came from, so one subscription covers every cell — including cells a later layout change creates:

ws.on('script:run', (run) => console.log(run.cell, run.title, run.strategy?.equity));

The lower-level snapshot

handle.context(select?) remains the pull counterpart — a read-only deep copy of the engine's execution context (phase, barIndex, meta, plots, variables, strategy, trades, warnings), async on both the in-process and Web-Worker engines (the context never leaves the worker; only the snapshot crosses), and selective via select. script:run is built on it and is what host code should normally use; reach for context() when you want a snapshot at a moment of your choosing rather than at a run. On a runIndicator failure the same snapshot is attached post-mortem ({ ok: false, error, context }) — the state at the moment of the crash.

Chart-level events

Subscribe with chart.on(event, handler); every subscription returns an unsubscribe function.

chart.renderer — the renderer control surface

A thin facade over the active renderer for reading and changing how the chart is drawn at runtime, with no indicator re-run. Unsupported keys/methods warn and no-op, so the chart is never left half-changed.

Feature-detect, read, and change how the chart is drawn at runtime — with no indicator re-run:

// Only touch a feature the active renderer actually supports.
if (chart.renderer.supports('glow')) {
    console.log('glow is', chart.renderer.get('glow'));
    chart.renderer.set('glow', 0.6);
}

// Apply several features at once (one repaint).
chart.renderer.set({ logScale: true, currentPriceLine: false });

See Renderer Features for the full feature catalog (common + native-specific) and config/screenshot examples.

chart.data — the data control surface

A facade over the provider registry for where candles come from. Register one or more market-data providers; the chart routes each symbol to the right one. No provider is bundled — registering the one that resolves the chart symbol fires the parked initial load.

Register the provider that resolves the chart symbol, then wait for both the index and the initial load:

import { Vela } from '@luxalgo/vela';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';

const chart = new Vela('#chart', { symbol: 'BTCUSDT', timeframe: '1h' });

// Registering the provider that resolves the symbol fires the parked initial load.
chart.data.registerProvider('binance', new BinanceProvider());
await chart.data.ready(); // provider symbol indexes settled
await chart.ready();      // chart painted and interactive

console.log(chart.data.resolve('BTCUSDT'));            // { provider: 'binance', ticker: 'BTCUSDT' }
console.log(chart.data.symbols('binance').length, 'symbols indexed');
console.log(chart.data.capabilities('BTCUSDT'));       // ProviderCapabilities | null

On a chart given a custom deps.dataFeed, these warn and no-op (that feed owns its data). See Data Providers for symbol formats, resolution, and the load lifecycle.

chart.drawings — the drawings control surface

A chainable facade over the interactive drawing tools. The drawing model is core-owned, so the interactive methods are capability-gated (they warn + no-op when the renderer can't paint drawings — chart.drawings.supported reports this), while the model methods (reading, persisting, undo) always work.

Drawing lifecycle is also surfaced as chart events (drawing:created / drawing:edited / drawing:removed / drawing:selected / drawing:settings), and the tool/mode state as drawing:tool / drawing:snap / drawing:stay / drawing:mode — the seam an external toolbar mirrors. See Drawing tools for the tool catalogue, toolbar UX, and keyboard shortcuts.

deps — the swap point

The optional third constructor argument is where you replace a layer's default with your own implementation of that layer's port:

Each layer is one narrow port — implement it, declare its honest capabilities, and inject it here. The composition root is the only place that imports concrete backends.

The three adding-a-backend guides are Contributing docs and are still being written. Until they land, no link points at them — see the Contributing section of the docs index.

Stability: The API is still stabilizing and will evolve as the library develops; pin a source revision if you need a fixed surface.