Documentation / @finchart/core / index / SeriesHandle
Interface: SeriesHandle<T, TPoint>
Defined in: packages/core/src/plot/series-handle.ts:18
Extends
Source<TPoint>
Type Parameters
T
T extends BaseDataPoint
TPoint
TPoint extends BaseDataPoint = T
Properties
attached
readonlyattached:boolean
Defined in: packages/core/src/plot/series-handle.ts:151
Whether this handle is still attached to the pane. The six write doors throw on a detached handle, so this is where to ask before that.
socket.on("tick", (t) => { if (handle.attached) handle.updateLast(t); });Without it, the only option for code holding onto a late-arriving callback is wrapping it in try/catch — a throwing contract only holds up if you can ask first.
The line between asking and throwing sits in a different place. When the whole chart has come down (Plot.removePane, destroy), this is also false, but the write doors don't throw — a late callback firing mid-unmount is the normal path, and by then the pane is already out of both the list and the layout, so whatever it wrote lands nowhere. Read the two cases apart:
attached | write door | what happened |
|---|---|---|
| false | throws | the registration is gone — dispose() or a syncSeries eviction |
| false | silent | the chart came down — removePane or destroy |
read(), xRange, and dispose() are safe even after detaching — reading before asking doesn't blow up.
xRange
readonlyxRange:Range|null
Defined in: packages/core/src/plot/series-handle.ts:122
The x range of the points this registration draws. null if empty.
If it's a derivation, this is the derived result's range — a moving average is shorter than the source by its period, since the leading points are missing. What infinite scroll asks — "how far have we come" — should be answered by what's drawn.
Methods
append()
append(
points):void
Defined in: packages/core/src/plot/series-handle.ts:66
Splices the latest onto the back. Leaves the domain alone.
Parameters
points
T[]
Returns
void
dispose()
dispose():
void
Defined in: packages/core/src/plot/series-handle.ts:154
Detaches the registration. Safe to call twice.
Returns
void
prepend()
prepend(
points):void
Defined in: packages/core/src/plot/series-handle.ts:63
Splices past data onto the front. Leaves the domain alone — dragging left to load history shouldn't snap the screen back to the full range.
Parameters
points
T[]
Returns
void
read()
read():
DataView<TPoint>
Defined in: packages/core/src/plot/series-handle.ts:39
The points this registration draws. Where an indicator's input lives.
const price = pane.addSeries({ series: candleSeries(), data: candles });
computation({ inputs: [price], calc: (candles) => ... });If a derivation is attached, this is its result — what's on screen is exactly the next computation's input.
The returned view is live and read-only. The reason it isn't a copy is that this door is an indicator pipeline's input — copying 100,000 points somewhere that runs on every tick would eat the frame budget on its own. If the receiver needs to sort or filter, it floats one off with [...handle.read()].
Returns
DataView<TPoint>
Overrides
setData()
setData(
data,options?):void
Defined in: packages/core/src/plot/series-handle.ts:57
Replaces the whole dataset. Refits both axes — unless told not to.
refit: false keeps the current window: the door for reconciling recent bars from a REST snapshot while the user is scrolled into history. Replacing what the screen shows is still a replacement — only the viewport verdict changes, not the data contract below.
The array is copied; the points are not. A point is handed over, not lent — from here on the chart reads x off the object you gave it, so editing that object afterward changes the chart with nothing scheduled and the sort order that slicing relies on possibly gone. To change a point, pass a new one (updateLast, or setData again). Copying every point on a door that takes 100,000 of them per call would cost the frame budget on its own, so it's a contract instead.
Parameters
data
T[]
options?
refit?
boolean
Returns
void
swapSeries()
swapSeries(
next):void
Defined in: packages/core/src/plot/series-handle.ts:112
Swaps out only the drawn representation — the data, the derivation, and whatever holds this handle (an indicator's source, live updateLast) all stay put. This is the door for switching chart type, like candle to area: plot.setSeries also discards the pane's other series (a moving average, say), so it can't be used there.
Refits the value axis — different series occupy different ranges (a candle spans low to high, a close line only close).
A Series must be stateless (the same rule as SeriesSpec.series) — a representation that carries state loses it the moment it's swapped out.
Parameters
next
Series<TPoint>
Returns
void
updateLast()
updateLast(
point):void
Defined in: packages/core/src/plot/series-handle.ts:74
A tick for the bar in progress. Same x as the last point means replace, greater means append. Smaller throws DataError — fixing the past is setData's job. Doesn't touch the domain — pan/zoom and a manual value range both stay put.
Parameters
point
T
Returns
void
upsert()
upsert(
points):void
Defined in: packages/core/src/plot/series-handle.ts:97
A snapshot, merged by x. Every x you hand over becomes yours: what the series held at that x is replaced by what you hand over at it, and an x it did not hold is put where it belongs. An x you do not name keeps what it had — a sparse correction is not a deletion, and a snapshot that ends before the live tail does not cut the tail. So a reconnect gap and the previous bar's corrected volume are one call, and the history prepend brought in keeps its objects.
An x before the first point held is history, and history comes in through prepend — this throws DataError there, because the history loader keeps a cursor at the first point it delivered and cannot see a prepend it did not make. Removing a bar is setData's job; this cannot. Leaves the domain alone the way append does.
Which bars a snapshot may speak for is yours to decide — the chart cannot tell a closed bar from one still forming, or a snapshot from before a tick from one after it. Hand over closed bars; the bar in progress is the tick's. A conflated feed holds one pending tick: flush() it first, or its delivery lands on top of the snapshot.
Parameters
points
T[]
Returns
void