@jarenjs/core 0.46.5 → 0.56.0

package/dist/types/random.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The suite's one seeded generator, and the three draws built on
+ * it. Every seeded corpus, oracle and property test in this repository
+ * needs the same thing: a stream of numbers that is identical on every
+ * host for a given seed, so that a benchmark can state a delta and a
+ * failing property test can be replayed. Before this file that stream
+ * was written ten times; a generator that exists once is one whose
+ * sequence can be pinned once.
+ *
+ * The algorithm is mulberry32 — a 32-bit state, one multiply-xorshift
+ * round per draw, a period of 2^32. It is named by its algorithm rather
+ * than by its role because the SEQUENCE is the contract: a corpus
+ * generated from seed 20260825 must regenerate byte-for-byte, and a
+ * "better" generator under the same name would silently change every
+ * fixture that trusts it. A second algorithm gets a second name.
+ *
+ * Nothing here is cryptographic, and nothing here reads `Math.random`.
+ */
+/**
+ * A seeded generator: uniform in `[0, 1)`, identical on every host for
+ * the same seed.
+ *
+ * The seed is taken as an unsigned 32-bit integer (`seed >>> 0`, the
+ * ToUint32 conversion): `1.5` seeds as `1`, `-1` as `4294967295`,
+ * `2^32 + 5` as `5`, and `NaN` as `0`. Two seeds that agree modulo 2^32
+ * are one stream — say so wherever a seed is published.
+ * @param {number} seed
+ * @returns {() => number} the stream; each call is the next draw
+ */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * One integer draw over the half-open range `[min, max)`: `min +
+ * floor(random() * (max - min))`.
+ *
+ * This is the floor draw and deliberately so. Every committed corpus in
+ * the suite was generated with exactly this arithmetic, and a generator
+ * whose integer draw changed would regenerate every one of them
+ * differently. It is uniform up to a bias bounded by `(max - min) /
+ * 2^32` — under one part in a million for a span of four thousand, and
+ * far below anything a benchmark row can resolve. A draw that rejects
+ * to remove even that bias would be a different function under a
+ * different name, not a change to this one.
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} min - inclusive integer lower bound
+ * @param {number} max - exclusive integer upper bound; must exceed `min`
+ * @returns {number} an integer in `[min, max)`
+ * @throws {RangeError} when a bound is not an integer or `max <= min`
+ */
+export declare function randomInt(random: () => number, min: number, max: number): number;
+/**
+ * Fisher–Yates, in place, from the given stream: for `i` from the last
+ * index down to 1, swap `i` with a uniform `j` in `[0, i]`. Returns the
+ * same array. An empty or one-element list draws nothing.
+ *
+ * The descending form is the one the seeded corpora were generated
+ * with; the ascending form is a different permutation of the same
+ * stream and must not be substituted.
+ * @template T
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {T[]} list - reordered in place
+ * @returns {T[]} `list`
+ */
+export declare function shuffle<T>(random: () => number, list: T[]): T[];
+/**
+ * `k` distinct indices from `[0, n)`, uniformly, as a partial forward
+ * Fisher–Yates over a fresh index pool: the first `k` positions of a
+ * shuffle, without paying for the rest. Asked for more than `n` it
+ * answers `n` — a draw cannot invent a member the population does not
+ * hold; asked for nothing, or from nothing, it answers `[]`.
+ *
+ * The stream is the caller's, so one stream can serve many draws
+ * (a policy that draws per question from one seeded closure stays
+ * reproducible across the whole run).
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} n - the population size (a non-negative integer)
+ * @param {number} k - how many to draw (a non-negative integer)
+ * @returns {number[]} `min(k, n)` distinct indices, in draw order
+ * @throws {RangeError} when `n` or `k` is not a non-negative integer
+ */
+export declare function drawDistinct(random: () => number, n: number, k: number): number[];

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

@@ -0,0 +1,88 @@
+export type Sample = import('./normalize.js').Sample;
+export type AsOfMatch = {
+    /**
+     * - the canonical left sample
+     */
+    left: any;
+    /**
+     * - the canonical right sample, or `null`
+     */
+    right: any | null;
+    /**
+     * - milliseconds between the two
+     * instants, never negative; `null` when there was no match
+     */
+    distance: number | null;
+};
+/**
+ * `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 declare const ASOF_MEMBERS: readonly string[];
+/**
+ * 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 declare function asOfJoin(left: any[], right: any[], spec?: {
+    direction?: 'backward' | 'forward' | 'nearest';
+    tolerance?: number | string;
+    key?: string | ((item: any, index: number) => any);
+    left?: {
+        at?: any;
+        value?: any;
+        key?: any;
+    };
+    right?: {
+        at?: any;
+        value?: any;
+        key?: any;
+    };
+}): AsOfMatch[];

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[];