@jarenjs/core 0.49.2 → 0.56.0

package/ARCHITECTURE.md

@@ -161,6 +161,15 @@ flowchart TB
 
         subgraph FunctionModule["Function Utilities"]
             FunctionUtil["function.js<br/>trueThat, falseThat"]
+            AsyncUtil["async.js<br/>Bounded ordered asynchronous map"]
+        end
+
+        subgraph RandomModule["Randomness"]
+            RandomUtil["random.js<br/>Seeded generator, integer draw, shuffle, distinct draw"]
+        end
+
+        subgraph StatsModule["Statistics"]
+            StatsUtil["stats.js<br/>Mean, sample variance, median, named quantile"]
         end
 
         subgraph StringModules["String &amp; Scanning"]
@@ -628,9 +637,9 @@ direction is *not* claimed, because WKT whitespace, the `M` measure and number
 spelling are normalized on the way through.
 
 Against [`wellknown`](https://www.npmjs.com/package/wellknown), the established
-WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->):
+WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--fact:geo.node-->v24.19.0<!--/fact-->):
 
-<!--bm:geo.wktTable-->
+<!--fact:geo.wktTable-->
 | scenario | Jaren | rival | ratio |
 |---|---|---|---|
 | wkt parse (POINT) | 431.1 ns | 1.31 µs (wellknown) | **3.1×** |
@@ -638,7 +647,7 @@ WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.
 | wkt stringify (2000-vertex polygon) | 163.40 µs | 229.70 µs (wellknown) | **1.4×** |
 | wkt validate (POINT) | 242.7 ns | 1.28 µs (wellknown) | **5.3×** |
 | wkt validate (2000-vertex polygon) | 496.00 µs | 1.90 ms (wellknown) | **3.8×** |
-<!--/bm-->
+<!--/fact-->
 
 The last two rows are the ones the sink exists for: `wellknown` has no
 predicate, so validating means parsing and throwing the geometry away. And the
@@ -677,7 +686,7 @@ RFC 7946 removed coordinate-reference-system support and mandates WGS 84, so
 there is no SRID table and no reprojection: conformance removes the need rather
 than an omission hiding it.
 
-**Measured against the field** (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->). Every
+**Measured against the field** (`npm run benchmark:geo`, Node <!--fact:geo.node-->v24.19.0<!--/fact-->). Every
 scenario asserts result equivalence before any timing, and the harness refuses
 to print a table if the engines disagree: distance, area, length and bounding
 box come out *bit-identical* to Turf, containment agrees on a 400-point sweep,
@@ -685,7 +694,7 @@ and the index returns exactly Flatbush's answer on 200 queries. Ratios are the
 rival's time over this kernel's, so above 1 means Jaren is faster; the rows
 below derive from the committed measurement and are refreshed with it.
 
-<!--bm:geo.table-->
+<!--fact:geo.table-->
 | scenario | Jaren | rival | ratio |
 |---|---|---|---|
 | distance (two positions) | 28.3 ns | 111.0 ns (turf) | **3.9×** |
@@ -700,11 +709,11 @@ below derive from the committed measurement and are refreshed with it.
 | index build (100k boxes) | 12.70 ms | 10.62 ms (flatbush) | 0.8× |
 | index probe (100k boxes) | 602.3 ns | 668.9 ns (flatbush) | **1.1×** |
 | linear scan (100k boxes, no index) | 141.50 µs | — | — |
-<!--/bm-->
+<!--/fact-->
 
-The losses are kept, and named by the same measurement: on the committed run <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+The losses are kept, and named by the same measurement: on the committed run <!--fact:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/fact-->.
 **Point-in-polygon on a large ring runs at about half Turf's speed**
-(<!--bm:geo.pip2000-->0.5×<!--/bm--> at 2000 vertices) because every edge that could
+(<!--fact:geo.pip2000-->0.5×<!--/fact--> at 2000 vertices) because every edge that could
 matter goes through the exact orientation predicate, where Turf uses naive
 floating-point arithmetic. That is the trade this module exists to make — it
 is the difference between a containment test that is right on near-collinear
@@ -713,7 +722,7 @@ predicate on edges that cannot affect the answer, which took this from 0.2×
 to about 0.5×; the rest is the predicate itself, and the campaign that made
 geography reachable across the suite never traded it away. The bounding box
 of the same ring and the index build against Flatbush sit within a few tenths
-of level (<!--bm:geo.bbox2000-->0.9×<!--/bm--> and <!--bm:geo.indexBuild-->0.8×<!--/bm-->) and move
+of level (<!--fact:geo.bbox2000-->0.9×<!--/fact--> and <!--fact:geo.indexBuild-->0.8×<!--/fact-->) and move
 between runs and Node versions; they are published as measured rather than
 rounded to a win.
 

package/README.md

@@ -13,6 +13,9 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/object` | deep equality (`equalsDeep`, JSON-only `equalsJson`), the `isJsonObject` and deep `isJsonValue` predicates, `__proto__`-safe `setObjectMember`, `deepFreeze`, map/set merging |
 | `@jarenjs/core/string` | Unicode string helpers (`countCodePoints`, `compareCodePoints`, ...), cached regex compilation, the suite's one content hash (`fnv1a` and the `hashContent` fingerprint over it) and `kebabCase` |
 | `@jarenjs/core/cache` | the bounded LRU (`createBoundedCache`), the reference-keyed `createWeakCache`, and `createSemanticCache` — keyed by what a value IS, for caches whose entries decide a result |
+| `@jarenjs/core/random` | the suite's one seeded generator (`mulberry32`, pinned sequence, ToUint32 seed) and the draws built on it: `randomInt` over a half-open range, in-place Fisher–Yates `shuffle`, and `drawDistinct` — `k` distinct indices from one stream |
+| `@jarenjs/core/stats` | descriptive statistics over a sample: `mean`, sample `variance`/`stddev`, the midpoint `median`, and `quantile(values, p, { method })` — `p` on 0..1 under a NAMED rule, `'nearest-rank'` or `'linear'`, because a default would decide silently; an empty sample answers `undefined`, never `0` |
+| `@jarenjs/core/async` | `mapConcurrent(items, limit, worker, { signal })` — the bounded ordered asynchronous map: never more than `limit` workers in flight, results in input order, a rejection or an abort stops dispatch and drains the lanes before the map rejects, so nothing is still running when it settles |
 | `@jarenjs/core/chunk` | cutting a value down to size: `sizeOf` (the suite's one size rule — a string is its length, anything else its JSON), `excerpt`, `truncate`, and `chunkText` by size, line or separator with offsets that locate a piece in its source |
 | `@jarenjs/core/scan` | char-code constants and predicates for recursive-descent parsers |
 | `@jarenjs/core/message` | the message template/catalog compiler shared by the validator and the form layer |
@@ -98,7 +101,7 @@ Four design decisions carry the module:
 - **Orientation is computed exactly** (Shewchuk's adaptive predicates): a naive floating-point determinant returns the *wrong sign* on near-collinear input, which makes containment contradict itself. Every ring winding and point-in-polygon answer rests on this sign, and the deliberate cost is on the [benchmark page](https://jklarenbeek.github.io/jarenjs/#/benchmarks?suite=geo).
 - **Measurement is spherical, drawing is projected, and the two never mix.** A Euclidean norm on raw degrees is 64% wrong over 1 km at Dutch latitudes, so `haversineDistance`/`sphericalRingArea` work on the sphere (`equirectDistance` is the cheap screening form for rejecting candidates first), while `projectMercator`/`fitMercator` and `simplifyLine`/`simplifyRing` exist for renderers — never measure on a projected coordinate.
 - **Validity is a separate concern from traversal, and a box is refused rather than made too small.** `eachPosition`, `bboxOf`, `centroidOf` and friends measure without judging (a ring is read as closed whether or not it is); a box over any non-finite coordinate is `null`, never a plausible box that misses its input; and boxes never cross the antimeridian — cut the geometry at ±180° as RFC 7946 §3.1.9 asks, and every containment test and index probe is right. `isValidGeoJson` (structure plus the ring closure a JSON Schema provably cannot express), `isValidWkt` and `isValidGeohash` are the one-call judgments that back the `geoFormats` group in [`@jarenjs/formats`](../formats), next to the full GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json).
-- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is <!--bm:geo.wktParsePoint-->3.1×<!--/bm--> faster on a `POINT` and the yes-or-no answer <!--bm:geo.wktValidatePoint-->5.3×<!--/bm--> — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md). The kernel's own losses are published there too, derived from the same run: <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is <!--fact:geo.wktParsePoint-->3.1×<!--/fact--> faster on a `POINT` and the yes-or-no answer <!--fact:geo.wktValidatePoint-->5.3×<!--/fact--> — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md). The kernel's own losses are published there too, derived from the same run: <!--fact:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/fact-->.
 
 The spatial query operators (`$distance`, `$within`, `$geohash`, spatial joins over the box index) live in the query engine in [`@jarenjs/json`](../json); the streaming map chart that draws a FeatureCollection with bounded memory lives in [`@jarenjs/charts`](../../components/charts). The full module reference is [docs/GEO.md](./docs/GEO.md).
 

package/dist/types/async.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 declare function mapConcurrent<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R> | R, options?: {
+    signal?: AbortSignal;
+}): Promise<R[]>;

package/dist/types/random.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The suite's one seeded generator, and the three draws built on
+ * it. Every seeded corpus, oracle and property test in this repository
+ * needs the same thing: a stream of numbers that is identical on every
+ * host for a given seed, so that a benchmark can state a delta and a
+ * failing property test can be replayed. Before this file that stream
+ * was written ten times; a generator that exists once is one whose
+ * sequence can be pinned once.
+ *
+ * The algorithm is mulberry32 — a 32-bit state, one multiply-xorshift
+ * round per draw, a period of 2^32. It is named by its algorithm rather
+ * than by its role because the SEQUENCE is the contract: a corpus
+ * generated from seed 20260825 must regenerate byte-for-byte, and a
+ * "better" generator under the same name would silently change every
+ * fixture that trusts it. A second algorithm gets a second name.
+ *
+ * Nothing here is cryptographic, and nothing here reads `Math.random`.
+ */
+/**
+ * A seeded generator: uniform in `[0, 1)`, identical on every host for
+ * the same seed.
+ *
+ * The seed is taken as an unsigned 32-bit integer (`seed >>> 0`, the
+ * ToUint32 conversion): `1.5` seeds as `1`, `-1` as `4294967295`,
+ * `2^32 + 5` as `5`, and `NaN` as `0`. Two seeds that agree modulo 2^32
+ * are one stream — say so wherever a seed is published.
+ * @param {number} seed
+ * @returns {() => number} the stream; each call is the next draw
+ */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * One integer draw over the half-open range `[min, max)`: `min +
+ * floor(random() * (max - min))`.
+ *
+ * This is the floor draw and deliberately so. Every committed corpus in
+ * the suite was generated with exactly this arithmetic, and a generator
+ * whose integer draw changed would regenerate every one of them
+ * differently. It is uniform up to a bias bounded by `(max - min) /
+ * 2^32` — under one part in a million for a span of four thousand, and
+ * far below anything a benchmark row can resolve. A draw that rejects
+ * to remove even that bias would be a different function under a
+ * different name, not a change to this one.
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} min - inclusive integer lower bound
+ * @param {number} max - exclusive integer upper bound; must exceed `min`
+ * @returns {number} an integer in `[min, max)`
+ * @throws {RangeError} when a bound is not an integer or `max <= min`
+ */
+export declare function randomInt(random: () => number, min: number, max: number): number;
+/**
+ * Fisher–Yates, in place, from the given stream: for `i` from the last
+ * index down to 1, swap `i` with a uniform `j` in `[0, i]`. Returns the
+ * same array. An empty or one-element list draws nothing.
+ *
+ * The descending form is the one the seeded corpora were generated
+ * with; the ascending form is a different permutation of the same
+ * stream and must not be substituted.
+ * @template T
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {T[]} list - reordered in place
+ * @returns {T[]} `list`
+ */
+export declare function shuffle<T>(random: () => number, list: T[]): T[];
+/**
+ * `k` distinct indices from `[0, n)`, uniformly, as a partial forward
+ * Fisher–Yates over a fresh index pool: the first `k` positions of a
+ * shuffle, without paying for the rest. Asked for more than `n` it
+ * answers `n` — a draw cannot invent a member the population does not
+ * hold; asked for nothing, or from nothing, it answers `[]`.
+ *
+ * The stream is the caller's, so one stream can serve many draws
+ * (a policy that draws per question from one seeded closure stays
+ * reproducible across the whole run).
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} n - the population size (a non-negative integer)
+ * @param {number} k - how many to draw (a non-negative integer)
+ * @returns {number[]} `min(k, n)` distinct indices, in draw order
+ * @throws {RangeError} when `n` or `k` is not a non-negative integer
+ */
+export declare function drawDistinct(random: () => number, n: number, k: number): number[];

package/dist/types/stats.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Descriptive statistics over a sample of numbers: the mean, the
+ * sample variance and its root, the median, and a quantile that will
+ * not answer until told which quantile it is being asked for.
+ *
+ * Before this file the suite computed these in two places with two
+ * quantile rules — linear interpolation in the query layer's statistics
+ * pack, nearest rank in the benchmark harness — and each was the right
+ * rule for its consumer: an interpolated percentile is what an analyst
+ * expects of `$percentile`, while a benchmark row of eleven readings
+ * should not publish a latency nobody measured. Both rules stay; the
+ * definitions move here so that there is one of each, and `quantile`
+ * makes the caller name its method, because "the 95th percentile" of a
+ * small sample is a different number under every one of the seven
+ * common definitions and a default would decide silently.
+ *
+ * Every function answers `undefined` for a sample it cannot summarize —
+ * an empty one, or fewer than two values for a variance — rather than
+ * `NaN` or `0`: a number that was not measured must not format as one.
+ * The caller's array is never reordered; a quantile sorts a copy.
+ * Values are numbers by contract and are not checked one by one.
+ */
+/**
+ * The arithmetic mean.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for an empty sample
+ */
+export declare function mean(values: readonly number[]): number | undefined;
+/**
+ * The SAMPLE variance, with Bessel's correction (`n − 1`): the sample is
+ * taken as drawn from a population it did not enumerate, which is what a
+ * benchmark's rounds and a query's rows both are.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for fewer than two values
+ */
+export declare function variance(values: readonly number[]): number | undefined;
+/**
+ * The sample standard deviation — the root of {@link variance}.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` where the variance is
+ */
+export declare function stddev(values: readonly number[]): number | undefined;
+/**
+ * The median: the middle value, or the mean of the two middle values
+ * when the sample has an even count.
+ *
+ * This is NOT `quantile(values, 0.5, …)` under either method, and on an
+ * even count the three disagree: for `[1, 2, 3, 4]` the median is `2.5`,
+ * the nearest-rank p50 is `2`, and the linear p50 is `2.5` only because
+ * that sample happens to be evenly spaced. A consumer publishing a "p50"
+ * beside a "p95" wants `quantile` with its method named; a consumer
+ * asking for the median wants this.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for an empty sample
+ */
+export declare function median(values: readonly number[]): number | undefined;
+export type QuantileMethod = 'nearest-rank' | 'linear';
+/**
+ * The `p`-quantile of a sample, `p` on `[0, 1]`, under a NAMED method.
+ *
+ * The method is required, not defaulted: on a small sample the common
+ * definitions disagree by whole values, and a caller who did not say
+ * which one it wanted has published a number it cannot explain.
+ * @param {readonly number[]} values
+ * @param {number} p - the probability, `0` (the minimum) to `1` (the maximum)
+ * @param {{ method: QuantileMethod }} options
+ * @returns {number | undefined} `undefined` for an empty sample
+ * @throws {TypeError} when `method` is absent or not one of {@link QuantileMethod}
+ * @throws {RangeError} when `p` is not a number in `[0, 1]`
+ */
+export declare function quantile(values: readonly number[], p: number, options: {
+    method: QuantileMethod;
+}): number | undefined;

package/docs/GEO.md

@@ -22,10 +22,10 @@ the *wrong sign* on near-collinear input, which makes containment
 contradict itself. `orient2dFast` is the naive form, exported for
 callers that provably do not care. Every winding and containment answer
 in this module rests on this sign; its cost is the deliberate
-point-in-polygon loss on the benchmark page (<!--bm:geo.pip2000-->0.5×<!--/bm--> against
+point-in-polygon loss on the benchmark page (<!--fact:geo.pip2000-->0.5×<!--/fact--> against
 Turf at 2000 vertices, kept on purpose). Every loss the kernel carries is
 published in [ARCHITECTURE](../ARCHITECTURE.md), derived from the committed
-measurement: <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+measurement: <!--fact:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/fact-->.
 
 ## Distance — `distance.js`
 

package/docs/SERIES.md

@@ -311,16 +311,16 @@ downsampleSeries(readings, { target: 2000 });   // → { points, sourceCount, re
 
 ## What it costs
 
-Measured by `benchmark/series.js` over <!--bm:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/bm-->,
+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 <!--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-->.
+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-->.
 
-<!--bm:series.kernelTable-->
+<!--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× |
@@ -328,11 +328,11 @@ and against the vocabulary a consumer had instead it is <!--bm:series.kernelVsQu
 | `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-->
+<!--/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. <!--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-->
+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. <!--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-->
+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
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.49.2",
+  "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"
@@ -120,6 +128,10 @@
       "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;
+}

package/src/random.js

@@ -0,0 +1,125 @@
+//@ts-check
+/**
+ * @file The suite's one seeded generator, and the three draws built on
+ * it. Every seeded corpus, oracle and property test in this repository
+ * needs the same thing: a stream of numbers that is identical on every
+ * host for a given seed, so that a benchmark can state a delta and a
+ * failing property test can be replayed. Before this file that stream
+ * was written ten times; a generator that exists once is one whose
+ * sequence can be pinned once.
+ *
+ * The algorithm is mulberry32 — a 32-bit state, one multiply-xorshift
+ * round per draw, a period of 2^32. It is named by its algorithm rather
+ * than by its role because the SEQUENCE is the contract: a corpus
+ * generated from seed 20260825 must regenerate byte-for-byte, and a
+ * "better" generator under the same name would silently change every
+ * fixture that trusts it. A second algorithm gets a second name.
+ *
+ * Nothing here is cryptographic, and nothing here reads `Math.random`.
+ */
+
+/**
+ * A seeded generator: uniform in `[0, 1)`, identical on every host for
+ * the same seed.
+ *
+ * The seed is taken as an unsigned 32-bit integer (`seed >>> 0`, the
+ * ToUint32 conversion): `1.5` seeds as `1`, `-1` as `4294967295`,
+ * `2^32 + 5` as `5`, and `NaN` as `0`. Two seeds that agree modulo 2^32
+ * are one stream — say so wherever a seed is published.
+ * @param {number} seed
+ * @returns {() => number} the stream; each call is the next draw
+ */
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function random() {
+    a = (a + 0x6D2B79F5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * @param {number} value
+ * @param {string} what
+ */
+function assertInteger(value, what) {
+  if (!Number.isInteger(value))
+    throw new RangeError(`${what} must be an integer, got ${String(value)}`);
+}
+
+/**
+ * One integer draw over the half-open range `[min, max)`: `min +
+ * floor(random() * (max - min))`.
+ *
+ * This is the floor draw and deliberately so. Every committed corpus in
+ * the suite was generated with exactly this arithmetic, and a generator
+ * whose integer draw changed would regenerate every one of them
+ * differently. It is uniform up to a bias bounded by `(max - min) /
+ * 2^32` — under one part in a million for a span of four thousand, and
+ * far below anything a benchmark row can resolve. A draw that rejects
+ * to remove even that bias would be a different function under a
+ * different name, not a change to this one.
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} min - inclusive integer lower bound
+ * @param {number} max - exclusive integer upper bound; must exceed `min`
+ * @returns {number} an integer in `[min, max)`
+ * @throws {RangeError} when a bound is not an integer or `max <= min`
+ */
+export function randomInt(random, min, max) {
+  assertInteger(min, 'min');
+  assertInteger(max, 'max');
+  if (max <= min) throw new RangeError(`randomInt needs max > min, got [${min}, ${max})`);
+  return min + Math.floor(random() * (max - min));
+}
+
+/**
+ * Fisher–Yates, in place, from the given stream: for `i` from the last
+ * index down to 1, swap `i` with a uniform `j` in `[0, i]`. Returns the
+ * same array. An empty or one-element list draws nothing.
+ *
+ * The descending form is the one the seeded corpora were generated
+ * with; the ascending form is a different permutation of the same
+ * stream and must not be substituted.
+ * @template T
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {T[]} list - reordered in place
+ * @returns {T[]} `list`
+ */
+export function shuffle(random, list) {
+  for (let i = list.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [list[i], list[j]] = [list[j], list[i]];
+  }
+  return list;
+}
+
+/**
+ * `k` distinct indices from `[0, n)`, uniformly, as a partial forward
+ * Fisher–Yates over a fresh index pool: the first `k` positions of a
+ * shuffle, without paying for the rest. Asked for more than `n` it
+ * answers `n` — a draw cannot invent a member the population does not
+ * hold; asked for nothing, or from nothing, it answers `[]`.
+ *
+ * The stream is the caller's, so one stream can serve many draws
+ * (a policy that draws per question from one seeded closure stays
+ * reproducible across the whole run).
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} n - the population size (a non-negative integer)
+ * @param {number} k - how many to draw (a non-negative integer)
+ * @returns {number[]} `min(k, n)` distinct indices, in draw order
+ * @throws {RangeError} when `n` or `k` is not a non-negative integer
+ */
+export function drawDistinct(random, n, k) {
+  assertInteger(n, 'n');
+  assertInteger(k, 'k');
+  if (n < 0 || k < 0) throw new RangeError(`drawDistinct needs n >= 0 and k >= 0, got n=${n} k=${k}`);
+  const count = Math.min(k, n);
+  if (count === 0) return [];
+  const pool = Array.from({ length: n }, (_, i) => i);
+  for (let i = 0; i < count; i++) {
+    const j = i + Math.floor(random() * (pool.length - i));
+    [pool[i], pool[j]] = [pool[j], pool[i]];
+  }
+  return pool.slice(0, count);
+}

package/src/stats.js

@@ -0,0 +1,133 @@
+//@ts-check
+/**
+ * @file Descriptive statistics over a sample of numbers: the mean, the
+ * sample variance and its root, the median, and a quantile that will
+ * not answer until told which quantile it is being asked for.
+ *
+ * Before this file the suite computed these in two places with two
+ * quantile rules — linear interpolation in the query layer's statistics
+ * pack, nearest rank in the benchmark harness — and each was the right
+ * rule for its consumer: an interpolated percentile is what an analyst
+ * expects of `$percentile`, while a benchmark row of eleven readings
+ * should not publish a latency nobody measured. Both rules stay; the
+ * definitions move here so that there is one of each, and `quantile`
+ * makes the caller name its method, because "the 95th percentile" of a
+ * small sample is a different number under every one of the seven
+ * common definitions and a default would decide silently.
+ *
+ * Every function answers `undefined` for a sample it cannot summarize —
+ * an empty one, or fewer than two values for a variance — rather than
+ * `NaN` or `0`: a number that was not measured must not format as one.
+ * The caller's array is never reordered; a quantile sorts a copy.
+ * Values are numbers by contract and are not checked one by one.
+ */
+
+/**
+ * The arithmetic mean.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for an empty sample
+ */
+export function mean(values) {
+  if (values.length === 0) return undefined;
+  let sum = 0;
+  for (const value of values) sum += value;
+  return sum / values.length;
+}
+
+/**
+ * The SAMPLE variance, with Bessel's correction (`n − 1`): the sample is
+ * taken as drawn from a population it did not enumerate, which is what a
+ * benchmark's rounds and a query's rows both are.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for fewer than two values
+ */
+export function variance(values) {
+  if (values.length < 2) return undefined;
+  const m = /** @type {number} */ (mean(values));
+  let sum = 0;
+  for (const value of values) sum += (value - m) * (value - m);
+  return sum / (values.length - 1);
+}
+
+/**
+ * The sample standard deviation — the root of {@link variance}.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` where the variance is
+ */
+export function stddev(values) {
+  const v = variance(values);
+  return v === undefined ? undefined : Math.sqrt(v);
+}
+
+/**
+ * @param {readonly number[]} values
+ * @returns {number[]} an ascending copy
+ */
+function ascending(values) {
+  return [...values].sort((a, b) => a - b);
+}
+
+/**
+ * The median: the middle value, or the mean of the two middle values
+ * when the sample has an even count.
+ *
+ * This is NOT `quantile(values, 0.5, …)` under either method, and on an
+ * even count the three disagree: for `[1, 2, 3, 4]` the median is `2.5`,
+ * the nearest-rank p50 is `2`, and the linear p50 is `2.5` only because
+ * that sample happens to be evenly spaced. A consumer publishing a "p50"
+ * beside a "p95" wants `quantile` with its method named; a consumer
+ * asking for the median wants this.
+ * @param {readonly number[]} values
+ * @returns {number | undefined} `undefined` for an empty sample
+ */
+export function median(values) {
+  if (values.length === 0) return undefined;
+  const sorted = ascending(values);
+  const mid = sorted.length >> 1;
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * The quantile methods this module knows.
+ *
+ * - `'nearest-rank'`: the value at rank `max(1, ceil(p · n))` of the
+ *   ascending sample — always a value that was measured, never one
+ *   invented between two. The benchmark rule.
+ * - `'linear'`: rank `(n − 1) · p`, interpolated linearly between the
+ *   values at `floor` and `ceil` of it (Hyndman–Fan type 7, the default
+ *   of R, NumPy and spreadsheets). The analyst's rule.
+ * @typedef {'nearest-rank' | 'linear'} QuantileMethod
+ */
+
+/** @type {readonly QuantileMethod[]} */
+const METHODS = ['nearest-rank', 'linear'];
+
+/**
+ * The `p`-quantile of a sample, `p` on `[0, 1]`, under a NAMED method.
+ *
+ * The method is required, not defaulted: on a small sample the common
+ * definitions disagree by whole values, and a caller who did not say
+ * which one it wanted has published a number it cannot explain.
+ * @param {readonly number[]} values
+ * @param {number} p - the probability, `0` (the minimum) to `1` (the maximum)
+ * @param {{ method: QuantileMethod }} options
+ * @returns {number | undefined} `undefined` for an empty sample
+ * @throws {TypeError} when `method` is absent or not one of {@link QuantileMethod}
+ * @throws {RangeError} when `p` is not a number in `[0, 1]`
+ */
+export function quantile(values, p, options) {
+  const method = options?.method;
+  if (!METHODS.includes(/** @type {any} */ (method)))
+    throw new TypeError(`quantile needs { method: 'nearest-rank' | 'linear' }, got ${JSON.stringify(method)}`);
+  if (typeof p !== 'number' || !(p >= 0 && p <= 1))
+    throw new RangeError(`quantile needs p in [0, 1], got ${String(p)}`);
+  const n = values.length;
+  if (n === 0) return undefined;
+  const sorted = ascending(values);
+  if (method === 'nearest-rank') return sorted[Math.max(1, Math.ceil(p * n)) - 1];
+  const rank = (n - 1) * p;
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo];
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (rank - lo);
+}