pond-ts 0.67.0 → 0.69.0

package/dist/core/time-zone.d.ts

@@ -0,0 +1,122 @@
+import type { CalendarUnit, WeekStartsOn } from './calendar.js';
+/**
+ * How `TimeZone.instant()` resolves a wall-clock time that a transition
+ * makes ambiguous (a fall-back repeats an hour) or skips (a spring-forward
+ * drops one). Same vocabulary and same defaults as Temporal:
+ *
+ * - `'compatible'` (default) — the earlier instant when the time repeats,
+ *   the instant *after* the gap when it is skipped (02:30 on a spring-forward
+ *   night becomes 03:30). This is also what `startOf('day')` needs on the
+ *   rare days that have no midnight.
+ * - `'earlier'` / `'later'` — always the earlier / later of the two readings.
+ * - `'reject'` — throw a `RangeError` for either case.
+ */
+export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+/** The wall-clock reading of an instant in a zone. `weekday` is ISO: 1 = Monday … 7 = Sunday. */
+export type ZonedParts = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+    weekday: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+};
+/** The date-and-time fields `TimeZone.instant()` accepts. Time fields default to zero. */
+export type ZonedPartsInput = {
+    year: number;
+    month: number;
+    day: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+};
+export type StartOfOptions = {
+    /** First day of the week for `'week'`, ISO numbering (1 = Monday, default) … 7 = Sunday. */
+    weekStartsOn?: WeekStartsOn;
+};
+declare function assertCalendarUnit(unit: string): asserts unit is CalendarUnit;
+/**
+ * An IANA time zone as a calendar: the one place in pond that turns instants
+ * (UTC epoch milliseconds) into wall-clock readings and calendar boundaries,
+ * and back.
+ *
+ * Instances are interned — `TimeZone.of('Europe/Berlin')` returns the same
+ * object every time — and cache the zone's offset transitions as they are
+ * discovered, so after the first query in a stretch of history every call
+ * is integer arithmetic. `Sequence.calendar` buckets with it; the charts'
+ * time axis places and labels ticks with it; the two therefore agree on
+ * every boundary by construction.
+ *
+ * A `TimeZone` holds no instant. Values (`Time`, `TimeRange`, `Interval`)
+ * stay plain UTC milliseconds; the zone is a parameter to the code that
+ * interprets them.
+ */
+export declare class TimeZone {
+    #private;
+    /** The canonical IANA identifier, e.g. `'America/New_York'` or `'UTC'`. */
+    readonly id: string;
+    private constructor();
+    /**
+     * Example: `TimeZone.of('Australia/Sydney')`. Looks up a zone by IANA
+     * identifier. Throws `RangeError` for an identifier the runtime does not
+     * know. Case-insensitive on input; `id` reports the canonical spelling.
+     * A fixed-offset identifier such as `'+05:30'` is accepted too, as
+     * Temporal accepts it, and behaves as a zone with a single segment.
+     */
+    static of(id: string): TimeZone;
+    /** Example: `TimeZone.UTC.startOf('month', t)`. The UTC zone. */
+    static get UTC(): TimeZone;
+    /**
+     * Example: `TimeZone.local()`. The runtime's own zone, as the environment
+     * reports it. Resolved on every call, so a test that changes `TZ` between
+     * calls sees the change.
+     */
+    static local(): TimeZone;
+    /** Example: `zone.offsetAt(t)`. The zone's UTC offset at an instant, in milliseconds east of UTC. */
+    offsetAt(ms: number): number;
+    /**
+     * Example: `zone.parts(t).hour`. The wall-clock reading of an instant in
+     * this zone.
+     */
+    parts(ms: number): ZonedParts;
+    /**
+     * Example: `zone.instant({ year: 2026, month: 3, day: 29, hour: 2, minute: 30 })`.
+     * The instant at which this zone's clocks read the given wall time. When
+     * a transition makes the reading ambiguous or nonexistent,
+     * `disambiguation` decides (default `'compatible'`, as Temporal).
+     */
+    instant(parts: ZonedPartsInput, options?: {
+        disambiguation?: Disambiguation;
+    }): number;
+    /**
+     * Example: `zone.startOf('week', t, { weekStartsOn: 7 })`. The first
+     * instant of the calendar unit containing `ms`, in this zone. On a day
+     * with no midnight (a spring-forward at 00:00) this is the first instant
+     * that exists, as `Temporal.ZonedDateTime.startOfDay` does.
+     */
+    startOf(unit: CalendarUnit, ms: number, options?: StartOfOptions): number;
+    /**
+     * Example: `zone.next('month', t)`. The first instant of the calendar unit
+     * *after* the one containing `ms` — i.e. the exclusive end of `startOf`'s
+     * bucket.
+     */
+    next(unit: CalendarUnit, ms: number, options?: StartOfOptions): number;
+    /**
+     * Example: `zone.abbreviation(t)` → `'EDT'`. The zone's short name at an
+     * instant, as `Intl` reports it for `locale` (default: the runtime's
+     * locale). Which zones have a conventional abbreviation is a locale
+     * question — `en-US` knows `EST`, `en-AU` knows `AEDT`, and neither knows
+     * the other's; the fallback is a `GMT±h[:mm]` offset string. Pass the
+     * viewer's locale when rendering.
+     */
+    abbreviation(ms: number, options?: {
+        locale?: string;
+    }): string;
+    toString(): string;
+    toJSON(): string;
+}
+export { assertCalendarUnit };
+//# sourceMappingURL=time-zone.d.ts.map

package/dist/core/time-zone.js

@@ -0,0 +1,413 @@
+var _a;
+import { Temporal } from '@js-temporal/polyfill';
+const MS_PER_DAY = 86_400_000;
+const MS_PER_HOUR = 3_600_000;
+/**
+ * Half-window either side of a civil time within which every candidate
+ * offset for that wall time must lie. IANA offsets span −12:00 … +14:00, and
+ * the two offsets bracketing a transition differ by at most a few hours, so
+ * ±16 h comfortably covers both sides of any transition.
+ */
+const CANDIDATE_WINDOW_MS = 16 * MS_PER_HOUR;
+/**
+ * Days since 1970-01-01 for a proleptic-Gregorian civil date (Howard
+ * Hinnant's algorithm, valid for the whole `Date` range).
+ */
+function daysFromCivil(year, month, day) {
+    const y = month <= 2 ? year - 1 : year;
+    const era = Math.floor(y / 400);
+    const yoe = y - era * 400;
+    const mp = (month + 9) % 12;
+    const doy = Math.floor((153 * mp + 2) / 5) + day - 1;
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+    return era * 146_097 + doe - 719_468;
+}
+/** Inverse of `daysFromCivil`: `[year, month, day]` for a day number. */
+function civilFromDays(days) {
+    const z = days + 719_468;
+    const era = Math.floor(z / 146_097);
+    const doe = z - era * 146_097;
+    const yoe = Math.floor((doe -
+        Math.floor(doe / 1460) +
+        Math.floor(doe / 36_524) -
+        Math.floor(doe / 146_096)) /
+        365);
+    const y = yoe + era * 400;
+    const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+    const mp = Math.floor((5 * doy + 2) / 153);
+    const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+    const m = mp < 10 ? mp + 3 : mp - 9;
+    return [m <= 2 ? y + 1 : y, m, d];
+}
+/** Days in a proleptic-Gregorian month. */
+function daysInMonth(year, month) {
+    return (daysFromCivil(month === 12 ? year + 1 : year, (month % 12) + 1, 1) -
+        daysFromCivil(year, month, 1));
+}
+/** ISO weekday (1 = Monday … 7 = Sunday) for a day number; day 0 was a Thursday. */
+function weekdayFromDays(days) {
+    return ((((days % 7) + 7 + 3) % 7) + 1);
+}
+function floorMs(ms, label) {
+    if (!Number.isFinite(ms)) {
+        throw new RangeError(`${label} must be a finite epoch millisecond`);
+    }
+    // Floor, not trunc: before 1970 they disagree, and -5.5 lies inside the
+    // millisecond spanning [-6, -5). See `toPlainDateStart` for why a fraction
+    // is not a caller error (a chart's wheel zoom hands us `1.7e12 + 0.37`).
+    return Math.floor(ms);
+}
+function assertCalendarUnit(unit) {
+    switch (unit) {
+        case 'day':
+        case 'week':
+        case 'month':
+        case 'quarter':
+        case 'year':
+            return;
+        default:
+            throw new RangeError(`unknown calendar unit ${JSON.stringify(unit)}; expected 'day', 'week', 'month', 'quarter' or 'year'`);
+    }
+}
+const registry = new Map();
+/**
+ * An IANA time zone as a calendar: the one place in pond that turns instants
+ * (UTC epoch milliseconds) into wall-clock readings and calendar boundaries,
+ * and back.
+ *
+ * Instances are interned — `TimeZone.of('Europe/Berlin')` returns the same
+ * object every time — and cache the zone's offset transitions as they are
+ * discovered, so after the first query in a stretch of history every call
+ * is integer arithmetic. `Sequence.calendar` buckets with it; the charts'
+ * time axis places and labels ticks with it; the two therefore agree on
+ * every boundary by construction.
+ *
+ * A `TimeZone` holds no instant. Values (`Time`, `TimeRange`, `Interval`)
+ * stay plain UTC milliseconds; the zone is a parameter to the code that
+ * interprets them.
+ */
+export class TimeZone {
+    /** The canonical IANA identifier, e.g. `'America/New_York'` or `'UTC'`. */
+    id;
+    /** Offset segments sorted by `start`, non-overlapping. */
+    #segments = [];
+    /** The segment most recently hit — almost every query lands here. */
+    #last;
+    #abbreviationFormats;
+    constructor(id) {
+        this.id = id;
+        Object.freeze(this);
+    }
+    /**
+     * Example: `TimeZone.of('Australia/Sydney')`. Looks up a zone by IANA
+     * identifier. Throws `RangeError` for an identifier the runtime does not
+     * know. Case-insensitive on input; `id` reports the canonical spelling.
+     * A fixed-offset identifier such as `'+05:30'` is accepted too, as
+     * Temporal accepts it, and behaves as a zone with a single segment.
+     */
+    static of(id) {
+        const hit = registry.get(id);
+        if (hit !== undefined)
+            return hit;
+        let canonical;
+        try {
+            canonical =
+                Temporal.Instant.fromEpochMilliseconds(0).toZonedDateTimeISO(id).timeZoneId;
+        }
+        catch {
+            throw new RangeError(`unknown time zone ${JSON.stringify(id)}`);
+        }
+        const existing = registry.get(canonical);
+        const zone = existing ?? new _a(canonical);
+        registry.set(id, zone);
+        registry.set(canonical, zone);
+        return zone;
+    }
+    /** Example: `TimeZone.UTC.startOf('month', t)`. The UTC zone. */
+    static get UTC() {
+        return _a.of('UTC');
+    }
+    /**
+     * Example: `TimeZone.local()`. The runtime's own zone, as the environment
+     * reports it. Resolved on every call, so a test that changes `TZ` between
+     * calls sees the change.
+     */
+    static local() {
+        return _a.of(Intl.DateTimeFormat().resolvedOptions().timeZone);
+    }
+    /** Example: `zone.offsetAt(t)`. The zone's UTC offset at an instant, in milliseconds east of UTC. */
+    offsetAt(ms) {
+        return this.#segmentAt(floorMs(ms, 'instant')).offsetMs;
+    }
+    /**
+     * Example: `zone.parts(t).hour`. The wall-clock reading of an instant in
+     * this zone.
+     */
+    parts(ms) {
+        const t = floorMs(ms, 'instant');
+        const civil = t + this.#segmentAt(t).offsetMs;
+        return _a.#civilParts(civil);
+    }
+    /**
+     * Example: `zone.instant({ year: 2026, month: 3, day: 29, hour: 2, minute: 30 })`.
+     * The instant at which this zone's clocks read the given wall time. When
+     * a transition makes the reading ambiguous or nonexistent,
+     * `disambiguation` decides (default `'compatible'`, as Temporal).
+     */
+    instant(parts, options = {}) {
+        const civil = _a.#civilMs(parts);
+        return this.#instantForCivil(civil, options.disambiguation ?? 'compatible');
+    }
+    /**
+     * Example: `zone.startOf('week', t, { weekStartsOn: 7 })`. The first
+     * instant of the calendar unit containing `ms`, in this zone. On a day
+     * with no midnight (a spring-forward at 00:00) this is the first instant
+     * that exists, as `Temporal.ZonedDateTime.startOfDay` does.
+     */
+    startOf(unit, ms, options = {}) {
+        assertCalendarUnit(unit);
+        const t = floorMs(ms, 'instant');
+        const civil = t + this.#segmentAt(t).offsetMs;
+        const days = Math.floor(civil / MS_PER_DAY);
+        return this.#instantForCivil(_a.#startDays(unit, days, options.weekStartsOn ?? 1) * MS_PER_DAY, 'compatible');
+    }
+    /**
+     * Example: `zone.next('month', t)`. The first instant of the calendar unit
+     * *after* the one containing `ms` — i.e. the exclusive end of `startOf`'s
+     * bucket.
+     */
+    next(unit, ms, options = {}) {
+        assertCalendarUnit(unit);
+        const t = floorMs(ms, 'instant');
+        const civil = t + this.#segmentAt(t).offsetMs;
+        const days = Math.floor(civil / MS_PER_DAY);
+        const startDays = _a.#startDays(unit, days, options.weekStartsOn ?? 1);
+        return this.#instantForCivil(_a.#advanceDays(unit, startDays) * MS_PER_DAY, 'compatible');
+    }
+    /**
+     * Example: `zone.abbreviation(t)` → `'EDT'`. The zone's short name at an
+     * instant, as `Intl` reports it for `locale` (default: the runtime's
+     * locale). Which zones have a conventional abbreviation is a locale
+     * question — `en-US` knows `EST`, `en-AU` knows `AEDT`, and neither knows
+     * the other's; the fallback is a `GMT±h[:mm]` offset string. Pass the
+     * viewer's locale when rendering.
+     */
+    abbreviation(ms, options = {}) {
+        const t = floorMs(ms, 'instant');
+        const segment = this.#segmentAt(t);
+        const locale = options.locale ?? '';
+        const cached = segment.abbreviations?.get(locale);
+        if (cached !== undefined)
+            return cached;
+        this.#abbreviationFormats ??= new Map();
+        let format = this.#abbreviationFormats.get(locale);
+        if (format === undefined) {
+            format = new Intl.DateTimeFormat(locale === '' ? undefined : locale, {
+                timeZone: this.id,
+                timeZoneName: 'short',
+            });
+            this.#abbreviationFormats.set(locale, format);
+        }
+        const part = format
+            .formatToParts(new Date(t))
+            .find((p) => p.type === 'timeZoneName');
+        const abbreviation = part?.value ?? this.id;
+        (segment.abbreviations ??= new Map()).set(locale, abbreviation);
+        return abbreviation;
+    }
+    toString() {
+        return this.id;
+    }
+    toJSON() {
+        return this.id;
+    }
+    // ---- internals ---------------------------------------------------------
+    #segmentAt(t) {
+        const last = this.#last;
+        if (last !== undefined && t >= last.start && t < last.end)
+            return last;
+        const segments = this.#segments;
+        // Binary search for the segment whose start is the greatest <= t.
+        let lo = 0;
+        let hi = segments.length - 1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const s = segments[mid];
+            if (t < s.start)
+                hi = mid - 1;
+            else if (t >= s.end)
+                lo = mid + 1;
+            else {
+                this.#last = s;
+                return s;
+            }
+        }
+        const created = this.#discoverSegment(t);
+        segments.splice(lo, 0, created);
+        this.#last = created;
+        return created;
+    }
+    /**
+     * Ask Temporal for the offset at `t` and the transitions bracketing it.
+     *
+     * `getTimeZoneTransition('previous')` is *strictly* before its receiver,
+     * while the offset at a transition instant is already the new one — so
+     * asking at `t` itself, when `t` *is* a transition, would pair the new
+     * offset with the start of the old segment and poison the cache for the
+     * whole preceding stretch (every hourly series crosses a DST instant
+     * exactly). Asking from `t + 1 ms` returns transitions `<= t`, which is
+     * the segment start we want; `'next'` from `t` is strictly after, which
+     * is the exclusive end we want.
+     */
+    #discoverSegment(t) {
+        const zoned = Temporal.Instant.fromEpochMilliseconds(t).toZonedDateTimeISO(this.id);
+        const previous = Temporal.Instant.fromEpochMilliseconds(t + 1)
+            .toZonedDateTimeISO(this.id)
+            .getTimeZoneTransition('previous');
+        const next = zoned.getTimeZoneTransition('next');
+        return {
+            start: previous === null ? -Infinity : previous.epochMilliseconds,
+            end: next === null ? Infinity : next.epochMilliseconds,
+            offsetMs: zoned.offsetNanoseconds / 1_000_000,
+        };
+    }
+    /**
+     * The instant whose wall-clock reading is the civil millisecond `civil`
+     * (a UTC-encoded wall time). Candidate offsets are the ones in force just
+     * before and just after the wall time; a candidate is valid when the
+     * instant it implies actually carries that offset.
+     */
+    #instantForCivil(civil, disambiguation) {
+        const before = this.#segmentAt(civil - CANDIDATE_WINDOW_MS);
+        const after = this.#segmentAt(civil + CANDIDATE_WINDOW_MS);
+        const tBefore = civil - before.offsetMs;
+        const validBefore = this.#segmentAt(tBefore).offsetMs === before.offsetMs;
+        if (before === after || before.offsetMs === after.offsetMs) {
+            if (validBefore)
+                return tBefore;
+            // Same offset either side but a transition pair sits in between
+            // (a brief change and back) — fall through to the general search.
+        }
+        const tAfter = civil - after.offsetMs;
+        const validAfter = this.#segmentAt(tAfter).offsetMs === after.offsetMs;
+        if (validBefore && validAfter) {
+            if (tBefore === tAfter)
+                return tBefore;
+            // The wall time repeats: `tBefore` is the earlier reading.
+            switch (disambiguation) {
+                case 'reject':
+                    throw new RangeError(`wall-clock time ${_a.#civilString(civil)} is ambiguous in ${this.id}`);
+                case 'later':
+                    return Math.max(tBefore, tAfter);
+                default:
+                    return Math.min(tBefore, tAfter);
+            }
+        }
+        if (validBefore)
+            return tBefore;
+        if (validAfter)
+            return tAfter;
+        // The wall time is skipped. Temporal's 'compatible' moves forward past
+        // the gap: keep the offset that was in force before it, which lands
+        // the same distance after the transition as the wall time was after
+        // the old clock's last reading.
+        switch (disambiguation) {
+            case 'reject':
+                throw new RangeError(`wall-clock time ${_a.#civilString(civil)} does not exist in ${this.id}`);
+            case 'earlier':
+                return civil - after.offsetMs;
+            default:
+                return civil - before.offsetMs;
+        }
+    }
+    static #civilMs(parts) {
+        const { year, month, day } = parts;
+        const hour = parts.hour ?? 0;
+        const minute = parts.minute ?? 0;
+        const second = parts.second ?? 0;
+        const millisecond = parts.millisecond ?? 0;
+        const inRange = (v, lo, hi) => Number.isInteger(v) && v >= lo && v <= hi;
+        if (!Number.isInteger(year) ||
+            !inRange(month, 1, 12) ||
+            !inRange(day, 1, daysInMonth(year, month)) ||
+            !inRange(hour, 0, 23) ||
+            !inRange(minute, 0, 59) ||
+            !inRange(second, 0, 59) ||
+            !inRange(millisecond, 0, 999)) {
+            // Reject rather than roll over: `{ month: 2, day: 30 }` is a caller
+            // error, not February 30th, and silently landing on March 2nd is how
+            // a bucket edge ends up in the wrong month.
+            throw new RangeError(`invalid wall-clock time ${JSON.stringify(parts)}`);
+        }
+        return (daysFromCivil(year, month, day) * MS_PER_DAY +
+            hour * MS_PER_HOUR +
+            minute * 60_000 +
+            second * 1_000 +
+            millisecond);
+    }
+    static #civilParts(civil) {
+        const days = Math.floor(civil / MS_PER_DAY);
+        let rem = civil - days * MS_PER_DAY;
+        const [year, month, day] = civilFromDays(days);
+        const hour = Math.floor(rem / MS_PER_HOUR);
+        rem -= hour * MS_PER_HOUR;
+        const minute = Math.floor(rem / 60_000);
+        rem -= minute * 60_000;
+        const second = Math.floor(rem / 1_000);
+        const millisecond = rem - second * 1_000;
+        return {
+            year,
+            month,
+            day,
+            hour,
+            minute,
+            second,
+            millisecond,
+            weekday: weekdayFromDays(days),
+        };
+    }
+    static #civilString(civil) {
+        return new Date(civil).toISOString().replace('Z', '');
+    }
+    /** Day number of the first day of the `unit` containing day number `days`. */
+    static #startDays(unit, days, weekStartsOn) {
+        switch (unit) {
+            case 'day':
+                return days;
+            case 'week':
+                return days - ((weekdayFromDays(days) - weekStartsOn + 7) % 7);
+            case 'month': {
+                const [y, m] = civilFromDays(days);
+                return daysFromCivil(y, m, 1);
+            }
+            case 'quarter': {
+                const [y, m] = civilFromDays(days);
+                return daysFromCivil(y, m - ((m - 1) % 3), 1);
+            }
+            case 'year': {
+                const [y] = civilFromDays(days);
+                return daysFromCivil(y, 1, 1);
+            }
+        }
+    }
+    /** Day number of the start of the following `unit`, given a unit-start day number. */
+    static #advanceDays(unit, startDays) {
+        switch (unit) {
+            case 'day':
+                return startDays + 1;
+            case 'week':
+                return startDays + 7;
+            case 'month':
+            case 'quarter':
+            case 'year': {
+                const [y, m] = civilFromDays(startDays);
+                const months = unit === 'month' ? 1 : unit === 'quarter' ? 3 : 12;
+                const total = y * 12 + (m - 1) + months;
+                return daysFromCivil(Math.floor(total / 12), (total % 12) + 1, 1);
+            }
+        }
+    }
+}
+_a = TimeZone;
+export { assertCalendarUnit };
+//# sourceMappingURL=time-zone.js.map

package/dist/index.d.ts

@@ -35,6 +35,8 @@ export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColum
 export { type ValidityBitmap } from './columnar/validity.js';
 export type { AlignSchema, ArrayColumnNameForSchema, BaselineSchema, AggregateFunction, AggregateReducer, AggregateOutputMap, AggregateOutputSpec, AggregateMap, AggregateSchema, ValidatedAggregateMap, ColumnDef, CollapseData, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CollapseSchema, DedupeKeep, EventDataForSchema, EventForSchema, EventKeyForKind, FillMapping, FillStrategy, MaterializeSchema, EventKeyForSchema, FirstColKind, FirstColumn, IntervalKeyedSchema, JsonIntervalInput, JsonObjectRowForSchema, JsonRowFormat, JsonRowForSchema, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, RollingAlignment, RollingSchema, JoinConflictMode, JoinManySchema, PrefixedJoinManySchema, PrefixedJoinSchema, LiveSource, JoinType, JoinSchema, NormalizedRowForSchema, NormalizedObjectRowForSchema, NormalizedObjectRow, NormalizedValueForKind, ReduceResult, RenameData, RenameMap, RenameSchema, RekeySchema, RowForSchema, AppendColumn, OptionalNumberColumn, ArrayValue, ColumnValue, ScalarKind, ScalarValue, CustomAggregateReducer, DiffSchema, NumericColumnNameForSchema, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectData, SelectSchema, SeriesSchema, TimeKeyedSchema, FlatKeyColumns, TimeSeriesColumnarInput, TimeSeriesColumnarOutput, TimeSeriesInput, TimeSeriesJsonColumns, TimeSeriesJsonInput, TimeRangeKeyedSchema, ValueColumnsForSchema, ValueColumn, ValueForKind, ValueFirstColumn, ValueKeyedSchema, ValueSeriesColumnarInput, ValueSeriesColumnarOutput, ValueSeriesColumnName, ValueSeriesJsonCell, ValueSeriesJsonColumns, ValueSeriesJsonInput, ValueSeriesJsonObjectRow, ValueSeriesJsonOutputArray, ValueSeriesJsonOutputObject, ValueSeriesJsonRow, ValueSeriesObjectRow, ValueSeriesRow, ValueSeriesSchema, ValueSeriesValueColumns, } from './schema/index.js';
 export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './core/calendar.js';
+export { TimeZone } from './core/time-zone.js';
+export type { Disambiguation, StartOfOptions, ZonedParts, ZonedPartsInput, } from './core/time-zone.js';
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './core/temporal.js';
 export type { DurationInput } from './core/duration.js';
 export type { SequenceSample } from './sequence/sequence.js';

package/dist/index.js

@@ -55,4 +55,5 @@ export { StringColumn } from './columnar/string-column.js';
 export { ArrayColumn } from './columnar/array-column.js';
 export { ChunkedArrayColumn, ChunkedBooleanColumn, ChunkedFloat64Column, ChunkedStringColumn, } from './columnar/chunked-column.js';
 export { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, } from './columnar/key-column.js';
+export { TimeZone } from './core/time-zone.js';
 //# sourceMappingURL=index.js.map

package/dist/sequence/sequence.d.ts

@@ -66,7 +66,10 @@ export declare class 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"`.
+     * fixed millisecond duration. Supported units are `"day"`, `"week"`, `"month"`, `"quarter"`
+     * and `"year"`; any other unit throws `RangeError`. Boundaries come from `TimeZone`, the
+     * same primitive the charts' time axis places ticks with, so a bucket edge and the tick
+     * that labels it are one instant.
      *
      * Defaults:
      * - `timeZone`: `"UTC"`

package/dist/sequence/sequence.js

@@ -1,5 +1,6 @@
 import { BoundedSequence } from './bounded-sequence.js';
-import { normalizeWeekStartsOn, nextCalendarStart, plainDateToStart, resolveTimeZone, toPlainDateStart, } from '../core/calendar.js';
+import { normalizeWeekStartsOn, resolveTimeZone, } from '../core/calendar.js';
+import { TimeZone, assertCalendarUnit } from '../core/time-zone.js';
 import { parseDuration } from '../core/duration.js';
 import { Interval } from '../core/interval.js';
 import { toTimeRange } from '../core/time-range.js';
@@ -31,8 +32,10 @@ export class Sequence {
         }
         else {
             this.#kind = 'calendar';
+            assertCalendarUnit(input.unit);
             this.#calendarUnit = input.unit;
-            this.#timeZone = input.timeZone;
+            // Resolve eagerly so an unknown zone fails here, not on first `bounded()`.
+            this.#timeZone = TimeZone.of(input.timeZone).id;
             this.#weekStartsOn = normalizeWeekStartsOn(input.weekStartsOn);
         }
         Object.freeze(this);
@@ -62,7 +65,10 @@ export class 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"`.
+     * fixed millisecond duration. Supported units are `"day"`, `"week"`, `"month"`, `"quarter"`
+     * and `"year"`; any other unit throws `RangeError`. Boundaries come from `TimeZone`, the
+     * same primitive the charts' time axis places ticks with, so a bucket edge and the tick
+     * that labels it are one instant.
      *
      * Defaults:
      * - `timeZone`: `"UTC"`
@@ -181,16 +187,12 @@ export class Sequence {
             }
             return new BoundedSequence(intervals);
         }
-        const timeZone = this.#timeZone;
+        const zone = TimeZone.of(this.#timeZone);
         const unit = this.#calendarUnit;
-        const weekStartsOn = this.#weekStartsOn;
-        let currentDate = toPlainDateStart(requested.begin(), timeZone, unit, weekStartsOn);
+        const startOptions = { weekStartsOn: this.#weekStartsOn };
+        let start = zone.startOf(unit, requested.begin(), startOptions);
         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 end = zone.next(unit, start, startOptions);
             const sampleTime = sample === 'end'
                 ? end
                 : sample === 'center'
@@ -206,7 +208,7 @@ export class Sequence {
             // 'end':                 sample ∈ (requested.begin, requested.end]
             //
             // Under 'overlap' every candidate is in: the walk starts at the bucket
-            // containing `requested.begin()` (`toPlainDateStart` floors to it), and
+            // containing `requested.begin()` (`zone.startOf` floors to it), and
             // every later bucket starts after that, so the leading test can only
             // ever pass. This is the one line the leading-bucket drop turned on —
             // the containing bucket was computed above and then discarded here.
@@ -218,7 +220,7 @@ export class Sequence {
             if (include) {
                 intervals.push(new Interval({ value: start, start, end }));
             }
-            currentDate = nextDate;
+            start = end;
         }
         return new BoundedSequence(intervals);
     }