Timescope

Interfaces ​

Public interfaces exported from timescope.

TimescopePreparedView ​

Timescope.prepareView() · Guide

Properties ​

signal
Property
Cancellation signal for this draft and its fetch.
Type
AbortSignal

Methods ​

setTime(value, animation?)

Method
Sets the draft's selected time.
Parameters
value
TimescopeTimeLike
animation?
TimescopeAnimationInput
Defaults
Same as Timescope.setTime().
Returnsboolean
false for invalid input.
Throws
InvalidStateError: fetch() started or abort() called.

setZoom(value, animation?)

Method
Sets the draft's zoom level.
Parameters
value
TimescopeNumberLike
animation?
TimescopeAnimationInput
Defaults
Same as Timescope.setZoom().
Returnsboolean
false for invalid input.
Throws
InvalidStateError: fetch() started or abort() called.

setPlaybackTime(value)

Method
Sets the draft's playback clock; null restores wall-clock time.
Parameters
value
TimescopeTimeLike
Returnsvoid
Throws
InvalidStateError: fetch() started or abort() called.

fetch()

Method
Loads required data and activates the prepared view.
ReturnsPromise<void>
Drawing may still be pending; await Timescope.nextFrame() to finish rendering.
Rejects
InvalidStateError: unmounted, or another view fetching.
AbortError: navigation, interaction, option change, resize, or unmount during fetch.
Acquisition error: data acquisition failed.

abort(reason?)

Method
Cancels the draft or its active fetch.
Parameters
reason?
unknown
Defaults
reason: AbortError.
Returnsvoid

TimescopeDataSource ​

createDataSource() · TimescopeDataSourceBase · Chunk Loading

Properties ​

chunkSize
Property
Preferred number of resolution intervals per query chunk.
Type
number | ((resolution: Decimal) => number)
chunkOrigin
Property
Origin for chunks and aggregation buckets.
Type
Decimal
resolutions?
Property
Preferred loader resolutions; direct queries remain unrestricted.
Type
readonly Decimal[]
immediate
Property
Whether loading is permitted while the view moves.
Type
boolean
cacheSize?
Property
Number of inactive query results retained; 0 disables retention.
Type
number
revision
Property
Current source revision.
Type
number
invalidation?
Property
Latest invalidation range and revision.
Type
TimescopeDataSourceInvalidation

Methods ​

query(request)

Method
Queries a finite range at a positive resolution; no chunk alignment required.
Parameters
request
TimescopeDataSourceQuery
ReturnsPromise<readonly TimescopeDataRow[]>
Points: start <= time && time < end.
Intervals: rowStart < end && start < rowEnd, without trimming.
Aggregates return whole buckets; response requirements.

invalidate(range?)

Method
Notifies consumers of changed data; undefined endpoints are unbounded.
Parameters
range?
TimescopeRange<TimescopeTimeLike<undefined>>
Defaults
range: all data.
Returnsvoid
Does not wait for replacement data or drawing.

on('invalidate', handler)

Method
Subscribes to source invalidation.
Parameters
handler
(event: { type: 'invalidate', value: TimescopeDataSourceInvalidation }) => void
Returns() => void
Unsubscribe function.

dispose?()

Method
Releases source resources.
Returnsvoid

Invalidation ​

range?
Field
Affected range; omitted means all data, and undefined endpoints are unbounded.
Type
TimescopeRange<Decimal | undefined>
revision
Field
Source revision after the change.
Type
number

Built-in sources reacquire invalidated data on demand; snapshot invalidation replaces the whole snapshot even when a range is supplied. Charts manage their DataSources' lifetime, including shared instances. Keep the same instance across configuration updates to retain loaded data; dispose a standalone source with source.dispose?.() when no longer needed.

Refreshing data

Events ​

invalidate
Event
Source data is invalidated or changed.
Payload
{ type: 'invalidate', value: TimescopeDataSourceInvalidation }

TimescopeAppendOnlyDataSource ​

ts
interface TimescopeAppendOnlyDataSource extends TimescopeDataSource

Guide

Methods ​

Only 'point-aggregate' sources support appending. Equal-time points retain insertion order. Later snapshot invalidation discards appended points absent from the original input.

append(rows)

Method
Appends point rows in nondecreasing time order and refreshes consumers; invalid batches insert nothing.
Parameters
rows
TimescopeDataRowInput | readonly TimescopeDataRowInput[]
ReturnsPromise<void>
Resolves after the data update, before drawing necessarily completes. Only direct source mappings apply to appended input.