Sequence

classpond-tssource

An unbounded fixed-step grid definition used for alignment or aggregation.

Sequence defines where buckets fall. Call bounded(...) to realize a finite BoundedSequence over a specific range.

Important distinction:

the sequence anchor defines where the unbounded grid starts
the caller-supplied range defines which finite slice is realized

The default anchor is Unix epoch 0.

Constructor

new Sequence(input: FixedSequenceInput | CalendarSequenceInput)

Static methods

calendarstatic

calendar(unit: CalendarUnit, options?: CalendarOptions): Sequence

Creates an unbounded calendar-aware sequence.

Calendar sequences step by local calendar boundaries in an IANA time zone instead of by a fixed millisecond duration. Supported units are "day", "week", and "month".

Defaults:

timeZone: "UTC"

dailystatic

daily(options?: { anchor?: TimestampInput }): Sequence

Sequence.daily()

Creates a daily fixed-step sequence.

everystatic

every(every: DurationInput, options?: { anchor?: TimestampInput }): Sequence

Creates an unbounded fixed-step sequence.

The returned sequence is a grid definition, not a finite bucket list. By default the grid is anchored at Unix epoch 0, which makes independently-created sequences line up by default. Use bounded(...) or series operations like align(...) / aggregate(...) to realize a finite slice of the grid over a concrete range.

hourlystatic

hourly(options?: { anchor?: TimestampInput }): Sequence

Sequence.hourly()

Creates an hourly fixed-step sequence.

Methods

anchor

anchor(): number

sequence.anchor()

Returns the millisecond anchor used by this grid definition.

bounded

bounded(range: TemporalLike, options?: { coverage?: SequenceCoverage; sample?: SequenceSample }): BoundedSequence

sequence.bounded(new TimeRange({ start, end }))

Realizes a finite BoundedSequence over the supplied range.

coverage chooses what "over the range" means, and is the more consequential of the two options:

'sample' (default) — select by sample point, per the table below. The bucket containing range.begin() is excluded when it starts before it, because its sample point sits outside the range.
'overlap' — select every bucket whose extent overlaps the range, including the one containing range.begin(). sample is then ignored: selection is on extent, not on a point. Use this whenever the buckets are containers that must account for every instant in the range — aggregate realizes its grid this way.

At the default sample: 'begin' only the leading edge differs between the two: both keep a trailing bucket that starts inside the range and runs past its end. Against a non-default sample the trailing edge moves too, because 'overlap' drops the sample offset that 'sample' shifts both edges by — another reason to read 'overlap' as ignoring sample outright rather than as a modifier on it.

A single-instant range under 'overlap' is the flooring primitive: sequence.bounded({ start: t, end: t }, { coverage: 'overlap' }) returns exactly the bucket containing t.

Sample position controls which intervals are selected under coverage: 'sample':

'begin' (default) — sample point is the interval's start. Includes buckets where sample ∈ [range.begin, range.end].
'center' — sample point is the interval's midpoint. Same inclusive range as 'begin'.
'end' — sample point is the interval's exclusive end (i.e. the start of the next bucket). Inclusion is left-exclusive: sample ∈ (range.begin, range.end]. This keeps the boundary case symmetric — an end-sample at exactly range.begin() would otherwise pull in an interval whose extent sits entirely before the range.