Skip to content

Types ​

Public types exported from timescope.

Inputs and Navigation ​

Number and time inputs ​

ts
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.

Decimal · Calendar

Ranges and sizes ​

ts
type TimescopeRange<T> = [start: T, end: T];
x, y
Field
Canvas position within the viewport.
Type
number
Unit
CSS px
width, height
Field
Canvas dimensions.
Type
number
Unit
CSS px
dpr
Field
Device pixel ratio used for drawing.
Type
number
Unit
Ratio

TimescopeFitOptions ​

animation?
Field
Animates the fitted view.
Type
boolean
Default
true
padding?
Field
Space around the fitted range; finite and nonnegative. A scalar applies to both sides.
Type
number | [left: number, right: number]
Default
0
Unit
CSS px

Guide

TimescopeAnimationInput ​

ts
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.

Method defaults

Data ​

TimescopeSourceInput ​

Snapshot guide · Chunk Loading

TimescopeSourceOptions ​

type?
Field
Source query and aggregation strategy.
Type
'simple' | 'point-aggregate' | 'point-percentile'
Default
'simple'
percentiles?
Field
Percentile selection for a 'point-percentile' source.

TimescopeDataLoaderOptions · TimescopeSourceCommonOptions

Source typeAcquisitionRowsOutput value suffixesUnsuffixed value
'simple'Snapshot / rangePoints / intervals—Original
'point-aggregate'SnapshotPoints#avg, #first, #last, #min, #max#avg
'point-percentile'SnapshotPoints#first, #last, #min, #max, #p50, #p90, #p95percentiles.primary

Decimation guide

Common source options ​

chunkSize?
Field
Preferred query size; a positive safe integer, stable per resolution.
Type
number | ((resolution: Decimal) => number)
Default
256
chunkOrigin?
Field
Origin for chunks and aggregation buckets.
Default
0
immediate?
Field
Permits loading while the view moves.
Type
boolean
Default
true
resolutions?
Field
Positive resolution hints for range loaders; overrides zoomLevels.
Type
readonly TimescopeNumberLike[]
zoomLevels?
Field
Range-loader resolution hints expressed as zoom levels.
Type
readonly number[]
cacheSize?
Field
Inactive query results retained; nonnegative integer, 0 disables retention.
Type
number
Default
1000

Guide

Percentiles ​

values?
Field
Percentiles exposed as suffixed output values.
Type
readonly (0.5 | 0.9 | 0.95)[]
Default
[0.5, 0.9, 0.95]
primary?
Field
Percentile used for the unsuffixed output value.
Type
0.5 | 0.9 | 0.95
Default
0.5

TimescopeDataLoaderOptions ​

data?
Field
Inline payload; row array without a transform.
Type
unknown
Constraint
Exactly one of data, url, and loader.
url?
Field
Snapshot URL or range URL with placeholders.
Type
string
Constraint
Exactly one of data, url, and loader.
loader?
Field
Acquisition callback or reusable loader.
Constraint
Exactly one of data, url, and loader; transforms belong on a supplied DataLoader.
chunked?
Field
Range-loading mode; function loaders default to true.
Type
boolean
Constraint
Snapshot callbacks and snapshot DataLoader inputs require false.
decoder?
Field
Converts a payload or fetched response to rows.
Constraint
Mutually exclusive with mappings.
mappings?
Field
Maps record-array fields to row coordinates.
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 ​

PlaceholderValue
{z}, {zoom}-log2(resolution)
{r}, {resolution}resolution
{s}, {start}range[0]
{e}, {end}range[1]

Load and query requests ​

range
Field
Constraint
Finite; start <= end
resolution
Field
Constraint
> 0

Response requirements

Loader callbacks ​

ts
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[]>;

Acquisition and transforms

Data rows ​

ts
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 };

Guide

Normalized rows ​

times
Field
Normalized named time coordinates.
Type
Record<string, Decimal>
values
Field
Normalized named values.
Type
Record<string, Decimal | null>
data
Field
Original row metadata.
Type
unknown

Field mappings ​

times
Field
Time names mapped to payload paths.
Type
Record<string, string>
values
Field
Value names mapped to payload paths.
Type
Record<string, string>

Acquisition and transforms

Configuration ​

TimescopeOptions ​

cursor?
Field
Time cursor visibility; color sets the center line (default: 'red'), borderColor sets the side borders (default: 'transparent').
Type
boolean | { color?: string, borderColor?: string }
Default
true
showFps?
Field
Frame-rate display.
Type
boolean
Default
false
font?
Field
Global text font.
sources?
Field
Named DataSource inputs.
domains?
Field
Named value Domains.
series?
Field
Named Series configurations.
tracks?
Field
Named drawing regions; an empty object is invalid.
Default
Implicit default Track
selection?
Field
Selection interaction and overlay settings.
Default
true

Referenced DataSources, Tracks, and named Domains must exist. Omitting tracks creates an implicit default Track; an empty Track object is invalid.

Guide · Typed configuration

TimescopeOptionsInitial ​

TimescopeOptions · Constructor

time?
Field
Initial selected time; null follows the clock.
Default
null
Constraint
Mutually exclusive with fit.
zoom?
Field
Initial zoom level.
Default
0
Constraint
Mutually exclusive with fit.
fit?
Field
Initial fitted range and CSS-pixel padding; padding defaults to 0.
Type
TimescopeRange<TimescopeTimeLike<never>> | { range: TimescopeRange<TimescopeTimeLike<never>>, padding?: number | [number, number] }
Constraint
Mutually exclusive with time and zoom; start < end; padding finite and nonnegative.
timeRange?
Field
Navigation bounds.
Default
[undefined, null]
zoomRange?
Field
Zoom bounds.
Default
[undefined, undefined]
target?
Field
Mount target; omit to mount later.
backend?
Field
Backend or ordered candidates.
Default
Auto
renderThread?
Field
Rendering thread.
Type
'worker' | 'main'
Default
Auto
environment?
Field
Canvas environment overrides.
fonts?
Field
Additional browser font data; ignored by Skia Canvas.
Type
(string | { family: string, source: string | BufferSource, desc?: FontFaceDescriptors })[]
Default
Document fonts
wheelSensitivity?
Field
Wheel delta per zoom level.
Type
number
Default
200
selection.range?
Field
Initial selected range.
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?
Field
Type
TimescopeOptions['cursor']
showFps?
Field
Type
boolean
font?
Field
sources?
Field
Type
Record<string, TimescopeSourceInput | null>
domains?
Field
Type
Record<string, TimescopeDomainOptions | null>
series?
Field
Type
Record<string, TimescopeSeriesInput | null>
tracks?
Field
Type
Record<string, { height?: number, symmetric?: boolean, timeAxis?: boolean | TimescopeTimeAxisOptions } | null>
selection?
Field

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.

Update methods

TimescopeSeriesInput ​

data.source
Field
Type
string
data.name?
Field
Type
string
data.color?
Field
Type
string
data.domain?
Field
data.resolution?
Field
data.instantaneous?
Field
Type
false | { using?: Using1, zoom?: number, resolution?: TimescopeNumberLike }
chart?
Field
Type
TimescopeChartType | { marks?: TimescopeChartMark[] | ((context) => TimescopeChartMark[]), links?: TimescopeChartLink[] | ((context) => TimescopeChartLink[]) }
tooltip?
Field
Type
boolean | { label?: string, side?: 'left' | 'right', round?: TimescopeRound, format?: (context) => string }
track?
Field
Type
string

Chart callbacks · Guide

Instantaneous Values ​

using?
Field
Value sampled at the cursor.
Type
Using1
Default
'value'
zoom?
Field
Sampling zoom level.
Type
number
resolution?
Field
Sampling resolution.

Guide

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?
Field
Tooltip label override.
Type
string
side?
Field
Preferred label side relative to the sample.
Type
'left' | 'right'
Default
'right'
round?
Field
Number rounding and label format; omitted values remain unrounded.
format?
Field
Complete tooltip formatter, overriding name, unit, and rounding.
Type
(context: { time: Decimal, value: Decimal | null, name: string | undefined, unit: string }) => string

Guide

Resolution ​

TimescopeDataResolution ​

resolve?
Field
Preferred data interval; resolved values must be positive.
Default
Display resolution
snap?
Field
Snapping mode for source hints or integer-zoom resolutions.
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.

Guide

Resolver context ​

resolution
Field
Display time units per pixel, 2 ** (-zoom).
resolutions
Field
Preferred source resolutions; empty if unrestricted.
Type
readonly Decimal[]

Formatting ​

TimescopeRound ​

ts
type TimescopeRoundMode = 'decimal' | 'pow10';
type TimescopeRoundLabel = 'decimal' | 'e' | 'pow10';
type TimescopeRound =
  | number
  | TimescopeRoundLabel
  | {
      mode?: TimescopeRoundMode;
      digits?: number;
      label?: TimescopeRoundLabel | ((context: TimescopeRoundContext) => string);
    };
ShortcutEquivalent 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' }

Guide

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 ​

mode
Field
Resolved rounding mode.
value
Field
Original tooltip value or finalized axis value.
roundedValue
Field
Displayed value; equal to value on axes.
mantissa
Field
Signed, formatted mantissa.
Type
string
base
Field
Exponent base.
Type
10
exponent
Field
Decimal exponent; 0n in decimal mode.
Type
bigint

Charts and Styles ​

Using ​

ts
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>;
FormValueTime
'value@time'valuetime
'value'valueDefault
'@start'Defaultstart
['min', 'max']min, maxDefault
'#zero'Shared baselineDefault
'#top', '#bottom'Chart-area edgesDefault
'value#avg'value#avgDefault
PrimitiveDefault using
Single-coordinate Mark / Link'value@time'
line, bar, section Marks['min', 'max']
Area Links['value', '#zero']

Guide

TimescopeChartType ​

PresetMarksLinks:filled variant
'lines'—linearea
'curves'—curvecurve-area
'steps-start'—step-startstep-area-start
'steps'—stepstep-area
'steps-end'—step-endstep-area-end
'points'circle——
'linespoints'circlelinearea
'curvespoints'circlecurvecurve-area
'stepspoints-start'circlestep-startstep-area-start
'stepspoints'circlestepstep-area
'stepspoints-end'circlestep-endstep-area-end
'impulses'line to #zero——
'impulsespoints'line to #zero, circle——
'bars'bar to #zero—Bar fill

Preset guide · Custom Charts

drawusingStyle
'line', 'curve'Using1Stroke
'step-start', 'step', 'step-end'Using1Stroke
'area', 'curve-area'Using2Stroke, Fill
'step-area-start', 'step-area', 'step-area-end'Using2Stroke, Fill

Entry fields and callback context

TimescopeChartMark ​

Entry fields and callback context

Chart entries ​

draw
Field
Primitive name; determines supported coordinates and styles.
Type
string
Callback form
(context) => value
using?
Field
Coordinate selectors for the primitive.
Callback form
(context) => value
style?
Field
Drawing style; individual fields also accept callbacks except origin, scale, and fillPost.
Callback form
(context) => value
CallbackContext
Mark{ times: Record<string, Decimal>, values: Record<string, Decimal | null>, data: unknown, resolution: Decimal }
Link{ resolution: Decimal }

Guide

Chart styles ​

Stroke and fill ​

lineWidth?
Field
Type
number
Default
1
lineColor?
Field
Type
string
lineDashArray?
Field
Type
number[]
lineDashOffset?
Field
Type
number
fillColor?
Field
Type
string
fillOpacity?
Field
Type
number
Default
1
fillPost?
Field
Type
boolean
Default
false

Guide

fillOpacity is clamped to 0–1.

Geometry ​

size?
Field
Type
number
Unit
px
angle?
Field
Type
number
Unit
deg
offset?
Field
Type
[x: number, y: number]
Unit
px
extrude?
Field
Type
number | [top: number, right?: number, bottom?: number, left?: number]
Unit
px
radius?
Field
Type
number
Unit
px
path?
Field
Type
string
Unit
SVG
origin?
Field
Type
[number, number]
scale?
Field
Type
number

Text and icons ​

TextStyle fieldIconStyle fieldType
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 ​

ts
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.

Guide

Layout and Axes ​

TimescopeOptionsTracks ​

ts
type TimescopeOptionsTracks<Track extends string> = {
  [K in Track]: {
    height?: number;
    symmetric?: boolean;
    timeAxis?: boolean | TimescopeTimeAxisOptions;
  };
};

Guide

TimescopeTimeAxisOptions ​

axis?
Field
Type
false | { color?: string }
ticks?
Field
Type
false | { color?: string }
labels?
Field
Type
false | { color?: string, font?: TimescopeFontStyle }
relative?
Field
Type
boolean
Default
false
timeFormat?
Field
timeUnit?
Field
Type
's' | 'ms' | 'us' | 'ns'
Default
's'
timeZone?
Field
Type
string
Default
'local'

Guide

Time formatting ​

ts
type CalendarLevel = 'subsecond' | 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year' | 'relative';
type TimeFormatFunc = (context: TimeFormatFuncOptions) => string | undefined;
time
Field
unit
Field
Type
's' | 'ms' | 'us' | 'ns'
level
Field
digits
Field
Type
number
stride?
Field
Type
bigint
year?, month?, quarter?, date?, minutes?, seconds?
Field
Type
(context: TimeFormatLabelerOptions) => string
year, second
Field
Type
bigint
quarter, month, day, hour, minute, digits
Field
Type
number
week
Field
Type
number
time, subseconds
Field

Guide

TimescopeOptionsSelection ​

ts
type TimescopeOptionsSelection =
  | boolean
  | {
      resizable?: boolean;
      color?: string;
      invert?: boolean;
    };
resizable?
Field
Enables Shift-drag creation and handle resizing.
Type
boolean
Default
true
color?
Field
Selected-range overlay color.
Type
string
invert?
Field
Shades outside the selected range.
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.

Range methods · Component range

TimescopeDomainOptions ​

scale?
Field
Type
'linear' | 'linear-symmetric' | 'log'
Default
'linear'
axis?
Field
Type
boolean | 'left' | 'right' | TimescopeYAxisOptions
Default
false
animation?
Field
Type
boolean
Default
true
range?
Field
Type
TimescopeNumberLike | TimescopeRange<TimescopeNumberLike | undefined> | { expand?: boolean, shrink?: boolean, default?: TimescopeNumberLike | TimescopeRange<TimescopeNumberLike | undefined> }
expand?
Field
Type
boolean
Default
false
shrink?
Field
Type
boolean
Default
true
floatingGap?
Field
Type
number
Default
20 px
unit?
Field
Type
string
Default
''

Guide

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?
Field
Type
'left' | 'right'
label?
Field
Type
string
round?
Field
color?
Field
Type
string
font?
Field

Guide

Rendering ​

Rendering targets ​

ts
type TimescopeBackendChoice = 'canvas' | 'skia-canvas';
type TimescopeBackendTarget = Element | string | TimescopeCanvas;
width, height
Field
Type
number
getContext
Field
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.

Node.js guide

TimescopeEnvironment ​

requestAnimationFrame?
Field
Type
(callback: () => void) => number | void
cancelAnimationFrame?
Field
Type
(handle: number) => void
Path2D?
Field
Type
new (path?: string) => Path2D
fonts?
Field
Type
FontFaceSet