Types
Public types exported from timescope.
Inputs and Navigation
Number and time inputs
type TimescopeNumberLike = number | string | bigint | Decimal;
type DecimalLike = TimescopeNumberLike | { coeff: bigint; digits: number | bigint };
type TimescopeTimeLike<N extends null | undefined = null> = TimescopeNumberLike | Date | N;Numeric strings are decimal values, including scientific notation. JavaScript numbers have already been rounded to their native precision; use strings or Decimal to preserve exact digits.
Time strings are calendar dates parsed by Calendar, not numeric strings. Numbers, bigint, and Decimal use the data's time units, seconds by default; Date converts to Unix epoch seconds. Navigation null follows the clock, and an undefined range endpoint is unbounded. TimescopeTimeLike<never> excludes both nullish values; TimescopeTimeLike<undefined> permits undefined instead of null.
Ranges and sizes
type TimescopeRange<T> = [start: T, end: T];x, y- Type
number- Unit
- CSS px
width, height- Type
number- Unit
- CSS px
dpr- Type
number- Unit
- Ratio
TimescopeFitOptions
animation?- Type
boolean- Default
true
padding?- Type
number | [left: number, right: number]- Default
0- Unit
- CSS px
TimescopeAnimationInput
type TimescopeAnimationInput =
| false
| 'in-out'
| 'linear'
| 'out'
| {
animation: false | 'in-out' | 'linear' | 'out';
duration: number;
lazy?: boolean;
tangent?: number;
};false changes the value immediately. String presets use 500 ms: 'in-out' starts and ends smoothly, 'linear' has constant speed, and 'out' slows toward the end. Object lazy commits the selected value after the animation; tangent controls the initial slope of an 'out' animation.
Data
TimescopeSourceInput
type TimescopeSourceInput =
| string
| readonly TimescopeDataRowInput[]
| TimescopeRangeLoader<readonly TimescopeDataRowInput[]>
| TimescopeSourceOptions
| TimescopeDataSource;TimescopeSourceOptions
type?- Type
'simple' | 'point-aggregate' | 'point-percentile'- Default
'simple'
percentiles?'point-percentile' source. TimescopeDataLoaderOptions · TimescopeSourceCommonOptions
| Source type | Acquisition | Rows | Output value suffixes | Unsuffixed value |
|---|---|---|---|---|
'simple' | Snapshot / range | Points / intervals | — | Original |
'point-aggregate' | Snapshot | Points | #avg, #first, #last, #min, #max | #avg |
'point-percentile' | Snapshot | Points | #first, #last, #min, #max, #p50, #p90, #p95 | percentiles.primary |
Common source options
chunkSize?- Type
number | ((resolution: Decimal) => number)- Default
256
chunkOrigin?- Default
0
immediate?- Type
boolean- Default
true
resolutions?zoomLevels. - Type
readonly TimescopeNumberLike[]
zoomLevels?- Type
readonly number[]
cacheSize?0 disables retention. - Type
number- Default
1000
Percentiles
values?- Type
readonly (0.5 | 0.9 | 0.95)[]- Default
[0.5, 0.9, 0.95]
primary?- Type
0.5 | 0.9 | 0.95- Default
0.5
TimescopeDataLoaderOptions
data?- Type
unknown- Constraint
- Exactly one of
data,url, andloader.
url?- Type
string- Constraint
- Exactly one of
data,url, andloader.
loader?- Constraint
- Exactly one of
data,url, andloader; transforms belong on a supplied DataLoader.
chunked?true. - Type
boolean- Constraint
- Snapshot callbacks and snapshot DataLoader inputs require
false.
decoder?- Constraint
- Mutually exclusive with
mappings.
mappings?- Constraint
- Mutually exclusive with
decoder.
Without a transform, inline data and callback results must be row arrays; URL responses are read as JSON. decoder receives the inline payload, fetched Response, or loader result. URL responses with mappings are read as JSON before mapping. Snapshot sources retain data until invalidation.
Snapshot guide · Range loader guide
URL Placeholders
| Placeholder | Value |
|---|---|
{z}, {zoom} | -log2(resolution) |
{r}, {resolution} | resolution |
{s}, {start} | range[0] |
{e}, {end} | range[1] |
Load and query requests
range- Type
TimescopeRange<Decimal>- Constraint
- Finite;
start <= end
resolution- Type
Decimal- Constraint
> 0
Loader callbacks
type TimescopeRangeLoader<T = unknown> = (request: TimescopeLoadRequest) => T | Promise<T>;
type TimescopeSnapshotLoader<T = unknown> = () => T | Promise<T>;
type TimescopeDataDecoder = (
payload: any,
) => readonly TimescopeDataRowInput[] | Promise<readonly TimescopeDataRowInput[]>;Data rows
type TimescopeDataRowInput = (
| { time: TimescopeTimeLike<never>; times?: never }
| { time?: never; times: Record<string, TimescopeTimeLike<never>> }
) &
(
| { value: TimescopeNumberLike | null; values?: never }
| { value?: never; values: Record<string, TimescopeNumberLike | null> }
) & { data?: unknown };Normalized rows
times- Type
Record<string, Decimal>
values- Type
Record<string, Decimal | null>
data- Type
unknown
Field mappings
times- Type
Record<string, string>
values- Type
Record<string, string>
Configuration
TimescopeOptions
cursor?color sets the center line (default: 'red'), borderColor sets the side borders (default: 'transparent'). - Type
boolean | { color?: string, borderColor?: string }- Default
true
showFps?- Type
boolean- Default
false
font?sources?domains?series?tracks?- Default
- Implicit
defaultTrack
selection?- Default
true
Referenced DataSources, Tracks, and named Domains must exist. Omitting tracks creates an implicit default Track; an empty Track object is invalid.
TimescopeOptionsInitial
TimescopeOptions · Constructor
time?null follows the clock. - Default
null- Constraint
- Mutually exclusive with
fit.
zoom?- Default
0- Constraint
- Mutually exclusive with
fit.
fit?0. - Type
TimescopeRange<TimescopeTimeLike<never>> | { range: TimescopeRange<TimescopeTimeLike<never>>, padding?: number | [number, number] }- Constraint
- Mutually exclusive with
timeandzoom;start < end; padding finite and nonnegative.
timeRange?- Type
TimescopeRange<TimescopeTimeLike | undefined>- Default
[undefined, null]
zoomRange?- Type
TimescopeRange<TimescopeNumberLike | undefined>- Default
[undefined, undefined]
target?backend?- Type
TimescopeBackendChoice | readonly TimescopeBackendChoice[]- Default
- Auto
renderThread?- Type
'worker' | 'main'- Default
- Auto
environment?fonts?- Type
(string | { family: string, source: string | BufferSource, desc?: FontFaceDescriptors })[]- Default
- Document fonts
wheelSensitivity?- Type
number- Default
200
selection.range?- Type
TimescopeRange<TimescopeTimeLike<never>> | null- Default
null
backend, renderThread, and fonts are creation-only. Automatic backend selection normally uses Canvas in browsers and Skia Canvas in Node.js; an array selects the first compatible backend. Automatic thread selection can be overridden with 'main' or 'worker'; requiring a Worker needs Worker support and a compatible target. fonts: [] disables additional font loading; omitted fonts loads accessible document @font-face rules.
View control · Fonts · Node.js
TimescopeUpdateOptions
cursor?- Type
TimescopeOptions['cursor']
showFps?- Type
boolean
font?sources?- Type
Record<string, TimescopeSourceInput | null>
domains?- Type
Record<string, TimescopeDomainOptions | null>
series?- Type
Record<string, TimescopeSeriesInput | null>
tracks?- Type
Record<string, { height?: number, symmetric?: boolean, timeAxis?: boolean | TimescopeTimeAxisOptions } | null>
selection?updateOptions() merges objects; arrays and source inputs replace their previous values. Named entries accept null for deletion. Remove dependent Series in the same update when deleting a source. setOptions() replaces the entire configuration, restoring defaults for omitted settings. Both preserve time and zoom, and clear selection only when it is disabled.
TimescopeSeriesInput
data.source- Type
string
data.name?- Type
string
data.color?- Type
string
data.domain?- Type
string | TimescopeDomainOptions
data.resolution?data.instantaneous?- Type
false | { using?: Using1, zoom?: number, resolution?: TimescopeNumberLike }
chart?- Type
TimescopeChartType | { marks?: TimescopeChartMark[] | ((context) => TimescopeChartMark[]), links?: TimescopeChartLink[] | ((context) => TimescopeChartLink[]) }
tooltip?- Type
boolean | { label?: string, side?: 'left' | 'right', round?: TimescopeRound, format?: (context) => string }
track?- Type
string
Instantaneous Values
using?- Type
Using1- Default
'value'
zoom?- Type
number
resolution?The default sample is the latest row at or before the cursor, without interpolation. zoom or resolution chooses sampling granularity independently of the Chart. Set data.instantaneous: false or tooltip: false to disable cursor sampling.
Tooltip
label?- Type
string
side?- Type
'left' | 'right'- Default
'right'
round?- Type
TimescopeRound
format?Resolution
TimescopeDataResolution
type TimescopeResolutionSnap = 'nearest' | 'floor' | 'ceil';
type TimescopeResolutionResolver = TimescopeNumberLike | ((context: TimescopeResolutionContext) => TimescopeNumberLike);
type TimescopeDataResolution =
| TimescopeResolutionSnap
| TimescopeResolutionResolver
| { resolve?: TimescopeResolutionResolver; snap?: TimescopeResolutionSnap };resolve?- Default
- Display resolution
snap?- Default
'nearest'
'nearest' snaps on the logarithmic zoom scale. 'floor' chooses the largest interval at or below the preference; 'ceil' chooses the smallest at or above it. Both clamp to the available endpoints. Source hints apply to range loaders, not snapshots, and do not restrict direct query() calls.
Resolver context
resolution2 ** (-zoom). - Type
Decimal
resolutions- Type
readonly Decimal[]
Formatting
TimescopeRound
type TimescopeRoundMode = 'decimal' | 'pow10';
type TimescopeRoundLabel = 'decimal' | 'e' | 'pow10';
type TimescopeRound =
| number
| TimescopeRoundLabel
| {
mode?: TimescopeRoundMode;
digits?: number;
label?: TimescopeRoundLabel | ((context: TimescopeRoundContext) => string);
};| Shortcut | Equivalent options |
|---|---|
n (number) | { mode: 'decimal', digits: n, label: 'decimal' } |
'decimal' | { mode: 'decimal', digits: 2, label: 'decimal' } |
'e' | { mode: 'pow10', digits: 2, label: 'e' } |
'pow10' | { mode: 'pow10', digits: 2, label: 'pow10' } |
Object mode is inferred from a string label, otherwise it defaults to 'decimal'; an omitted label uses the mode. digits must be a safe integer and cannot be negative in 'pow10' mode. Incompatible mode/label pairs are rejected.
Formatter context
modevalue- Type
Decimal
roundedValuevalue on axes. - Type
Decimal
mantissa- Type
string
base- Type
10
exponent0n in decimal mode. - Type
bigint
Charts and Styles
Using
type UsingElement<V extends [string, string]> =
| `${V[1] | '#zero' | '#top' | '#bottom'}@${V[0]}`
| (V[1] | '#zero' | '#top' | '#bottom')
| `@${V[0]}`;
type Using1<V extends [string, string]> = UsingElement<V> | [UsingElement<V>];
type Using2<V extends [string, string]> = [UsingElement<V>, UsingElement<V>];
type Using<V extends [string, string] = [string, string]> = Using1<V> | Using2<V>;| Form | Value | Time |
|---|---|---|
'value@time' | value | time |
'value' | value | Default |
'@start' | Default | start |
['min', 'max'] | min, max | Default |
'#zero' | Shared baseline | Default |
'#top', '#bottom' | Chart-area edges | Default |
'value#avg' | value#avg | Default |
| Primitive | Default using |
|---|---|
| Single-coordinate Mark / Link | 'value@time' |
line, bar, section Marks | ['min', 'max'] |
| Area Links | ['value', '#zero'] |
TimescopeChartType
| Preset | Marks | Links | :filled variant |
|---|---|---|---|
'lines' | — | line | area |
'curves' | — | curve | curve-area |
'steps-start' | — | step-start | step-area-start |
'steps' | — | step | step-area |
'steps-end' | — | step-end | step-area-end |
'points' | circle | — | — |
'linespoints' | circle | line | area |
'curvespoints' | circle | curve | curve-area |
'stepspoints-start' | circle | step-start | step-area-start |
'stepspoints' | circle | step | step-area |
'stepspoints-end' | circle | step-end | step-area-end |
'impulses' | line to #zero | — | — |
'impulsespoints' | line to #zero, circle | — | — |
'bars' | bar to #zero | — | Bar fill |
TimescopeChartLink
| draw | using | Style |
|---|---|---|
'line', 'curve' | Using1 | Stroke |
'step-start', 'step', 'step-end' | Using1 | Stroke |
'area', 'curve-area' | Using2 | Stroke, Fill |
'step-area-start', 'step-area', 'step-area-end' | Using2 | Stroke, Fill |
TimescopeChartMark
| draw | using | Style |
|---|---|---|
'circle' | Using1 | Stroke, Fill, Size, Offset |
'triangle', 'square', 'diamond', 'star' | Using1 | Stroke, Fill, Size, Angle, Offset |
'cross', 'plus', 'minus' | Using1 | Stroke, Size, Angle, Offset |
'line', 'section' | Using2 | Stroke, Size, Offset |
'bar' | Using2 | Stroke, Fill, Size, Box, Offset |
'region' | Using2 | Stroke, Fill, Box |
'text' | Using1 | Text, Size, Angle, Offset |
'icon' | Using1 | Icon, Size, Angle, Offset |
'path' | Using1 | Path, Size, Angle, Offset |
Chart entries
draw- Type
string- Callback form
(context) => value
using?- Callback form
(context) => value
style?origin, scale, and fillPost. - Type
- Chart style
- Callback form
(context) => value
Chart styles
Stroke and fill
lineWidth?- Type
number- Default
1
lineColor?- Type
string
lineDashArray?- Type
number[]
lineDashOffset?- Type
number
fillColor?- Type
string
fillOpacity?- Type
number- Default
1
fillPost?- Type
boolean- Default
false
fillOpacity is clamped to 0–1.
Geometry
size?- Type
number- Unit
- px
angle?- Type
number- Unit
- deg
offset?- Type
[x: number, y: number]- Unit
- px
extrude?- Type
number | [top: number, right?: number, bottom?: number, left?: number]- Unit
- px
radius?- Type
number- Unit
- px
path?- Type
string- Unit
- SVG
origin?- Type
[number, number]
scale?- Type
number
Text and icons
| TextStyle field | IconStyle field | Type |
|---|---|---|
text? | icon? | string |
font? | font? | TimescopeFontStyle |
textAlign? | iconAlign? | 'start' | 'center' | 'end' | 'left' | 'right' |
textBaseline? | iconBaseline? | 'top' | 'middle' | 'bottom' | 'hanging' | 'alphabetic' | 'ideographic' |
textColor? | iconColor? | string |
textOpacity? | iconOpacity? | number |
textOutline? | iconOutline? | boolean |
textOutlineColor? | iconOutlineColor? | string |
textOutlineWidth? | iconOutlineWidth? | number |
TimescopeFontStyle
type TimescopeFontStyle =
| string
| {
style?: string;
variant?: string;
weight?: string;
stretch?: string;
size?: number | string;
lineHeight?: number | string;
family?: string;
};Object properties inherit from local settings, then global settings, then location defaults. A local string replaces the global font; local objects inherit defaults rather than properties from a global string. Icon fonts use local settings only. Numeric size is in pixels; numeric lineHeight is unitless. String sizes and line heights use CSS syntax.
Text Mark size priority: local string font → local object font.size → Mark style.size → global object font.size → default. A global string is used unchanged when neither a local font nor an explicit Mark size is set.
Layout and Axes
TimescopeOptionsTracks
type TimescopeOptionsTracks<Track extends string> = {
[K in Track]: {
height?: number;
symmetric?: boolean;
timeAxis?: boolean | TimescopeTimeAxisOptions;
};
};TimescopeTimeAxisOptions
axis?- Type
false | { color?: string }
ticks?- Type
false | { color?: string }
labels?- Type
false | { color?: string, font?: TimescopeFontStyle }
relative?- Type
boolean- Default
false
timeFormat?timeUnit?- Type
's' | 'ms' | 'us' | 'ns'- Default
's'
timeZone?- Type
string- Default
'local'
Time formatting
type CalendarLevel = 'subsecond' | 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year' | 'relative';
type TimeFormatFunc = (context: TimeFormatFuncOptions) => string | undefined;time- Type
Decimal
unit- Type
's' | 'ms' | 'us' | 'ns'
level- Type
CalendarLevel
digits- Type
number
stride?- Type
bigint
year?, month?, quarter?, date?, minutes?, seconds?- Type
(context: TimeFormatLabelerOptions) => string
year, second- Type
bigint
quarter, month, day, hour, minute, digits- Type
number
week- Type
number
time, subseconds- Type
Decimal
TimescopeOptionsSelection
type TimescopeOptionsSelection =
| boolean
| {
resizable?: boolean;
color?: string;
invert?: boolean;
};resizable?- Type
boolean- Default
true
color?- Type
string
invert?- Type
boolean
Selection is enabled by default. false disables selection and clears its range; true restores default settings. resizable: false disables Shift-drag creation and handle resizing without clearing an existing selection. Set the initial range with constructor selection.range, or use the range methods after creation.
TimescopeDomainOptions
scale?- Type
'linear' | 'linear-symmetric' | 'log'- Default
'linear'
axis?- Type
boolean | 'left' | 'right' | TimescopeYAxisOptions- Default
false
animation?- Type
boolean- Default
true
range?- Type
TimescopeNumberLike | TimescopeRange<TimescopeNumberLike | undefined> | { expand?: boolean, shrink?: boolean, default?: TimescopeNumberLike | TimescopeRange<TimescopeNumberLike | undefined> }
expand?- Type
boolean- Default
false
shrink?- Type
boolean- Default
true
floatingGap?- Type
number- Default
20px
unit?- Type
string- Default
''
An undefined range endpoint follows visible data; a scalar range means [0, value]. Top-level expand and shrink override the corresponding fields inside range. Logarithmic Domains draw positive values only and require positive specified bounds. unit appears in Tooltips and value-axis labels.
TimescopeYAxisOptions
side?- Type
'left' | 'right'
label?- Type
string
round?- Type
TimescopeRound
color?- Type
string
font?Rendering
Rendering targets
type TimescopeBackendChoice = 'canvas' | 'skia-canvas';
type TimescopeBackendTarget = Element | string | TimescopeCanvas;width, height- Type
number
getContext- Type
(type: '2d') => unknown
Container and selector targets are sized automatically; Timescope creates and owns their canvas. Supplied canvases retain application ownership and use explicit resize(width, height, dpr). Omit constructor target to mount later. The mounted canvas property is null while unmounted.
TimescopeEnvironment
requestAnimationFrame?- Type
(callback: () => void) => number | void
cancelAnimationFrame?- Type
(handle: number) => void
Path2D?- Type
new (path?: string) => Path2D
fonts?- Type
FontFaceSet