@jarenjs/core 0.46.5 → 0.49.2

package/src/series/rolling.js

@@ -0,0 +1,229 @@
+//@ts-check
+
+//#region Rolling windows of time
+// A rolling aggregate over a *duration* rather than over a count of
+// rows. The distinction is the whole reason this module exists: a
+// sixty-row window over a sensor that reports every second is a minute,
+// and over a sensor that dropped half its readings it is two minutes.
+// One of those is a specification and the other is an accident.
+//
+// The window is `(at − width, at]`: exactly `width` milliseconds wide,
+// holding the current instant and not the one a full width behind it.
+// That is the mirror of the `[start, end)` rule the rest of this kernel
+// runs on — one endpoint in, one out, so consecutive windows neither
+// overlap at a boundary nor drop it — turned around because a trailing
+// window is anchored at its newest point rather than its oldest.
+//
+// Every output is one row, in the input's order, so the result lines up
+// with the series it came from. Rows sharing an instant therefore share
+// a window and share an answer: a span of time is a function of the
+// instant it ends at, not of which of two simultaneous readings the
+// loop happened to reach first.
+//
+// The complexity claim is per aggregate, and it is a claim about
+// structure rather than about a stopwatch:
+//
+//   sum, mean, count   a running total. The arriving row is added and
+//                      the departing row subtracted, so the window is
+//                      never re-read.
+//   min, max           a monotone deque. A row that arrives smaller
+//                      than the rows behind it makes them unreachable,
+//                      so they leave; each row is pushed and popped at
+//                      most once.
+//   first, last        the window's own ends, tracked by two pointers
+//                      that only ever 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 rather than a tolerance.
+
+import { addToParts } from '../dates/civil.js';
+import { canonicalSeries } from './normalize.js';
+import { compileSpan } from './bucket.js';
+import { requireSpecMembers } from './selector.js';
+import { CLOCK_MEMBERS } from './zone.js';
+
+/** @typedef {import('./normalize.js').Sample} Sample */
+
+/** What a window's rows can be reduced to — the seven of D5. */
+const AGGREGATES = Object.freeze(['sum', 'mean', 'min', 'max', 'first', 'last', 'count']);
+
+/**
+ * `rollingSeries`' closed specification: a window measured in time,
+ * how much of one counts, the clock a calendar width walks, and where
+ * a row keeps its instant and its reading.
+ */
+export const ROLLING_MEMBERS = Object.freeze([
+  'width', 'aggregate', 'minPeriods', 'at', 'value', ...CLOCK_MEMBERS,
+]);
+
+/**
+ * A rolling aggregate over a time-width window.
+ *
+ * Returns one `{ at, value, count }` per input sample, labelled at that
+ * sample's own instant, where the window is the half-open span
+ * `(at − width, at]`. Two samples at one instant share that window, and
+ * so report the same value and count.
+ *
+ * `count` is the number of **source rows** in the window — duplicates
+ * and measured gaps included — and the six value aggregates skip `null`
+ * readings, so `value` is `null` exactly when the window had nothing to
+ * measure. `aggregate: 'count'` returns that row count as the value.
+ *
+ * `minPeriods` is the number of source rows the window must hold before
+ * a value is reported at all; below it the row is `null` with its real
+ * `count`. It counts rows rather than readings, so a window full of
+ * measured gaps satisfies it and still reports `null` — which is the
+ * honest answer: readings were due, and none of them carried a number.
+ *
+ * `width` is a fixed duration (`'PT1H'`, `86400000`) or, with a clock,
+ * a calendar one (`'P1M'`, and `'P1D'` on a named zone where a day may
+ * be 23 or 25 hours long). A calendar window's start is computed by the
+ * calendar kernel per output, which is O(1) each — it is never a scan
+ * back through the window.
+ *
+ * @param {any[]} rows - the samples, in any order
+ * @param {Object} spec
+ * @param {number | string} spec.width - the window's width
+ * @param {'sum'|'mean'|'min'|'max'|'first'|'last'|'count'} [spec.aggregate]
+ *   default `'mean'`
+ * @param {number} [spec.minPeriods] - default 1
+ * @param {string} [spec.zone] - a named zone, needing `provider`
+ * @param {number} [spec.offset] - minutes east of UTC
+ * @param {import('./zone.js').ZoneProvider} [spec.provider]
+ * @param {'reject'|'earlier'|'later'} [spec.disambiguation]
+ * @param {string | ((item: any, index: number) => any)} [spec.at]
+ * @param {string | ((item: any, index: number) => any)} [spec.value]
+ * @returns {{ at: number, value: number | null, count: number }[]}
+ * @throws {TypeError} for a width that is not one positive whole span,
+ *   an unknown aggregate, a `minPeriods` that is not a positive whole
+ *   number, or a row that is not a canonical sample
+ * @example
+ * rollingSeries(readings, { width: 'PT5M', aggregate: 'mean' });
+ * rollingSeries(readings, { width: 'PT1M', minPeriods: 60 });
+ */
+export function rollingSeries(rows, spec) {
+  requireSpecMembers(spec, ROLLING_MEMBERS, 'rollingSeries',
+    'a rolling spec is an object with a \'width\'');
+  const samples = canonicalSeries(rows, spec);
+  const span = compileSpan(spec.width, spec);
+  const aggregate = spec.aggregate ?? 'mean';
+  if (typeof aggregate !== 'string' || !AGGREGATES.includes(aggregate)) {
+    throw new TypeError(`aggregate is ${AGGREGATES.map((a) => `'${a}'`).join(', ')}, not ${
+      JSON.stringify(aggregate)}`);
+  }
+  const minPeriods = spec.minPeriods ?? 1;
+  if (!Number.isInteger(minPeriods) || minPeriods < 1)
+    throw new TypeError(`minPeriods is a positive whole number, not ${minPeriods}`);
+
+  const n = samples.length;
+  /** @type {{ at: number, value: number | null, count: number }[]} */
+  const out = new Array(n);
+
+  // where the window holding `at` opens — exclusively, so a sample
+  // exactly one width behind the current one has already left
+  const opensAt = span.calendar
+    ? (/** @type {number} */ at) =>
+      span.clock.epochOf(addToParts(span.clock.partsAt(at), -span.amount, span.unit))
+    : (/** @type {number} */ at) => at - span.width;
+
+  const wantsExtremum = aggregate === 'min' || aggregate === 'max';
+  const sign = aggregate === 'min' ? 1 : -1;
+  /** The monotone deque, as indices into `samples`; `head`..`tail-1` is live. */
+  const deque = wantsExtremum ? new Int32Array(n) : null;
+  let head = 0;
+  let tail = 0;
+
+  let lo = 0;
+  let sum = 0;
+  let measured = 0;
+  let firstAt = 0;
+  let lastAt = -1;
+
+  // rows are admitted a whole instant at a time. A window is a span of
+  // time, so two readings in the same millisecond are both inside every
+  // window that holds either of them — and the two output rows, sharing
+  // an instant, therefore share an answer. Letting the loop admit one
+  // and then report before admitting the other would make the aggregate
+  // a function of arrival order rather than of the instant it is
+  // labelled at.
+  let i = 0;
+  while (i < n) {
+    const at = samples[i].at;
+    let group = i;
+    while (group + 1 < n && samples[group + 1].at === at)
+      group++;
+
+    const opens = opensAt(at);
+    while (lo < i && samples[lo].at <= opens) {
+      const leaving = samples[lo].value;
+      if (leaving !== null) {
+        sum -= leaving;
+        measured--;
+      }
+      lo++;
+    }
+    for (let k = i; k <= group; k++) {
+      const value = samples[k].value;
+      if (value !== null) {
+        sum += value;
+        measured++;
+        lastAt = k;
+        if (deque !== null) {
+          while (tail > head
+            && sign * (/** @type {number} */(samples[deque[tail - 1]].value) - value) >= 0)
+            tail--;
+          deque[tail++] = k;
+        }
+      }
+    }
+    if (deque !== null) {
+      while (tail > head && deque[head] < lo)
+        head++;
+    }
+    if (firstAt < lo)
+      firstAt = lo;
+    while (firstAt <= group && samples[firstAt].value === null)
+      firstAt++;
+
+    const count = group - lo + 1;
+    const value = count < minPeriods ? null
+      : reduce(aggregate, count, measured, sum, samples, deque, head,
+        firstAt <= group ? firstAt : -1, lastAt >= lo ? lastAt : -1);
+    for (let k = i; k <= group; k++)
+      out[k] = { at, count, value };
+    i = group + 1;
+  }
+  return out;
+}
+
+/**
+ * One window's rows, reduced from the state the loop already carries.
+ * @param {string} aggregate
+ * @param {number} count - source rows, gaps included
+ * @param {number} measured - rows carrying a number
+ * @param {number} sum
+ * @param {Sample[]} samples
+ * @param {Int32Array | null} deque
+ * @param {number} head
+ * @param {number} first - index of the window's first reading, or -1
+ * @param {number} last - index of the window's last reading, or -1
+ * @returns {number | null}
+ */
+function reduce(aggregate, count, measured, sum, samples, deque, head, first, last) {
+  if (aggregate === 'count')
+    return count;
+  if (measured === 0)
+    return null;
+  switch (aggregate) {
+    case 'sum': return sum;
+    case 'mean': return sum / measured;
+    case 'min':
+    case 'max': return /** @type {number} */ (samples[/** @type {Int32Array} */(deque)[head]].value);
+    case 'first': return first < 0 ? null : samples[first].value;
+    default: return last < 0 ? null : samples[last].value;
+  }
+}
+
+//#endregion

package/src/series/selector.js

@@ -0,0 +1,104 @@
+//@ts-check
+
+//#region Reading a source row
+// Where a member lives in a caller's row, and nothing else.
+//
+// Timestamped rows almost never arrive spelled `{ at, value }` or
+// `{ start, end }`. They come out of a document as `on`, out of a
+// database as `recorded_at`, out of a booking system as `from`/`to`. A
+// selector is either that member's name or a function of the row, so
+// nothing has to be rewritten into the canonical shape before it can be
+// normalized or indexed.
+//
+// This module imports nothing on purpose: it is the leaf both the
+// normalizer and the index stand on.
+
+/**
+ * A reader for one member of a source row.
+ * @param {string | ((item: any, index: number) => any)} spec - a
+ *   property name, or a function of the row and its position
+ * @param {string} role - the member's name, for the message
+ * @returns {(item: any, index: number) => any}
+ * @throws {TypeError} when `spec` is neither
+ */
+export function selectorOf(spec, role) {
+  if (typeof spec === 'string')
+    return (item) => item[spec];
+  if (typeof spec === 'function')
+    return spec;
+  throw new TypeError(`the '${role}' selector is a property name or a function`);
+}
+
+/**
+ * The row at `index`, confirmed to be something with members to read.
+ * @param {any} item
+ * @param {number} index
+ * @returns {any}
+ * @throws {TypeError} when it is not an object
+ */
+export function requireRow(item, index) {
+  if (item === null || typeof item !== 'object')
+    throw new TypeError(`row ${index} is not an object`);
+  return item;
+}
+
+//#endregion
+
+//#region Reading a specification
+// A specification is closed, and a member nobody admitted is a refusal.
+//
+// `minPeriod` for `minPeriods` silently ignored is the bug that takes
+// an afternoon: the window still answers, the number is still
+// plausible, and it was computed from a specification nobody wrote.
+// The zone members are worse — a named zone with NO provider refuses
+// (`zone.js`), so the only way left to reach a quiet UTC ladder is to
+// misspell the member that refusal keys on, and UTC is right for
+// Amsterdam for none of the year while looking right for eight months
+// of it.
+//
+// The near miss is named because that is the whole cost of the bug:
+// same first letter and a length within two, or a case-folded match.
+// It never guesses when nothing is close.
+
+/**
+ * The nearest admitted member to a misspelling.
+ * @param {string} name
+ * @param {readonly string[]} allowed
+ * @returns {string} `''`, or ` (did you mean 'x'?)`
+ */
+function nearMiss(name, allowed) {
+  const lower = name.toLowerCase();
+  for (const candidate of allowed) {
+    const other = candidate.toLowerCase();
+    if (other === lower
+      || (other.startsWith(lower) && other.length - lower.length <= 2)
+      || (lower.startsWith(other) && lower.length - other.length <= 2))
+      return ` (did you mean '${candidate}'?)`;
+  }
+  return '';
+}
+
+/**
+ * One specification, confirmed to name only admitted members.
+ * @param {any} spec - the caller's specification object
+ * @param {readonly string[]} allowed - the closed member list
+ * @param {string} kernel - the function's name, for the message
+ * @param {string} shape - what the specification is, for the message
+ *   when it is not an object at all
+ * @returns {any} the same object
+ * @throws {TypeError} when it is not an object, or names a member the
+ *   kernel does not admit
+ */
+export function requireSpecMembers(spec, allowed, kernel, shape) {
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec))
+    throw new TypeError(shape);
+  for (const name of Object.keys(spec)) {
+    if (!allowed.includes(name)) {
+      throw new TypeError(`${kernel} has no specification member '${name}'${
+        nearMiss(name, allowed)}; it admits ${allowed.map((m) => `'${m}'`).join(', ')}`);
+    }
+  }
+  return spec;
+}
+
+//#endregion

package/src/series/zone.js

@@ -0,0 +1,188 @@
+//@ts-check
+
+//#region The zone seam
+// 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; reading the host's zone is the
+// hidden clock D7 exists to forbid. So this module is a **seam**, not an
+// implementation.
+//
+// Three clocks come out of it:
+//
+//   UTC              the default. Nothing to configure, nothing to
+//                    install, and no local time is ever ambiguous.
+//   a fixed offset   `{ offset: -300 }` — minutes east of UTC, constant.
+//                    Exact integer arithmetic, still unambiguous.
+//   a named zone     `{ zone: 'Europe/Amsterdam', provider }` — the
+//                    caller supplies the tzdb, in whatever form they
+//                    already have one (Intl, Temporal, a table of their
+//                    own). This module only says what it must answer.
+//
+// A provider answers two questions, and the second is the hard one:
+//
+//   toParts(epoch, zone)                  → the wall clock at an instant
+//   toEpoch(parts, zone, disambiguation)  → the instant at a wall clock
+//
+// The instant is hard because a local time is not a function of the
+// clock. On a spring-forward day 02:30 never happens, and on a
+// fall-back day 02:30 happens twice. `disambiguation` says which answer
+// the caller wants — `'reject'` (the default: neither, it is an error),
+// `'earlier'` or `'later'` — and a provider that cannot produce one says
+// so by returning a non-finite number or throwing, which this module
+// turns into a refusal naming the local time rather than a silent hour.
+
+import { partsFromEpoch } from '../dates/civil.js';
+import { epochOfRFC3339Parts } from '../dates/rfc3339.js';
+
+/**
+ * A wall clock the caller supplies, for zones this suite does not carry.
+ * @typedef {Object} ZoneProvider
+ * @property {(epoch: number, zone: string) => any} toParts - the wall
+ *   clock at an instant, as a parts record (`year`, `month` 1-12, `day`,
+ *   `hours`, `minutes`, `seconds`, and `offset` in minutes east if known)
+ * @property {(parts: any, zone: string, disambiguation: string) => number}
+ *   toEpoch - the instant a wall clock names, in epoch milliseconds;
+ *   non-finite (or a throw) when the local time is ambiguous or does not
+ *   exist and `disambiguation` does not resolve it
+ */
+
+/**
+ * A resolved wall clock: the two directions, already bound to a zone.
+ * @typedef {Object} Clock
+ * @property {string} zone - what the clock is called, for messages
+ * @property {(epoch: number) => any} partsAt
+ * @property {(parts: any) => number} epochOf
+ */
+
+/** What a caller may ask for when a local time is ambiguous or absent. */
+const DISAMBIGUATION = Object.freeze(['reject', 'earlier', 'later']);
+
+/**
+ * The four members every calendar-aware specification carries, so
+ * a bucket ladder, a rolling window and a query document all spell
+ * the clock the same way.
+ */
+export const CLOCK_MEMBERS = Object.freeze(['zone', 'offset', 'provider', 'disambiguation']);
+
+/**
+ * The clock an operation reads its calendar boundaries on.
+ *
+ * Defaults to UTC, which needs nothing: no provider, no zone name, no
+ * ambiguity. `{ offset }` is a constant number of minutes east and is
+ * exact integer arithmetic. `{ zone }` is a name, and a name means
+ * nothing without a `provider` — asking for `'Europe/Amsterdam'` with no
+ * tzdb is a refusal, never a silent fall back to UTC that is right for
+ * eight months of the year.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.zone] - an IANA name; `'UTC'` needs no provider
+ * @param {number} [options.offset] - minutes east of UTC, for a fixed offset
+ * @param {ZoneProvider} [options.provider] - the tzdb, for a named zone
+ * @param {'reject' | 'earlier' | 'later'} [options.disambiguation]
+ *   what a local time that happens twice, or never, resolves to
+ *   (default `'reject'`)
+ * @returns {Clock}
+ * @throws {TypeError} for a named zone with no provider, a non-finite
+ *   offset, an unknown disambiguation, or both a zone and an offset
+ * @example
+ * resolveClock();                        // UTC
+ * resolveClock({ offset: 330 });         // +05:30, constant
+ * resolveClock({ zone: 'Europe/Amsterdam', provider, disambiguation: 'later' });
+ */
+export function resolveClock(options = {}) {
+  if (options === null || typeof options !== 'object')
+    throw new TypeError('clock options are an object');
+  const disambiguation = options.disambiguation ?? 'reject';
+  if (!DISAMBIGUATION.includes(disambiguation)) {
+    throw new TypeError(`disambiguation is ${
+      DISAMBIGUATION.map((d) => `'${d}'`).join(', ')}, not '${disambiguation}'`);
+  }
+  const named = options.zone !== undefined && options.zone !== 'UTC';
+  if (named && options.offset !== undefined)
+    throw new TypeError(`a clock is a zone or an offset, not both ('${options.zone}' and ${options.offset})`);
+  if (named)
+    return providerClock(/** @type {string} */(options.zone), options.provider, disambiguation);
+  const offset = options.offset ?? 0;
+  if (typeof offset !== 'number' || !Number.isFinite(offset))
+    throw new TypeError('an offset is a finite number of minutes east of UTC');
+  return offsetClock(offset);
+}
+
+/**
+ * The UTC-or-fixed-offset clock: a constant shift, so every local time
+ * exists exactly once and `disambiguation` never has anything to decide.
+ * @param {number} offset - minutes east of UTC
+ * @returns {Clock}
+ */
+function offsetClock(offset) {
+  return {
+    zone: offset === 0 ? 'UTC' : formatOffset(offset),
+    partsAt: (epoch) => partsFromEpoch(epoch, offset),
+    epochOf: (parts) => {
+      const ms = epochOfRFC3339Parts({ ...parts, offset });
+      if (!Number.isFinite(ms))
+        throw new TypeError(`${describe(parts)} names no instant at ${formatOffset(offset)}`);
+      return ms;
+    },
+  };
+}
+
+/**
+ * The named-zone clock: every question goes to the caller's provider,
+ * and an answer that is not a finite instant becomes a refusal naming
+ * the local time that has none.
+ * @param {string} zone
+ * @param {ZoneProvider | undefined} provider
+ * @param {string} disambiguation
+ * @returns {Clock}
+ */
+function providerClock(zone, provider, disambiguation) {
+  if (provider === null || typeof provider !== 'object'
+    || typeof provider.toParts !== 'function' || typeof provider.toEpoch !== 'function') {
+    throw new TypeError(`the zone '${zone}' needs a provider with toParts(epoch, zone) and`
+      + ' toEpoch(parts, zone, disambiguation); this suite bundles no time-zone database');
+  }
+  return {
+    zone,
+    partsAt: (epoch) => {
+      const parts = provider.toParts(epoch, zone);
+      if (parts === null || typeof parts !== 'object')
+        throw new TypeError(`the provider gave no wall clock for ${epoch} in '${zone}'`);
+      return parts;
+    },
+    epochOf: (parts) => {
+      let ms;
+      try {
+        ms = provider.toEpoch(parts, zone, disambiguation);
+      }
+      catch (error) {
+        throw new TypeError(`${describe(parts)} in '${zone}': ${
+          error instanceof Error ? error.message : String(error)}`);
+      }
+      if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+        throw new TypeError(`${describe(parts)} in '${zone}' is ambiguous or does not exist,`
+          + ` and disambiguation is '${disambiguation}'`);
+      }
+      return ms;
+    },
+  };
+}
+
+/** `+02:00` / `-05:30`, for a message. @param {number} minutes @returns {string} */
+function formatOffset(minutes) {
+  const sign = minutes < 0 ? '-' : '+';
+  const abs = Math.abs(minutes);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}
+
+/** A local time, for a message. @param {any} parts @returns {string} */
+function describe(parts) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${parts.year}-${pad(parts.month)}-${pad(parts.day)}T${
+    pad(Math.max(parts.hours, 0))}:${pad(Math.max(parts.minutes, 0))}:${
+    pad(Math.floor(Math.max(parts.seconds, 0)))}`;
+}
+
+//#endregion