@jarenjs/core 0.46.4 → 0.49.2

package/ARCHITECTURE.md

@@ -109,7 +109,9 @@ flowchart TB
             DatesRfc["rfc3339.js<br/>RFC 3339 / ISO 8601"]
             DatesCivil["civil.js<br/>Gregorian day-number math"]
             DatesFormat["format.js<br/>LDML pattern compiler"]
+            DatesParse["parse.js<br/>LDML pattern parser"]
             DatesDuration["duration.js<br/>ISO 8601 durations"]
+            DatesTicks["ticks.js<br/>Time-axis step ladder"]
         end
 
         subgraph GeoModule["Spatial"]
@@ -130,6 +132,14 @@ flowchart TB
             VectorIndex["vector/index.js<br/>Similarity kernels, normalization, packed form"]
         end
 
+        subgraph SeriesModule["Temporal"]
+            SeriesIndex["series/index.js"]
+            SeriesSelector["selector.js<br/>Where a member lives in a row"]
+            SeriesNormalize["normalize.js<br/>Instants, stable sort, binary bounds"]
+            SeriesInterval["interval.js<br/>Half-open set algebra"]
+            SeriesTree["interval-index.js<br/>Prefix-max-end interval index"]
+        end
+
         subgraph MathModules["Mathematics"]
             MathIndex["math/index.js"]
             Int32Math["int32.js<br/>Fixed-point math"]
@@ -191,6 +201,7 @@ flowchart TB
     DatesIndex --> DatesCivil
     DatesIndex --> DatesFormat
     DatesIndex --> DatesDuration
+    DatesIndex --> DatesTicks
 
     GeoIndex --> GeoPred
     GeoIndex --> GeoDist
@@ -462,7 +473,9 @@ intermediate and is plain data, never an opaque handle.
 | `rfc3339.js` | validation, lexical decomposition, epoch conversion |
 | `civil.js` | proleptic Gregorian arithmetic over integers |
 | `format.js` | LDML pattern → compiled formatter |
+| `parse.js` | LDML pattern → compiled strict parser (the formatter's inverse) |
 | `duration.js` | ISO 8601 duration decomposition and date arithmetic |
+| `ticks.js` | the time-axis step ladder and its calendar boundaries |
 
 Calendar math goes through day numbers (`daysFromCivil`/`civilFromDays`),
 never through `Date`: the conversions are ~10 integer operations and allocate
@@ -475,6 +488,23 @@ allocates nothing per value. Formatting is the two-stage compiler again — a
 pattern is scanned once into a chain of appenders, which measured ~4.5×
 against re-scanning it per call.
 
+Parsing is the same compiler run backwards. `compileDateParser` scans a
+pattern once into a chain of readers and returns a function from text to the
+same parts record `parseRFC3339Parts` produces, so every calendar function
+takes its output unchanged. It is strict in three ways that a permissive
+reader is not: trailing input fails, an impossible civil date (31 February,
+hour 24) fails rather than rolling forward into the next month, and a
+fixed-width token reads exactly its width. Failure is `null` — malformed
+*text* is data — while a malformed *pattern* throws at compile time. The
+tokens that only ever format, because they are derived from a date rather
+than fields of one (`EEEE`, `DDD`, `ww`, `Q`), are compile errors with a
+message saying which and why, rather than tokens that quietly read nothing.
+A consumer whose patterns are not LDML — Mermaid's Gantt `dateFormat` is
+moment's grammar and its `axisFormat` is strftime — adapts its own tokens
+onto this vocabulary rather than handing its spelling to this compiler:
+LDML's `YYYY` is the week-numbering year, so `YYYY-MM-DD` read as LDML
+answers 2019 for 2018-12-31.
+
 Locale-dependent presentation (month and weekday names, meridiem, relative
 phrasing) is deliberately **not** here, so this package stays zero-dependency
 and free of data that drifts per language: `compileDateFormat` takes a names
@@ -532,11 +562,31 @@ import {
 const parts = parseRFC3339Parts('2026-01-31');
 addToParts(parts, 1, 'month');          // 2026-02-28 — month math clamps
 startOfParts(parts, 'week');            // the Monday of that week (ISO 8601)
+addToParts(parts, 3, 'hour');           // TypeError — a full-date has no clock
 
 const fmt = compileDateFormat("yyyy-'W'ww");  // compile once…
 fmt(parts);                             // …call many: '2026-W05'
+
+const read = compileDateParser('dd-MM-yyyy');
+read('06-01-2014');                     // { year: 2014, month: 1, day: 6, … }
+read('06-01-2014x');                    // null — trailing input
+read('31-02-2014');                     // null — February has no 31st
+```
+
+**Ticks a caller chose, or ticks this module chose:**
+
+```javascript
+import { axisTicksTime, timeTicksEvery } from '@jarenjs/core/dates';
+
+axisTicksTime(from, to, 4);                  // the ladder picks the step
+timeTicksEvery(from, to, 'week', 1, { weekStart: 7 });  // Sundays
 ```
 
+`axisTicksTime` is the chart axis's planner; `timeTicksEvery` is the same
+boundary rule with the step supplied, which is what a document declaring its
+own interval (Mermaid's `tickInterval 1week`) needs. One ladder, so a chart
+and a timeline cannot disagree about where a tick falls.
+
 ### 5b. Geo Module (`geo/`)
 
 The spatial kernel. As with dates, **there is no geometry type**: the
@@ -721,6 +771,60 @@ their reason to exist; they guarantee a finite answer. The fixed-arity vector
 classes in `math/` (`Vec2f64`, `Vec3f64`) are 2D/3D geometry with a
 different convention and a different job, and they stay where they are.
 
+### 5d. Series Module (`series/`)
+
+The temporal kernel: one meaning for an instant, one for a sorted series of
+readings, one for an interval, and the set algebra over them. As with dates,
+**there is no type** — an instant is epoch milliseconds or an RFC 3339 string,
+a sample is `{ at, value }`, an interval is `{ start, end }` — and, as with
+dates, **there is no `now`**: every bound is data, so every answer here is
+reproducible and cacheable.
+
+| File | Owns |
+|---|---|
+| `selector.js` | where a member lives in a caller's row — a property name or a function, so `on`/`recorded_at`/`from`/`to` are read where they are |
+| `normalize.js` | `toEpoch`, `normalizeSeries`, `normalizeIntervals` and the `lowerBoundTime`/`upperBoundTime` cuts a sorted array is read through |
+| `interval.js` | `containsInstant`, `overlapsInterval`, `intersectInterval`, `mergeIntervals`, `subtractIntervals`, `gapsWithin`, `coverageOf`, `findSlots` |
+| `interval-index.js` | `createIntervalIndex` — build once, query many, by point or by range |
+
+Four decisions carry it. **Half-open `[start, end)`**: an interval holds its
+start and not its end, so touching intervals neither overlap nor double-count
+and a boundary instant belongs to exactly one of them — while `mergeIntervals`
+*joins* touching spans by default, because availability means continuous cover,
+with `{ adjacent: false }` as the explicit other answer. **Nothing is dropped**:
+a member that names no instant, or an interval that is empty, reversed or
+non-finite, is a refusal naming the row rather than a silently shorter result,
+and the sort is stable so duplicate instants keep their order and both count.
+**No clock**: `gapsWithin` and `coverageOf` derive their window from the input's
+own hull when given none, because the only other default would be "now".
+
+And **the index cuts on both ends**. Sorting by start alone is the bug: a span
+that began long before a query sits far to the left of the query's own
+neighbourhood and still overlaps it, so a binary search around the query loses
+it while looking plausible. `createIntervalIndex` therefore carries a prefix
+maximum end beside the starts — non-decreasing by construction, hence
+binary-searchable — and 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), returning the caller's own rows in a
+fresh array. Like the packed-Hilbert box index it is **static**: bounds are
+copied into flat typed arrays at build time, so a query reads no source object
+and a row mutated afterwards cannot change what the index answers.
+
+Buckets, resampling, rolling windows and as-of joins are the layer above this
+one; named zones, recurrence grammars and scheduling solvers are outside it.
+`findSlots` enumerates where a fixed-width span fits — choosing among the
+answers is a solver's job, deliberately not this kernel's.
+
+```javascript
+import { createIntervalIndex, mergeIntervals, findSlots } from '@jarenjs/core/series';
+
+const shifts = [{ start: 0, end: 4 * 3600_000 }, { start: 4 * 3600_000, end: 8 * 3600_000 }];
+mergeIntervals(shifts);                         // one span — touching IS continuous cover
+mergeIntervals(shifts, { adjacent: false });    // two — a handover is two shifts
+findSlots(shifts, { duration: 'PT30M' }).length; // 16
+createIntervalIndex(shifts).at(4 * 3600_000);   // the second shift only: [start, end)
+```
+
 ### 6. Text Module (`text/`)
 
 Comprehensive string format validation organized by domain.

package/README.md

@@ -1,6 +1,6 @@
 # @jarenjs/core
 
-The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the vector kernel, the message-catalog compiler, unit/currency conversion and a finance library.
+The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the vector kernel, the interval kernel, the message-catalog compiler, unit/currency conversion and a finance library.
 
 None of it depends on JSON Schema: every module can be used standalone in any JavaScript project.
 
@@ -24,6 +24,7 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/dates` | RFC 3339 / ISO 8601 validation, plus the calendar kernel: integer date arithmetic, compiled formatting, durations |
 | `@jarenjs/core/geo` | the spatial kernel over GeoJSON: robust orientation, great-circle measurement, rings, bounding boxes, geohash, GeoJSON/WKT validity, a packed-Hilbert box index, Web Mercator and Douglas-Peucker simplification |
 | `@jarenjs/core/vector` | the vector kernel over plain arrays: dot, cosine and Euclidean similarity (higher-is-better; a malformed pair scores 0), l2 normalization, the packed little-endian Float32 form and the one shape guard (`isVector`) |
+| `@jarenjs/core/series` | the temporal kernel over plain records: instant/sample/interval normalization with a stable sort, half-open `[start, end)` set algebra (overlap, merge, subtract, gaps, coverage, slot enumeration), a static interval index, and the series operations built on them — fixed and calendar buckets with five fill policies, time-width rolling aggregates, as-of joins and gap-aware downsampling, on an injected zone seam |
 | `@jarenjs/core/text` | text validators: emails, hostnames, IPs, URIs/IRIs, UUIDs, punycode, ... |
 | `@jarenjs/core/math` | int32/float64 math and 2D/3D vector classes; the linear `remap` and unit-interval `clamp01` |
 | `@jarenjs/core/finance` | zero-dependency finance/trading formulas: TVM, cash flow, amortization, interest, depreciation, bonds, technical indicators, returns/risk |
@@ -65,7 +66,7 @@ Grouped by file: `email` (RFC 5321 + internationalized addresses), `host` (hostn
 
 ## Dates, numbers and math
 
-- `dates` — RFC 3339 date/time/date-time validation and parsing (leap years and month lengths included), the more lenient ISO date-time forms, and the suite's calendar kernel: proleptic Gregorian arithmetic over integer day numbers (`addToParts`, `startOfParts`, `endOfParts` — month math clamps, so 31 Jan plus a month is 28 Feb), ISO 8601 duration decomposition, and `compileDateFormat`, which turns an LDML pattern into a formatter once instead of re-scanning it per call. Dates stay JSON: an RFC 3339 string or epoch milliseconds, never a wrapper object. Locale names live in `@jarenjs/locales`, so a pattern needing `MMMM` takes a names provider. The full module reference is [docs/DATES.md](./docs/DATES.md).
+- `dates` — RFC 3339 date/time/date-time validation and parsing (leap years and month lengths included), the more lenient ISO date-time forms, and the suite's calendar kernel: proleptic Gregorian arithmetic over integer day numbers (`addToParts`, `startOfParts`, `endOfParts` — month math clamps, so 31 Jan plus a month is 28 Feb, and an operation reading a half the value has not got is refused rather than guessed), ISO 8601 duration decomposition, the locale-free time-axis step ladder (`niceTimeStep`, `axisTicksTime`, and `timeTicksEvery` for a step the caller declares) a chart and a timeline both read, and the two-stage pattern compilers `compileDateFormat` and its strict inverse `compileDateParser`, which turn an LDML pattern into a formatter or a parser once instead of re-scanning it per call — the parser refuses trailing input, an impossible civil date, and the tokens that only format because they are derived from a date rather than fields of one. Dates stay JSON: an RFC 3339 string or epoch milliseconds, never a wrapper object. Locale names live in `@jarenjs/locales`, so a pattern needing `MMMM` takes a names provider. The full module reference is [docs/DATES.md](./docs/DATES.md); the interval algebra built on top of it is [`series`](#intervals-and-series).
 - `integer`/`float`/`bigint` — range constants and validators for every fixed-width type from `int8` to `uint64` and `float16` to `float64`, including float increment/decrement in representable steps.
 - `math` — asm.js-style typed math (`Int32`, `Float64`) and vector classes (`Vec2i32`, `Vec2f64`, `Vec3f64`) with a fast integer sine approximation; reference in [docs/MATH.md](./docs/MATH.md).
 
@@ -123,6 +124,49 @@ Three rules, kept by every function so that no caller has to check them again:
 
 The packed form is `4·d` bytes of little-endian binary32 — the value a database column stores; components round to `Math.fround` and come back exactly. Unpacking aligned bytes on a little-endian host is a *view*, not a copy, which is what a sweep over ten thousand fetched rows is paid for by; misaligned bytes (a pooled `Buffer`, an odd offset into a record) and big-endian hosts take the copy path to the same values. The client that produces embeddings — and a deterministic reference embedder for tests — lives in [`@jarenjs/ai`](../ai/README.md#embeddings).
 
+## Intervals and series
+
+`@jarenjs/core/series` is the suite's temporal kernel: one meaning for an interval, one meaning for a sorted series of timestamped readings, the set algebra over them, and the five operations every consumer of a timeline otherwise rebuilds by hand — bucket, fill, roll, join as-of, downsample. As with dates, there is no type — an instant is epoch milliseconds or an RFC 3339 string, a sample is `{ at, value }`, an interval is `{ start, end }` — so every value stays a plain JSON item, and nothing here reads a clock.
+
+```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, so 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
+findSlots(cover, { duration: 'PT30M' });  // sixteen half-hour slots, one straddling the handover
+```
+
+```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 }
+```
+
+Seven decisions carry the module:
+
+- **Half-open, everywhere.** `[start, end)` holds its start and not its end, so a day ends exactly where the next begins, a boundary instant belongs to exactly one of two touching intervals, and nothing is counted twice. Touching intervals therefore do *not* overlap — back-to-back bookings are not a double booking — while `mergeIntervals` joins them by default, because availability asks whether there is continuous cover. `{ adjacent: false }` is the other answer, spelled out rather than guessed.
+- **A row is never dropped, and a duplicate is never merged away.** A member that cannot become a finite instant is a refusal naming the row, not a silently shorter result; an empty (`[t, t)`), reversed or non-finite interval is refused at the point it was written. The sort is stable, so two readings in the same millisecond keep their input order and both count.
+- **Nothing reads a clock.** `gapsWithin` and `coverageOf` derive their window from the input's own hull when given none, because the only other default would be "now" — and an operation that read the clock could not be cached, reproduced or run in a test twice.
+- **The index cuts on both ends, and cannot lose a long span.** Sorting by start alone is the bug: a conference week that began before an hourly meeting sits far to the left of that meeting's neighbourhood and still overlaps it. `createIntervalIndex` carries a prefix maximum end beside the starts — non-decreasing, so binary-searchable — and a query becomes two binary cuts and a walk between them, O(log n + k), returning the caller's own rows. It is static: bounds are copied at build time, so a query reads no source object and a row mutated afterwards changes nothing.
+
+- **Bucketing is arithmetic; filling is a policy.** An average over an empty hour is not zero, and it is not yesterday's average, and it is not nothing — it is whichever of `omit | null | zero | locf | linear` the caller asked for, and the aggregate had no opinion. `count` reports source rows (duplicates and measured gaps included) beside every value, so `null` and "nobody reported" are distinguishable. Neither `locf` nor `linear` invents a value at the leading edge.
+- **A rolling window is a duration, not a row count.** Sixty rows of a sensor reporting every second is a minute; sixty rows of a sensor that dropped half its readings is two minutes. The window is `(at − width, at]`, so two readings in the same millisecond share it and therefore share an answer. `sum`/`mean`/`count` carry a running total, `min`/`max` use a monotone deque, `first`/`last` are forward-only pointers — the complexity is structural, and the tests count the reads rather than the milliseconds.
+- **Time zones are injected, never bundled.** UTC and fixed offsets work with no setup; a named zone takes the caller's own `provider`, because a bundled tzdb is megabytes that go stale on a government's timetable. A local time that never happened, or happened twice, is a refusal unless `disambiguation` says `earlier` or `later`. A sampler never bridges a gap, never moves an end, and refuses a target too small to hold both rather than drawing a prettier line.
+- **A specification is closed.** Every kernel that takes one publishes the members it admits, and anything else is a refusal naming the near miss — because `minPeriod` for `minPeriods` quietly ignored is a window with no minimum and a plausible number to show for it, and `timezone` for `zone` is precisely the silent fall back to UTC the injected clock exists to prevent. The query language reads the same lists, minus the `provider`, which is a pair of functions and therefore not something a document can carry.
+
+The kernel is measured against one-pass loops written for one question and against the query vocabulary a consumer had instead, and both ratios are published: it costs about twice a hand-written loop and answers about a hundred times faster than the generic route. Named time zones' data, recurrence grammars and scheduling solvers are deliberately outside it. The full module reference is [docs/SERIES.md](./docs/SERIES.md).
+
 ## Messages
 
 `@jarenjs/core/message` is the template/catalog compiler behind the validator's uniform error messages and the form layer's labels — msgid plus parameters in, rendered text out, so every message is translatable by swapping a catalog ([`@jarenjs/locales`](../locales) ships eleven language packs over it):

package/dist/types/dates/civil.d.ts

@@ -111,36 +111,55 @@ export declare function fixedUnitMs(unit: string): number;
 /**
  * Add a signed amount of calendar units to a parts record, returning a
  * new one. The input is never mutated and its lexical shape is kept: a
- * full-date stays a full-date, and a value keeps its own UTC offset
- * rather than being normalized.
+ * full-date stays a full-date, a full-time stays a full-time, and a
+ * value keeps its own UTC offset rather than being normalized.
  *
  * Month and year arithmetic **clamps** to the end of the target month —
  * 2026-01-31 plus one month is 2026-02-28 — which is the rule every
  * mainstream date library uses, because the alternative (overflowing
  * into March) makes `add(1, 'month')` non-monotonic.
  *
+ * A fraction is a quantity only where the unit has an exact conversion.
+ * A fixed-width fraction becomes whole milliseconds, so `1.5 day` is
+ * thirty-six hours; a calendar fraction is refused unless it lands on a
+ * whole month, because half of January is not a length. The clock those
+ * milliseconds land on has to exist: a full-date can be moved by whole
+ * days but not by half of one.
+ *
  * @param {object} parts - a parts record from `parseRFC3339Parts`
- * @param {number} amount - signed count, may be fractional only for
- *   fixed-width units (a fractional month has no meaning)
+ * @param {number} amount - signed count, fractional only where the unit
+ *   converts exactly and the value has the half to carry it
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, a fraction with no exact
+ *   conversion, or a value missing a half the operation reads
  */
 export declare function addToParts(parts: object, amount: number, unit: string): object;
 /**
  * Truncate a parts record to the start of a calendar unit, returning a
  * new one. `week` starts on Monday (ISO 8601).
+ *
+ * `day` and coarser name a boundary the calendar has, so the start of
+ * the day of a full-time is midnight. A sub-day unit names a boundary
+ * inside a day, which a value with no clock does not have, and is
+ * refused rather than answered from a clock that is not there.
+ *
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export declare function startOfParts(parts: object, unit: string): object;
 /**
  * The last representable instant inside a calendar unit: the start of
  * the next unit less one millisecond. A value with no time half is
  * truncated to the unit's last *day* instead, so a full-date stays a
- * full-date.
+ * full-date, and it refuses the same sub-day units `startOfParts` does.
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export declare function endOfParts(parts: object, unit: string): object;

package/dist/types/dates/index.d.ts

@@ -1,4 +1,6 @@
 export * from './rfc3339.js';
 export * from './civil.js';
 export * from './format.js';
+export * from './parse.js';
 export * from './duration.js';
+export * from './ticks.js';

package/dist/types/dates/parse.d.ts

@@ -0,0 +1,47 @@
+export type Reader = (text: string, i: number, out: any) => number;
+/**
+ * Compile an LDML date pattern into a strict parser.
+ *
+ * The returned function takes a string and returns a parts record in
+ * exactly the shape `parseRFC3339Parts` produces — so
+ * `epochOfRFC3339Parts`, `formatRFC3339Parts`, `addToParts` and every
+ * other calendar function accept it unchanged — or `null` when the text
+ * does not match. Failure is `null`, never a throw and never a partial
+ * record: a malformed *pattern* is the programmer's error and throws at
+ * compile time; malformed *text* is data and is reported as no match.
+ *
+ * Strict means three things:
+ *
+ * 1. **Full consumption.** Trailing text fails; `yyyy-MM-dd` does not
+ *    read `2026-01-02T03:04`.
+ * 2. **Impossible civil dates fail.** 31 February and hour 24 are not
+ *    silently rolled forward into March and the next day.
+ * 3. **Fixed-width tokens are fixed width.** `MM` reads exactly two
+ *    digits, `M` one or two, and neither reads three.
+ *
+ * The lexical family of the result follows the pattern: a pattern with
+ * only date tokens yields a full-date (`hours`/`minutes`/`seconds` are
+ * the contract's `-1`), one with only time tokens a full-time
+ * (`year`/`month`/`day` are `-1`), and one with both a date-time. A
+ * pattern with no field token at all is a compile error — it could only
+ * ever return the same empty record.
+ *
+ * Two tokens are not strict inverses of an arbitrary value and are
+ * documented rather than refused: `yy` reads 00–68 as 2000–2068 and
+ * 69–99 as 1969–1999 (the POSIX pivot moment uses), and `h`/`hh`
+ * without an `a` in the same pattern read as the morning, so 12 is
+ * midnight. Both round-trip their own spelling exactly.
+ *
+ * @param {string} pattern - an LDML pattern, e.g. `'yyyy-MM-dd'`
+ * @param {import('./format.js').DateNames} [names] - locale names, required only if the
+ *   pattern uses `MMM`/`MMMM`/`a`
+ * @returns {(text: string) => object | null} the compiled parser
+ * @throws {TypeError} on an unterminated quote, a derived token, a name
+ *   token with no provider, or a pattern that reads no field
+ * @example
+ * const read = compileDateParser('dd-MM-yyyy');
+ * read('06-01-2014');  // { year: 2014, month: 1, day: 6, hours: -1, … }
+ * read('06-01-2014x'); // null — trailing input
+ * read('31-02-2014');  // null — February has no 31st
+ */
+export declare function compileDateParser(pattern: string, names?: import('./format.js').DateNames): (text: string) => object | null;

package/dist/types/dates/ticks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Choose the calendar step closest to covering `span` in `count` ticks.
+ *
+ * A year is the coarsest unit a calendar has, so above one year the
+ * ladder continues as whole years on the same 1/2/5×10^k steps — 2, 5,
+ * 10, 50, 1000 years. Without that continuation a millennial domain
+ * asks for one tick per year and runs out of axis long before it runs
+ * out of domain.
+ *
+ * @param {number} span - Domain width in milliseconds
+ * @param {number} count - Desired tick count
+ * @returns {[string, number]} a [unit, amount] pair
+ */
+export declare function niceTimeStep(span: number, count: number): [string, number];
+/**
+ * Time ticks on calendar boundaries: the first tick is the start of a
+ * `[unit, amount]` step at or after `min`, and each following one is a
+ * whole step later. A multi-unit step lands on a multiple of its own
+ * amount — months on 1, 4, 7, 10 and years on 1900, 1950, 2000 — so an
+ * axis reads as a calendar rather than as offsets from wherever the
+ * data happened to start.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]} tick values in epoch milliseconds
+ */
+export declare function axisTicksTime(min: number, max: number, count?: number): number[];
+/**
+ * Time ticks on a step the CALLER chose, rather than one this module
+ * picked for a target count: the first tick is the start of the
+ * `amount`-wide `unit` at or after `min`, and each following one is a
+ * whole step later. This is the boundary rule {@link axisTicksTime}
+ * uses once it has decided a step, exposed on its own because a
+ * consumer whose document declares its own interval — Mermaid's Gantt
+ * `tickInterval 1week` is the one in this repo — needs the same
+ * boundaries without the ladder choosing for it.
+ *
+ * A multi-unit step lands on a multiple of its own amount, so months
+ * fall on 1, 4, 7, 10 and years on 1900, 1950, 2000. A `week` step
+ * starts on Monday unless `weekStart` names another ISO weekday, which
+ * is what a document that says "weeks begin on Sunday" means.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {string} unit - a `DATE_UNITS` member (`'day'`, `'week'`, …)
+ * @param {number} [amount] - whole steps per tick, at least 1
+ * @param {{ weekStart?: number, limit?: number }} [options] -
+ *   `weekStart` is an ISO weekday, 1 (Monday) to 7 (Sunday);
+ *   `limit` caps the tick count (default 1000)
+ * @returns {number[]} tick values in epoch milliseconds
+ * @example
+ * timeTicksEvery(Date.UTC(2024, 0, 3), Date.UTC(2024, 0, 20), 'week', 1);
+ * // the Mondays of 2024-01-08 and 2024-01-15
+ */
+export declare function timeTicksEvery(min: number, max: number, unit: string, amount?: number, options?: {
+    weekStart?: number;
+    limit?: number;
+}): number[];

package/dist/types/math/float64.d.ts

@@ -222,6 +222,19 @@ export declare function remap(v: number, smin: number, smax: number, dmin: numbe
  * @returns {number}
  */
 export declare function niceStep(span: number, count?: number): number;
+/**
+ * Ticks on the {@link niceStep} ladder inside `[min, max]`: every whole
+ * multiple of the step the domain contains, rounded to the step's own
+ * precision so an axis never shows `0.30000000000000004`. A degenerate
+ * domain yields a single tick, a reversed one reads the same as its
+ * forward twin, and a non-finite bound yields nothing.
+ *
+ * @param {number} min - Domain minimum
+ * @param {number} max - Domain maximum
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]}
+ */
+export declare function axisTicksLinear(min: number, max: number, count?: number): number[];
 /**
  * Clamp a value into the unit interval `[0, 1]` — the fraction every
  * unit-space geometry stage emits. `NaN` passes through as `NaN` rather

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

@@ -0,0 +1,88 @@
+export type Sample = import('./normalize.js').Sample;
+export type AsOfMatch = {
+    /**
+     * - the canonical left sample
+     */
+    left: any;
+    /**
+     * - the canonical right sample, or `null`
+     */
+    right: any | null;
+    /**
+     * - milliseconds between the two
+     * instants, never negative; `null` when there was no match
+     */
+    distance: number | null;
+};
+/**
+ * `asOfJoin`'s closed specification: which way to look, how far, what
+ * makes two rows comparable, and where each side keeps its members.
+ *
+ * This is the one series kernel whose spelling a query DOCUMENT cannot
+ * reuse: `left`/`right` are nested selector records, and §8.16 flattens
+ * them to `by`, `leftAt` and `rightAt` so the whole spec stays a
+ * literal. `@jarenjs/json` therefore keeps its own list, and says so.
+ */
+export declare const ASOF_MEMBERS: readonly string[];
+/**
+ * Join each left sample to the right sample that was current for it.
+ *
+ * The result is one record **per left row**, in the left series'
+ * normalized order — sorted by instant, with rows sharing an instant in
+ * the order they arrived. Both `left` and `right` are canonical samples:
+ * shallow copies carrying every member of the source row plus a numeric
+ * `at` and `value`, so a consumer reads `match.right.at` rather than
+ * parsing a timestamp a second time.
+ *
+ * | 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: duplicates are two readings in the same millisecond, and
+ * "as of" means the later one.
+ *
+ * `tolerance` is the furthest a match may be, in milliseconds or as a
+ * fixed duration. Beyond it there is no match — not a distant one.
+ *
+ * `key` joins within groups: a property name or a function, applied to
+ * both sides (or `left.key`/`right.key` when the two sides spell it
+ * differently). The right side is partitioned **once**; no left row ever
+ * filters it.
+ *
+ * @param {any[]} left
+ * @param {any[]} right
+ * @param {Object} [spec]
+ * @param {'backward'|'forward'|'nearest'} [spec.direction] default `'backward'`
+ * @param {number | string} [spec.tolerance] - the furthest a match may be
+ * @param {string | ((item: any, index: number) => any)} [spec.key] - the
+ *   group both sides join within
+ * @param {{ at?: any, value?: any, key?: any }} [spec.left] - where the
+ *   left side's members live
+ * @param {{ at?: any, value?: any, key?: any }} [spec.right] - where the
+ *   right side's members live
+ * @returns {AsOfMatch[]}
+ * @throws {TypeError} for an unknown direction, a tolerance that is not
+ *   a non-negative fixed width, or a row that is not a canonical sample
+ * @example
+ * asOfJoin(trades, quotes);                              // the last quote at or before
+ * asOfJoin(alarms, shifts, { direction: 'nearest', tolerance: 'PT1H' });
+ * asOfJoin(readings, calibrations, { key: 'sensor' });   // per sensor
+ */
+export declare function asOfJoin(left: any[], right: any[], spec?: {
+    direction?: 'backward' | 'forward' | 'nearest';
+    tolerance?: number | string;
+    key?: string | ((item: any, index: number) => any);
+    left?: {
+        at?: any;
+        value?: any;
+        key?: any;
+    };
+    right?: {
+        at?: any;
+        value?: any;
+        key?: any;
+    };
+}): AsOfMatch[];