@jarenjs/core 0.49.2 → 0.66.1

package/src/object.js

@@ -14,8 +14,9 @@ const hasOwn = Object.hasOwn;
  * Deep equality comparison for arbitrary values.
  *
  * Generic JavaScript equality: understands Maps, Sets, RegExps,
- * functions, typed arrays and class instances (constructors must
- * match). Not the same as `equalsJson`, which compares JSON values
+ * functions, typed arrays and class instances (prototype constructors
+ * must match; an own `constructor` member is data). Not the same as
+ * `equalsJson`, which compares JSON values
  * only and is the hot-path variant — keep both.
  * @param {any} target
  * @param {any} source
@@ -34,23 +35,24 @@ export function equalsDeep(target, source) {
   if (isScalarType(target))
     return false;
 
-  if (target.constructor !== source.constructor)
+  const constructor = Object.getPrototypeOf(target)?.constructor;
+  if (constructor !== Object.getPrototypeOf(source)?.constructor)
     return false;
 
-  if (target.constructor === Object) {
+  if (constructor === Object) {
     const tks = Object.keys(target);
     const sks = Object.keys(source);
     if (tks.length !== sks.length)
       return false;
     for (let i = 0; i < tks.length; ++i) {
       const key = tks[i];
-      if (!equalsDeep(target[key], source[key]))
+      if (!hasOwn(source, key) || !equalsDeep(target[key], source[key]))
         return false;
     }
     return true;
   }
 
-  if (target.constructor === Map) {
+  if (constructor === Map) {
     if (target.size !== source.size)
       return false;
     for (const [key, value] of target) {
@@ -62,7 +64,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === Array) {
+  if (constructor === Array) {
     if (target.length !== source.length)
       return false;
     for (let i = 0; i < target.length; ++i) {
@@ -72,7 +74,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === Set) {
+  if (constructor === Set) {
     if (target.size !== source.size)
       return false;
     for (const value of target) {
@@ -82,7 +84,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === RegExp) {
+  if (constructor === RegExp) {
     return target.toString() === source.toString();
   }
 
@@ -104,7 +106,7 @@ export function equalsDeep(target, source) {
   if (tkeys.length === 0) return true;
   for (let i = 0; i < tkeys.length; ++i) {
     const key = tkeys[i];
-    if (!equalsDeep(target[key], source[key]))
+    if (!hasOwn(source, key) || !equalsDeep(target[key], source[key]))
       return false;
   }
   return true;
@@ -375,7 +377,7 @@ function semanticToken(value, path, open) {
     // an own property beyond the elements would vanish positionally
     for (const key of Object.keys(items)) {
       const index = Number(key);
-      if (!Number.isInteger(index) || index < 0 || index >= items.length)
+      if (!Number.isInteger(index) || index < 0 || index >= items.length || String(index) !== key)
         refuse(`the extra array property ${JSON.stringify(key)}`);
     }
     out = '[';
@@ -422,7 +424,7 @@ function semanticToken(value, path, open) {
  * functions, symbols, cycles, and non-plain objects (a `Date`, `Map`,
  * `RegExp` or class instance, all of which serialize to `{}`), plus the
  * two members a serialization cannot show — a symbol key, and an own
- * array property past the last element. A caller that may hold such a
+ * array property that is not an element index. A caller that may hold such a
  * value must treat the refusal as "not cacheable" and compute afresh —
  * never as "reuse whatever shares the key".
  *
@@ -634,4 +636,4 @@ export function mergeSet(set, ...iterables) {
       set.add(item);
     }
   }
-}
+}

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/runtime.js

@@ -0,0 +1,130 @@
+//@ts-check
+/**
+ * @file The runtime record: the host facts every subsystem that needs
+ * one used to take separately — the clock, secure identifiers,
+ * randomness and the zone provider — as one frozen record a host builds
+ * once and hands to the store, the jobs engine, the migration runner and
+ * the http binding. Nothing here IS a clock, a random source or a zone
+ * database: the defaults are the platform's own (`Date.now`,
+ * `crypto.randomUUID`, `Math.random`, and no zone provider, which keeps
+ * a named zone the refusal it always was), so adopting the record changes
+ * nothing a consumer can observe. What it buys is that a deterministic
+ * run — a fixed clock, a seeded generator, a counting identifier — is
+ * configured in one place, and that four subsystems can no longer
+ * disagree about what time it is.
+ *
+ * Precedence is fixed: a subsystem's own explicit option wins over the
+ * record's member, which wins over the built-in default. The options are
+ * published surface, and a record that silently overrode them would be a
+ * breaking change dressed as an ergonomic.
+ *
+ * The record reaches hosts, never query compilation. A compiled query is
+ * cached by document identity and saved as a rule, so the current instant
+ * enters it as data — an external — and there is no `now` operator for
+ * this record to feed.
+ */
+
+/**
+ * The record every host-facing subsystem takes as `runtime`.
+ * @typedef {Object} Runtime
+ * @property {() => number} now - the clock, in epoch milliseconds
+ * @property {() => string} uuid - a fresh identifier; secure by default
+ * @property {() => number} random - uniform in `[0, 1)`
+ * @property {import('./series/zone.js').ZoneProvider | null} zoneProvider
+ *   - the tzdb a named zone is read through, or `null`: a named zone is
+ *   then a refusal, never a quiet UTC
+ */
+
+/**
+ * The four members a runtime record carries, so a subsystem, a test and
+ * a document all spell the host facts the same way.
+ */
+export const RUNTIME_MEMBERS = Object.freeze(['now', 'uuid', 'random', 'zoneProvider']);
+
+/**
+ * The platform's own answers — exactly what every subsystem fell back
+ * to before the record existed, member for member, so a run that never
+ * builds a record behaves as it always did.
+ * @type {Readonly<Runtime>}
+ */
+const DEFAULT_RUNTIME = Object.freeze({
+  now: Date.now,
+  // `randomUUID` is a method of the platform's Crypto object and refuses
+  // to run unbound, so the default is a call rather than a reference
+  uuid: () => globalThis.crypto.randomUUID(),
+  random: Math.random,
+  zoneProvider: null,
+});
+
+/**
+ * Whether a value is the pair of functions the temporal kernel's clock
+ * seam takes for a named zone.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isZoneProvider(value) {
+  return value !== null && typeof value === 'object'
+    && typeof value.toParts === 'function' && typeof value.toEpoch === 'function';
+}
+
+/**
+ * Build a runtime record: the platform defaults, with any member
+ * overridden. The result is frozen, so a subsystem that was handed one
+ * can hand it on without a copy.
+ *
+ * The record is closed: a member it does not have is a refusal naming
+ * the four it does, because `clock` for `now` quietly ignored would be a
+ * deterministic run that is not.
+ *
+ * @param {Partial<Runtime>} [overrides]
+ * @returns {Readonly<Runtime>}
+ * @throws {TypeError} for a member that is not a function, a
+ *   `zoneProvider` that is neither `null` nor a provider, or a member
+ *   the record does not have
+ * @example
+ * createRuntime();                                  // the platform's own
+ * createRuntime({ now: () => 1_700_000_000_000 });  // a fixed clock, the rest default
+ * createRuntime({ uuid: () => `id-${++n}`, random: mulberry32(1), zoneProvider });
+ */
+export function createRuntime(overrides = undefined) {
+  if (overrides === undefined || overrides === null)
+    return DEFAULT_RUNTIME;
+  if (typeof overrides !== 'object')
+    throw new TypeError('a runtime record is an object');
+  /** @type {any} */
+  const record = { ...DEFAULT_RUNTIME };
+  for (const key of Object.keys(overrides)) {
+    if (!RUNTIME_MEMBERS.includes(key)) {
+      throw new TypeError(`a runtime record has ${
+        RUNTIME_MEMBERS.map((m) => `'${m}'`).join(', ')}, not '${key}'`);
+    }
+    const value = /** @type {any} */ (overrides)[key];
+    if (value === undefined)
+      continue;
+    if (key === 'zoneProvider') {
+      if (value !== null && !isZoneProvider(value)) {
+        throw new TypeError('runtime.zoneProvider is null or a provider with'
+          + ' toParts(epoch, zone) and toEpoch(parts, zone, disambiguation)');
+      }
+    }
+    else if (typeof value !== 'function') {
+      throw new TypeError(`runtime.${key} is a function`);
+    }
+    record[key] = value;
+  }
+  return Object.freeze(record);
+}
+
+/**
+ * The record a subsystem reads its `runtime` option through: nothing
+ * given is the platform default, and anything given is validated and
+ * frozen — so every member a subsystem reads is a function, and a
+ * malformed record is refused where it was passed rather than where it
+ * was first called.
+ * @param {Partial<Runtime> | undefined | null} [candidate] - a subsystem's `options.runtime`
+ * @returns {Readonly<Runtime>}
+ * @throws {TypeError} as `createRuntime` does
+ */
+export function resolveRuntime(candidate = undefined) {
+  return candidate === DEFAULT_RUNTIME ? DEFAULT_RUNTIME : createRuntime(candidate);
+}

package/src/series/index.js

@@ -75,6 +75,13 @@ export { createIntervalIndex } from './interval-index.js';
 
 export { resolveClock, CLOCK_MEMBERS } from './zone.js';
 
+/**
+ * The wall clock a caller supplies for a named zone - the shape a host
+ * passes as `provider`, named here so it can be spelled where the seam
+ * is crossed.
+ * @typedef {import('./zone.js').ZoneProvider} ZoneProvider
+ */
+
 export { compileBuckets, resampleSeries, RESAMPLE_MEMBERS } from './bucket.js';
 
 export { rollingSeries, ROLLING_MEMBERS } from './rolling.js';

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);
+}

package/src/string.js

@@ -166,6 +166,37 @@ export function countCharCode(str, code, start = 0, end = str.length) {
   return n;
 }
 
+/**
+ * The UTF-8 byte length of a slice of a string — the one measure every
+ * byte bound in the suite counts (a body limit, a page, a change
+ * record, a parser's record or token limit) — computed without encoding
+ * a copy: one byte below U+0080, two below U+0800, four for a surrogate
+ * pair (one code point), three otherwise; a lone surrogate counts three,
+ * as its replacement would.
+ * @param {string} str
+ * @param {number} [start] - Inclusive start offset (defaults to 0)
+ * @param {number} [end] - Exclusive end offset (defaults to full length)
+ * @returns {number} The UTF-8 bytes of `str[start, end)`
+ */
+export function utf8ByteLength(str, start = 0, end = str.length) {
+  let bytes = 0;
+  for (let i = start; i < end; i++) {
+    const code = str.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xD800 && code <= 0xDBFF && i + 1 < end) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 0xDC00 && next <= 0xDFFF) {
+        bytes += 4;
+        i++;
+      }
+      else bytes += 3;
+    }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
 /**
  * Count the Unicode code points of a string (surrogate-pair aware;
  * a lone surrogate counts as one code point).