pond-ts 0.67.0 → 0.69.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.67.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.69.0...HEAD
+[0.69.0]: https://github.com/pond-ts/pond/compare/v0.68.0...v0.69.0
+[0.68.0]: https://github.com/pond-ts/pond/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/pond-ts/pond/compare/v0.66.0...v0.67.0
 [0.66.0]: https://github.com/pond-ts/pond/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/pond-ts/pond/compare/v0.64.0...v0.65.0
@@ -70,6 +72,112 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.69.0] — 2026-09-13
+
+### Added
+
+- **`<ChartContainer timeZone>` — the time axis in any IANA zone
+  ([PND-TZAXIS]).** Day / week / month ticks land on that zone's midnights,
+  Mondays and month starts; labels, the stacked date bands, the hierarchical
+  grid, session dividers and every cursor / marker / annotation readout read
+  in it. **Omitted ⇒ the viewer's zone**, exactly as before. The d3 specifier
+  strings on `timeFormat` / `cursorFormat` are unchanged; `%Z` / `%z` now read
+  the zone's abbreviation / offset. Sub-day ticks align to the zone's wall
+  clock, so a 6 h grain reads 00 / 06 / 12 / 18 across a DST jump instead of
+  drifting by an hour until the next midnight. The resolved zone is on the
+  chart context as `timeZone`. Built on core's `TimeZone` ([PND-TZCAL]), so a
+  `Sequence.calendar('day', { timeZone })` bucket edge and the tick that
+  labels it are one instant — pinned by a cross-package test.
+- **`<XAxis timeZone>` — a second strip in another zone.** Two time axes
+  over one shared mapping, each ticking and labelling (and pilling) in its
+  own zone: `<XAxis side="top" timeZone="America/New_York" />` above a
+  UTC container's own strip below. Backed by
+  `TradingTimeScale.withTimeZone(zone)` / `.timeZone()` and an optional
+  `DiscontinuityProvider.withTimeZone` (the identity provider re-derives its
+  day anchors; a trading calendar's session opens are zone-independent).
+- **`TradingCalendarLike.timeZone?`** — a calendar that carries its exchange
+  zone supplies the axis default (`calendar={cal}` renders in exchange time
+  wherever it is viewed); an explicit `timeZone` prop wins.
+- `scaleTradingTime(provider, { timeZone })` and
+  `identityProvider({ timeZone })` take the zone directly for consumers
+  building the scale themselves; `identityProvider`, `TradingCalendarLike`
+  and `ScaleTimeZoneOptions` are now exported. Internally the tick ladder
+  runs on a `TickCalendar` seam whose local implementation is the previous
+  `Date` arithmetic verbatim — the default path is unchanged.
+- **`TradingCalendar.timeZone` ([PND-TZFIN]).** `@pond-ts/financial`'s
+  calendar keeps the zone its sessions were resolved in — `fromRules` carries
+  `rules.timeZone`, `fromSessions(list, { timeZone })` takes it — so
+  `<ChartContainer calendar={cal}>` renders the axis in exchange time with no
+  further wiring.
+- `@pond-ts/charts` now depends on `d3-time-format` directly (it was already
+  a transitive dependency via `d3-scale`).
+- **`TimeZone` — the zone-calendar primitive ([PND-TZCAL]).** `pond-ts`
+  exports `TimeZone.of(id)` (interned; also `TimeZone.UTC`,
+  `TimeZone.local()`) with `startOf(unit, t)`, `next(unit, t)`, `parts(t)`,
+  `instant(parts, { disambiguation })`, `offsetAt(t)` and
+  `abbreviation(t, { locale })`. Temporal underneath, but each zone caches its
+  offset transitions as it discovers them, so steady-state calls are integer
+  arithmetic: `startOf('day')` went from ~24 µs to ~23 ns per call, and a
+  three-year hourly series aggregated to `America/New_York` days from 38 ms
+  to 0.5 ms. `Sequence.calendar`, `TimeRange.fromCalendar` and
+  `Interval.fromCalendar` now bucket through it (no behaviour change; pinned
+  against Temporal on eight zones including southern-hemisphere DST, a
+  30-minute DST shift, a +05:30 zone, a day with no midnight and Samoa's
+  skipped day). This is the primitive the charts' time axis will place and
+  label ticks with, so a bucket edge and the tick that labels it are one
+  instant. First task of the time-zone plan
+  (`docs/plans/PND_TIMEZONE_PLAN.md`).
+- **`CalendarUnit` gains `'quarter'` and `'year'`** for
+  `Sequence.calendar`, `TimeRange.fromCalendar` and `Interval.fromCalendar`.
+
+### Changed
+
+- **`Sequence.calendar` validates its inputs at construction.** An unknown
+  unit (`'hour'`) or zone (`'Nowhere'`) now throws `RangeError` immediately;
+  before, an unknown unit silently produced wrong buckets (the two unit
+  dispatchers fell through to different defaults — the 2026-06 audit's §6
+  finding) and an unknown zone failed only on first `bounded()`.
+
+### Fixed
+
+- **`pond-ts`: two type-level corners of [PND-PARTCOL] (0.68.0) found by the Codex pass on #724.** (1) On a broad `TimeSeries<SeriesSchema>` with a _literal_ partition column, the injected `'first'` could not look up a kind and typed the column as `undefined`; `WithPartitionColumns` now takes the schema and leaves the mapping alone when the schema is broad, so the result type is exactly 0.67's. (2) `By` had no variance pin, so `PartitionedTimeSeries<S, K, 'host'>` accepted a view partitioned by `region` (and an untyped view could be narrowed to any column); a phantom contravariant member now rejects both while a specialised view still assigns to the legacy `PartitionedTimeSeries<S>` shape. Type tests cover both plus the `K`-survives-`smooth`/`baseline` claim. No runtime change.
+- **Docs said a wall-clock string without `parse.timeZone` throws. It never
+  did** ([PND-TZDOCS]) — it is read as UTC, silently. `creating.mdx`, the
+  agent guide (`AGENTS.md`) and the decision table now say so and describe
+  how the shift shows up. The agent guide also gains the one time-zone rule:
+  pass the same `timeZone` to `Sequence.calendar` and `<ChartContainer>`.
+  The aggregation page cross-links `Sequence.calendar` for weekly / monthly
+  bars (issue #358 item 1, supersedes #359). The finance gallery's off-chart
+  readout takes the calendar's zone instead of hard-coding New York; the
+  Niño 3.4 heat map's year grain uses `Sequence.calendar('year')`.
+
+## [0.68.0] — 2026-09-13
+
+### Added
+
+- **Agent adoption tranche ([PND-ADOPTMETA] / [PND-ADOPTLINKS] /
+  [PND-LLMSTXT] / [PND-AGENTGUIDE] / [PND-SKILL] / [PND-CONTEXT7]).** Every
+  package now declares `keywords`, `homepage` and `bugs` (there were none —
+  `pond-ts` ranked last in `npm search "time series"`). Every tarball ships an
+  `AGENTS.md` (source `docs/agents/USING_POND.md`): which package for which
+  task, the core idioms, the mistakes agents make. `pond-ts.org/llms.txt` is
+  now llmstxt.org-shaped (titles + descriptions per page, one section per
+  docs area, `Optional` links to `API.md` / the agent guide) with per-area
+  `llms-<area>.txt` dumps so a single fetch stays small. A Claude Code plugin
+  marketplace lives in the repo (`/plugin marketplace add pond-ts/pond`) with
+  `pond-ts`, `pond-charts` and `pond-financial` skills. `context7.json`
+  configures docs-MCP indexing. Plan and baseline:
+  `docs/plans/PND_ADOPTION_PLAN.md`.
+
+- **Agent guide + skill hardened by the first cold-start run** (`docs/agents/USING_POND.md`, shipped as `AGENTS.md`; `plugins/pond-ts/skills/pond-ts`): install with `@latest` and the `.d.ts` paths that carry signatures. Cold-start harness committed at `docs/adoption/cold-start/`.
+
+### Fixed
+
+- **`pond-ts`: the partition column is now in the static type after a partitioned `aggregate` / `rolling` ([PND-PARTCOL]).** `series.partitionBy('host').aggregate(seq, { p95: { from: 'ms', using: 'p95' } }).collect()` always carried `host` at runtime (auto-injected as `'first'`) but the result type omitted it, so `e.get('host')` failed to compile — every fresh agent in the cold-start experiment hit or pre-empted it. `PartitionedTimeSeries` gains a third type parameter `By` (the partition column names, captured by `partitionBy`, default `never`), and the two schema-replacing operators are typed over `WithPartitionColumns<Mapping, By>` — the user's keys win, kind and all; missing partition columns are added as `'first'`. Composite partitions and typed `groups` carry through; `smooth` / `baseline` under `partitionBy` now also keep `K`. Additive: untyped views are unchanged.
+- `@pond-ts/charts` and `@pond-ts/fit` READMEs (rendered on npm) and eight
+  docs pages pointed at the retired `pjm17971.github.io/pond-ts` site /
+  `pjm17971/pond-ts` repo; now `pond-ts.org` / `pond-ts/pond`.
+
 ## [0.67.0] — 2026-09-11
 
 ### Added

package/README.md

@@ -1,21 +1,44 @@
 # pond-ts
 
+[![npm](https://img.shields.io/npm/v/pond-ts?label=pond-ts)](https://www.npmjs.com/package/pond-ts)
+[![CI](https://github.com/pond-ts/pond/actions/workflows/ci.yml/badge.svg)](https://github.com/pond-ts/pond/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/pond-ts)](https://github.com/pond-ts/pond/blob/main/LICENSE)
+[![docs](https://img.shields.io/badge/docs-pond--ts.org-1f6feb)](https://pond-ts.org)
+
 **Highly optimised, fully typed Timeseries library for TypeScript**
 
 Schema-driven events, composable batch transforms, push-based streaming
-ingest, multi-entity partitioning, and an optional React integration —
-all strict TypeScript end to end, all immutable.
+ingest, multi-entity partitioning — and, optionally, React hooks and
+canvas charts that read the series directly. All strict TypeScript end to
+end, all immutable.
 
 **pond-ts** is the TypeScript-first successor to
 [pondjs](https://github.com/esnet/pond), rewritten from scratch with a
 focus on type safety, composability, and the live-streaming patterns
 that pondjs never grew.
 
+## The packages
+
+Three packages carry most projects. The core has no dependency on the other
+two; add them only if you render.
+
+| Package                                                                           | What it is                                                                                                                                                                                         | Needs                                    |
+| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **[`pond-ts`](https://www.npmjs.com/package/pond-ts)** — core                     | `TimeSeries` (batch) and `LiveSeries` (streaming) with one operator vocabulary: aggregate, rolling, align, fill, partition, join, typed columns. Node or browser, no React.                        | nothing                                  |
+| **[`@pond-ts/charts`](https://www.npmjs.com/package/@pond-ts/charts)** — optional | Declarative React charts on a canvas data plane that consume a pond series with no adapter: line, area, band, bar, scatter, box, candlestick, heat map; cursors, selection, pan/zoom, annotations. | `pond-ts`, `@pond-ts/react`, React 18/19 |
+| **[`@pond-ts/react`](https://www.npmjs.com/package/@pond-ts/react)** — optional   | Hooks to own a series in a component and read live views on a throttled snapshot cadence (`useLiveSeries`, `useSnapshot`, …).                                                                      | `pond-ts`, React 18/19                   |
+
 ```sh
-npm install pond-ts                 # core
-npm install @pond-ts/react          # React hooks (optional)
+npm install pond-ts                                   # core — enough for Node pipelines and non-React apps
+npm install @pond-ts/charts @pond-ts/react pond-ts    # add the React chart stack
 ```
 
+Two domain packages ([`@pond-ts/financial`](#domain-packages) for markets,
+[`@pond-ts/fit`](#domain-packages) for activity data) and one experimental
+runtime ([`@pond-ts/process`](#domain-packages)) sit on top — see
+[Domain packages](#domain-packages) below. All six release together under
+one version; keep them in step.
+
 - **Typed schemas** — declare once, every transform downstream narrows
   off it. `event.get('cpu')` returns `number | undefined` straight from
   the schema; no `as` casts.
@@ -108,6 +131,43 @@ The full live surface (`filter`, `map`, `select`, `window`, `aggregate`,
 `sample`) is incremental — events flow, views emit, retention bounds
 memory.
 
+## Quick start: charts (React)
+
+`@pond-ts/charts` reads a `TimeSeries` or `LiveSeries` directly — do the maths
+in pond, hand the result to a layer. Rows share one x scale, so they pan,
+zoom and track the cursor together.
+
+```tsx
+import {
+  BandChart,
+  ChartContainer,
+  ChartRow,
+  Layers,
+  LineChart,
+  YAxis,
+} from '@pond-ts/charts';
+
+// `bands` is the baseline() result from the batch quick start:
+// cpu + avg / sd / upper / lower columns.
+export function CpuChart({ width }: { width: number }) {
+  return (
+    <ChartContainer width={width} cursor="crosshair" panZoom>
+      <ChartRow height={240}>
+        <YAxis id="cpu" format=".0%" />
+        <Layers>
+          <BandChart series={bands} lower="lower" upper="upper" axis="cpu" />
+          <LineChart series={bands} column="cpu" axis="cpu" />
+        </Layers>
+      </ChartRow>
+    </ChartContainer>
+  );
+}
+```
+
+Pass `width="auto"` to measure the parent instead. Live data renders through
+the same layers: own the series with `useLiveSeries` from `@pond-ts/react`
+and pass its snapshot as `series`.
+
 ## Quick start: multi-entity
 
 `partitionBy` routes events into per-key buffers. Every stateful
@@ -182,6 +242,26 @@ it is behind. Run locally:
 npm run build && node packages/core/bench/vs-pondjs.cjs
 ```
 
+## Domain packages
+
+Optional, domain-specific, all on plain pond series:
+
+- **[`@pond-ts/financial`](https://www.npmjs.com/package/@pond-ts/financial)**
+  — sixty-plus oracle-verified technical studies (SMA, EMA, RSI, MACD,
+  Bollinger, ATR, VWAP, …) that append columns to a bar series, a fluent
+  `bars.sma({ period: 20 }).rsi({ period: 14 })` form, and a
+  `TradingCalendar` so session-aligned bars, rolling windows and chart axes
+  stop at the close.
+- **[`@pond-ts/fit`](https://www.npmjs.com/package/@pond-ts/fit)** — fitness
+  and activity analytics: typed quantities with units, canonical activity
+  series, geo (distance, elevation, best efforts), power (NP / IF / TSS,
+  curves), heart-rate zones, splits.
+- **[`@pond-ts/process`](https://www.npmjs.com/package/@pond-ts/process)** —
+  **experimental.** Computations as data: processing graphs authored fluently
+  or composed as JSON, resolved against a declared op vocabulary with
+  content-addressed caching, provenance and per-node timings. The API is
+  expected to move.
+
 ## Documentation
 
 The full guide is at **<https://pond-ts.org/>**.
@@ -202,6 +282,26 @@ The full guide is at **<https://pond-ts.org/>**.
   — TypeDoc output, every public class and method.
 - **[CHANGELOG](./CHANGELOG.md)** — what shipped in each release.
 
+## For coding agents
+
+pond is built by agents and expects to be used by them. Three things exist so
+an agent can go from "never heard of pond" to working code without a human in
+the loop:
+
+- **`AGENTS.md` + `API.md` ship inside every npm tarball** —
+  `node_modules/pond-ts/AGENTS.md` is a one-read guide (which package for
+  which task, the idioms, the mistakes agents make); `API.md` maps every
+  public export to its source file. Source:
+  [docs/agents/USING_POND.md](docs/agents/USING_POND.md), [API.md](API.md).
+- **<https://pond-ts.org/llms.txt>** — every docs page with a one-line
+  description, plus `llms-<area>.txt` single-fetch dumps per package.
+- **Claude Code plugin** — skills for core, charts and financial, versioned
+  with the library:
+  ```
+  /plugin marketplace add pond-ts/pond
+  /plugin install pond-ts@pond-ts
+  ```
+
 ## Examples
 
 - **[pond-ts-dashboard](https://github.com/pjm17971/pond-ts-dashboard)**
@@ -213,20 +313,22 @@ The full guide is at **<https://pond-ts.org/>**.
 
 ## Develop
 
-The repo is an npm-workspaces monorepo with two published packages
-(`pond-ts`, `@pond-ts/react`). Node 18+ for runtime; Node 20+ for the
+The repo is an npm-workspaces monorepo with six published packages
+(`pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, `@pond-ts/financial`,
+`@pond-ts/fit`, `@pond-ts/process`). Node 18+ for runtime; Node 20+ for the
 docs site (Docusaurus).
 
 ```sh
-npm install         # one-time, hoists deps for both packages
+npm install         # one-time, hoists deps for all packages
 npm run build       # build both packages
 npm test            # runtime + type-level tests on both packages
 npm run format      # prettier write across the repo
 npm run verify      # format check + build + test (CI parity)
 ```
 
-`packages/core/` is the `pond-ts` package; `packages/react/` is
-`@pond-ts/react`. Docs live in `website/`.
+Each package lives under `packages/<name>/` (`core` is `pond-ts`, the rest
+match their scoped names). Docs live in `website/` — its own npm root, not a
+workspace.
 
 ## License
 

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

@@ -4,11 +4,29 @@ 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';
 type AlignSample = 'begin' | 'center' | 'end';
+/**
+ * The mapping a partitioned `aggregate` / `rolling` actually runs with
+ * ([PND-PARTCOL]). The runtime (`augmentMappingWithPartitionCols`) appends
+ * every partition column the user's mapping does not already name as a
+ * `'first'` spec, so the collected series carries the partition key. This
+ * is the same rule at the type level: keys the user wrote win (kind and
+ * all — `host: 'count'` stays an optional number), the rest are added as
+ * `'first'` and so keep the source column's kind. `By` defaults to `never`
+ * on an untyped view, which leaves the mapping untouched; a widened
+ * `string` `By` does too (see the conditional). One knowing lie: when the
+ * partition column is a union-typed variable (`c: 'host' | 'region'`), the
+ * type names both as `string | undefined` while the runtime carries only
+ * the one actually passed — harmless because injected columns are already
+ * optional.
+ */
+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';
+};
 /**
  * View over a `TimeSeries` that scopes stateful transforms to within
  * each partition. Created by `TimeSeries.partitionBy(by)`.
@@ -52,10 +70,26 @@ type AlignSample = 'begin' | 'center' | 'end';
  * );
  * ```
  */
-export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends string = string> {
+export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends string = string, By extends string = never> {
     #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
@@ -205,12 +239,12 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
      * reservoir. Safe by construction; no `unsafeGlobal: true` token.
      * See {@link TimeSeries.sample}.
      */
-    sample(strategy: BatchSampleStrategy): PartitionedTimeSeries<S, K>;
+    sample(strategy: BatchSampleStrategy): PartitionedTimeSeries<S, K, By>;
     /** Per-partition `fill`. See {@link TimeSeries.fill}. */
     fill(strategy: FillStrategy | FillMapping<S>, options?: {
         limit?: number;
         maxGap?: DurationInput;
-    }): PartitionedTimeSeries<S, K>;
+    }): PartitionedTimeSeries<S, K, By>;
     /**
      * Per-partition `dedupe`. The duplicate key becomes "same partition
      * columns AND same timestamp" — `partitionBy` provides the partition
@@ -221,13 +255,13 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
      */
     dedupe(options?: {
         keep?: DedupeKeep<S>;
-    }): PartitionedTimeSeries<S, K>;
+    }): PartitionedTimeSeries<S, K, By>;
     /** Per-partition `align`. See {@link TimeSeries.align}. */
     align(sequence: SequenceLike, options?: {
         method?: AlignMethod;
         sample?: AlignSample;
         range?: TemporalLike;
-    }): PartitionedTimeSeries<AlignSchema<S>, K>;
+    }): PartitionedTimeSeries<AlignSchema<S>, K, By>;
     /**
      * Per-partition `materialize`. See {@link TimeSeries.materialize}.
      *
@@ -243,18 +277,18 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
         sample?: AlignSample;
         select?: 'first' | 'last' | 'nearest';
         range?: TemporalLike;
-    }): PartitionedTimeSeries<MaterializeSchema<S>, K>;
+    }): PartitionedTimeSeries<MaterializeSchema<S>, K, By>;
     /** Per-partition `rolling`. See {@link TimeSeries.rolling}. */
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         minSamples?: number;
-    }): PartitionedTimeSeries<RollingSchema<S, Mapping>, K>;
+    }): 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, Mapping>, K>;
+    }): 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;
@@ -267,7 +301,7 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     } | {
         span: number;
         output?: Output;
-    }): PartitionedTimeSeries<Output extends string ? SmoothAppendSchema<S, Output> : SmoothSchema<S, Target>>;
+    }): PartitionedTimeSeries<Output extends string ? SmoothAppendSchema<S, Output> : SmoothSchema<S, Target>, K, By>;
     /** Per-partition `baseline`. See {@link TimeSeries.baseline}. */
     baseline<const Col extends NumericColumnNameForSchema<S>, const AvgName extends string = 'avg', const SdName extends string = 'sd', const UpperName extends string = 'upper', const LowerName extends string = 'lower'>(col: Col, options: {
         window: DurationInput;
@@ -280,41 +314,41 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
             upper?: UpperName;
             lower?: LowerName;
         };
-    }): PartitionedTimeSeries<BaselineSchema<S, AvgName, SdName, UpperName, LowerName>>;
+    }): PartitionedTimeSeries<BaselineSchema<S, AvgName, SdName, UpperName, LowerName>, K, By>;
     /** Per-partition `outliers`. See {@link TimeSeries.outliers}. */
     outliers<const Col extends NumericColumnNameForSchema<S>>(col: Col, options: {
         window: DurationInput;
         sigma: number;
         alignment?: RollingAlignment;
         minSamples?: number;
-    }): PartitionedTimeSeries<S, K>;
+    }): PartitionedTimeSeries<S, K, By>;
     /** Per-partition `diff`. See {@link TimeSeries.diff}. */
     diff<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], options?: {
         drop?: boolean;
-    }): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
+    }): PartitionedTimeSeries<DiffSchema<S, Target>, K, By>;
     /** Per-partition `rate`. See {@link TimeSeries.rate}. */
     rate<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], options?: {
         drop?: boolean;
-    }): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
+    }): PartitionedTimeSeries<DiffSchema<S, Target>, K, By>;
     /** Per-partition `pctChange`. See {@link TimeSeries.pctChange}. */
     pctChange<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], options?: {
         drop?: boolean;
-    }): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
+    }): PartitionedTimeSeries<DiffSchema<S, Target>, K, By>;
     /** Per-partition `cumulative`. See {@link TimeSeries.cumulative}. */
     cumulative<const Targets extends NumericColumnNameForSchema<S>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
-    }): PartitionedTimeSeries<DiffSchema<S, Targets>, K>;
+    }): PartitionedTimeSeries<DiffSchema<S, Targets>, K, By>;
     /** Per-partition `scan`. See {@link TimeSeries.scan}. */
-    scan<const Source extends NumericColumnNameForSchema<S>, A>(source: Source, step: ScanStep<A>, init: A): PartitionedTimeSeries<DiffSchema<S, Source>, K>;
+    scan<const Source extends NumericColumnNameForSchema<S>, A>(source: Source, step: ScanStep<A>, init: A): PartitionedTimeSeries<DiffSchema<S, Source>, K, By>;
     scan<const Source extends NumericColumnNameForSchema<S>, const Name extends string, A>(source: Source, step: ScanStep<A>, init: A, options: {
         output: Name;
-    }): PartitionedTimeSeries<AppendColumn<S, Name, 'number'>, K>;
+    }): PartitionedTimeSeries<AppendColumn<S, Name, 'number'>, K, By>;
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
-    shift<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], n: number): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
+    shift<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], n: number): PartitionedTimeSeries<DiffSchema<S, Target>, K, By>;
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */
     aggregate<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, mapping: Mapping, options?: {
         range?: TemporalLike;
-    }): PartitionedTimeSeries<AggregateSchema<S, Mapping>, K>;
+    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
 }
 export {};
 //# sourceMappingURL=partitioned-time-series.d.ts.map

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

@@ -956,8 +956,8 @@ export declare class TimeSeries<S extends SeriesSchema> {
      */
     partitionBy<Col extends keyof EventDataForSchema<S> & string, const Groups extends ReadonlyArray<string>>(by: Col | readonly [Col], options: {
         groups: Groups;
-    }): PartitionedTimeSeries<S, Groups[number]>;
-    partitionBy(by: (keyof EventDataForSchema<S> & string) | ReadonlyArray<keyof EventDataForSchema<S> & string>): PartitionedTimeSeries<S>;
+    }): PartitionedTimeSeries<S, Groups[number], Col>;
+    partitionBy<const Col extends keyof EventDataForSchema<S> & string>(by: Col | ReadonlyArray<Col>): PartitionedTimeSeries<S, string, Col>;
     /**
      * Example: `series.pivotByGroup("host", "cpu")`.
      * Reshapes long-form data into wide rows. Each distinct value of

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