@jarenjs/core 0.46.5 → 0.49.2

package/dist/types/series/rolling.d.ts

@@ -0,0 +1,67 @@
+export type Sample = import('./normalize.js').Sample;
+/**
+ * `rollingSeries`' closed specification: a window measured in time,
+ * how much of one counts, the clock a calendar width walks, and where
+ * a row keeps its instant and its reading.
+ */
+export declare const ROLLING_MEMBERS: readonly string[];
+/**
+ * A rolling aggregate over a time-width window.
+ *
+ * Returns one `{ at, value, count }` per input sample, labelled at that
+ * sample's own instant, where the window is the half-open span
+ * `(at − width, at]`. Two samples at one instant share that window, and
+ * so report the same value and count.
+ *
+ * `count` is the number of **source rows** in the window — duplicates
+ * and measured gaps included — and the six value aggregates skip `null`
+ * readings, so `value` is `null` exactly when the window had nothing to
+ * measure. `aggregate: 'count'` returns that row count as the value.
+ *
+ * `minPeriods` is the number of source rows the window must hold before
+ * a value is reported at all; below it the row is `null` with its real
+ * `count`. It counts rows rather than readings, so a window full of
+ * measured gaps satisfies it and still reports `null` — which is the
+ * honest answer: readings were due, and none of them carried a number.
+ *
+ * `width` is a fixed duration (`'PT1H'`, `86400000`) or, with a clock,
+ * a calendar one (`'P1M'`, and `'P1D'` on a named zone where a day may
+ * be 23 or 25 hours long). A calendar window's start is computed by the
+ * calendar kernel per output, which is O(1) each — it is never a scan
+ * back through the window.
+ *
+ * @param {any[]} rows - the samples, in any order
+ * @param {Object} spec
+ * @param {number | string} spec.width - the window's width
+ * @param {'sum'|'mean'|'min'|'max'|'first'|'last'|'count'} [spec.aggregate]
+ *   default `'mean'`
+ * @param {number} [spec.minPeriods] - default 1
+ * @param {string} [spec.zone] - a named zone, needing `provider`
+ * @param {number} [spec.offset] - minutes east of UTC
+ * @param {import('./zone.js').ZoneProvider} [spec.provider]
+ * @param {'reject'|'earlier'|'later'} [spec.disambiguation]
+ * @param {string | ((item: any, index: number) => any)} [spec.at]
+ * @param {string | ((item: any, index: number) => any)} [spec.value]
+ * @returns {{ at: number, value: number | null, count: number }[]}
+ * @throws {TypeError} for a width that is not one positive whole span,
+ *   an unknown aggregate, a `minPeriods` that is not a positive whole
+ *   number, or a row that is not a canonical sample
+ * @example
+ * rollingSeries(readings, { width: 'PT5M', aggregate: 'mean' });
+ * rollingSeries(readings, { width: 'PT1M', minPeriods: 60 });
+ */
+export declare function rollingSeries(rows: any[], spec: {
+    width: number | string;
+    aggregate?: 'sum' | 'mean' | 'min' | 'max' | 'first' | 'last' | 'count';
+    minPeriods?: number;
+    zone?: string;
+    offset?: number;
+    provider?: import('./zone.js').ZoneProvider;
+    disambiguation?: 'reject' | 'earlier' | 'later';
+    at?: string | ((item: any, index: number) => any);
+    value?: string | ((item: any, index: number) => any);
+}): {
+    at: number;
+    value: number | null;
+    count: number;
+}[];

package/dist/types/series/selector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A reader for one member of a source row.
+ * @param {string | ((item: any, index: number) => any)} spec - a
+ *   property name, or a function of the row and its position
+ * @param {string} role - the member's name, for the message
+ * @returns {(item: any, index: number) => any}
+ * @throws {TypeError} when `spec` is neither
+ */
+export declare function selectorOf(spec: string | ((item: any, index: number) => any), role: string): (item: any, index: number) => any;
+/**
+ * The row at `index`, confirmed to be something with members to read.
+ * @param {any} item
+ * @param {number} index
+ * @returns {any}
+ * @throws {TypeError} when it is not an object
+ */
+export declare function requireRow(item: any, index: number): any;
+/**
+ * One specification, confirmed to name only admitted members.
+ * @param {any} spec - the caller's specification object
+ * @param {readonly string[]} allowed - the closed member list
+ * @param {string} kernel - the function's name, for the message
+ * @param {string} shape - what the specification is, for the message
+ *   when it is not an object at all
+ * @returns {any} the same object
+ * @throws {TypeError} when it is not an object, or names a member the
+ *   kernel does not admit
+ */
+export declare function requireSpecMembers(spec: any, allowed: readonly string[], kernel: string, shape: string): any;

package/dist/types/series/zone.d.ts

@@ -0,0 +1,59 @@
+export type ZoneProvider = {
+    /**
+     * - the wall
+     * clock at an instant, as a parts record (`year`, `month` 1-12, `day`,
+     * `hours`, `minutes`, `seconds`, and `offset` in minutes east if known)
+     */
+    toParts: (epoch: number, zone: string) => any;
+    /**
+     * - the instant a wall clock names, in epoch milliseconds;
+     * non-finite (or a throw) when the local time is ambiguous or does not
+     * exist and `disambiguation` does not resolve it
+     */
+    toEpoch: (parts: any, zone: string, disambiguation: string) => number;
+};
+export type Clock = {
+    /**
+     * - what the clock is called, for messages
+     */
+    zone: string;
+    partsAt: (epoch: number) => any;
+    epochOf: (parts: any) => number;
+};
+/**
+ * The four members every calendar-aware specification carries, so
+ * a bucket ladder, a rolling window and a query document all spell
+ * the clock the same way.
+ */
+export declare const CLOCK_MEMBERS: readonly string[];
+/**
+ * The clock an operation reads its calendar boundaries on.
+ *
+ * Defaults to UTC, which needs nothing: no provider, no zone name, no
+ * ambiguity. `{ offset }` is a constant number of minutes east and is
+ * exact integer arithmetic. `{ zone }` is a name, and a name means
+ * nothing without a `provider` — asking for `'Europe/Amsterdam'` with no
+ * tzdb is a refusal, never a silent fall back to UTC that is right for
+ * eight months of the year.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.zone] - an IANA name; `'UTC'` needs no provider
+ * @param {number} [options.offset] - minutes east of UTC, for a fixed offset
+ * @param {ZoneProvider} [options.provider] - the tzdb, for a named zone
+ * @param {'reject' | 'earlier' | 'later'} [options.disambiguation]
+ *   what a local time that happens twice, or never, resolves to
+ *   (default `'reject'`)
+ * @returns {Clock}
+ * @throws {TypeError} for a named zone with no provider, a non-finite
+ *   offset, an unknown disambiguation, or both a zone and an offset
+ * @example
+ * resolveClock();                        // UTC
+ * resolveClock({ offset: 330 });         // +05:30, constant
+ * resolveClock({ zone: 'Europe/Amsterdam', provider, disambiguation: 'later' });
+ */
+export declare function resolveClock(options?: {
+    zone?: string;
+    offset?: number;
+    provider?: ZoneProvider;
+    disambiguation?: 'reject' | 'earlier' | 'later';
+}): Clock;

package/docs/DATES.md

@@ -42,6 +42,43 @@ start Monday, per ISO). **Month math clamps**: 31 Jan + 1 month =
 28 Feb, which is what makes add and diff behave as inverses in the
 query operators built on this.
 
+Two refusals keep those answers honest, both `TypeError`:
+
+- **A unit reads a half, and a value may not carry it.** `year` through
+  `day` read the calendar; `hour` through `millisecond` read the clock.
+  Adding hours to a full-date, adding a day to a full-time, or
+  truncating either to the unit it has not got has no answer to give.
+  `day` and coarser truncations are the boundary both forms have, so
+  `startOfParts` / `endOfParts` of a `day` on a full-time is midnight and
+  `23:59:59.999`.
+- **A fraction is a quantity only where it converts exactly.** A
+  fractional fixed-width amount becomes whole milliseconds — `1.5 day` is
+  thirty-six hours, and needs a value with a clock to land on. A
+  fractional calendar unit is refused unless it lands on a whole month:
+  half a year is six months, half a month is nothing.
+
+## Time-axis ticks — `ticks.js`
+
+`niceTimeStep(span, count)` picks the `[unit, amount]` a domain should be
+read in — from 1/5/15/30 seconds and minutes through 1/3/6/12 hours, 1/2
+days, 1/2 weeks and 1/3/6 months, then whole years on the 1/2/5 × 10^k
+ladder, so a millennial domain steps by centuries rather than running out
+of axis. `axisTicksTime(min, max, count)` lays the boundaries down: each
+tick is a multiple of the step's own amount, so an axis reads
+`1850 1900 1950 2000` rather than offsets from wherever the data began.
+Below a second the calendar has nothing to say and the numeric ladder
+answers instead. The chart component re-exports both rather than
+carrying its own copy.
+
+`timeTicksEvery(min, max, unit, amount?, options?)` is the same boundary
+rule with the step supplied instead of chosen — what a document that
+declares its own interval needs (Mermaid's Gantt `tickInterval 1week` is
+the one in this repo). `options.weekStart` is an ISO weekday, so a
+document whose weeks begin on Sunday gets Sundays; `options.limit` caps
+the count. `axisTicksTime` is now this function with the ladder in
+front of it, so a chart axis and a timeline cannot disagree about where
+a tick falls.
+
 ## Durations — `duration.js`
 
 `parseDuration('P3DT4H')` — ISO 8601 duration decomposition into
@@ -65,6 +102,43 @@ ISO tokens work bare; name tokens (`MMMM`, `EEE`, `a`) require a
 `names` provider, which is where `@jarenjs/locales` plugs in — the
 kernel ships no month names, so server-rendered output stays
 byte-stable across Node/ICU versions.
+`compileDateLocale(pack).names` is that provider: five arrays (12 months
+wide and short, 7 weekdays wide and short from Sunday, the two day-period
+markers), read once out of a locale pack's own msgids and frozen, so a
+pattern compiled against them costs no lookup per date.
+
+## Parsing — `parse.js`
+
+`compileDateParser(pattern, names?)` is the formatter's strict inverse
+over the same LDML vocabulary, compiled the same way: the pattern is
+scanned once into a chain of readers, and no regular expression is built
+per compile or per parse. It returns a function from text to the parts
+record `parseRFC3339Parts` produces, so `epochOfRFC3339Parts`,
+`addToParts` and `formatRFC3339Parts` all take its output unchanged, and
+the lexical family follows the pattern — date tokens only give a
+full-date, time tokens only a full-time.
+
+Strict means three things, and each of them is the difference between an
+answer and a plausible wrong answer:
+
+1. **Full consumption.** `yyyy-MM-dd` does not read `2026-01-02T03:04`.
+2. **Impossible civil dates fail.** `31-02-2014` is `null`, not 3 March.
+3. **Fixed-width tokens are fixed width.** `MM` reads exactly two digits.
+
+Malformed *text* is data and comes back `null`; a malformed *pattern* is
+the programmer's error and throws at compile time. The tokens that only
+ever format — `EEEE`, `DDD`, `ww`, `Q` are derived *from* a date rather
+than fields *of* one — throw with a message naming the token and the
+reason, rather than reading nothing in silence. Two tokens are
+documented rather than refused: `yy` reads 00–68 as 2000–2068 and 69–99
+as 1969–1999 (the POSIX pivot), and `h`/`hh` with no `a` in the same
+pattern read as the morning.
+
+A consumer whose patterns are **not** LDML adapts its own tokens onto
+this vocabulary rather than handing its spelling over. `@jarenjs/mermaid`
+does exactly that for a Gantt's `dateFormat` (moment's grammar) and
+`axisFormat` (strftime): LDML's `YYYY` is the *week-numbering* year, so
+reading `YYYY-MM-DD` as LDML answers 2019 for 2018-12-31.
 
 ## Not here
 
@@ -72,7 +146,9 @@ byte-stable across Node/ICU versions.
 Node ≥ 24 baseline); the string/number representation is exactly what
 `Temporal.Instant.from()` consumes, so the kernel can delegate
 internally later without a surface change. Relative-time phrasing and
-month-name catalogs are `@jarenjs/locales`' job; `formatMinimum`/
+month-name catalogs are `@jarenjs/locales`' job — including the decision
+that a relative phrase is handed its signed amount rather than working
+one out, which is the same "no `now`" rule this kernel keeps; `formatMinimum`/
 `formatMaximum` bound comparison lives in `@jarenjs/formats`; time
 *axes* (charts) and date *controls* (forms) consume this kernel from
 their own packages.

package/docs/SERIES.md

@@ -0,0 +1,342 @@
+# `@jarenjs/core/series`
+
+The temporal kernel: one meaning for an instant, one meaning for an
+interval, and the set algebra over them. A roster, a calendar, an event
+log, an availability view and a telemetry graph each rebuild the same
+loops today — "does this overlap", "where is the free time", "what is
+covered", "which events are live right now" — and this is the module
+that answers them once.
+
+Two constraints shape it, the same two the calendar kernel is built on.
+**There is no type**: an instant is epoch milliseconds or an RFC 3339
+string, a sample is `{ at, value }`, an interval is `{ start, end }` —
+all of them JSON already, so they survive a patch, a schema, a pointer,
+a stored document and a wire reply unchanged. And **there is no `now`**:
+every bound is data, and an operation that needs a window and was given
+none derives it from its own input, never from the clock. Import the
+barrel (`@jarenjs/core/series`) or a single module.
+
+**Every specification is closed.** `resampleSeries`, `rollingSeries`,
+`asOfJoin`, `downsampleSeries`, `findSlots` and `mergeIntervals` each
+publish the members they admit — `RESAMPLE_MEMBERS`, `ROLLING_MEMBERS`,
+`ASOF_MEMBERS`, `DOWNSAMPLE_MEMBERS`, `SLOTS_MEMBERS`, `MERGE_MEMBERS`
+— and anything else is a `TypeError` naming the near miss. `minPeriod`
+for `minPeriods` accepted and ignored is a window with no minimum and a
+plausible number; `timezone` for `zone` is the quiet fall back to UTC
+that the clock's own refusal exists to prevent. The query language
+reads these same lists (§8.16), minus `provider`, which is a pair of
+functions and therefore not something a document can carry.
+
+## Normalization — `normalize.js`
+
+`toEpoch(value)` is the one door: a finite number passes through, a
+valid RFC 3339 string becomes the instant it names. A full-date reads as
+UTC midnight. Three things are `TypeError` rather than a guess — a
+full-time (`'09:30:00Z'` names no day), an offset-less date-time
+(`'2026-01-01T09:30:00'` names no instant without a zone, and there is
+no implicit machine zone here), and a `Date` object.
+
+`normalizeSeries(rows, {at, value}?)` and
+`normalizeIntervals(rows, {start, end}?)` convert a whole collection
+once and sort it. Both take a **selector** per member — a property name
+or a function — so rows spelled `on`, `recorded_at` or `from`/`to` are
+read where they are rather than rewritten first. Each result is a
+shallow copy of its source row with the canonical members written over
+it, so nothing a caller attached is lost.
+
+Three rules make the result safe to build on:
+
+- **A row is never dropped.** A member that cannot become a finite
+  instant is a refusal naming the row (`row 4172, at: …`), not a
+  silently shorter answer.
+- **The sort is stable.** Rows sharing an instant come out in input
+  order, and *all* of them are present: a duplicate instant is two
+  readings in the same millisecond, not a key collision.
+- **A value may be absent, but only explicitly.** `null` is a measured
+  gap and survives; `undefined`, a string or a `NaN` is a defect.
+
+`lowerBoundTime(rows, at, key?)` and `upperBoundTime(rows, at, key?)`
+are the binary cuts a normalized array is then read through — together
+they bracket the rows *at* an instant, which is what a duplicate-tolerant
+as-of has to read.
+
+## Interval algebra — `interval.js`
+
+Every interval is **half-open**, `[start, end)`: it holds its start and
+not its end. So a day ends exactly where the next begins, nothing is
+counted twice at a boundary, and two intervals that touch do **not**
+overlap — back-to-back bookings are not a double booking. An interval
+that is empty (`[t, t)`), reversed or not finite is refused at the point
+it was written.
+
+| Function | Answers |
+|---|---|
+| `containsInstant(interval, at)` | is this instant inside — `start <= at < end` |
+| `overlapsInterval(a, b)` | do they share an instant (touching does not) |
+| `intersectInterval(a, b)` | the span they share, or `null` |
+| `mergeIntervals(list, {adjacent}?)` | the union, as the fewest disjoint spans |
+| `subtractIntervals(from, remove)` | the set difference; a cut through the middle splits |
+| `gapsWithin(list, window?)` | the uncovered spans |
+| `coverageOf(list, window?)` | milliseconds covered, an instant counted once |
+| `findSlots(availability, spec)` | where a fixed-width span fits |
+
+Merging is the one place "touching does not overlap" is not the answer
+a caller wants, which is why `mergeIntervals` **joins touching spans by
+default**: availability asks whether there is continuous cover, and
+09:00–13:00 plus 13:00–17:00 is continuous cover. The other reading is
+real too — a handover is two shifts, not one — and it is spelled
+`{ adjacent: false }`, so nothing has to guess. Overlapping spans join
+under both settings.
+
+`gapsWithin` and `coverageOf` take an optional window. Without one they
+work inside the hull of the intervals themselves, because the only other
+default would be a clock. Passing the window explicitly is what reports a
+missing *edge*: an empty morning is only a gap once the caller says the
+day starts at nine. `coverageOf` returns milliseconds, so the ratio is
+the caller's own division:
+`coverageOf(shifts, day) / (day.end - day.start)`.
+
+`findSlots(availability, { duration, step? })` merges availability, then
+walks each window from its own start in `step` increments (default: back
+to back), keeping every span that still ends inside. `duration` and
+`step` are fixed widths — milliseconds, or a fixed ISO 8601 duration
+(`'PT30M'`); a calendar duration (`P1M`) is refused rather than called
+thirty days. It is enumeration, not scheduling: choosing among the
+answers, weighing preferences and assigning people is a solver's job,
+deliberately not this one.
+
+Merge, subtract, gaps and slots return bare `{ start, end }` records. A
+span welded out of three source rows belongs to none of them, and
+carrying one of their identities forward would be a claim the data does
+not support.
+
+## The index — `interval-index.js`
+
+`createIntervalIndex(items, selectors?)` builds once and answers many:
+`index.at(instant)` for the spans holding an instant,
+`index.overlapping(start, end)` for the spans sharing one with a window.
+Results are the caller's **own rows**, ascending by start and — for rows
+sharing a start — in the order they arrived, in a fresh array each time.
+
+Sorting by start is not enough, and the reason is the whole design. A
+binary search finds where a query falls among the starts, but a span that
+began a year earlier and has not ended yet sits far to the *left* of that
+neighbourhood and still overlaps — a conference week among hourly
+meetings is exactly that span, and an index that merely cuts around the
+query loses it while looking plausible. So the index carries a second
+array: the prefix maximum end, non-decreasing by construction and
+therefore binary-searchable too. The first position where it passes the
+query's start is the first position where anything can still be live.
+
+A query is two binary cuts and a walk between them — O(log n + k) — with
+no pass over the array and no per-query sort. It is **static**: the
+bounds are copied into flat typed arrays at build time, so a query reads
+no source object at all, and a row mutated afterwards cannot change what
+the index answers.
+
+```javascript
+import { createIntervalIndex, mergeIntervals, gapsWithin, findSlots } from '@jarenjs/core/series';
+
+const shifts = [
+  { from: '2026-03-02T09:00:00Z', to: '2026-03-02T13:00:00Z', who: 'ada' },
+  { from: '2026-03-02T13:00:00Z', to: '2026-03-02T17:00:00Z', who: 'grace' },
+];
+const index = createIntervalIndex(shifts, { start: 'from', end: 'to' });
+index.at('2026-03-02T13:00:00Z');        // [grace] — half-open: the handover belongs to one shift
+
+const cover = shifts.map((s) => ({ start: s.from, end: s.to }));
+mergeIntervals(cover);                    // one span, 09:00–17:00: touching is continuous cover
+gapsWithin(cover, { start: '2026-03-02T08:00:00Z', end: '2026-03-02T18:00:00Z' });
+                                          // the hour before and the hour after
+findSlots(cover, { duration: 'PT30M' });  // sixteen half-hour slots, one straddling the handover
+```
+
+## The clock — `zone.js`
+
+Where a calendar boundary falls depends on a wall clock, and a wall
+clock that is not UTC is data this suite refuses to bundle: a tzdb is
+megabytes that go stale on a government's timetable, a Temporal
+polyfill is a runtime dependency, and reading the host's zone is the
+hidden clock this kernel exists without. So `resolveClock(options)` is a
+**seam**:
+
+| options | the clock |
+|---|---|
+| *(nothing)* | UTC. Nothing to configure, and no local time is ever ambiguous |
+| `{ offset: -300 }` | minutes east of UTC, constant. Exact integer arithmetic |
+| `{ zone, provider }` | the caller's tzdb, in whatever form they already have one |
+
+A provider answers two questions, and the second is the hard one:
+`toParts(epoch, zone)` is the wall clock at an instant, and
+`toEpoch(parts, zone, disambiguation)` is the instant at a wall clock —
+hard because a local time is not a function of the clock. On a
+spring-forward day 02:30 never happens; on a fall-back day it happens
+twice. `disambiguation` is `'reject'` (the default: an error, not an
+hour nobody notices), `'earlier'` or `'later'`. Asking for a named zone
+with no provider is a refusal, never a quiet fall back to UTC — which is
+right for Amsterdam for none of the year and *looks* right for eight
+months of it.
+
+## Buckets, resampling and fill — `bucket.js`
+
+Two questions that are always asked together and are not the same
+question. **Bucketing** is "which span does this instant fall in", and
+it is arithmetic. **Filling** is "what does a span with no readings
+say", and it is a policy. An average over an empty hour is not zero, and
+it is not yesterday's average, and it is not nothing.
+
+`compileBuckets(spec, options?)` validates a ladder once —
+`compileBuckets('PT15M')`, or `{ every, origin }` — and returns
+`floor`, `startOf`, `indexOf` and the shape it resolved to. Boundaries
+come in two flavours, and the difference is physical:
+
+- **fixed** — `PT15M`, `PT1H`, `P1D`, or a number of milliseconds. The
+  boundary is `origin + k × width`, integer arithmetic all the way down,
+  and it *floors*, so an instant before 1970 lands in its own bucket
+  rather than the one after it.
+- **calendar** — `P1M`, `P1Y`, and a whole number of days *on a named
+  zone*. A month has no width, so the boundary is walked by the calendar
+  kernel from the anchor; on a named zone a day that the clock changed
+  on is 23 or 25 hours long, and a ladder multiplying by 86,400,000
+  would drift off local midnight for the rest of the year.
+
+A width that mixes the two families (`P1MT1H`) is refused: a month and
+an hour share no boundary. The default `origin` is local
+`1970-01-01T00:00:00` **on the clock**, so a daily bucket in `+02:00`
+falls on local midnight rather than on UTC's.
+
+`resampleSeries(rows, spec)` returns ascending `{ at, value, count }`
+labelled at each bucket's **start**. `count` is the number of source
+rows — duplicates and measured gaps included — so it is the honest
+denominator of what was *seen*. All six value aggregates (`sum`, `mean`,
+`min`, `max`, `first`, `last`) skip `null` readings, so `value` is
+`null` exactly when there was nothing to measure and `count` says
+whether that was because nobody reported or because everybody reported a
+gap. `aggregate: 'count'` returns that row count as the value.
+
+With no `start`/`end` the window is the data's own — the bucket holding
+the first sample through the bucket holding the last — because the only
+other default would be a clock. Pass them when an empty *edge* matters.
+
+The five fill policies decide what an **empty** bucket says, and nothing
+else; a bucket that held rows and no numbers reports `null`, because
+that is a measurement:
+
+| fill | an empty bucket |
+|---|---|
+| `omit` | is not emitted — the default: a gap is not a row |
+| `null` | is emitted as `null` |
+| `zero` | is emitted as `0` |
+| `locf` | repeats the last value before it |
+| `linear` | is interpolated between its two neighbours |
+
+Neither `locf` nor `linear` invents a value at the leading edge, and
+`linear` needs a value on **both** sides. To seed one, widen the window
+until the earlier reading falls inside it: the seed is then a bucket
+with data, which is the only anchor either policy will extrapolate from.
+
+## Rolling windows — `rolling.js`
+
+`rollingSeries(rows, spec)` aggregates over a *duration* rather than a
+count of rows, which is the whole point: sixty rows of a sensor
+reporting every second is a minute, and sixty rows of a sensor that
+dropped half its readings is two minutes. One of those is a
+specification.
+
+The window is `(at − width, at]` — exactly `width` wide, holding the
+current instant and not the one a full width behind it. Two samples at
+one instant share that window and therefore share an answer: a span of
+time is a function of the instant it ends at, not of which simultaneous
+reading arrived first. `minPeriods` is how many source rows the window
+must hold before a value is reported at all.
+
+The complexity is per aggregate and is structural rather than hopeful:
+`sum`/`mean`/`count` carry a running total, `min`/`max` use a monotone
+deque, and `first`/`last` are two pointers that only move forward. A
+carried total is not a fresh sum in the last bits when the values are
+not exactly representable — that is what carrying one costs, and the
+suite's corpora use exact binary fractions so the difference is zero and
+equality is the check.
+
+## As-of joins — `asof.js`
+
+`asOfJoin(left, right, spec?)` answers "what was the price when this
+trade printed" for two series that share a timeline and nothing else.
+One record per left row, in the left series' order, unmatched included
+as `{ left, right: null, distance: null }` — a join that quietly returns
+fewer rows than it was given is how a report loses the events nothing
+explained.
+
+| direction | the right row chosen |
+|---|---|
+| `backward` | the last one at or before the left instant (default) |
+| `forward` | the last one at or after it |
+| `nearest` | whichever is closer; a tie chooses `backward` |
+
+At an equal instant the **last** right-side row wins in every direction,
+because duplicates are two readings and "as of" means the later one. A
+`nearest` tie chooses backward because a value already observed is
+evidence and one that has not been is a forecast. `tolerance` is the
+furthest a match may be; beyond it there is no match, not a distant one.
+`key` joins within groups — the right side is partitioned **once**, and
+no left row ever filters it.
+
+## Downsampling — `downsample.js`
+
+A hundred thousand points on a line eight hundred pixels wide is a
+hundred and twenty five points per pixel. `downsampleSeries(rows, spec)`
+supplies `lttb` (largest-triangle-three-buckets: keeps the shape a
+reader recognizes) and `minmax` (keeps the envelope exactly), and
+reports `{ points, sourceCount, renderedCount, method }` so a consumer
+can always say how much of the data it is looking at.
+
+Three rules stop either from lying. **A gap is never bridged** — the
+series is cut at every run of `null`s, each run keeps a marker, and each
+segment is sampled on its own budget. **The ends stay** — and a series
+ending in gaps keeps its last instant as that run's marker, so the
+rendered domain still reaches the end of the data. **An impossible
+target is refused** — those markers and endpoints are the minimum a
+faithful picture needs, and a prettier lie is worse than a `RangeError`
+naming the number.
+
+```javascript
+import { resampleSeries, rollingSeries, asOfJoin, downsampleSeries } from '@jarenjs/core/series';
+
+resampleSeries(readings, { every: 'PT1H', aggregate: 'mean', fill: 'linear' });
+resampleSeries(readings, { every: 'P1M', zone: 'Europe/Amsterdam', provider });
+rollingSeries(readings, { width: 'PT5M', aggregate: 'max', minPeriods: 3 });
+asOfJoin(trades, quotes, { direction: 'nearest', tolerance: 'PT1S', key: 'symbol' });
+downsampleSeries(readings, { target: 2000 });   // → { points, sourceCount, renderedCount, method }
+```
+
+## What it costs
+
+Measured by `benchmark/series.js` over <!--bm:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/bm-->,
+which gates every timing on equivalence first: no number below is printed
+unless the kernel answered the identical rows the references did.
+
+The kernel is not the ceiling and does not claim to be. A one-pass loop
+written for one question validates nothing, normalizes nothing and
+returns a bare pair. Against those loops the kernel costs <!--bm:series.kernelVsCeiling-->3.4× the one-pass bucket loop and 6.2× the one-pass ring sum<!--/bm-->,
+and against the vocabulary a consumer had instead it is <!--bm:series.kernelVsQuery-->73.6× faster than the generic query bucket and 81.2× faster than the labelled count window<!--/bm-->.
+
+<!--bm:series.kernelTable-->
+| operation | median | rows | against | what that is | ratio |
+|---|---:|---:|---:|---|---:|
+| `resampleSeries`, 60 s buckets | 1.5 ms | 1,667 | 0.45 ms | one-pass loop | 3.4× |
+| `resampleSeries`, + linear fill | 1.1 ms | 1,657 | 1 ms | the same buckets, omitting | 1.0× |
+| `rollingSeries`, 60 s window | 7.2 ms | 100,000 | 1.2 ms | one-pass ring sum | 6.2× |
+| `asOfJoin`, one left row per 100 | 1.7 ms | 1,000 | 2.2 ms | one index read per row | 0.8× |
+| `downsampleSeries`, lttb, gap corpus | 1.6 ms | 2,000 | 1.8 ms | the same line with no holes in it | 0.9× |
+<!--/bm-->
+
+A row that loses stays in, and the two shapes of the same join are published side by side rather than the flattering one alone. <!--bm:series.asofShape-->The as-of join costs 14.7× a handful of index reads, and beats them by 1.3× once there is one left row per hundred right ones. The reason is the shape rather than the engine: a b-tree pays per probe, and a sorted walk pays for the whole right side whether it was asked one question or a thousand.<!--/bm-->
+
+And the seam has a price that this corpus cannot charge it. <!--bm:series.zoneCost-->Walking every boundary through an injected zone provider costs 1.0× the integer ladder over an identical answer — near parity because it is near nothing, since the benchmark corpus spans 28 hours and holds two daily boundaries. What the suite gates instead is that the provider is consulted per boundary rather than per sample.<!--/bm-->
+
+## Not here
+
+Named time zones are injected, never bundled; recurrence grammars
+(RRULE, iCalendar) and any kind of scheduling solver are somebody else's
+layer. This module supplies the algebra those are built from, and
+nothing that needs a clock, a locale or a zone database to be correct.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -112,6 +112,14 @@
       "types": "./dist/types/schema.d.ts",
       "default": "./src/schema.js"
     },
+    "./series": {
+      "types": "./dist/types/series/index.d.ts",
+      "default": "./src/series/index.js"
+    },
+    "./series/*": {
+      "types": "./dist/types/series/*.d.ts",
+      "default": "./src/series/*.js"
+    },
     "./string": {
       "types": "./dist/types/string.d.ts",
       "default": "./src/string.js"