Classes

Public classes exported from timescope.

Timescope

Timescope

Constructor

new Timescope(options?: TimescopeOptionsInitial)

Constructor options · Guide

Properties

time

Property

Selected time; null follows the clock. Assignments use setTime().

Get

Decimal | null

Set

TimescopeTimeLike

timeChanging

Property

Time during interaction.

Get

Decimal | null

timeAnimating

Property

Time during animation.

Get

Decimal | null

timeRange

Property

Navigation bounds; undefined is unbounded and null follows the clock.

Get

TimescopeRange<Decimal | null | undefined>

zoom

Property

Selected zoom level. Assignments use setZoom().

Get

number

Set

TimescopeNumberLike

zoomChanging

Property

Zoom level during interaction.

Get

number

zoomAnimating

Property

Zoom level during animation.

Get

number

zoomRange

Property

Zoom bounds; undefined is unbounded.

Get

TimescopeRange<number | undefined>

selectionRange

Property

Committed selection; null when cleared.

Get

TimescopeRange<Decimal> | null

selectionRangeChanging

Property

Selection range during interaction.

Get

TimescopeRange<Decimal> | null

size

Property

Viewport position, CSS-pixel dimensions, and drawing DPR.

Get

TimescopeSize

disabled

Property

Disables interaction when true; initially false.

Get

boolean

Set

boolean

animating

Property

Whether a time animation is active.

Get

boolean

editing

Property

Whether time is being edited.

Get

boolean

options

Property

Current configuration, excluding creation-only state.

Get

TimescopeOptions

canvas

Property

Mounted canvas; null while unmounted.

Get

TimescopeCanvas | null

Methods

setTime(value, animation?)

Method

Sets the selected time; null follows the clock.

Parameters

value

TimescopeTimeLike

animation?

TimescopeAnimationInput

Defaults

animation: 'out', 500 ms.

Returnsboolean

false for invalid input.

setZoom(value, animation?)

Method

Sets the selected zoom level.

Parameters

value

TimescopeNumberLike

animation?

TimescopeAnimationInput

Defaults

animation: 'linear', 200 ms; lazy commit when zooming in.

Returnsboolean

false for invalid input.

setTimeRange(range?)

Method

Sets navigation bounds.

Parameters

range?

TimescopeRange<TimescopeTimeLike | undefined>

Defaults

range: [undefined, null].

Returnsvoid

setZoomRange(range?)

Method

Sets zoom bounds.

Parameters

range?

TimescopeRange<TimescopeNumberLike | undefined>

Defaults

range: [undefined, undefined].

Returnsvoid

fitTo(range, options?)

Method

Fits a time range, deferred until the canvas has a drawable size.

Parameters

range

TimescopeRange<TimescopeTimeLike<never>>

options?

TimescopeFitOptions

Defaults

options.animation: true; options.padding: 0 CSS px.

Returnsboolean

false for invalid range or padding; requires start < end and finite, nonnegative padding.

setPlaybackTime(value)

Method

Sets the clock followed while time is null; null restores wall-clock time.

Parameters

value

TimescopeTimeLike

Returnsvoid

setSelectionRange(range)

Method

Sets or clears selection; ignored while selection is disabled.

Parameters

range

TimescopeRange<TimescopeTimeLike<never>> | null

Returnsvoid

clearSelectionRange()

Method

Clears the selected range.

Returnsvoid

setOptions(next)

Method

Replaces configuration; preserves time and zoom.

Parameters

next

TimescopeOptions

Defaults

Omitted settings use their defaults.

Returnsvoid

updateOptions(patch)

Method

Merges configuration; null removes named entries.

Parameters

patch

TimescopeUpdateOptions

Defaults

Omitted settings retain their values.

Returnsvoid

reload(sources?)

Method

Requests source invalidation.

Parameters

sources?

string[]

Defaults

sources: all sources.

ReturnsPromise<boolean>

false if unavailable or failed; does not wait for replacement data or drawing.

prepareView()

Method

Creates an editable pending view for data acquisition.

ReturnsTimescopePreparedView

Prepared-view API.

resize(width, height, dpr?)

Method

Resizes an externally managed canvas.

Parameters

width

number

height

number

dpr?

number

Defaults

dpr: 1.

ReturnsPromise<boolean>

false for automatically sized targets or failure.

redraw()

Method

Requests drawing without fetching data.

ReturnsPromise<void>

nextFrame()

Method

Waits for a drawable mount and completed drawing.

ReturnsPromise<void>

Does not fetch data.

mount(target?)

Method

Mounts on a compatible target; built-in backends require one.

Parameters

target?

TimescopeBackendTarget

Returnsthis

The current instance.

unmount()

Method

Releases the mount, retaining instance listeners and externally supplied canvases.

Returnsvoid

dispose()

Method

Releases the instance and its event listeners.

Returnsvoid

on(event, handler)

Method

Subscribes to an event; its name determines the handler payload.

Parameters

event

string

handler

(event: object | string) => void

Returns() => void

Unsubscribe function.

un(event, handler)

Method

Removes a registered event handler.

Parameters

event

string

handler

(event: object | string) => void

Returnsvoid

dispose() also removes instance event listeners; unmount() retains them for a later mount. The unsubscribe function returned by on() ends an individual subscription while keeping the instance alive.

View control · Data refresh · Node.js · Cleanup

Events

timechanging

Event

Time changes during interaction.

Payload

{ type: 'timechanging', value: Decimal | null, origin?: string }

timechanged

Event

Selected time is committed.

Payload

{ type: 'timechanged', value: Decimal | null, origin?: string }

timeanimating

Event

Time animation progresses.

Payload

{ type: 'timeanimating', value: Decimal | null, origin?: string }

timeanimated

Event

Time animation finishes.

Payload

{ type: 'timeanimated', value: Decimal | null, origin?: string }

zoomchanging

Event

Zoom changes during interaction.

Payload

{ type: 'zoomchanging', value: number, origin?: string }

zoomchanged

Event

Selected zoom is committed.

Payload

{ type: 'zoomchanged', value: number, origin?: string }

zoomanimating

Event

Zoom animation progresses.

Payload

{ type: 'zoomanimating', value: number, origin?: string }

zoomanimated

Event

Zoom animation finishes.

Payload

{ type: 'zoomanimated', value: number, origin?: string }

selectionrangechanging

Event

Selection changes during interaction.

Payload

{ type: 'selectionrangechanging', value: TimescopeRange<Decimal> | null, origin?: string }

selectionrangechanged

Event

Selection is committed or cleared.

Payload

{ type: 'selectionrangechanged', value: TimescopeRange<Decimal> | null, origin?: string }

error

Event

Backend selection or initialization fails.

Payload

{ type: 'error', value: Error, origin?: string }

ready

Event

First drawable mount with a non-zero size; once per instance.

Payload

'ready'

mount

Event

Each drawable mount with a non-zero size.

Payload

'mount'

unmount

Event

Mounted chart is removed.

Payload

'unmount'

resize

Event

Canvas size or device pixel ratio changes.

Payload

'resize'

change

Event

Observable state changes.

Payload

'change'

Navigation values have committed (time, zoom), interaction (timeChanging, zoomChanging), and animation (timeAnimating, zoomAnimating) phases. Value events contain { type, value, origin? }; lifecycle events carry their event-name string. Mount readiness does not imply data acquisition or drawing completion; use a prepared view and nextFrame() when reading pixels.

Guide

TimescopeDataLoader

TimescopeDataLoader

Constructor

new TimescopeDataLoader(options: TimescopeDataLoaderOptions)

Each load() performs acquisition again; a DataLoader does not cache results. Sharing an instance shares acquisition and conversion settings, not DataSource caches or invalidation state. Configure transforms on the loader, not on a DataSource receiving it.

ranged is true for templated URLs or function loaders without chunked: false. A snapshot DataLoader requires chunked: false when supplied to a DataSource.

Options · Factory

Properties

ranged

Property

Whether load() requires a range request.

Type

boolean

Methods

load()

Method

Acquires and normalizes a fresh snapshot.

ReturnsPromise<readonly TimescopeDataRow[]>

Rejects

Error: range loader called without a request.
Acquisition or conversion error: input could not be loaded or normalized.

load(request)

Method

Acquires and normalizes rows for a range.

Parameters

request

TimescopeLoadRequest

ReturnsPromise<readonly TimescopeDataRow[]>

Rejects

Error: snapshot loader called with a request, or unknown alphabetic URL placeholder.
RangeError: reversed range or nonpositive resolution.
Acquisition or conversion error: input could not be loaded or normalized.

Request · Callbacks

TimescopeDataSourceBase

TimescopeDataSourceBase

abstract class TimescopeDataSourceBase implements TimescopeDataSource

Constructor

constructor(options?: TimescopeSourceCommonOptions)

Options · DataSource contract

Properties

Inherited properties

revision

Property

Source revision, incremented on invalidation.

Type

number

Initial value

0

invalidation

Property

Latest invalidation range and revision.

Type

TimescopeDataSourceInvalidation | undefined

Initial value

undefined

Methods

query(request)

Method

Abstract query implementation.

Parameters

request

TimescopeDataSourceQuery

ReturnsPromise<readonly TimescopeDataRow[]>

Canonical rows following the query contract.

invalidate(range?)

Method

Increments revision and emits change and invalidate, without acquiring data; omitted range affects all data.

Parameters

range?

TimescopeRange<TimescopeTimeLike<undefined>>

Returnsvoid

Throws

RangeError: reversed range.

on(event, handler)

Method

Subscribes to source events.

Parameters

event

'change' | 'invalidate'

handler

(event: object | string) => void

Returns() => void

Unsubscribe function.

un(event, handler)

Method

Removes a registered handler.

Parameters

event

'change' | 'invalidate'

handler

(event: object | string) => void

Returnsvoid

dispose()

Method

Releases event handlers.

Returnsvoid

Events

change

Event

Source revision is incremented.

Payload

'change'

invalidate

Event

Source data is invalidated.

Payload

{ type: 'invalidate', value: TimescopeDataSourceInvalidation }

Decimal

Decimal

@kikuchan/decimal

Constructor

Decimal(value: DecimalLike): Decimal
Decimal(value: null): null
Decimal(value: undefined): undefined

Numeric inputs

Accepts decimal and scientific-notation strings, numbers, bigint, Decimal values, and coefficient/scale objects. For example, { coeff: 123n, digits: 2 } represents 1.23. digits may be negative. Nullish inputs are preserved.

Properties

coeff

Property

Signed coefficient in coeff × 10⁻ᵈⁱᵍⁱᵗˢ.

Type

bigint

digits

Property

Decimal scale; a safe integer.

Type

number

Methods

Numeric methods return new values; their $ variants mutate the receiver. Use non-mutating methods on values received from Timescope.

Operation	Semantics
round, floor, ceil, trunc	Decimal places, default 0; negative places round to powers of ten. Nearest ties round away from zero; floor and ceil round toward negative and positive infinity; trunc rounds toward zero. force: true preserves scale, including trailing zeros.
roundBy, floorBy, ceilBy, truncBy	Round to a multiple of the supplied step. roundBy defaults to nearest rounding.
div, divExact	precision counts significant digits and must be a positive safe integer. div is exact for terminating results when precision is omitted; otherwise it rounds, defaulting to 18. divExact throws for non-terminating results without a fallback precision.
divRound, divFloor, divCeil, divTrunc	Round division results to decimal places.
pow, sqrt, root	Exact when possible with precision omitted; otherwise precision 18. Fractional exponents are supported.
log, inverse	log defaults to precision 18; inverse follows division precision rules.
mod, modPositive	JavaScript remainder sign rules, or a nonnegative remainder respectively.
between, isCloseTo	Inclusive bounds, or absolute-difference tolerance respectively.
split, splitBy	Return the rounded part and remainder; default mode 'floor'. split defaults to digits: 0; splitBy uses step multiples.
rescale, toFixed, number, integer	Set decimal scale (omitting scale removes trailing fractional zeros), format rounded fixed decimal places, convert with possible precision loss, or truncate toward zero respectively.
neg	Negates by default; false preserves the sign.

add(v)

Method

Parameters

v

DecimalLike

ReturnsDecimal

sub(v)

Method

Parameters

v

DecimalLike

ReturnsDecimal

mul(v, digits?)

Method

Parameters

v

DecimalLike

digits?

number | bigint

ReturnsDecimal

div(v, precision?, mode?)

Method

Parameters

v

DecimalLike

precision?

number | bigint

mode?

'round' | 'floor' | 'ceil' | 'trunc'

ReturnsDecimal

divExact(v, fallbackPrecision?, mode?)

Method

Parameters

v

DecimalLike

fallbackPrecision?

number | bigint

mode?

'round' | 'floor' | 'ceil' | 'trunc'

ReturnsDecimal

divRound(v, digits?, mode?)

Method

Parameters

v

DecimalLike

digits?

number | bigint

mode?

'round' | 'floor' | 'ceil' | 'trunc'

ReturnsDecimal

divFloor(v, digits?)

Method

Parameters

v

DecimalLike

digits?

number | bigint

ReturnsDecimal

divCeil(v, digits?)

Method

Parameters

v

DecimalLike

digits?

number | bigint

ReturnsDecimal

divTrunc(v, digits?)

Method

Parameters

v

DecimalLike

digits?

number | bigint

ReturnsDecimal

mod(v)

Method

Parameters

v

DecimalLike

ReturnsDecimal

modPositive(v)

Method

Parameters

v

DecimalLike

ReturnsDecimal

neg(flag?)

Method

Parameters

flag?

boolean

ReturnsDecimal

abs()

Method

ReturnsDecimal

sign()

Method

Returnsnumber

eq(v)neq(v)

Method

Parameters

v

DecimalLike

Returnsboolean

lt(v)le(v)

Method

Parameters

v

DecimalLike

Returnsboolean

gt(v)ge(v)

Method

Parameters

v

DecimalLike

Returnsboolean

cmp(v)

Method

Parameters

v

DecimalLike

Returnsnumber

between(min, max)

Method

Parameters

min

DecimalLike | undefined

max

DecimalLike | undefined

Returnsboolean

isCloseTo(v, tolerance)

Method

Parameters

v

DecimalLike

tolerance

DecimalLike

Returnsboolean

isZero()isPositive()isNegative()

Method

Returnsboolean

round(digits?, force?)

Method

Parameters

digits?

number | bigint

force?

boolean

ReturnsDecimal

floor(digits?, force?)

Method

Parameters

digits?

number | bigint

force?

boolean

ReturnsDecimal

ceil(digits?, force?)

Method

Parameters

digits?

number | bigint

force?

boolean

ReturnsDecimal

trunc(digits?, force?)

Method

Parameters

digits?

number | bigint

force?

boolean

ReturnsDecimal

roundBy(step, mode?)

Method

Parameters

step

DecimalLike

mode?

'round' | 'floor' | 'ceil' | 'trunc'

ReturnsDecimal

floorBy(step)ceilBy(step)truncBy(step)

Method

Parameters

step

DecimalLike

ReturnsDecimal

rescale(digits?, mode?)

Method

Parameters

digits?

number | bigint

mode?

'round' | 'floor' | 'ceil' | 'trunc'

ReturnsDecimal

toString()

Method

Returnsstring

toFixed(digits)

Method

Parameters

digits

number | bigint

Returnsstring

number()

Method

Returnsnumber

integer()

Method

Returnsbigint

pow(exponent, precision?)

Method

Parameters

exponent

DecimalLike

precision?

number | bigint

ReturnsDecimal

sqrt(precision?)

Method

Parameters

precision?

number | bigint

ReturnsDecimal

root(degree, precision?)

Method

Parameters

degree

number | bigint

precision?

number | bigint

ReturnsDecimal

log(base, precision?)

Method

Parameters

base

DecimalLike

precision?

number | bigint

ReturnsDecimal

inverse(precision?)

Method

Parameters

precision?

number | bigint

ReturnsDecimal

clamp(min, max)

Method

Parameters

min

DecimalLike | undefined

max

DecimalLike | undefined

ReturnsDecimal

shift10(exponent)

Method

Parameters

exponent

number | bigint

ReturnsDecimal

order()

Method

Returnsbigint

frac()

Method

ReturnsDecimal

split(digits?, mode?)

Method

Parameters

digits?

number | bigint

mode?

'round' | 'floor' | 'ceil' | 'trunc'

Returns[Decimal, Decimal]

splitBy(step, mode?)

Method

Parameters

step

DecimalLike

mode?

'round' | 'floor' | 'ceil' | 'trunc'

Returns[Decimal, Decimal]

clone()

Method

ReturnsDecimal

Static Methods

min, max, and minmax ignore nullish values and return null for an extremum when no values remain. isDecimal checks for a Decimal instance, isDecimalLike for accepted input, and isDecimalType for a Decimal or coefficient/scale object.

Decimal.isDecimal(value)

Static method

Parameters

value

unknown

Returnsvalue is Decimal

Decimal.isDecimalLike(value)

Static method

Parameters

value

unknown

Returnsvalue is DecimalLike

Decimal.isDecimalType(value)

Static method

Parameters

value

unknown

Returnsboolean

Decimal.pow10(exponent)

Static method

Parameters

exponent

number | bigint

ReturnsDecimal

Decimal.min(...values)

Static method

Parameters

...values

(DecimalLike | null | undefined)[]

ReturnsDecimal | null

Decimal.max(...values)

Static method

Parameters

...values

(DecimalLike | null | undefined)[]

ReturnsDecimal | null

Decimal.minmax(...values)

Static method

Parameters

...values

(DecimalLike | null | undefined)[]

Returns[Decimal | null, Decimal | null]

Decimal.equals(a, b)

Static method

Parameters

a

DecimalLike | null | undefined

b

DecimalLike | null | undefined

Returnsboolean

Calendar

Calendar

@kikuchan/calendar

Calendar instants use Unix epoch seconds, including fractional seconds; Date inputs convert from milliseconds. The initial display zone is 'local'. Zones accept 'local', 'utc', or IANA names; changing the zone preserves the instant. Factory methods preserve null and undefined.

Constructor

new Calendar()new Calendar(epochSeconds)new Calendar(year, month, day, hour?, minutes?, seconds?)

Constructor

Creates a calendar value in the local display zone.

Parameters

epochSeconds

DecimalLike | Date

Unix epoch seconds or a JavaScript date.

year, month, day

bigint | number

Calendar components; month and day are one-based.

hour?, minutes?

bigint | number

seconds?

DecimalLike

Defaults

No arguments: current time. hour, minutes, seconds: 0.

ReturnsCalendar

Static Methods

Calendar.fromEpoch(epochSeconds)

Static method

Parameters

epochSeconds

DecimalLike

ReturnsCalendar

Calendar.fromDate(date)

Static method

Parameters

date

Date

ReturnsCalendar

Calendar.fromComponents(input)

Static method

Creates a calendar value from integer components; seconds may be fractional.

Parameters

input

{ year: DecimalLike, month: DecimalLike, day: DecimalLike, hour?: DecimalLike, minutes?: DecimalLike, seconds?: DecimalLike, zone?: string }

Defaults

input.hour, input.minutes, input.seconds: 0.
input.zone: 'local'.

ReturnsCalendar

Calendar.parse(value, format?, inputZone?)

Static method

Parses a calendar date; explicit offsets take precedence over the input zone.

Parameters

value

string

format?

string

inputZone?

string

Defaults

format: ISO 8601; inputZone: 'local'.

ReturnsCalendar

Methods

Component getters use the display zone: months 1–12, days 1–31, hours 0–23, minutes 0–59, weekdays Sunday 0 through Saturday 6. Component setters and zone-changing methods return new instances; $ variants mutate the receiver. The zone argument to fromComponents() determines component interpretation, not the initial display zone.

Day/month/year alignment methods return new instances at midnight in the current zone. alignToSecond(step) aligns to a seconds interval within the day.

year()

Method

Returnsbigint

month()

Method

Returnsbigint

day()

Method

Returnsbigint

hour()

Method

Returnsbigint

minutes()

Method

Returnsbigint

seconds()

Method

ReturnsDecimal

weekday()

Method

Returnsnumber

epoch()

Method

ReturnsDecimal

components()

Method

Returns{ year: bigint, month: bigint, day: bigint, hour: bigint, minutes: bigint, seconds: Decimal, weekday: number }

clone()

Method

ReturnsCalendar

year(value)month(value)day(value)hour(value)minutes(value)seconds(value)

Method

Parameters

value

DecimalLike

ReturnsCalendar

year$(value)month$(value)day$(value)hour$(value)minutes$(value)seconds$(value)

Method

Parameters

value

DecimalLike

ReturnsCalendar

epoch(value)

Method

Parameters

value

DecimalLike

ReturnsCalendar

epoch$(value)

Method

Parameters

value

DecimalLike

Returnsthis

zone()

Method

Returnsstring

zone(value)

Method

Parameters

value

string

ReturnsCalendar

utc()

Method

ReturnsCalendar

local()

Method

ReturnsCalendar

zone$(value)utc$()local$()

Method

Parameters

value

string

Returnsthis

alignToDay(step?)

Method

Day boundary at or before this date; arrays specify boundaries.

Parameters

step?

number | bigint | (number | bigint)[]

Defaults

step: 1.

ReturnsCalendar

nextDay(step?)

Method

Next day boundary; arrays specify boundaries.

Parameters

step?

number | bigint | (number | bigint)[]

Defaults

step: 1.

ReturnsCalendar

alignToMonth(step?)

Method

Month boundary at or before this date; arrays specify boundaries.

Parameters

step?

number | bigint | (number | bigint)[]

Defaults

step: 1.

ReturnsCalendar

nextMonth(step?)

Method

Next month boundary; arrays specify boundaries.

Parameters

step?

number | bigint | (number | bigint)[]

Defaults

step: 1.

ReturnsCalendar

alignToYear(step?, options?)

Method

Year boundary at or before this date; options.era enables era-aware alignment.

Parameters

step?

number | bigint | (number | bigint)[]

options?

{ era?: boolean }

Defaults

step: 1.

ReturnsCalendar

nextYear(step?, options?)

Method

Next year boundary; options.era enables era-aware alignment.

Parameters

step?

number | bigint | (number | bigint)[]

options?

{ era?: boolean }

Defaults

step: 1.

ReturnsCalendar

alignToSecond(step)

Method

Parameters

step

DecimalLike

ReturnsCalendar

format(format)

Method

Parameters

format

string

Returnsstring

Format Tokens

Token	Parsing	Formatting
Y / y, repeated n times	Optional sign; one or more digits	At least n digits; negative sign only
IY	Same as Y	Four digits for years 0–9999; otherwise sign and at least six digits
G, repeated n times	Positive era year; BC prefix or AD suffix	At least n digits; BC prefix or AD suffix
g, repeated n times	Positive era year; optional BC prefix	At least n digits; BC prefix before AD 1
MM / M	1–2 digit month	Two digits / no padding
DD	1–2 digit day	Two digits
hh / h	1–2 digit 24-hour time	Two digits / no padding
mm	1–2 digit minute	Two digits
ss	1–2 digit whole second	Two digits
S, repeated n times	1–n fractional digits	Exactly n digits; padded or truncated
S*	One or more fractional digits	All fractional digits without trailing zeros; 0 for integer seconds
Z	Z, ±HH:mm, or ±HHmm	Z for zero offset; otherwise ±HH:mm
[text]	Literal text	Literal text
Backslash + character	Literal next character	Literal next character

Custom parse formats require year and month; omitted components default to day 1 and midnight. Invalid dates throw. Formatting uses the current display zone. Year widths are minimum widths and never truncate; astronomical year 0 is 1 BC and -1 is 2 BC, while era-year tokens use positive era years. Characters other than recognized tokens and escapes, including fractional separators, are literal.