pond-ts 0.1.0

package/dist/Event.js

@@ -0,0 +1,162 @@
+import { Interval } from './Interval.js';
+import { Time } from './Time.js';
+import { TimeRange } from './TimeRange.js';
+/**
+ * An immutable event made of a temporal key and typed payload data.
+ *
+ * @example
+ * ```ts
+ * const event = new Event(
+ *   new Time(new Date("2025-01-01T00:00:00.000Z")),
+ *   { cpu: 0.42, host: "api-1" },
+ * );
+ *
+ * event.get("cpu"); // 0.42
+ * event.timeRange(); // TimeRange for the event extent
+ * ```
+ */
+export class Event {
+    #key;
+    #data;
+    /** Example: `new Event(new Time(Date.now()), { value: 1 })`. Creates an immutable event from a key and typed payload object. */
+    constructor(key, data) {
+        this.#key = key;
+        this.#data = Object.freeze({ ...data });
+        Object.freeze(this);
+    }
+    /** Example: `event.key()`. Returns the event key. */
+    key() {
+        return this.#key;
+    }
+    /** Example: `event.withKey(new Time(Date.now()))`. Returns a new event with the same payload and a different key. */
+    withKey(key) {
+        return new Event(key, this.#data);
+    }
+    /** Example: `event.type()`. Returns the underlying key kind. */
+    type() {
+        return this.#key.kind;
+    }
+    /** Example: `event.data()`. Returns the immutable event payload. */
+    data() {
+        return this.#data;
+    }
+    /** Example: `event.get("value")`. Returns a single payload field by name. */
+    get(field) {
+        return this.#data[field];
+    }
+    /** Example: `event.set("value", 2)`. Returns a new event with one payload field replaced. */
+    set(field, value) {
+        return new Event(this.#key, {
+            ...this.#data,
+            [field]: value,
+        });
+    }
+    /** Example: `event.merge({ host: "api-1" })`. Returns a new event with a shallow payload merge applied. */
+    merge(patch) {
+        return new Event(this.#key, {
+            ...this.#data,
+            ...patch,
+        });
+    }
+    /** Example: `event.select("cpu", "healthy")`. Returns a new event containing only the selected payload fields. */
+    select(...keys) {
+        const selected = {};
+        for (const key of keys) {
+            selected[key] = this.#data[key];
+        }
+        return new Event(this.#key, selected);
+    }
+    /** Example: `event.rename({ cpu: "usage" })`. Returns a new event with payload fields renamed according to the supplied mapping. */
+    rename(mapping) {
+        const renamed = {};
+        for (const [key, value] of Object.entries(this.#data)) {
+            const nextKey = mapping[key] ?? key;
+            renamed[nextKey] = value;
+        }
+        return new Event(this.#key, renamed);
+    }
+    collapse(keys, output, reducer, options) {
+        const selected = {};
+        for (const key of keys) {
+            selected[key] = this.#data[key];
+        }
+        const collapsedValue = reducer(selected);
+        const append = options?.append === true;
+        if (append) {
+            return new Event(this.#key, {
+                ...this.#data,
+                [output]: collapsedValue,
+            });
+        }
+        const nextData = {};
+        for (const [key, value] of Object.entries(this.#data)) {
+            if (!keys.includes(key)) {
+                nextData[key] = value;
+            }
+        }
+        nextData[output] = collapsedValue;
+        return new Event(this.#key, nextData);
+    }
+    /** Example: `event.timeRange()`. Returns the event extent as a `TimeRange`. */
+    timeRange() {
+        const key = this.key();
+        return key instanceof TimeRange
+            ? key
+            : new TimeRange({ start: key.begin(), end: key.end() });
+    }
+    /** Example: `event.begin()`. Returns the inclusive event start in milliseconds since epoch. */
+    begin() {
+        return this.#key.begin();
+    }
+    /** Example: `event.end()`. Returns the inclusive event end in milliseconds since epoch. */
+    end() {
+        return this.#key.end();
+    }
+    /** Example: `event.overlaps(range)`. Returns `true` when the event extent overlaps the supplied temporal value. */
+    overlaps(other) {
+        return this.#key.overlaps(other);
+    }
+    /** Example: `event.contains(time)`. Returns `true` when the event extent fully contains the supplied temporal value. */
+    contains(other) {
+        return this.#key.contains(other);
+    }
+    /** Example: `event.isBefore(range)`. Returns `true` when the event ends strictly before the supplied temporal value begins. */
+    isBefore(other) {
+        return this.#key.isBefore(other);
+    }
+    /** Example: `event.isAfter(range)`. Returns `true` when the event begins strictly after the supplied temporal value ends. */
+    isAfter(other) {
+        return this.#key.isAfter(other);
+    }
+    /** Example: `event.intersection(range)`. Returns the temporal intersection of the event extent and the supplied value, if any. */
+    intersection(other) {
+        return this.#key.intersection(other);
+    }
+    /** Example: `event.trim(range)`. Returns a new event clipped to the supplied temporal value, if the event overlaps it. */
+    trim(other) {
+        const trimmedKey = this.#key.trim(other);
+        if (!trimmedKey) {
+            return undefined;
+        }
+        return new Event(trimmedKey, this.#data);
+    }
+    /** Example: `event.asTime({ at: "center" })`. Converts the event key to a point-in-time key using the supplied anchor within the current extent. */
+    asTime(options = {}) {
+        const at = options.at ?? 'begin';
+        const timestamp = at === 'center'
+            ? this.begin() + (this.end() - this.begin()) / 2
+            : at === 'end'
+                ? this.end()
+                : this.begin();
+        return this.withKey(new Time(timestamp));
+    }
+    /** Example: `event.asTimeRange()`. Converts the event key to an unlabeled `TimeRange` covering the same extent. */
+    asTimeRange() {
+        return this.withKey(new TimeRange({ start: this.begin(), end: this.end() }));
+    }
+    asInterval(value) {
+        const nextValue = typeof value === 'function' ? value(this) : value;
+        return this.withKey(new Interval({ value: nextValue, start: this.begin(), end: this.end() }));
+    }
+}
+//# sourceMappingURL=Event.js.map

package/dist/Event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Event.js","sourceRoot":"","sources":["../src/Event.ts"],"names":[],"mappings":"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"}

package/dist/Interval.d.ts

@@ -0,0 +1,51 @@
+import { type CalendarOptions, type CalendarUnit, type TimeZoneOptions } from './calendar.js';
+import { TimeRange } from './TimeRange.js';
+import type { EventKey, IntervalInput, IntervalValue, TemporalLike } from './temporal.js';
+/** A labeled time interval event key. Example: `new Interval({ value: "bucket", start, end })`. */
+export declare class Interval implements EventKey {
+    readonly kind = "interval";
+    readonly value: IntervalValue;
+    readonly start: number;
+    readonly endMs: number;
+    /** Example: `Interval.fromDate("2025-01-01", { timeZone: "UTC" })`. Creates a labeled local-day interval using the ISO date string as the default label. */
+    static fromDate(reference: string, options?: TimeZoneOptions & {
+        value?: IntervalValue;
+    }): Interval;
+    /** Example: `Interval.fromCalendar("month", "2025-01", { timeZone: "America/New_York", value: "2025-01" })`. Creates a labeled calendar interval for the supplied reference. */
+    static fromCalendar(unit: CalendarUnit, reference: string, options?: CalendarOptions & {
+        value?: IntervalValue;
+    }): Interval;
+    /** Example: `new Interval(["bucket", start, end])`. Creates a labeled interval key from a `{ value, start, end }` object or tuple. */
+    constructor(input: IntervalInput);
+    /** Example: `interval.type() // "interval"`. Returns the key kind. */
+    type(): 'interval';
+    /** Example: `interval.begin()`. Returns the inclusive start of the interval in milliseconds since epoch. */
+    begin(): number;
+    /** Example: `interval.end()`. Returns the inclusive end of the interval in milliseconds since epoch. */
+    end(): number;
+    /** Example: `interval.valueOf()`. Returns the interval label. */
+    valueOf(): IntervalValue;
+    /** Example: `interval.asString()`. Returns the interval label as a string. */
+    asString(): string;
+    /** Example: `interval.timeRange()`. Returns the interval extent as a `TimeRange`. */
+    timeRange(): TimeRange;
+    /** Example: `interval.duration()`. Returns the temporal duration of the interval in milliseconds. */
+    duration(): number;
+    /** Example: `interval.overlaps(range)`. Returns `true` when this interval overlaps the supplied temporal value. */
+    overlaps(other: TemporalLike): boolean;
+    /** Example: `interval.contains(range)`. Returns `true` when this interval fully contains the supplied temporal value. */
+    contains(other: TemporalLike): boolean;
+    /** Example: `interval.isBefore(range)`. Returns `true` when this interval ends strictly before the supplied temporal value begins. */
+    isBefore(other: TemporalLike): boolean;
+    /** Example: `interval.isAfter(range)`. Returns `true` when this interval begins strictly after the supplied temporal value ends. */
+    isAfter(other: TemporalLike): boolean;
+    /** Example: `interval.intersection(range)`. Returns the temporal intersection with the supplied value, if any. */
+    intersection(other: TemporalLike): TimeRange | undefined;
+    /** Example: `interval.trim(range)`. Returns this interval clipped to the supplied temporal value, preserving its label when overlapping. */
+    trim(other: TemporalLike): Interval | undefined;
+    /** Example: `interval.equals(otherInterval)`. Returns `true` when the supplied key has the same label and temporal extent. */
+    equals(other: EventKey): boolean;
+    /** Example: `interval.compare(otherInterval)`. Compares this key to another key for ordering. */
+    compare(other: EventKey): number;
+}
+//# sourceMappingURL=Interval.d.ts.map

package/dist/Interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Interval.d.ts","sourceRoot":"","sources":["../src/Interval.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,YAAY,EAEb,MAAM,eAAe,CAAC;AAavB,mGAAmG;AACnG,qBAAa,QAAS,YAAW,QAAQ;IACvC,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4JAA4J;IAC5J,MAAM,CAAC,QAAQ,CACb,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAe,GAAG;QAAE,KAAK,CAAC,EAAE,aAAa,CAAA;KAAO,GACxD,QAAQ;IASX,gLAAgL;IAChL,MAAM,CAAC,YAAY,CACjB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAe,GAAG;QAAE,KAAK,CAAC,EAAE,aAAa,CAAA;KAAO,GACxD,QAAQ;IASX,sIAAsI;gBAC1H,KAAK,EAAE,aAAa;IAyBhC,sEAAsE;IACtE,IAAI,IAAI,UAAU;IAIlB,4GAA4G;IAC5G,KAAK,IAAI,MAAM;IAIf,wGAAwG;IACxG,GAAG,IAAI,MAAM;IAIb,iEAAiE;IACjE,OAAO,IAAI,aAAa;IAIxB,8EAA8E;IAC9E,QAAQ,IAAI,MAAM;IAIlB,qFAAqF;IACrF,SAAS,IAAI,SAAS;IAItB,qGAAqG;IACrG,QAAQ,IAAI,MAAM;IAIlB,mHAAmH;IACnH,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAItC,yHAAyH;IACzH,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAItC,sIAAsI;IACtI,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAItC,oIAAoI;IACpI,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAIrC,kHAAkH;IAClH,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS;IAIxD,4IAA4I;IAC5I,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS;IAY/C,8HAA8H;IAC9H,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAShC,iGAAiG;IACjG,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;CAOjC"}

package/dist/Interval.js

@@ -0,0 +1,130 @@
+import { calendarRangeForReference, dayRangeForDate, } from './calendar.js';
+import { TimeRange } from './TimeRange.js';
+import { compareEventKeys, compareIntervalValues, normalizeTimestamp, } from './temporal.js';
+/** A labeled time interval event key. Example: `new Interval({ value: "bucket", start, end })`. */
+export class Interval {
+    kind = 'interval';
+    value;
+    start;
+    endMs;
+    /** Example: `Interval.fromDate("2025-01-01", { timeZone: "UTC" })`. Creates a labeled local-day interval using the ISO date string as the default label. */
+    static fromDate(reference, options = {}) {
+        const range = dayRangeForDate(reference, options);
+        return new Interval({
+            value: options.value ?? reference,
+            start: range.start,
+            end: range.end,
+        });
+    }
+    /** Example: `Interval.fromCalendar("month", "2025-01", { timeZone: "America/New_York", value: "2025-01" })`. Creates a labeled calendar interval for the supplied reference. */
+    static fromCalendar(unit, reference, options = {}) {
+        const range = calendarRangeForReference(unit, reference, options);
+        return new Interval({
+            value: options.value ?? reference,
+            start: range.start,
+            end: range.end,
+        });
+    }
+    /** Example: `new Interval(["bucket", start, end])`. Creates a labeled interval key from a `{ value, start, end }` object or tuple. */
+    constructor(input) {
+        let value;
+        let rawStart;
+        let rawEnd;
+        if (Array.isArray(input)) {
+            value = input[0];
+            rawStart = input[1];
+            rawEnd = input[2];
+        }
+        else {
+            const objectInput = input;
+            value = objectInput.value;
+            rawStart = objectInput.start;
+            rawEnd = objectInput.end;
+        }
+        const start = normalizeTimestamp(rawStart, 'interval start');
+        const end = normalizeTimestamp(rawEnd, 'interval end');
+        if (start > end) {
+            throw new TypeError('interval start must be <= end');
+        }
+        this.value = value;
+        this.start = start;
+        this.endMs = end;
+        Object.freeze(this);
+    }
+    /** Example: `interval.type() // "interval"`. Returns the key kind. */
+    type() {
+        return this.kind;
+    }
+    /** Example: `interval.begin()`. Returns the inclusive start of the interval in milliseconds since epoch. */
+    begin() {
+        return this.start;
+    }
+    /** Example: `interval.end()`. Returns the inclusive end of the interval in milliseconds since epoch. */
+    end() {
+        return this.endMs;
+    }
+    /** Example: `interval.valueOf()`. Returns the interval label. */
+    valueOf() {
+        return this.value;
+    }
+    /** Example: `interval.asString()`. Returns the interval label as a string. */
+    asString() {
+        return String(this.value);
+    }
+    /** Example: `interval.timeRange()`. Returns the interval extent as a `TimeRange`. */
+    timeRange() {
+        return new TimeRange({ start: this.start, end: this.endMs });
+    }
+    /** Example: `interval.duration()`. Returns the temporal duration of the interval in milliseconds. */
+    duration() {
+        return this.endMs - this.start;
+    }
+    /** Example: `interval.overlaps(range)`. Returns `true` when this interval overlaps the supplied temporal value. */
+    overlaps(other) {
+        return this.timeRange().overlaps(other);
+    }
+    /** Example: `interval.contains(range)`. Returns `true` when this interval fully contains the supplied temporal value. */
+    contains(other) {
+        return this.timeRange().contains(other);
+    }
+    /** Example: `interval.isBefore(range)`. Returns `true` when this interval ends strictly before the supplied temporal value begins. */
+    isBefore(other) {
+        return this.timeRange().isBefore(other);
+    }
+    /** Example: `interval.isAfter(range)`. Returns `true` when this interval begins strictly after the supplied temporal value ends. */
+    isAfter(other) {
+        return this.timeRange().isAfter(other);
+    }
+    /** Example: `interval.intersection(range)`. Returns the temporal intersection with the supplied value, if any. */
+    intersection(other) {
+        return this.timeRange().intersection(other);
+    }
+    /** Example: `interval.trim(range)`. Returns this interval clipped to the supplied temporal value, preserving its label when overlapping. */
+    trim(other) {
+        const range = this.intersection(other);
+        if (!range) {
+            return undefined;
+        }
+        return new Interval({
+            value: this.value,
+            start: range.begin(),
+            end: range.end(),
+        });
+    }
+    /** Example: `interval.equals(otherInterval)`. Returns `true` when the supplied key has the same label and temporal extent. */
+    equals(other) {
+        return (other instanceof Interval &&
+            this.start === other.start &&
+            this.endMs === other.endMs &&
+            this.value === other.value);
+    }
+    /** Example: `interval.compare(otherInterval)`. Compares this key to another key for ordering. */
+    compare(other) {
+        const base = compareEventKeys(this, other);
+        if (base !== 0 || !(other instanceof Interval)) {
+            return base;
+        }
+        return compareIntervalValues(this.value, other.value);
+    }
+}
+//# sourceMappingURL=Interval.js.map

package/dist/Interval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Interval.js","sourceRoot":"","sources":["../src/Interval.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,eAAe,GAIhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQ3C,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAQvB,mGAAmG;AACnG,MAAM,OAAO,QAAQ;IACV,IAAI,GAAG,UAAU,CAAC;IAClB,KAAK,CAAgB;IACrB,KAAK,CAAS;IACd,KAAK,CAAS;IAEvB,4JAA4J;IAC5J,MAAM,CAAC,QAAQ,CACb,SAAiB,EACjB,UAAuD,EAAE;QAEzD,MAAM,KAAK,GAAG,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAClD,OAAO,IAAI,QAAQ,CAAC;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,SAAS;YACjC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC,CAAC;IACL,CAAC;IAED,gLAAgL;IAChL,MAAM,CAAC,YAAY,CACjB,IAAkB,EAClB,SAAiB,EACjB,UAAuD,EAAE;QAEzD,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAClE,OAAO,IAAI,QAAQ,CAAC;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,SAAS;YACjC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC,CAAC;IACL,CAAC;IAED,sIAAsI;IACtI,YAAY,KAAoB;QAC9B,IAAI,KAAoB,CAAC;QACzB,IAAI,QAAwB,CAAC;QAC7B,IAAI,MAAsB,CAAC;QAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACjB,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACpB,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,MAAM,WAAW,GAAG,KAA4B,CAAC;YACjD,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;YAC1B,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC;YAC7B,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC;QAC3B,CAAC;QACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACvD,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;YAChB,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;QACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,sEAAsE;IACtE,IAAI;QACF,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,4GAA4G;IAC5G,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,wGAAwG;IACxG,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,iEAAiE;IACjE,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,8EAA8E;IAC9E,QAAQ;QACN,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,qFAAqF;IACrF,SAAS;QACP,OAAO,IAAI,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,qGAAqG;IACrG,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACjC,CAAC;IAED,mHAAmH;IACnH,QAAQ,CAAC,KAAmB;QAC1B,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,yHAAyH;IACzH,QAAQ,CAAC,KAAmB;QAC1B,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,sIAAsI;IACtI,QAAQ,CAAC,KAAmB;QAC1B,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,oIAAoI;IACpI,OAAO,CAAC,KAAmB;QACzB,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,kHAAkH;IAClH,YAAY,CAAC,KAAmB;QAC9B,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,4IAA4I;IAC5I,IAAI,CAAC,KAAmB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC;YAClB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YACpB,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE;SACjB,CAAC,CAAC;IACL,CAAC;IAED,8HAA8H;IAC9H,MAAM,CAAC,KAAe;QACpB,OAAO,CACL,KAAK,YAAY,QAAQ;YACzB,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAC1B,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAC1B,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAC3B,CAAC;IACJ,CAAC;IAED,iGAAiG;IACjG,OAAO,CAAC,KAAe;QACrB,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC;CACF"}

package/dist/Sequence.d.ts

@@ -0,0 +1,80 @@
+import { BoundedSequence } from './BoundedSequence.js';
+import { type CalendarOptions, type CalendarUnit, type WeekStartsOn } from './calendar.js';
+import type { TemporalLike, TimestampInput } from './temporal.js';
+export type DurationInput = number | `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`;
+export type SequenceSample = 'begin' | 'center';
+type FixedSequenceInput = {
+    every: DurationInput;
+    anchor?: TimestampInput;
+};
+type CalendarSequenceInput = {
+    unit: CalendarUnit;
+    timeZone: string;
+    weekStartsOn?: WeekStartsOn;
+};
+/**
+ * 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`.
+ */
+export declare class Sequence {
+    #private;
+    constructor(input: FixedSequenceInput | CalendarSequenceInput);
+    /**
+     * 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.
+     */
+    static every(every: DurationInput, options?: {
+        anchor?: TimestampInput;
+    }): Sequence;
+    /** Example: `Sequence.hourly()`. Creates an hourly fixed-step sequence. */
+    static hourly(options?: {
+        anchor?: TimestampInput;
+    }): Sequence;
+    /** Example: `Sequence.daily()`. Creates a daily fixed-step sequence. */
+    static daily(options?: {
+        anchor?: TimestampInput;
+    }): 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"`
+     */
+    static calendar(unit: CalendarUnit, options?: CalendarOptions): Sequence;
+    /** Example: `sequence.kind()`. Returns whether this sequence is fixed-step or calendar-aware. */
+    kind(): 'fixed' | 'calendar';
+    /** Example: `sequence.anchor()`. Returns the millisecond anchor used by this grid definition. */
+    anchor(): number;
+    /** Example: `sequence.stepMs()`. Returns the fixed interval size in milliseconds. */
+    stepMs(): number;
+    /** Example: `sequence.timeZone()`. Returns the IANA time zone for calendar-aware sequences, if any. */
+    timeZone(): string | undefined;
+    /**
+     * Example: `sequence.bounded(new TimeRange({ start, end }))`.
+     * Realizes a finite `BoundedSequence` over the supplied range.
+     *
+     * Sample position controls which interval starts are selected:
+     * `begin` includes buckets whose starts fall within the range, while `center` includes buckets
+     * whose midpoints fall within the range.
+     */
+    bounded(range: TemporalLike, options?: {
+        sample?: SequenceSample;
+    }): BoundedSequence;
+}
+export {};
+//# sourceMappingURL=Sequence.d.ts.map

package/dist/Sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sequence.d.ts","sourceRoot":"","sources":["../src/Sequence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EAMlB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAGf,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAChF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEhD,KAAK,kBAAkB,GAAG;IACxB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAqEF;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;;gBAQP,KAAK,EAAE,kBAAkB,GAAG,qBAAqB;IAc7D;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CACV,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAO,GACxC,QAAQ;IAMX,2EAA2E;IAC3E,MAAM,CAAC,MAAM,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAO,GAAG,QAAQ;IAIlE,wEAAwE;IACxE,MAAM,CAAC,KAAK,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAO,GAAG,QAAQ;IAIjE;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,eAAoB,GAAG,QAAQ;IAO5E,iGAAiG;IACjG,IAAI,IAAI,OAAO,GAAG,UAAU;IAI5B,iGAAiG;IACjG,MAAM,IAAI,MAAM;IAShB,qFAAqF;IACrF,MAAM,IAAI,MAAM;IAShB,uGAAuG;IACvG,QAAQ,IAAI,MAAM,GAAG,SAAS;IAI9B;;;;;;;OAOG;IACH,OAAO,CACL,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,cAAc,CAAA;KAAO,GACxC,eAAe;CA0DnB"}

package/dist/Sequence.js

@@ -0,0 +1,197 @@
+import { BoundedSequence } from './BoundedSequence.js';
+import { normalizeWeekStartsOn, nextCalendarStart, plainDateToStart, resolveTimeZone, toPlainDateStart, } from './calendar.js';
+import { Interval } from './Interval.js';
+import { TimeRange } from './TimeRange.js';
+function normalizeTimestamp(value) {
+    return value instanceof Date ? value.getTime() : value;
+}
+function toTimeRange(value) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        'timeRange' in value &&
+        typeof value.timeRange === 'function') {
+        return value.timeRange();
+    }
+    if (typeof value === 'object' &&
+        value !== null &&
+        'begin' in value &&
+        'end' in value) {
+        return new TimeRange({ start: value.begin(), end: value.end() });
+    }
+    if (value instanceof Date || typeof value === 'number') {
+        const timestamp = normalizeTimestamp(value);
+        return new TimeRange({ start: timestamp, end: timestamp });
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 2) {
+            return new TimeRange(value);
+        }
+        return new Interval(value).timeRange();
+    }
+    if ('value' in value) {
+        return new Interval(value).timeRange();
+    }
+    return new TimeRange(value);
+}
+function parseDuration(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new TypeError('sequence duration must be a positive finite number of milliseconds');
+        }
+        return value;
+    }
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+    if (!match) {
+        throw new TypeError(`unsupported duration '${value}'`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    const multiplier = unit === 'ms'
+        ? 1
+        : unit === 's'
+            ? 1_000
+            : unit === 'm'
+                ? 60_000
+                : unit === 'h'
+                    ? 3_600_000
+                    : 86_400_000;
+    return amount * multiplier;
+}
+/**
+ * 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`.
+ */
+export class Sequence {
+    #kind;
+    #stepMs;
+    #anchorMs;
+    #calendarUnit;
+    #timeZone;
+    #weekStartsOn;
+    constructor(input) {
+        if ('every' in input) {
+            this.#kind = 'fixed';
+            this.#stepMs = parseDuration(input.every);
+            this.#anchorMs = normalizeTimestamp(input.anchor ?? 0);
+        }
+        else {
+            this.#kind = 'calendar';
+            this.#calendarUnit = input.unit;
+            this.#timeZone = input.timeZone;
+            this.#weekStartsOn = normalizeWeekStartsOn(input.weekStartsOn);
+        }
+        Object.freeze(this);
+    }
+    /**
+     * 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.
+     */
+    static every(every, options = {}) {
+        return options.anchor === undefined
+            ? new Sequence({ every })
+            : new Sequence({ every, anchor: options.anchor });
+    }
+    /** Example: `Sequence.hourly()`. Creates an hourly fixed-step sequence. */
+    static hourly(options = {}) {
+        return Sequence.every('1h', options);
+    }
+    /** Example: `Sequence.daily()`. Creates a daily fixed-step sequence. */
+    static daily(options = {}) {
+        return Sequence.every('1d', options);
+    }
+    /**
+     * 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"`
+     */
+    static calendar(unit, options = {}) {
+        const timeZone = resolveTimeZone(options);
+        return options.weekStartsOn === undefined
+            ? new Sequence({ unit, timeZone })
+            : new Sequence({ unit, timeZone, weekStartsOn: options.weekStartsOn });
+    }
+    /** Example: `sequence.kind()`. Returns whether this sequence is fixed-step or calendar-aware. */
+    kind() {
+        return this.#kind;
+    }
+    /** Example: `sequence.anchor()`. Returns the millisecond anchor used by this grid definition. */
+    anchor() {
+        if (this.#kind !== 'fixed') {
+            throw new TypeError('calendar sequences do not have a fixed millisecond anchor');
+        }
+        return this.#anchorMs;
+    }
+    /** Example: `sequence.stepMs()`. Returns the fixed interval size in milliseconds. */
+    stepMs() {
+        if (this.#kind !== 'fixed') {
+            throw new TypeError('calendar sequences do not have a fixed millisecond step size');
+        }
+        return this.#stepMs;
+    }
+    /** Example: `sequence.timeZone()`. Returns the IANA time zone for calendar-aware sequences, if any. */
+    timeZone() {
+        return this.#timeZone;
+    }
+    /**
+     * Example: `sequence.bounded(new TimeRange({ start, end }))`.
+     * Realizes a finite `BoundedSequence` over the supplied range.
+     *
+     * Sample position controls which interval starts are selected:
+     * `begin` includes buckets whose starts fall within the range, while `center` includes buckets
+     * whose midpoints fall within the range.
+     */
+    bounded(range, options = {}) {
+        const sample = options.sample ?? 'begin';
+        const requested = toTimeRange(range);
+        const intervals = [];
+        if (this.#kind === 'fixed') {
+            const stepMs = this.#stepMs;
+            const anchorMs = this.#anchorMs;
+            const sampleOffset = sample === 'center' ? stepMs / 2 : 0;
+            const firstIndex = Math.ceil((requested.begin() - sampleOffset - anchorMs) / stepMs);
+            const lastIndex = Math.floor((requested.end() - sampleOffset - anchorMs) / stepMs);
+            for (let index = firstIndex; index <= lastIndex; index += 1) {
+                const start = anchorMs + index * stepMs;
+                intervals.push(new Interval({ value: start, start, end: start + stepMs }));
+            }
+            return new BoundedSequence(intervals);
+        }
+        const timeZone = this.#timeZone;
+        const unit = this.#calendarUnit;
+        const weekStartsOn = this.#weekStartsOn;
+        let currentDate = toPlainDateStart(requested.begin(), timeZone, unit, weekStartsOn);
+        while (true) {
+            const currentStart = plainDateToStart(currentDate, timeZone);
+            const nextDate = nextCalendarStart(currentDate, unit);
+            const nextStart = plainDateToStart(nextDate, timeZone);
+            const start = currentStart.epochMilliseconds;
+            const end = nextStart.epochMilliseconds;
+            const sampleTime = sample === 'center' ? start + (end - start) / 2 : start;
+            if (sampleTime > requested.end()) {
+                break;
+            }
+            if (sampleTime >= requested.begin()) {
+                intervals.push(new Interval({ value: start, start, end }));
+            }
+            currentDate = nextDate;
+        }
+        return new BoundedSequence(intervals);
+    }
+}
+//# sourceMappingURL=Sequence.js.map

package/dist/Sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sequence.js","sourceRoot":"","sources":["../src/Sequence.ts"],"names":[],"mappings":"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"}