@jarenjs/core 0.46.5 → 0.56.0

package/src/series/interval.js

@@ -0,0 +1,374 @@
+//@ts-check
+
+//#region Half-open interval algebra
+// Set operations over `[start, end)` spans of epoch milliseconds — the
+// vocabulary a roster, a calendar, an availability view and a
+// maintenance window all rebuild by hand today.
+//
+// **Half-open is the whole design.** An interval contains `t` when
+// `start <= t && t < end`, so a day ends exactly where the next one
+// begins and nothing is counted twice at a boundary. Two intervals that
+// touch (`a.end === b.start`) therefore do NOT overlap: back-to-back
+// bookings are not a double booking.
+//
+// Merging is the one place that answer is not enough, and it is why
+// `mergeIntervals` joins touching spans by DEFAULT. Availability asks
+// "is there continuous cover from nine to five", and 09:00-13:00 plus
+// 13:00-17:00 is continuous cover; leaving a zero-width seam between
+// them would report a gap no one can be scheduled into. The other
+// answer is real too — a shift handover is two shifts, not one — so it
+// is spelled `{ adjacent: false }` and nothing has to guess.
+//
+// Every operation refuses an interval that is empty, reversed or not
+// finite. `[t, t)` contains no instant, so it is a defect at the point
+// it was written rather than a value that quietly disappears from a
+// union and quietly consumes a subtraction.
+//
+// A bound is read wherever it is written: every operation takes epoch
+// milliseconds or an RFC 3339 string, and every result is epoch
+// milliseconds. Conversion happens once, at the door.
+//
+// Merge, subtract, gaps and slots return bare `{ start, end }` records:
+// a span welded out of three source rows belongs to none of them, and
+// carrying one of their metadata forward would be a claim the data does
+// not support. Source members survive normalization and the index,
+// where a result IS a row.
+
+import { toEpoch, normalizeIntervals } from './normalize.js';
+import { requireSpecMembers } from './selector.js';
+import { parseDuration, durationToMs } from '../dates/duration.js';
+
+/** @typedef {import('./normalize.js').Interval} Interval */
+
+/**
+ * One interval as canonical epoch bounds, validated as `[start, end)`.
+ * Both bounds go through {@link toEpoch}, so every operation here reads
+ * an RFC 3339 string wherever it reads a number, and everything past
+ * this point is integer arithmetic.
+ * @param {any} interval
+ * @param {string} role - what the argument is, for the message
+ * @returns {Interval}
+ */
+function requireInterval(interval, role) {
+  if (interval === null || typeof interval !== 'object')
+    throw new TypeError(`${role} is not an interval`);
+  let start;
+  let end;
+  try {
+    start = toEpoch(interval.start);
+    end = toEpoch(interval.end);
+  }
+  catch (error) {
+    throw new TypeError(`${role} has a bound that names no instant: ${
+      error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!(start < end))
+    throw new TypeError(`${role} ends at ${end}, at or before its start ${start}`);
+  return { start, end };
+}
+
+/**
+ * A positive fixed width in milliseconds, from a number or a fixed ISO
+ * 8601 duration string.
+ *
+ * A calendar duration (`P1M`, `P1Y`) is refused rather than approximated:
+ * a month has no width until it is told where it starts, and calling it
+ * thirty days is how a schedule drifts.
+ *
+ * @param {number | string} spec
+ * @param {string} role
+ * @returns {number} milliseconds
+ */
+function requireWidth(spec, role) {
+  let ms = spec;
+  if (typeof spec === 'string') {
+    const parts = parseDuration(spec);
+    if (parts === null)
+      throw new TypeError(`${role} '${spec}' is not an ISO 8601 duration`);
+    ms = durationToMs(parts);
+    if (!Number.isFinite(ms))
+      throw new TypeError(`${role} '${spec}' is a calendar duration and has no fixed width`);
+  }
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0)
+    throw new TypeError(`${role} is a positive number of milliseconds or a fixed ISO 8601 duration`);
+  return ms;
+}
+
+/**
+ * Does `interval` contain the instant `at`?
+ *
+ * Half-open: the start is in, the end is out. An instant on a boundary
+ * belongs to exactly one of two touching intervals, which is what makes
+ * "which shift is this event in" answerable.
+ *
+ * @param {Interval} interval
+ * @param {number | string} at - epoch milliseconds or RFC 3339
+ * @returns {boolean}
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * containsInstant({ start: 0, end: 10 }, 0);  // true
+ * containsInstant({ start: 0, end: 10 }, 10); // false
+ */
+export function containsInstant(interval, at) {
+  const { start, end } = requireInterval(interval, 'the interval');
+  const t = toEpoch(at);
+  return t >= start && t < end;
+}
+
+/**
+ * Do two intervals share at least one instant?
+ *
+ * Touching intervals do not: `[0, 10)` and `[10, 20)` have no instant
+ * in common, so consecutive bookings never read as a conflict.
+ *
+ * @param {Interval} a
+ * @param {Interval} b
+ * @returns {boolean}
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * overlapsInterval({ start: 0, end: 10 }, { start: 10, end: 20 }); // false
+ * overlapsInterval({ start: 0, end: 10 }, { start: 9, end: 20 });  // true
+ */
+export function overlapsInterval(a, b) {
+  const left = requireInterval(a, 'the left interval');
+  const right = requireInterval(b, 'the right interval');
+  return left.start < right.end && right.start < left.end;
+}
+
+/**
+ * The span two intervals share, or `null` when they share none.
+ *
+ * `null` rather than an empty interval, because `[t, t)` is not a value
+ * this algebra has — the absence is the answer, and it cannot then be
+ * fed back in as if it were a span.
+ *
+ * @param {Interval} a
+ * @param {Interval} b
+ * @returns {Interval | null} a new record
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * intersectInterval({ start: 0, end: 10 }, { start: 5, end: 20 });
+ * // { start: 5, end: 10 }
+ */
+export function intersectInterval(a, b) {
+  const left = requireInterval(a, 'the left interval');
+  const right = requireInterval(b, 'the right interval');
+  const start = left.start > right.start ? left.start : right.start;
+  const end = left.end < right.end ? left.end : right.end;
+  return start < end ? { start, end } : null;
+}
+
+/**
+ * `mergeIntervals`' closed specification: whether spans that touch
+ * join, which availability normally wants and a handover does not.
+ */
+export const MERGE_MEMBERS = Object.freeze(['adjacent']);
+
+/**
+ * The union of `intervals`, as the fewest disjoint spans that cover the
+ * same instants, ascending.
+ *
+ * Touching spans are joined by default, because continuous cover is
+ * what availability means; `{ adjacent: false }` keeps them apart, which
+ * is what a handover between two shifts means. Overlapping spans always
+ * join, under both settings.
+ *
+ * @param {Interval[]} intervals - in any order
+ * @param {Object} [options]
+ * @param {boolean} [options.adjacent] - join touching spans (default `true`)
+ * @returns {Interval[]} new `{ start, end }` records
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * mergeIntervals([{ start: 0, end: 10 }, { start: 10, end: 20 }]);
+ * // [{ start: 0, end: 20 }]
+ * mergeIntervals([{ start: 0, end: 10 }, { start: 10, end: 20 }],
+ *                { adjacent: false });
+ * // [{ start: 0, end: 10 }, { start: 10, end: 20 }]
+ */
+export function mergeIntervals(intervals, options = {}) {
+  requireSpecMembers(options, MERGE_MEMBERS, 'mergeIntervals',
+    'a merge spec is an object with an \'adjacent\'');
+  const adjacent = options.adjacent ?? true;
+  const sorted = normalizeIntervals(intervals);
+  /** @type {Interval[]} */
+  const out = [];
+  for (let i = 0; i < sorted.length; i++) {
+    const { start, end } = sorted[i];
+    const last = out.length === 0 ? null : out[out.length - 1];
+    if (last !== null && (adjacent ? start <= last.end : start < last.end)) {
+      if (end > last.end)
+        last.end = end;
+    }
+    else out.push({ start, end });
+  }
+  return out;
+}
+
+/**
+ * The instants in `from` that `remove` does not cover, as disjoint
+ * ascending spans.
+ *
+ * Both sides are merged first, so the result is the set difference and
+ * nothing depends on the order the arguments arrived in. A cut through
+ * the middle of a span **splits** it into two; a cut that covers a span
+ * removes it entirely.
+ *
+ * @param {Interval[]} from - the spans being reduced
+ * @param {Interval[]} remove - the spans taken out of them
+ * @returns {Interval[]} new `{ start, end }` records
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * subtractIntervals([{ start: 0, end: 100 }], [{ start: 40, end: 60 }]);
+ * // [{ start: 0, end: 40 }, { start: 60, end: 100 }]
+ */
+export function subtractIntervals(from, remove) {
+  const base = mergeIntervals(from);
+  const cuts = mergeIntervals(remove);
+  /** @type {Interval[]} */
+  const out = [];
+  let j = 0;
+  for (let i = 0; i < base.length; i++) {
+    const span = base[i];
+    let at = span.start;
+    // cuts and base are both ascending and disjoint, so a cut that ends
+    // at or before this span's start is spent for every later span too
+    while (j < cuts.length && cuts[j].end <= at)
+      j++;
+    for (let k = j; k < cuts.length && cuts[k].start < span.end; k++) {
+      if (cuts[k].start > at)
+        out.push({ start: at, end: cuts[k].start });
+      if (cuts[k].end > at)
+        at = cuts[k].end;
+      if (at >= span.end)
+        break;
+    }
+    if (at < span.end)
+      out.push({ start: at, end: span.end });
+  }
+  return out;
+}
+
+/**
+ * The hull of `intervals` — the one span from the earliest start to the
+ * latest end, or `null` when there are none.
+ * @param {Interval[]} sorted - ascending on `start`
+ * @returns {Interval | null}
+ */
+function hullOf(sorted) {
+  if (sorted.length === 0)
+    return null;
+  let end = sorted[0].end;
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i].end > end)
+      end = sorted[i].end;
+  }
+  return { start: sorted[0].start, end };
+}
+
+/**
+ * The spans inside `within` that `intervals` leaves uncovered.
+ *
+ * `within` defaults to the hull of the intervals themselves — the gaps
+ * *between* them — because the alternative default would be a clock,
+ * and this kernel has none. Passing it explicitly is what reports a
+ * missing edge: an empty morning before the first booking is only a gap
+ * if the caller says the day starts at nine.
+ *
+ * @param {Interval[]} intervals - in any order
+ * @param {Interval} [within] - the window to look inside
+ * @returns {Interval[]} new `{ start, end }` records
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * gapsWithin([{ start: 0, end: 10 }, { start: 30, end: 40 }]);
+ * // [{ start: 10, end: 30 }]
+ * gapsWithin([{ start: 10, end: 20 }], { start: 0, end: 30 });
+ * // [{ start: 0, end: 10 }, { start: 20, end: 30 }]
+ */
+export function gapsWithin(intervals, within) {
+  const merged = mergeIntervals(intervals);
+  const bounds = within === undefined ? hullOf(merged) : requireInterval(within, 'the window');
+  if (bounds === null)
+    return [];
+  return subtractIntervals([bounds], merged);
+}
+
+/**
+ * How many milliseconds `intervals` cover, counting an instant once
+ * however many spans hold it.
+ *
+ * Restricted to `within` when given, which is what turns it into a
+ * ratio: `coverageOf(shifts, day) / (day.end - day.start)` is the
+ * fraction of the day that is staffed.
+ *
+ * @param {Interval[]} intervals - in any order
+ * @param {Interval} [within] - clip to this window first
+ * @returns {number} milliseconds
+ * @throws {TypeError} for an empty, reversed or non-finite interval
+ * @example
+ * coverageOf([{ start: 0, end: 10 }, { start: 5, end: 20 }]); // 20
+ */
+export function coverageOf(intervals, within) {
+  const merged = mergeIntervals(intervals);
+  const bounds = within === undefined ? null : requireInterval(within, 'the window');
+  let total = 0;
+  for (let i = 0; i < merged.length; i++) {
+    const start = bounds === null || merged[i].start > bounds.start ? merged[i].start : bounds.start;
+    const end = bounds === null || merged[i].end < bounds.end ? merged[i].end : bounds.end;
+    if (end > start)
+      total += end - start;
+  }
+  return total;
+}
+
+/**
+ * `findSlots`' closed specification: how long a slot is and how far
+ * apart two of them start. Enumeration, never a constraint solver.
+ */
+export const SLOTS_MEMBERS = Object.freeze(['duration', 'step']);
+
+/**
+ * Every place a span of `duration` fits inside `availability`.
+ *
+ * Availability is merged first — two touching windows are one window,
+ * so a meeting may straddle the seam — and each merged window is then
+ * walked from its own start in `step` increments (default: back to
+ * back), keeping every span that still ends inside the window. A window
+ * exactly one duration wide yields exactly one slot.
+ *
+ * This is enumeration, not scheduling: it answers "where could this
+ * go", and choosing among the answers, weighing preferences or
+ * assigning people is a solver's job, deliberately not this one.
+ *
+ * `duration` and `step` are fixed widths — a number of milliseconds or
+ * a fixed ISO 8601 duration (`'PT30M'`). A calendar duration is refused
+ * rather than approximated, because "every month" needs a calendar and
+ * a zone to say where its boundaries fall.
+ *
+ * @param {Interval[]} availability - in any order
+ * @param {Object} spec
+ * @param {number | string} spec.duration - how long the span is
+ * @param {number | string} [spec.step] - the spacing between starts
+ *   (default: `duration`)
+ * @returns {Interval[]} new `{ start, end }` records, ascending
+ * @throws {TypeError} for an empty, reversed or non-finite interval, or
+ *   a duration/step that is not a positive fixed width
+ * @example
+ * findSlots([{ start: 0, end: 90 }], { duration: 60, step: 30 });
+ * // [{ start: 0, end: 60 }, { start: 30, end: 90 }]
+ */
+export function findSlots(availability, spec) {
+  requireSpecMembers(spec, SLOTS_MEMBERS, 'findSlots', 'a slot spec is an object with a duration');
+  const duration = requireWidth(spec.duration, 'duration');
+  const step = spec.step === undefined ? duration : requireWidth(spec.step, 'step');
+  const windows = mergeIntervals(availability);
+  /** @type {Interval[]} */
+  const out = [];
+  for (let i = 0; i < windows.length; i++) {
+    const limit = windows[i].end - duration;
+    for (let start = windows[i].start; start <= limit; start += step)
+      out.push({ start, end: start + duration });
+  }
+  return out;
+}
+
+//#endregion

package/src/series/normalize.js

@@ -0,0 +1,330 @@
+//@ts-check
+
+//#region Canonical instants, samples and intervals
+// The one door every temporal kernel enters through. A consumer's rows
+// arrive as whatever their source spells — an RFC 3339 string out of a
+// document, epoch milliseconds out of a column, a member named `on` or
+// `timestamp` rather than `at` — and everything downstream wants sorted
+// numbers. Converting here, once, is what lets the algebra and the
+// index stay integer arithmetic over a sorted array.
+//
+// Three rules make that conversion safe to build on:
+//
+//   **A row is never dropped.** A member that cannot become a finite
+//   instant is a TypeError naming the row, not a silently shorter
+//   result. Quietly discarding the one malformed sample in ten thousand
+//   is how an aggregate becomes wrong without anything looking wrong.
+//
+//   **Sorting is stable.** Two samples at the same instant come out in
+//   the order they went in, and both participate in an aggregate. A
+//   duplicate instant is real data — two readings in the same
+//   millisecond — not a key collision to resolve.
+//
+//   **A value may be absent, but only explicitly.** `null` is a
+//   measured gap and survives; `undefined`, a string or a NaN is a
+//   defect and is refused.
+//
+// There is no clock here and no zone here. A full-date reads as UTC
+// midnight because RFC 3339 gives it no offset; a full-time has no
+// instant at all and is refused rather than being invented a day.
+
+import { parseRFC3339Parts, epochOfRFC3339Parts } from '../dates/rfc3339.js';
+import { selectorOf, requireRow } from './selector.js';
+
+/**
+ * @typedef {Object} Sample
+ * @property {number} at - Unix epoch milliseconds
+ * @property {number | null} value - the reading, or `null` for a
+ *   measured gap
+ */
+
+/**
+ * @typedef {Object} Interval
+ * @property {number} start - inclusive lower bound, epoch milliseconds
+ * @property {number} end - exclusive upper bound, epoch milliseconds
+ */
+
+/**
+ * The instant `value` names, in Unix epoch milliseconds.
+ *
+ * Accepts the two forms a date has in this suite: a finite **number**
+ * (already epoch milliseconds, returned unchanged) and a valid **RFC
+ * 3339 string**. A full-date reads as UTC midnight, an offset shifts to
+ * the instant it names, and `Z` is UTC.
+ *
+ * Refused, all as `TypeError`: a full-time (`'09:30:00Z'` names no day,
+ * and inventing one would be a hidden clock), a date-time without an
+ * offset (`'2026-01-01T09:30:00'` names no instant without a zone),
+ * `NaN`/`Infinity`, a `Date` object (dates are strings or numbers here,
+ * never a wrapper), and anything else.
+ *
+ * @param {number | string} value
+ * @returns {number} epoch milliseconds
+ * @throws {TypeError} when `value` names no instant
+ * @example
+ * toEpoch(0);                      // 0
+ * toEpoch('1970-01-01');           // 0
+ * toEpoch('1970-01-01T01:00:00+01:00'); // 0
+ */
+export function toEpoch(value) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value))
+      throw new TypeError(`${value} is not an instant`);
+    return value;
+  }
+  if (typeof value === 'string') {
+    const parts = parseRFC3339Parts(value);
+    const ms = parts === null ? NaN : epochOfRFC3339Parts(parts);
+    if (!Number.isFinite(ms))
+      throw new TypeError(`'${value}' is not an RFC 3339 instant`);
+    return ms;
+  }
+  throw new TypeError('an instant is epoch milliseconds or an RFC 3339 string');
+}
+
+/**
+ * One instant read out of a row, with the row named when it is not one.
+ * "not an RFC 3339 instant" is a puzzle when ten thousand rows were
+ * handed in; "row 4172, at: …" is a defect someone can go and look at.
+ *
+ * @param {any} value - the raw member
+ * @param {string} role - the member's name, for the message
+ * @param {number} index - the row's position
+ * @returns {number} epoch milliseconds
+ * @throws {TypeError} when `value` names no instant
+ */
+export function epochAt(value, role, index) {
+  try {
+    return toEpoch(value);
+  }
+  catch (error) {
+    throw new TypeError(`row ${index}, ${role}: ${
+      error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Is this array already ascending on `key`? An input that arrives
+ * sorted — a column read back in order, a stream appended in time — is
+ * the common case, and O(n) to confirm.
+ * @param {any[]} rows
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isAscending(rows, key) {
+  for (let i = 1; i < rows.length; i++) {
+    if (rows[i - 1][key] > rows[i][key])
+      return false;
+  }
+  return true;
+}
+
+/**
+ * Sorted canonical samples: every row's instant converted once, its
+ * value checked, its other members kept, and the whole ascending by
+ * instant.
+ *
+ * The sort is **stable**, so rows sharing an instant come out in input
+ * order — and both are present, because a duplicate instant is two
+ * readings, not one row written twice.
+ *
+ * Each result is a shallow copy of its source row with canonical `at`
+ * and `value` members written over it, so a source that spelled its
+ * instant `on` keeps `on` too and nothing a caller attached is lost.
+ *
+ * @param {any[]} rows - the source rows
+ * @param {Object} [options]
+ * @param {string | ((item: any, index: number) => any)} [options.at]
+ *   where the instant lives (default `'at'`)
+ * @param {string | ((item: any, index: number) => any)} [options.value]
+ *   where the reading lives (default `'value'`)
+ * @returns {(Sample & Record<string, any>)[]} a new array of new records
+ * @throws {TypeError} for a non-array, a row that is not an object, an
+ *   instant that names none, or a value that is neither a finite number
+ *   nor `null`
+ * @example
+ * normalizeSeries([{ on: '2026-01-01T00:00:01Z', v: 2 },
+ *                  { on: '2026-01-01T00:00:00Z', v: 1 }],
+ *                 { at: 'on', value: 'v' });
+ * // [{ on: '…:00Z', v: 1, at: 1767225600000, value: 1 },
+ * //  { on: '…:01Z', v: 2, at: 1767225601000, value: 2 }]
+ */
+export function normalizeSeries(rows, options = {}) {
+  if (!Array.isArray(rows))
+    throw new TypeError('a series is an array of rows');
+  const readAt = selectorOf(options.at ?? 'at', 'at');
+  const readValue = selectorOf(options.value ?? 'value', 'value');
+  const out = new Array(rows.length);
+  for (let i = 0; i < rows.length; i++) {
+    const row = requireRow(rows[i], i);
+    const at = epochAt(readAt(row, i), 'at', i);
+    const value = readValue(row, i);
+    if (value !== null && !(typeof value === 'number' && Number.isFinite(value)))
+      throw new TypeError(`row ${i}, value: neither a finite number nor null`);
+    out[i] = { ...row, at, value };
+  }
+  if (!isAscending(out, 'at'))
+    out.sort(compareAt);
+  return out;
+}
+
+/** @param {Sample} a @param {Sample} b @returns {number} */
+function compareAt(a, b) {
+  return a.at - b.at;
+}
+
+/**
+ * The same canonical samples, without the copy when there is nothing to
+ * convert.
+ *
+ * {@link normalizeSeries} always builds a new array of new records,
+ * which is the right answer at the door and the wrong one three kernels
+ * later: bucketing, rolling and joining all take a series that a caller
+ * usually normalized once already, and re-copying a hundred thousand
+ * rows per operation costs more than the operation. So this checks
+ * instead of converting — one pass, no allocation — and hands the
+ * caller's own array straight back when every row is already
+ * `{ at: <finite number>, value: <number | null> }` and ascending.
+ *
+ * Nothing is trusted: a row that fails the check sends the whole array
+ * through {@link normalizeSeries}, which refuses it there with the row
+ * named. The fast path is a measurement, not a promise.
+ *
+ * @param {any[]} rows
+ * @param {Object} [options]
+ * @param {string | ((item: any, index: number) => any)} [options.at]
+ * @param {string | ((item: any, index: number) => any)} [options.value]
+ * @returns {(Sample & Record<string, any>)[]} `rows` itself, or a new
+ *   normalized array
+ * @throws {TypeError} exactly where {@link normalizeSeries} does
+ */
+export function canonicalSeries(rows, options = {}) {
+  if (Array.isArray(rows) && options.at === undefined && options.value === undefined
+    && isCanonical(rows))
+    return rows;
+  return normalizeSeries(rows, options);
+}
+
+/**
+ * Is every row already a canonical sample, and the whole ascending?
+ * @param {any[]} rows
+ * @returns {boolean}
+ */
+function isCanonical(rows) {
+  let previous = -Infinity;
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (row === null || typeof row !== 'object')
+      return false;
+    const at = row.at;
+    if (typeof at !== 'number' || !Number.isFinite(at) || at < previous)
+      return false;
+    const value = row.value;
+    if (value !== null && (typeof value !== 'number' || !Number.isFinite(value)))
+      return false;
+    previous = at;
+  }
+  return true;
+}
+
+/**
+ * Sorted canonical intervals: every bound converted once, the direction
+ * checked, other members kept, and the whole ascending by start.
+ *
+ * Half-open `[start, end)` with `start < end` is the contract the whole
+ * algebra rests on, so an empty (`start === end`), reversed or
+ * non-finite interval is refused here rather than producing an answer
+ * later that no reader could predict. Duplicates survive — two bookings
+ * of the same slot are two bookings — and rows sharing a start keep
+ * their input order.
+ *
+ * @param {any[]} rows - the source rows
+ * @param {Object} [options]
+ * @param {string | ((item: any, index: number) => any)} [options.start]
+ *   where the lower bound lives (default `'start'`)
+ * @param {string | ((item: any, index: number) => any)} [options.end]
+ *   where the upper bound lives (default `'end'`)
+ * @returns {(Interval & Record<string, any>)[]} a new array of new records
+ * @throws {TypeError} for a non-array, a row that is not an object, a
+ *   bound that names no instant, or `end <= start`
+ * @example
+ * normalizeIntervals([{ start: '2026-01-01', end: '2026-01-02' }]);
+ * // [{ start: 1767225600000, end: 1767312000000 }]
+ */
+export function normalizeIntervals(rows, options = {}) {
+  if (!Array.isArray(rows))
+    throw new TypeError('intervals are an array of rows');
+  const readStart = selectorOf(options.start ?? 'start', 'start');
+  const readEnd = selectorOf(options.end ?? 'end', 'end');
+  const out = new Array(rows.length);
+  for (let i = 0; i < rows.length; i++) {
+    const row = requireRow(rows[i], i);
+    const start = epochAt(readStart(row, i), 'start', i);
+    const end = epochAt(readEnd(row, i), 'end', i);
+    if (!(start < end))
+      throw new TypeError(`row ${i}: an interval ends at ${end}, at or before its start ${start}`);
+    out[i] = { ...row, start, end };
+  }
+  if (!isAscending(out, 'start'))
+    out.sort(compareStart);
+  return out;
+}
+
+/** @param {Interval} a @param {Interval} b @returns {number} */
+function compareStart(a, b) {
+  return a.start - b.start;
+}
+
+/**
+ * The index of the first row at or after `at` — the lower end of a
+ * half-open cut. `rows` must already be ascending on `key`.
+ *
+ * This is the whole reason a series is normalized once: a range over a
+ * sorted array is two binary searches and a slice, not a pass over
+ * everything.
+ *
+ * @param {any[]} rows - ascending on `key`
+ * @param {number} at - epoch milliseconds
+ * @param {string} [key] - the member holding the instant (default `'at'`)
+ * @returns {number} an index in `[0, rows.length]`
+ * @example
+ * const lo = lowerBoundTime(samples, start);
+ * const hi = lowerBoundTime(samples, end);
+ * samples.slice(lo, hi); // every sample in [start, end)
+ */
+export function lowerBoundTime(rows, at, key = 'at') {
+  let lo = 0;
+  let hi = rows.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (rows[mid][key] < at) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * The index of the first row strictly after `at`. `rows` must already
+ * be ascending on `key`.
+ *
+ * The twin of {@link lowerBoundTime}: together they bracket the rows AT
+ * an instant (`[lowerBoundTime(rows, t), upperBoundTime(rows, t))`),
+ * which is what a duplicate-tolerant as-of has to read.
+ *
+ * @param {any[]} rows - ascending on `key`
+ * @param {number} at - epoch milliseconds
+ * @param {string} [key] - the member holding the instant (default `'at'`)
+ * @returns {number} an index in `[0, rows.length]`
+ */
+export function upperBoundTime(rows, at, key = 'at') {
+  let lo = 0;
+  let hi = rows.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (rows[mid][key] <= at) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+//#endregion