pond-ts 0.68.0 → 0.69.0

package/dist/batch/partitioned-time-series.d.ts

@@ -4,7 +4,7 @@ import { Sequence } from '../sequence/sequence.js';
 import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike } from '../core/temporal.js';
 import type { BatchSampleStrategy } from '../sequence/sample.js';
-import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, ValueColumnsForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
 import type { ScanStep } from './operators/scan.js';
 type SequenceLike = Sequence | BoundedSequence;
 type AlignMethod = 'hold' | 'linear';
@@ -24,7 +24,7 @@ type AlignSample = 'begin' | 'center' | 'end';
  * the one actually passed — harmless because injected columns are already
  * optional.
  */
-export type WithPartitionColumns<Mapping, By extends string> = string extends By ? Mapping : Mapping & {
+export type WithPartitionColumns<S extends SeriesSchema, Mapping, By extends string> = string extends By ? Mapping : string extends ValueColumnsForSchema<S>[number]['name'] ? Mapping : Mapping & {
     readonly [C in Exclude<By, keyof Mapping>]: 'first';
 };
 /**
@@ -74,6 +74,22 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     #private;
     readonly source: TimeSeries<S>;
     readonly by: ReadonlyArray<keyof EventDataForSchema<S> & string>;
+    /**
+     * Phantom, erased at runtime. Pins `By` **contravariantly** so a view
+     * partitioned by one column cannot be assigned where a view partitioned
+     * by another is claimed (`PartitionedTimeSeries<S, K, 'host'>` ←
+     * `partitionBy('region')` is an error), while a specialised view still
+     * assigns to the legacy `PartitionedTimeSeries<S>` / `<S, K>` shape.
+     * Without it `By` only appears inside a conditional in return positions
+     * and TypeScript treats it as freely convertible (Codex finding on #724).
+     *
+     * Spelling note: **`never` (the default) is the "any / unknown column"
+     * view**, and it is the top of this pin — every specialised view assigns
+     * to it. `string` is the *bottom* (a `string`-typed `By` assigns to any
+     * literal), so do not write `PartitionedTimeSeries<S, K, string>` to mean
+     * "any column"; the `partitionBy` overloads never produce it.
+     */
+    readonly __partitionColumns?: (by: By) => void;
     /**
      * Declared partition values when `partitionBy(col, { groups })` was
      * used. When set, `toMap` iterates in declared order (not insertion
@@ -266,13 +282,13 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         minSamples?: number;
-    }): PartitionedTimeSeries<RollingSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<RollingSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         sample?: AlignSample;
         range?: TemporalLike;
         minSamples?: number;
-    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
     /** Per-partition `smooth`. See {@link TimeSeries.smooth}. */
     smooth<const Target extends NumericColumnNameForSchema<S>, const Output extends string | undefined = undefined>(column: Target, method: SmoothMethod, options: {
         alpha: number;
@@ -332,7 +348,7 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */
     aggregate<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, mapping: Mapping, options?: {
         range?: TemporalLike;
-    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
 }
 export {};
 //# sourceMappingURL=partitioned-time-series.d.ts.map

package/dist/core/calendar.d.ts

@@ -1,5 +1,5 @@
-import { Temporal } from '@js-temporal/polyfill';
-export type CalendarUnit = 'day' | 'week' | 'month';
+/** A calendar bucket unit. Boundaries are wall-clock in an IANA zone, so a `'day'` is 23, 24 or 25 hours across DST. */
+export type CalendarUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
 export type WeekStartsOn = 1 | 2 | 3 | 4 | 5 | 6 | 7;
 export type TimeZoneOptions = {
     timeZone?: string;
@@ -10,9 +10,6 @@ export type CalendarOptions = TimeZoneOptions & {
 export declare function resolveTimeZone(options?: TimeZoneOptions): string;
 export declare function normalizeWeekStartsOn(value: number | undefined): WeekStartsOn;
 export declare function parseTimestampString(value: string, options?: TimeZoneOptions): number;
-export declare function toPlainDateStart(instantMs: number, timeZone: string, unit: CalendarUnit, weekStartsOn: WeekStartsOn): Temporal.PlainDate;
-export declare function plainDateToStart(date: Temporal.PlainDate, timeZone: string): Temporal.ZonedDateTime;
-export declare function nextCalendarStart(current: Temporal.PlainDate, unit: CalendarUnit): Temporal.PlainDate;
 export declare function dayRangeForDate(reference: string, options?: TimeZoneOptions): {
     start: number;
     end: number;

package/dist/core/calendar.js

@@ -1,4 +1,5 @@
 import { Temporal } from '@js-temporal/polyfill';
+import { TimeZone } from './time-zone.js';
 const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
 const YEAR_MONTH_RE = /^\d{4}-\d{2}$/;
 const DATE_TIME_LOCAL_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/;
@@ -42,51 +43,6 @@ export function parseTimestampString(value, options = {}) {
     }
     return Temporal.Instant.from(value).epochMilliseconds;
 }
-export function toPlainDateStart(instantMs, timeZone, unit, weekStartsOn) {
-    // **Floor to the containing millisecond.** `Temporal.Instant` refuses a
-    // fractional epoch ms outright — `fromEpochMilliseconds(1577836800000.37)`
-    // throws `epoch milliseconds must be an integer` — and a fraction is not a
-    // caller error here. A chart's wheel-zoom derives its view range from pixel
-    // positions through `xScale.invert()`, so a perfectly ordinary gesture hands
-    // us `1.7e12 + 0.37`; realizing a calendar sequence over that range then
-    // crashed the page outright.
-    //
-    // Flooring is the only sane reading rather than a papering-over: the epoch
-    // millisecond *is* the atomic unit of this model, so an over-precise input
-    // can only mean the millisecond containing it, and calendar boundaries are
-    // themselves whole milliseconds — so the bucket containing `t` and the one
-    // containing `t + 0.37` are necessarily the same. Integer inputs are
-    // untouched.
-    //
-    // `Math.floor`, not `Math.trunc`: before 1970 they disagree, and `-5.5` lies
-    // inside the millisecond spanning `[-6, -5)`, which is `-6`.
-    const zoned = Temporal.Instant.fromEpochMilliseconds(Math.floor(instantMs)).toZonedDateTimeISO(timeZone);
-    const date = zoned.toPlainDate();
-    if (unit === 'day') {
-        return date;
-    }
-    if (unit === 'month') {
-        return Temporal.PlainDate.from({
-            year: date.year,
-            month: date.month,
-            day: 1,
-        });
-    }
-    const offset = (date.dayOfWeek - weekStartsOn + 7) % 7;
-    return date.subtract({ days: offset });
-}
-export function plainDateToStart(date, timeZone) {
-    return date.toZonedDateTime({ timeZone }).startOfDay();
-}
-export function nextCalendarStart(current, unit) {
-    if (unit === 'day') {
-        return current.add({ days: 1 });
-    }
-    if (unit === 'week') {
-        return current.add({ weeks: 1 });
-    }
-    return current.add({ months: 1 });
-}
 export function dayRangeForDate(reference, options = {}) {
     const timeZone = resolveTimeZone(options);
     const start = Temporal.PlainDate.from(reference)
@@ -102,12 +58,10 @@ export function calendarRangeForReference(unit, reference, options = {}) {
     const timeZone = resolveTimeZone(options);
     const weekStartsOn = normalizeWeekStartsOn(options.weekStartsOn);
     const referenceMs = parseTimestampString(reference, { timeZone });
-    const startDate = toPlainDateStart(referenceMs, timeZone, unit, weekStartsOn);
-    const start = plainDateToStart(startDate, timeZone);
-    const end = plainDateToStart(nextCalendarStart(startDate, unit), timeZone);
+    const zone = TimeZone.of(timeZone);
     return {
-        start: start.epochMilliseconds,
-        end: end.epochMilliseconds,
+        start: zone.startOf(unit, referenceMs, { weekStartsOn }),
+        end: zone.next(unit, referenceMs, { weekStartsOn }),
     };
 }
 //# sourceMappingURL=calendar.js.map

package/dist/core/index.d.ts

@@ -6,4 +6,6 @@ export type { DurationInput, DurationUnit } from './duration.js';
 export { ValidationError } from './errors.js';
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './temporal.js';
 export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './calendar.js';
+export { TimeZone } from './time-zone.js';
+export type { Disambiguation, StartOfOptions, ZonedParts, ZonedPartsInput, } from './time-zone.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -3,4 +3,5 @@ export { Interval } from './interval.js';
 export { Time } from './time.js';
 export { TimeRange, toTimeRange } from './time-range.js';
 export { ValidationError } from './errors.js';
+export { TimeZone } from './time-zone.js';
 //# sourceMappingURL=index.js.map

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