@jarenjs/core 0.46.5 → 0.56.0

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 <!--fact:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/fact-->,
+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 <!--fact:series.kernelVsCeiling-->3.4× the one-pass bucket loop and 6.2× the one-pass ring sum<!--/fact-->,
+and against the vocabulary a consumer had instead it is <!--fact:series.kernelVsQuery-->73.6× faster than the generic query bucket and 81.2× faster than the labelled count window<!--/fact-->.
+
+<!--fact: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× |
+<!--/fact-->
+
+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. <!--fact: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.<!--/fact-->
+
+And the seam has a price that this corpus cannot charge it. <!--fact: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.<!--/fact-->
+
+## 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.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -40,6 +40,10 @@
       "types": "./dist/types/array.d.ts",
       "default": "./src/array.js"
     },
+    "./async": {
+      "types": "./dist/types/async.d.ts",
+      "default": "./src/async.js"
+    },
     "./bigint": {
       "types": "./dist/types/bigint.d.ts",
       "default": "./src/bigint.js"
@@ -104,6 +108,10 @@
       "types": "./dist/types/object.d.ts",
       "default": "./src/object.js"
     },
+    "./random": {
+      "types": "./dist/types/random.d.ts",
+      "default": "./src/random.js"
+    },
     "./scan": {
       "types": "./dist/types/scan.d.ts",
       "default": "./src/scan.js"
@@ -112,6 +120,18 @@
       "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"
+    },
+    "./stats": {
+      "types": "./dist/types/stats.d.ts",
+      "default": "./src/stats.js"
+    },
     "./string": {
       "types": "./dist/types/string.d.ts",
       "default": "./src/string.js"

package/src/async.js

@@ -0,0 +1,78 @@
+//@ts-check
+/**
+ * @file The bounded ordered asynchronous map: run a worker over a list
+ * with never more than `limit` calls in flight, and answer the results
+ * in the list's order. Before this file the same twelve lines lived in
+ * the AI package's program runner and in the benchmark harness, and a
+ * downstream consumer had written them a third time; a pool that exists
+ * once is one whose edge behavior can be pinned once.
+ *
+ * The contract, in full:
+ *
+ *  - results are in INPUT order, whatever order the workers finish in;
+ *  - never more than `limit` workers are in flight; `limit` must be a
+ *    number of at least 1 (`Infinity` is allowed and means unbounded) —
+ *    anything else is a `TypeError`, never a silent clamp, because a
+ *    limit of 0 is a bug in the caller and "sequential" is spelled 1;
+ *  - a worker rejection stops dispatch: no item starts after it, the
+ *    workers already in flight are awaited, and only then does the map
+ *    reject with that first rejection. A worker that throws
+ *    synchronously is a rejection;
+ *  - an abort does the same, rejecting with the signal's reason; a signal
+ *    that is already aborted rejects before any worker runs;
+ *  - so when the returned promise settles, NO worker is still running —
+ *    the caller can close whatever the workers were using.
+ *
+ * The map does not retry, rate-limit, delay per origin or know anything
+ * about what the worker does; those are the caller's policies around it.
+ */
+
+/**
+ * @template T, R
+ * @param {readonly T[]} items
+ * @param {number} limit - workers in flight at once; a number >= 1, `Infinity` for unbounded
+ * @param {(item: T, index: number) => Promise<R> | R} worker
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<R[]>} the results, in input order
+ * @throws {TypeError} (as a rejection) when `limit` is not a number >= 1
+ */
+export async function mapConcurrent(items, limit, worker, options = {}) {
+  if (typeof limit !== 'number' || !(limit >= 1))
+    throw new TypeError(`mapConcurrent needs a limit of at least 1, got ${String(limit)}`);
+  const { signal } = options;
+  if (signal?.aborted) throw signal.reason;
+  const count = items.length;
+  /** @type {R[]} */
+  const results = new Array(count);
+  if (count === 0) return results;
+
+  let next = 0;
+  // the first failure or abort, kept as a one-element list: the lanes
+  // stop dispatching the moment it is set and drain what they hold
+  /** @type {unknown[]} */
+  const stop = [];
+  /** @type {(() => void) | undefined} */
+  let onAbort;
+  if (signal !== undefined) {
+    onAbort = () => { if (stop.length === 0) stop.push(signal.reason); };
+    signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  const lane = async () => {
+    while (stop.length === 0) {
+      const index = next++;
+      if (index >= count) return;
+      try {
+        results[index] = await worker(items[index], index);
+      }
+      catch (error) {
+        if (stop.length === 0) stop.push(error);
+      }
+    }
+  };
+  const lanes = Array.from({ length: Math.min(limit, count) }, lane);
+  await Promise.all(lanes);
+  if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort);
+  if (stop.length > 0) throw stop[0];
+  return results;
+}