@jarenjs/core 0.46.5 → 0.49.2

package/dist/types/series/bucket.d.ts

@@ -0,0 +1,206 @@
+export type Sample = import('./normalize.js').Sample;
+export type Clock = import('./zone.js').Clock;
+export type CompiledBuckets = {
+    /**
+     * - the width as it was written
+     */
+    every: number | string;
+    /**
+     * - whether boundaries need the calendar
+     */
+    calendar: boolean;
+    /**
+     * - `'millisecond'`, `'day'` or `'month'`
+     */
+    unit: string;
+    /**
+     * - the count of that unit
+     */
+    amount: number;
+    /**
+     * - fixed width in milliseconds, or 0 when
+     * the ladder is a calendar one
+     */
+    width: number;
+    /**
+     * - the clock the boundaries fall on
+     */
+    zone: string;
+    /**
+     * - the anchor, in epoch milliseconds
+     */
+    origin: number;
+    /**
+     * - the boundary at a
+     * ladder position; position 0 is `origin`
+     */
+    startOf: (index: number) => number;
+    /**
+     * - the ladder position
+     * holding an instant
+     */
+    indexOf: (at: number) => number;
+    /**
+     * - the boundary of the bucket
+     * holding an instant
+     */
+    floor: (at: number) => number;
+};
+/**
+ * A duration taken apart on a clock: which family it belongs to, how
+ * much of that family's unit it is, and the clock itself.
+ *
+ * The seam between the two kernels that need the same answer. A bucket
+ * ladder and a rolling window both have to know whether `P1M` is
+ * arithmetic or a calendar question, and whether `P1D` is 86,400,000
+ * milliseconds (it is, on UTC and on a fixed offset) or a day that might
+ * be 23 hours long (it is, on a named zone).
+ *
+ * @param {number | string} every
+ * @param {Object} [options] - the clock, as {@link resolveClock} takes it
+ * @param {string} [options.zone]
+ * @param {number} [options.offset]
+ * @param {import('./zone.js').ZoneProvider} [options.provider]
+ * @param {'reject' | 'earlier' | 'later'} [options.disambiguation]
+ * @returns {{ calendar: boolean, unit: string, amount: number, width: number, clock: Clock }}
+ * @throws {TypeError} for a span that is not one positive whole family,
+ *   or a named zone with no provider
+ */
+export declare function compileSpan(every: number | string, options?: {
+    zone?: string;
+    offset?: number;
+    provider?: import('./zone.js').ZoneProvider;
+    disambiguation?: 'reject' | 'earlier' | 'later';
+}): {
+    calendar: boolean;
+    unit: string;
+    amount: number;
+    width: number;
+    clock: Clock;
+};
+/**
+ * The bucket ladder for a specification, validated once and returned as
+ * the four boundary operations everything downstream needs.
+ *
+ * `spec` may be the width alone (`compileBuckets('PT15M')`) or a record
+ * with `every` and an optional `origin`. `options` carries the clock —
+ * nothing, `{ offset }`, or `{ zone, provider }` — and defaults to UTC.
+ *
+ * The default `origin` is local `1970-01-01T00:00:00` on that clock, so
+ * a daily bucket in `+02:00` falls on local midnight rather than on
+ * UTC's, and a monthly bucket falls on the first of the month.
+ *
+ * @param {number | string | { every: number | string, origin?: number | string }} spec
+ * @param {Object} [options] - the clock, as {@link resolveClock} takes it
+ * @param {string} [options.zone]
+ * @param {number} [options.offset]
+ * @param {import('./zone.js').ZoneProvider} [options.provider]
+ * @param {'reject' | 'earlier' | 'later'} [options.disambiguation]
+ * @returns {CompiledBuckets}
+ * @throws {TypeError} for a width that is not a positive whole span, a
+ *   width mixing calendar and fixed units, an origin naming no instant,
+ *   or a named zone with no provider
+ * @example
+ * const b = compileBuckets('PT15M');
+ * b.floor(Date.UTC(2026, 0, 1, 9, 7));  // 09:00
+ * b.startOf(b.indexOf(0) + 1);          // the boundary after the epoch
+ */
+export declare function compileBuckets(spec: number | string | {
+    every: number | string;
+    origin?: number | string;
+}, options?: {
+    zone?: string;
+    offset?: number;
+    provider?: import('./zone.js').ZoneProvider;
+    disambiguation?: 'reject' | 'earlier' | 'later';
+}): CompiledBuckets;
+/**
+ * `resampleSeries`' closed specification: the D5 bucket contract, the
+ * clock it reads and where a row keeps its instant and its reading.
+ */
+export declare const RESAMPLE_MEMBERS: readonly string[];
+/**
+ * Bucket a series, reduce each bucket to one number, and say what the
+ * empty ones mean.
+ *
+ * The result is ascending `{ at, value, count }` records labelled at
+ * their bucket's **start**, which is the only label that is a boundary
+ * rather than a summary of where the rows happened to land.
+ *
+ * `count` is the number of **source rows** the bucket held — duplicates
+ * and measured gaps included — so it is the honest denominator of what
+ * was seen, not of what could be added up. The six value aggregates
+ * (`sum`, `mean`, `min`, `max`, `first`, `last`) all skip `null`
+ * readings, so `value` is `null` exactly when the bucket had nothing to
+ * measure, and `count` tells you whether that was because nobody
+ * reported or because everybody reported a gap. `aggregate: 'count'`
+ * returns that same row count as the value.
+ *
+ * The window, when `start`/`end` are not given, is the data's own: the
+ * bucket holding the first sample through the bucket holding the last.
+ * Pass them when an empty edge matters — an empty Monday is only a
+ * missing Monday once the caller says the week starts then.
+ *
+ * The five fill policies decide what an **empty** bucket says, and
+ * nothing else — a bucket that held rows and no numbers reports `null`
+ * because that is a measurement:
+ *
+ * | fill | an empty bucket |
+ * |---|---|
+ * | `omit` | is not emitted (the default: a gap is not a row) |
+ * | `null` | is emitted as `null` |
+ * | `zero` | is emitted as `0` |
+ * | `locf` | repeats the last value before it |
+ * | `linear` | is interpolated between its two neighbours |
+ *
+ * Neither `locf` nor `linear` invents a value at the leading edge, and
+ * `linear` needs a value on **both** sides: with no anchor to carry or
+ * to interpolate from, the bucket stays `null`. To seed one, widen the
+ * window until the earlier reading falls inside it — the seed is then a
+ * bucket with data, which is the only kind of anchor this function will
+ * extrapolate from. (With `aggregate: 'count'` an empty bucket is `0` by
+ * definition, so fill only decides whether it appears at all.)
+ *
+ * @param {any[]} rows - the samples, in any order
+ * @param {Object} spec
+ * @param {number | string} spec.every - the bucket width
+ * @param {number | string} [spec.origin] - where a boundary falls
+ *   (default: local `1970-01-01T00:00:00` on the clock)
+ * @param {number | string} [spec.start] - the half-open window's start
+ * @param {number | string} [spec.end] - the half-open window's end
+ * @param {'sum'|'mean'|'min'|'max'|'first'|'last'|'count'} [spec.aggregate]
+ *   default `'mean'`
+ * @param {'omit'|'null'|'zero'|'locf'|'linear'} [spec.fill] default `'omit'`
+ * @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] - where
+ *   the instant lives in a source row (default `'at'`)
+ * @param {string | ((item: any, index: number) => any)} [spec.value]
+ *   where the reading lives (default `'value'`)
+ * @returns {{ at: number, value: number | null, count: number }[]}
+ * @throws {TypeError} for a bad width, origin, window, aggregate or fill,
+ *   or a row that is not a canonical sample
+ * @example
+ * resampleSeries(readings, { every: 'PT1H', aggregate: 'mean', fill: 'linear' });
+ * resampleSeries(readings, { every: 'P1M', zone: 'Europe/Amsterdam', provider });
+ */
+export declare function resampleSeries(rows: any[], spec: {
+    every: number | string;
+    origin?: number | string;
+    start?: number | string;
+    end?: number | string;
+    aggregate?: 'sum' | 'mean' | 'min' | 'max' | 'first' | 'last' | 'count';
+    fill?: 'omit' | 'null' | 'zero' | 'locf' | 'linear';
+    zone?: string;
+    offset?: number;
+    provider?: import('./zone.js').ZoneProvider;
+    disambiguation?: 'reject' | 'earlier' | 'later';
+    at?: string | ((item: any, index: number) => any);
+    value?: string | ((item: any, index: number) => any);
+}): {
+    at: number;
+    value: number | null;
+    count: number;
+}[];

package/dist/types/series/downsample.d.ts

@@ -0,0 +1,53 @@
+export type Sample = import('./normalize.js').Sample;
+export type Downsampled = {
+    /**
+     * - the kept
+     * samples, ascending, with every gap still a gap
+     */
+    points: (Sample & Record<string, any>)[];
+    /**
+     * - how many samples went in
+     */
+    sourceCount: number;
+    /**
+     * - how many came out; never more than
+     * `target`, and less when a bucket's two extremes were one point
+     */
+    renderedCount: number;
+    /**
+     * - which strategy chose them
+     */
+    method: string;
+};
+/**
+ * `downsampleSeries`' closed specification: how many points may come
+ * back, which strategy chooses them, and where a row keeps its
+ * instant and its reading.
+ */
+export declare const DOWNSAMPLE_MEMBERS: readonly string[];
+/**
+ * Reduce a series to at most `target` points without bridging a gap or
+ * moving an end.
+ *
+ * @param {any[]} rows - the samples, in any order
+ * @param {Object} spec
+ * @param {number} spec.target - the most points to return, at least the
+ *   mandatory endpoints and gap markers
+ * @param {'lttb'|'minmax'} [spec.method] default `'lttb'`
+ * @param {string | ((item: any, index: number) => any)} [spec.at]
+ * @param {string | ((item: any, index: number) => any)} [spec.value]
+ * @returns {Downsampled}
+ * @throws {TypeError} for an unknown method, a target that is not a
+ *   positive whole number, or a row that is not a canonical sample
+ * @throws {RangeError} when `target` cannot hold the segment endpoints
+ *   and gap markers the data requires
+ * @example
+ * const { points, sourceCount, renderedCount } =
+ *   downsampleSeries(readings, { target: 800 });
+ */
+export declare function downsampleSeries(rows: any[], spec: {
+    target: number;
+    method?: 'lttb' | 'minmax';
+    at?: string | ((item: any, index: number) => any);
+    value?: string | ((item: any, index: number) => any);
+}): Downsampled;

package/dist/types/series/index.d.ts

@@ -0,0 +1,8 @@
+export { toEpoch, normalizeSeries, canonicalSeries, normalizeIntervals, lowerBoundTime, upperBoundTime, } from './normalize.js';
+export { containsInstant, overlapsInterval, intersectInterval, mergeIntervals, subtractIntervals, gapsWithin, coverageOf, findSlots, MERGE_MEMBERS, SLOTS_MEMBERS, } from './interval.js';
+export { createIntervalIndex } from './interval-index.js';
+export { resolveClock, CLOCK_MEMBERS } from './zone.js';
+export { compileBuckets, resampleSeries, RESAMPLE_MEMBERS } from './bucket.js';
+export { rollingSeries, ROLLING_MEMBERS } from './rolling.js';
+export { asOfJoin, ASOF_MEMBERS } from './asof.js';
+export { downsampleSeries, DOWNSAMPLE_MEMBERS } from './downsample.js';

package/dist/types/series/interval-index.d.ts

@@ -0,0 +1,47 @@
+export type IntervalIndex = {
+    /**
+     * - how many intervals were indexed
+     */
+    size: number;
+    /**
+     * - the items whose
+     * `[start, end)` contains this instant
+     */
+    at: (at: number | string) => any[];
+    /**
+     * - the items sharing an instant with `[start, end)`
+     */
+    overlapping: (start: number | string, end: number | string) => any[];
+};
+/**
+ * Build a queryable index over `[start, end)` intervals.
+ *
+ * Both queries answer with the caller's own items, ascending by start
+ * and — for items sharing a start — in the order they were given. Every
+ * result is a fresh array, so a caller can sort or splice it without
+ * reaching into the index.
+ *
+ * Bounds are read once at build time through the selectors, as epoch
+ * milliseconds or RFC 3339 strings, and an interval that is empty,
+ * reversed or names no instant is refused here rather than being
+ * skipped: an index quietly holding fewer rows than it was given
+ * answers every later question wrongly.
+ *
+ * @param {any[]} items - the rows, in any order
+ * @param {Object} [selectors]
+ * @param {string | ((item: any, index: number) => any)} [selectors.start]
+ *   where the lower bound lives (default `'start'`)
+ * @param {string | ((item: any, index: number) => any)} [selectors.end]
+ *   where the upper bound lives (default `'end'`)
+ * @returns {IntervalIndex}
+ * @throws {TypeError} for a non-array, a row that is not an object, a
+ *   bound that names no instant, or `end <= start`
+ * @example
+ * const index = createIntervalIndex(bookings, { start: 'from', end: 'to' });
+ * index.at('2026-03-01T10:00:00Z');              // who is booked then
+ * index.overlapping(dayStart, dayEnd);           // everything touching today
+ */
+export declare function createIntervalIndex(items: any[], selectors?: {
+    start?: string | ((item: any, index: number) => any);
+    end?: string | ((item: any, index: number) => any);
+}): IntervalIndex;

package/dist/types/series/interval.d.ts

@@ -0,0 +1,170 @@
+export type Interval = import('./normalize.js').Interval;
+/**
+ * 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 declare function containsInstant(interval: Interval, at: number | string): boolean;
+/**
+ * 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 declare function overlapsInterval(a: Interval, b: Interval): boolean;
+/**
+ * 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 declare function intersectInterval(a: Interval, b: Interval): Interval | null;
+/**
+ * `mergeIntervals`' closed specification: whether spans that touch
+ * join, which availability normally wants and a handover does not.
+ */
+export declare const MERGE_MEMBERS: readonly string[];
+/**
+ * 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 declare function mergeIntervals(intervals: Interval[], options?: {
+    adjacent?: boolean;
+}): Interval[];
+/**
+ * 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 declare function subtractIntervals(from: Interval[], remove: Interval[]): Interval[];
+/**
+ * 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 declare function gapsWithin(intervals: Interval[], within?: Interval): Interval[];
+/**
+ * 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 declare function coverageOf(intervals: Interval[], within?: Interval): number;
+/**
+ * `findSlots`' closed specification: how long a slot is and how far
+ * apart two of them start. Enumeration, never a constraint solver.
+ */
+export declare const SLOTS_MEMBERS: readonly string[];
+/**
+ * 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 declare function findSlots(availability: Interval[], spec: {
+    duration: number | string;
+    step?: number | string;
+}): Interval[];

package/dist/types/series/normalize.d.ts

@@ -0,0 +1,190 @@
+export type Sample = {
+    /**
+     * - Unix epoch milliseconds
+     */
+    at: number;
+    /**
+     * - the reading, or `null` for a
+     * measured gap
+     */
+    value: number | null;
+};
+export type Interval = {
+    /**
+     * - inclusive lower bound, epoch milliseconds
+     */
+    start: number;
+    /**
+     * - exclusive upper bound, epoch milliseconds
+     */
+    end: number;
+};
+/**
+ * @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 declare function toEpoch(value: number | string): number;
+/**
+ * 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 declare function epochAt(value: any, role: string, index: number): number;
+/**
+ * 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 declare function normalizeSeries(rows: any[], options?: {
+    at?: string | ((item: any, index: number) => any);
+    value?: string | ((item: any, index: number) => any);
+}): (Sample & Record<string, any>)[];
+/**
+ * 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 declare function canonicalSeries(rows: any[], options?: {
+    at?: string | ((item: any, index: number) => any);
+    value?: string | ((item: any, index: number) => any);
+}): (Sample & Record<string, any>)[];
+/**
+ * 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 declare function normalizeIntervals(rows: any[], options?: {
+    start?: string | ((item: any, index: number) => any);
+    end?: string | ((item: any, index: number) => any);
+}): (Interval & Record<string, any>)[];
+/**
+ * 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 declare function lowerBoundTime(rows: any[], at: number, key?: string): number;
+/**
+ * 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 declare function upperBoundTime(rows: any[], at: number, key?: string): number;