@jarenjs/core 0.46.5 → 0.49.2

package/src/dates/ticks.js

@@ -0,0 +1,184 @@
+//@ts-check
+
+//#region time-axis ticks
+// The locale-free planner behind a time axis: which calendar step a
+// domain should be read in, and where that step's boundaries fall. It
+// lives beside the calendar arithmetic rather than in a renderer
+// because a chart axis, a timeline and a bucketed series all want the
+// same answer, and a second copy of this ladder would be a second set
+// of tick positions.
+//
+// Positions only: these functions return domain values in epoch
+// milliseconds. Turning one into a coordinate is the caller's scale,
+// and turning one into a label is `compileDateFormat` (format.js).
+
+import { niceStep, axisTicksLinear } from '../math/float64.js';
+import {
+  partsFromEpoch, startOfParts, addToParts, isDateUnit,
+  daysFromCivil, civilFromDays, isoWeekdayFromDays,
+} from './civil.js';
+import { epochOfRFC3339Parts } from './rfc3339.js';
+
+// The steps a clock and a calendar actually have. The 1/2/5 ladder is
+// right for quantities and wrong for time: it puts ticks 50 seconds or
+// 8.64 days apart, which no reader converts back into a date. Each
+// entry is [unit, amount]; the unit names are the calendar's.
+const TIME_STEPS = Object.freeze([
+  ['second', 1], ['second', 5], ['second', 15], ['second', 30],
+  ['minute', 1], ['minute', 5], ['minute', 15], ['minute', 30],
+  ['hour', 1], ['hour', 3], ['hour', 6], ['hour', 12],
+  ['day', 1], ['day', 2], ['week', 1], ['week', 2],
+  ['month', 1], ['month', 3], ['month', 6],
+  ['year', 1],
+]);
+
+/**
+ * The first instant the parts contract can spell, `0000-01-01T00:00:00Z`.
+ * A negative year is that contract's "no date half" sentinel
+ * (rfc3339.js), so an older domain has no calendar boundary to land on
+ * and this planner has no ticks to offer it.
+ */
+const CALENDAR_MIN_MS = -62167219200000;
+
+// approximate widths, used only to pick a step near the target count
+const STEP_MS = Object.freeze({
+  second: 1000, minute: 60000, hour: 3600000, day: 86400000,
+  week: 604800000, month: 2629800000, year: 31557600000,
+});
+
+/**
+ * Choose the calendar step closest to covering `span` in `count` ticks.
+ *
+ * A year is the coarsest unit a calendar has, so above one year the
+ * ladder continues as whole years on the same 1/2/5×10^k steps — 2, 5,
+ * 10, 50, 1000 years. Without that continuation a millennial domain
+ * asks for one tick per year and runs out of axis long before it runs
+ * out of domain.
+ *
+ * @param {number} span - Domain width in milliseconds
+ * @param {number} count - Desired tick count
+ * @returns {[string, number]} a [unit, amount] pair
+ */
+export function niceTimeStep(span, count) {
+  const target = span / Math.max(1, count);
+  if (target > STEP_MS.year)
+    return ['year', Math.max(1, niceStep(target / STEP_MS.year))];
+  let best = TIME_STEPS[0];
+  let bestErr = Infinity;
+  for (let i = 0; i < TIME_STEPS.length; i++) {
+    const [unit, amount] = TIME_STEPS[i];
+    const err = Math.abs(Math.log(STEP_MS[unit] * amount / target));
+    if (err < bestErr) {
+      bestErr = err;
+      best = TIME_STEPS[i];
+    }
+  }
+  return /** @type {[string, number]} */ (best);
+}
+
+/**
+ * Time ticks on calendar boundaries: the first tick is the start of a
+ * `[unit, amount]` step at or after `min`, and each following one is a
+ * whole step later. A multi-unit step lands on a multiple of its own
+ * amount — months on 1, 4, 7, 10 and years on 1900, 1950, 2000 — so an
+ * axis reads as a calendar rather than as offsets from wherever the
+ * data happened to start.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]} tick values in epoch milliseconds
+ */
+export function axisTicksTime(min, max, count = 4) {
+  if (!Number.isFinite(min) || !Number.isFinite(max))
+    return [];
+  if (min === max)
+    return [min];
+  if (min > max)
+    return axisTicksTime(max, min, count);
+  const span = max - min;
+  // below a second the calendar has nothing to say; the numeric ladder does
+  if (span < 1000 * count)
+    return axisTicksLinear(min, max, count);
+  const [unit, amount] = niceTimeStep(span, count);
+  return timeTicksEvery(min, max, unit, amount);
+}
+
+/**
+ * Time ticks on a step the CALLER chose, rather than one this module
+ * picked for a target count: the first tick is the start of the
+ * `amount`-wide `unit` at or after `min`, and each following one is a
+ * whole step later. This is the boundary rule {@link axisTicksTime}
+ * uses once it has decided a step, exposed on its own because a
+ * consumer whose document declares its own interval — Mermaid's Gantt
+ * `tickInterval 1week` is the one in this repo — needs the same
+ * boundaries without the ladder choosing for it.
+ *
+ * A multi-unit step lands on a multiple of its own amount, so months
+ * fall on 1, 4, 7, 10 and years on 1900, 1950, 2000. A `week` step
+ * starts on Monday unless `weekStart` names another ISO weekday, which
+ * is what a document that says "weeks begin on Sunday" means.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {string} unit - a `DATE_UNITS` member (`'day'`, `'week'`, …)
+ * @param {number} [amount] - whole steps per tick, at least 1
+ * @param {{ weekStart?: number, limit?: number }} [options] -
+ *   `weekStart` is an ISO weekday, 1 (Monday) to 7 (Sunday);
+ *   `limit` caps the tick count (default 1000)
+ * @returns {number[]} tick values in epoch milliseconds
+ * @example
+ * timeTicksEvery(Date.UTC(2024, 0, 3), Date.UTC(2024, 0, 20), 'week', 1);
+ * // the Mondays of 2024-01-08 and 2024-01-15
+ */
+export function timeTicksEvery(min, max, unit, amount = 1, options = {}) {
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max < min)
+    return [];
+  if (!isDateUnit(unit) || !Number.isInteger(amount) || amount < 1)
+    return [];
+  if (min < CALENDAR_MIN_MS)
+    return [];
+  const limit = options.limit ?? 1000;
+  const from = partsFromEpoch(min);
+  let parts = startOfParts(from, unit);
+  if (amount > 1 && unit === 'month') {
+    // quarters and half-years start on month 1, 4, 7, 10 (or 1, 7)
+    parts = { ...parts, month: Math.floor((parts.month - 1) / amount) * amount + 1 };
+  }
+  else if (amount > 1 && unit === 'year') {
+    parts = { ...parts, year: Math.floor(parts.year / amount) * amount };
+  }
+  else if (unit === 'week') {
+    parts = { ...parts, ...weekStartDay(from, options.weekStart ?? 1) };
+  }
+  const ticks = [];
+  let ms = epochOfRFC3339Parts(parts);
+  while (ms < min) {
+    parts = addToParts(parts, amount, unit);
+    ms = epochOfRFC3339Parts(parts);
+  }
+  // the step is never zero, so this terminates; the cap is a guard
+  // against a pathological domain rather than an expected path
+  for (let i = 0; ms <= max && i < limit; i++) {
+    ticks.push(ms);
+    parts = addToParts(parts, amount, unit);
+    ms = epochOfRFC3339Parts(parts);
+  }
+  return ticks;
+}
+
+/**
+ * The civil date of the `weekStart`-day on or before `parts`' own day.
+ * @param {object} parts
+ * @param {number} weekStart - ISO weekday, 1 (Monday) to 7 (Sunday)
+ * @returns {{ year: number, month: number, day: number }}
+ */
+function weekStartDay(parts, weekStart) {
+  const start = weekStart >= 1 && weekStart <= 7 ? weekStart : 1;
+  const z = daysFromCivil(parts.year, parts.month, parts.day);
+  let back = isoWeekdayFromDays(z) - start;
+  if (back < 0) back += 7;
+  return civilFromDays(z - back);
+}
+
+//#endregion

package/src/math/float64.js

@@ -491,6 +491,35 @@ export function niceStep(span, count = 1) {
   return factor * base;
 }
 
+/**
+ * Ticks on the {@link niceStep} ladder inside `[min, max]`: every whole
+ * multiple of the step the domain contains, rounded to the step's own
+ * precision so an axis never shows `0.30000000000000004`. A degenerate
+ * domain yields a single tick, a reversed one reads the same as its
+ * forward twin, and a non-finite bound yields nothing.
+ *
+ * @param {number} min - Domain minimum
+ * @param {number} max - Domain maximum
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]}
+ */
+export function axisTicksLinear(min, max, count = 5) {
+  if (!Number.isFinite(min) || !Number.isFinite(max))
+    return [];
+  if (min === max)
+    return [min];
+  if (min > max)
+    return axisTicksLinear(max, min, count);
+  const step = niceStep(max - min, count);
+  const decimals = Math.max(0, -Math.floor(Math.log10(step)));
+  const ticks = [];
+  const first = Math.ceil(min / step);
+  const last = Math.floor(max / step);
+  for (let i = first; i <= last; ++i)
+    ticks.push(Number((i * step).toFixed(decimals)));
+  return ticks;
+}
+
 /**
  * Clamp a value into the unit interval `[0, 1]` — the fraction every
  * unit-space geometry stage emits. `NaN` passes through as `NaN` rather

package/src/series/asof.js

@@ -0,0 +1,276 @@
+//@ts-check
+
+//#region As-of joins
+// "What was the price when this trade printed." "Which shift was on
+// duty when this alarm fired." "What did the thermostat last read
+// before this door opened." One question, asked of two series that
+// share a timeline and nothing else — no common key, no matching
+// instants, and no promise that either side reported when the other
+// did.
+//
+// It is a join, so it is easy to write wrong twice:
+//
+//   **Once per left row.** Filtering the right side inside the loop is
+//   the obvious implementation and it is O(n·m). Both sides are sorted,
+//   and a sorted pair is one walk: this module keeps a single cursor
+//   that only ever moves forward, so the whole join is O(n + m) after
+//   normalization — and with a key, one partition pass plus a cursor
+//   per key.
+//
+//   **By dropping rows.** A left row with no match is still a left row.
+//   It comes back as `{ left, right: null, distance: null }`, because a
+//   join that quietly returns fewer rows than it was given is how a
+//   report loses the events nothing explained.
+//
+// Three directions, and the tie rules are pinned rather than emergent:
+// at an equal instant the **last** right-side row wins (duplicates are
+// two readings, and the later one is the one "as of" means), and a
+// `nearest` tie between an earlier and a later row chooses the earlier,
+// because a value that has already been observed is evidence and one
+// that has not is a forecast.
+
+import { canonicalSeries } from './normalize.js';
+import { selectorOf, requireSpecMembers } from './selector.js';
+import { parseDuration, durationToMs } from '../dates/duration.js';
+
+/** @typedef {import('./normalize.js').Sample} Sample */
+
+/**
+ * One left row and whatever the right side had to say about it.
+ * @typedef {Object} AsOfMatch
+ * @property {any} left - the canonical left sample
+ * @property {any | null} right - the canonical right sample, or `null`
+ * @property {number | null} distance - milliseconds between the two
+ *   instants, never negative; `null` when there was no match
+ */
+
+const DIRECTIONS = Object.freeze(['backward', 'forward', 'nearest']);
+
+/**
+ * A non-negative tolerance in milliseconds, from a number or a fixed
+ * ISO 8601 duration. A calendar duration is refused: "within a month"
+ * has no width until it is told which month.
+ * @param {any} spec
+ * @returns {number}
+ */
+function requireTolerance(spec) {
+  let ms = spec;
+  if (typeof spec === 'string') {
+    const parts = parseDuration(spec);
+    if (parts === null || parts.negative)
+      throw new TypeError(`tolerance '${spec}' is not a non-negative ISO 8601 duration`);
+    ms = durationToMs(parts);
+    if (!Number.isFinite(ms))
+      throw new TypeError(`tolerance '${spec}' is a calendar duration and has no fixed width`);
+  }
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0)
+    throw new TypeError('tolerance is a non-negative number of milliseconds or a fixed ISO 8601 duration');
+  return ms;
+}
+
+/**
+ * For each position, the last position sharing its instant — so the
+ * right-bias rule is a lookup rather than a scan through duplicates.
+ * @param {Sample[]} rows - ascending by `at`
+ * @returns {Int32Array}
+ */
+function lastAtSameInstant(rows) {
+  const out = new Int32Array(rows.length);
+  for (let i = rows.length - 1; i >= 0; i--)
+    out[i] = (i + 1 < rows.length && rows[i + 1].at === rows[i].at) ? out[i + 1] : i;
+  return out;
+}
+
+/**
+ * `asOfJoin`'s closed specification: which way to look, how far, what
+ * makes two rows comparable, and where each side keeps its members.
+ *
+ * This is the one series kernel whose spelling a query DOCUMENT cannot
+ * reuse: `left`/`right` are nested selector records, and §8.16 flattens
+ * them to `by`, `leftAt` and `rightAt` so the whole spec stays a
+ * literal. `@jarenjs/json` therefore keeps its own list, and says so.
+ */
+export const ASOF_MEMBERS = Object.freeze([
+  'direction', 'tolerance', 'key', 'left', 'right',
+]);
+
+/**
+ * Join each left sample to the right sample that was current for it.
+ *
+ * The result is one record **per left row**, in the left series'
+ * normalized order — sorted by instant, with rows sharing an instant in
+ * the order they arrived. Both `left` and `right` are canonical samples:
+ * shallow copies carrying every member of the source row plus a numeric
+ * `at` and `value`, so a consumer reads `match.right.at` rather than
+ * parsing a timestamp a second time.
+ *
+ * | direction | the right row chosen |
+ * |---|---|
+ * | `backward` | the last one at or before the left instant (default) |
+ * | `forward` | the last one at or after it |
+ * | `nearest` | whichever is closer; a tie chooses `backward` |
+ *
+ * At an equal instant the **last** right-side row wins in every
+ * direction: duplicates are two readings in the same millisecond, and
+ * "as of" means the later one.
+ *
+ * `tolerance` is the furthest a match may be, in milliseconds or as a
+ * fixed duration. Beyond it there is no match — not a distant one.
+ *
+ * `key` joins within groups: a property name or a function, applied to
+ * both sides (or `left.key`/`right.key` when the two sides spell it
+ * differently). The right side is partitioned **once**; no left row ever
+ * filters it.
+ *
+ * @param {any[]} left
+ * @param {any[]} right
+ * @param {Object} [spec]
+ * @param {'backward'|'forward'|'nearest'} [spec.direction] default `'backward'`
+ * @param {number | string} [spec.tolerance] - the furthest a match may be
+ * @param {string | ((item: any, index: number) => any)} [spec.key] - the
+ *   group both sides join within
+ * @param {{ at?: any, value?: any, key?: any }} [spec.left] - where the
+ *   left side's members live
+ * @param {{ at?: any, value?: any, key?: any }} [spec.right] - where the
+ *   right side's members live
+ * @returns {AsOfMatch[]}
+ * @throws {TypeError} for an unknown direction, a tolerance that is not
+ *   a non-negative fixed width, or a row that is not a canonical sample
+ * @example
+ * asOfJoin(trades, quotes);                              // the last quote at or before
+ * asOfJoin(alarms, shifts, { direction: 'nearest', tolerance: 'PT1H' });
+ * asOfJoin(readings, calibrations, { key: 'sensor' });   // per sensor
+ */
+export function asOfJoin(left, right, spec = {}) {
+  requireSpecMembers(spec, ASOF_MEMBERS, 'asOfJoin', 'an as-of spec is an object');
+  const direction = spec.direction ?? 'backward';
+  if (typeof direction !== 'string' || !DIRECTIONS.includes(direction)) {
+    throw new TypeError(`direction is ${DIRECTIONS.map((d) => `'${d}'`).join(', ')}, not ${
+      JSON.stringify(direction)}`);
+  }
+  const tolerance = spec.tolerance === undefined ? Infinity : requireTolerance(spec.tolerance);
+  const leftRows = canonicalSeries(left, spec.left);
+  const rightRows = canonicalSeries(right, spec.right);
+
+  const keySpec = spec.left?.key ?? spec.key;
+  const rightKeySpec = spec.right?.key ?? spec.key;
+  if (keySpec === undefined)
+    return joinRun(leftRows, rightRows, direction, tolerance);
+
+  const readLeftKey = selectorOf(keySpec, 'key');
+  const readRightKey = selectorOf(rightKeySpec ?? keySpec, 'key');
+  return joinKeyed(leftRows, rightRows, readLeftKey, readRightKey, direction, tolerance);
+}
+
+/**
+ * The unkeyed walk: one cursor over the right side, moved forward and
+ * never back, because the left side is sorted too.
+ * @param {Sample[]} leftRows
+ * @param {Sample[]} rightRows
+ * @param {string} direction
+ * @param {number} tolerance
+ * @returns {AsOfMatch[]}
+ */
+function joinRun(leftRows, rightRows, direction, tolerance) {
+  const groupEnd = lastAtSameInstant(rightRows);
+  const out = new Array(leftRows.length);
+  let cursor = 0;
+  for (let i = 0; i < leftRows.length; i++) {
+    while (cursor < rightRows.length && rightRows[cursor].at <= leftRows[i].at)
+      cursor++;
+    out[i] = pick(leftRows[i], rightRows, groupEnd, cursor, direction, tolerance);
+  }
+  return out;
+}
+
+/**
+ * The keyed walk: the right side partitioned once into per-key runs
+ * (each already sorted, because the whole was), then one cursor per key.
+ * A left row whose key the right side never carried is unmatched, which
+ * is an answer rather than an omission.
+ * @param {Sample[]} leftRows
+ * @param {Sample[]} rightRows
+ * @param {(item: any, index: number) => any} readLeftKey
+ * @param {(item: any, index: number) => any} readRightKey
+ * @param {string} direction
+ * @param {number} tolerance
+ * @returns {AsOfMatch[]}
+ */
+function joinKeyed(leftRows, rightRows, readLeftKey, readRightKey, direction, tolerance) {
+  /** @type {Map<any, { rows: Sample[], groupEnd: Int32Array | null, cursor: number }>} */
+  const groups = new Map();
+  for (let i = 0; i < rightRows.length; i++) {
+    const key = readRightKey(rightRows[i], i);
+    let group = groups.get(key);
+    if (group === undefined) {
+      group = { rows: [], groupEnd: null, cursor: 0 };
+      groups.set(key, group);
+    }
+    group.rows.push(rightRows[i]);
+  }
+  for (const group of groups.values())
+    group.groupEnd = lastAtSameInstant(group.rows);
+
+  const out = new Array(leftRows.length);
+  for (let i = 0; i < leftRows.length; i++) {
+    const group = groups.get(readLeftKey(leftRows[i], i));
+    if (group === undefined) {
+      out[i] = { left: leftRows[i], right: null, distance: null };
+      continue;
+    }
+    while (group.cursor < group.rows.length && group.rows[group.cursor].at <= leftRows[i].at)
+      group.cursor++;
+    out[i] = pick(leftRows[i], group.rows, /** @type {Int32Array} */(group.groupEnd),
+      group.cursor, direction, tolerance);
+  }
+  return out;
+}
+
+/**
+ * One left row's answer, given the cursor already standing at the first
+ * right row strictly after it.
+ *
+ * `cursor - 1` is therefore the last right row at or before the left
+ * instant — the right-bias rule, for free — and `groupEnd[cursor]` is
+ * the last row of the first instant strictly after it, which is the
+ * same rule looking the other way.
+ * @param {Sample} leftRow
+ * @param {Sample[]} rightRows
+ * @param {Int32Array} groupEnd
+ * @param {number} cursor
+ * @param {string} direction
+ * @param {number} tolerance
+ * @returns {AsOfMatch}
+ */
+function pick(leftRow, rightRows, groupEnd, cursor, direction, tolerance) {
+  const back = cursor - 1;
+  const forward = (back >= 0 && rightRows[back].at === leftRow.at)
+    ? back
+    : (cursor < rightRows.length ? groupEnd[cursor] : -1);
+  const backDistance = back >= 0 ? leftRow.at - rightRows[back].at : Infinity;
+  const forwardDistance = forward >= 0 ? rightRows[forward].at - leftRow.at : Infinity;
+
+  let index;
+  let distance;
+  if (direction === 'backward') {
+    index = back;
+    distance = backDistance;
+  }
+  else if (direction === 'forward') {
+    index = forward;
+    distance = forwardDistance;
+  }
+  else if (backDistance <= forwardDistance) {
+    index = back;
+    distance = backDistance;
+  }
+  else {
+    index = forward;
+    distance = forwardDistance;
+  }
+  if (index < 0 || distance > tolerance)
+    return { left: leftRow, right: null, distance: null };
+  return { left: leftRow, right: rightRows[index], distance };
+}
+
+//#endregion