pond-ts 0.1.0

package/dist/TimeSeries.js

@@ -0,0 +1,1217 @@
+import { BoundedSequence } from './BoundedSequence.js';
+import { parseTimestampString } from './calendar.js';
+import { Interval } from './Interval.js';
+import { Time } from './Time.js';
+import { TimeRange } from './TimeRange.js';
+import { Sequence } from './Sequence.js';
+import { validateAndNormalize } from './validate.js';
+function isObjectRow(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseJsonTimestamp(value, options = {}) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('expected finite timestamp');
+        }
+        return value;
+    }
+    if (typeof value === 'string') {
+        return parseTimestampString(value, options);
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    throw new TypeError('expected timestamp as number or string');
+}
+function parseJsonKey(kind, value, options = {}) {
+    if (value instanceof Time ||
+        value instanceof TimeRange ||
+        value instanceof Interval) {
+        return value;
+    }
+    switch (kind) {
+        case 'time':
+            return new Time(parseJsonTimestamp(value, options));
+        case 'timeRange':
+            if (Array.isArray(value) && value.length === 2) {
+                return new TimeRange({
+                    start: parseJsonTimestamp(value[0], options),
+                    end: parseJsonTimestamp(value[1], options),
+                });
+            }
+            if (typeof value === 'object' &&
+                value !== null &&
+                'start' in value &&
+                'end' in value &&
+                !('value' in value)) {
+                return new TimeRange({
+                    start: parseJsonTimestamp(value.start, options),
+                    end: parseJsonTimestamp(value.end, options),
+                });
+            }
+            throw new TypeError('expected timeRange as [start, end] or { start, end }');
+        case 'interval':
+            if (Array.isArray(value) && value.length === 3) {
+                return new Interval({
+                    value: value[0],
+                    start: parseJsonTimestamp(value[1], options),
+                    end: parseJsonTimestamp(value[2], options),
+                });
+            }
+            if (typeof value === 'object' &&
+                value !== null &&
+                'value' in value &&
+                'start' in value &&
+                'end' in value) {
+                return new Interval({
+                    value: value.value,
+                    start: parseJsonTimestamp(value.start, options),
+                    end: parseJsonTimestamp(value.end, options),
+                });
+            }
+            throw new TypeError('expected interval as [value, start, end] or { value, start, end }');
+    }
+}
+function parseJsonRows(schema, rows, options = {}) {
+    return rows.map((row) => {
+        const values = isObjectRow(row)
+            ? schema.map((column) => row[column.name])
+            : row;
+        return Object.freeze(values.map((value, index) => {
+            if (value === null) {
+                return undefined;
+            }
+            const column = schema[index];
+            if (index === 0) {
+                return parseJsonKey(column.kind, value, options);
+            }
+            return value;
+        }));
+    });
+}
+function toRows(schema, events) {
+    return events.map((event) => {
+        const data = event.data();
+        return Object.freeze([
+            event.key(),
+            ...schema
+                .slice(1)
+                .map((column) => data[column.name]),
+        ]);
+    });
+}
+function isEventKey(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'begin' in value &&
+        'end' in value);
+}
+function toBoundaryTimestamp(value) {
+    if (isEventKey(value)) {
+        return value.begin();
+    }
+    return value instanceof Date ? value.getTime() : value;
+}
+function toKey(value) {
+    if (isEventKey(value)) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 2) {
+            return new TimeRange(value);
+        }
+        return new Interval(value);
+    }
+    if (typeof value === 'object' && value !== null) {
+        if ('value' in value) {
+            return new Interval(value);
+        }
+        if ('start' in value && 'end' in value) {
+            return new TimeRange(value);
+        }
+    }
+    return new Time(value);
+}
+function toSelectionRange(value) {
+    if (value instanceof TimeRange) {
+        return value;
+    }
+    if (value instanceof Interval) {
+        return value.timeRange();
+    }
+    if (isEventKey(value)) {
+        return new TimeRange({ start: value.begin(), end: value.end() });
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 2) {
+            return new TimeRange(value);
+        }
+        return new Interval(value).timeRange();
+    }
+    if ('value' in value) {
+        return new Interval(value).timeRange();
+    }
+    return new TimeRange(value);
+}
+function toOptionalSeriesRange(value) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        'timeRange' in value &&
+        typeof value.timeRange === 'function') {
+        return value.timeRange() ?? undefined;
+    }
+    return toSelectionRange(value);
+}
+function makeAlignedSchema(schema) {
+    return Object.freeze([
+        { name: 'interval', kind: 'interval' },
+        ...schema.slice(1).map((column) => ({
+            ...column,
+            required: false,
+        })),
+    ]);
+}
+function sampleTime(interval, sample) {
+    return sample === 'center'
+        ? interval.begin() + interval.duration() / 2
+        : interval.begin();
+}
+function eventAnchorTime(key) {
+    return key instanceof Time ? key.begin() : key.timeRange().midpoint();
+}
+function loessAt(x, anchors, values, span) {
+    const points = anchors.flatMap((anchor, index) => {
+        const value = values[index];
+        return value === undefined ? [] : [{ x: anchor, y: value }];
+    });
+    if (points.length === 0) {
+        return undefined;
+    }
+    if (points.length === 1) {
+        return points[0].y;
+    }
+    const neighborCount = Math.max(2, Math.min(points.length, Math.ceil(span * points.length)));
+    const sortedDistances = points
+        .map((point) => ({ point, distance: Math.abs(point.x - x) }))
+        .sort((left, right) => left.distance - right.distance);
+    const bandwidth = sortedDistances[neighborCount - 1].distance;
+    if (bandwidth === 0) {
+        const coincident = sortedDistances
+            .filter((entry) => entry.distance === 0)
+            .map((entry) => entry.point.y);
+        return (coincident.reduce((sum, value) => sum + value, 0) / coincident.length);
+    }
+    let weightedCount = 0;
+    let sumW = 0;
+    let sumWX = 0;
+    let sumWY = 0;
+    let sumWXX = 0;
+    let sumWXY = 0;
+    for (const { point, distance } of sortedDistances.slice(0, neighborCount)) {
+        const ratio = distance / bandwidth;
+        const weight = ratio >= 1 ? 0 : (1 - ratio ** 3) ** 3;
+        if (weight === 0) {
+            continue;
+        }
+        weightedCount += 1;
+        sumW += weight;
+        sumWX += weight * point.x;
+        sumWY += weight * point.y;
+        sumWXX += weight * point.x * point.x;
+        sumWXY += weight * point.x * point.y;
+    }
+    if (weightedCount === 0 || sumW === 0) {
+        return undefined;
+    }
+    const denominator = sumW * sumWXX - sumWX * sumWX;
+    if (Math.abs(denominator) < Number.EPSILON) {
+        return sumWY / sumW;
+    }
+    const intercept = (sumWY * sumWXX - sumWX * sumWXY) / denominator;
+    const slope = (sumW * sumWXY - sumWX * sumWY) / denominator;
+    return intercept + slope * x;
+}
+function makeSmoothSchema(schema, target, output) {
+    if (output === undefined || output === target) {
+        return Object.freeze([
+            schema[0],
+            ...schema.slice(1).map((column) => column.name === target
+                ? {
+                    name: column.name,
+                    kind: 'number',
+                    required: false,
+                }
+                : column),
+        ]);
+    }
+    if (schema.slice(1).some((column) => column.name === output)) {
+        throw new TypeError(`smooth output column '${output}' already exists`);
+    }
+    return Object.freeze([
+        schema[0],
+        ...schema.slice(1),
+        { name: output, kind: 'number', required: false },
+    ]);
+}
+function toBoundedSequence(sequence, range, sample) {
+    return sequence instanceof BoundedSequence
+        ? sequence
+        : sequence.bounded(range, { sample });
+}
+function isTimeKeyed(series) {
+    return series.firstColumnKind === 'time';
+}
+function bucketContainsHalfOpen(bucket, timestamp) {
+    return timestamp >= bucket.begin() && timestamp < bucket.end();
+}
+function bucketOverlapsHalfOpen(bucket, event) {
+    if (event.begin() === event.end()) {
+        return bucketContainsHalfOpen(bucket, event.begin());
+    }
+    return event.begin() < bucket.end() && bucket.begin() < event.end();
+}
+function aggregateValues(operation, values) {
+    const defined = values.filter((value) => value !== undefined);
+    const numeric = defined.filter((value) => typeof value === 'number');
+    switch (operation) {
+        case 'count':
+            return defined.length;
+        case 'sum':
+            return numeric.reduce((sum, value) => sum + value, 0);
+        case 'avg':
+            return numeric.length === 0
+                ? undefined
+                : numeric.reduce((sum, value) => sum + value, 0) / numeric.length;
+        case 'min':
+            return numeric.length === 0
+                ? undefined
+                : numeric.reduce((left, right) => (left <= right ? left : right));
+        case 'max':
+            return numeric.length === 0
+                ? undefined
+                : numeric.reduce((left, right) => (left >= right ? left : right));
+        case 'first':
+            return defined[0];
+        case 'last':
+            return defined[defined.length - 1];
+    }
+}
+function parseDurationInput(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new TypeError('rolling window must be a positive finite number of milliseconds');
+        }
+        return value;
+    }
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+    if (!match) {
+        throw new TypeError(`unsupported duration '${value}'`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    const multiplier = unit === 'ms'
+        ? 1
+        : unit === 's'
+            ? 1_000
+            : unit === 'm'
+                ? 60_000
+                : unit === 'h'
+                    ? 3_600_000
+                    : 86_400_000;
+    return amount * multiplier;
+}
+function duplicateValueColumnNames(schemas) {
+    const counts = new Map();
+    for (const schema of schemas) {
+        for (const column of schema.slice(1)) {
+            counts.set(column.name, (counts.get(column.name) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([name]) => name)
+        .sort();
+}
+function assertDistinctValueColumns(schemas, message) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const schema of schemas) {
+        for (const column of schema.slice(1)) {
+            if (seen.has(column.name)) {
+                duplicates.add(column.name);
+            }
+            else {
+                seen.add(column.name);
+            }
+        }
+    }
+    if (duplicates.size > 0) {
+        throw new TypeError(`${message}: ${[...duplicates].sort().join(', ')}`);
+    }
+}
+function buildConflictRenameMap(schema, duplicates, prefix) {
+    const renameMap = {};
+    for (const column of schema.slice(1)) {
+        if (duplicates.has(column.name)) {
+            renameMap[column.name] = `${prefix}_${column.name}`;
+        }
+    }
+    return renameMap;
+}
+function prepareSeriesForJoin(series, options) {
+    const conflictMode = options.onConflict ?? 'error';
+    const duplicates = duplicateValueColumnNames(series.map((item) => item.schema));
+    if (duplicates.length === 0) {
+        return series;
+    }
+    if (conflictMode === 'error') {
+        throw new TypeError(`cannot join series with duplicate column names: ${duplicates.join(', ')}`);
+    }
+    const prefixOptions = options;
+    if (prefixOptions.prefixes.length !== series.length) {
+        throw new TypeError(`prefix conflict handling requires exactly ${series.length} prefixes`);
+    }
+    const duplicateSet = new Set(duplicates);
+    const renamedSeries = series.map((item, index) => {
+        const renameMap = buildConflictRenameMap(item.schema, duplicateSet, prefixOptions.prefixes[index]);
+        return item.rename(renameMap);
+    });
+    assertDistinctValueColumns(renamedSeries.map((item) => item.schema), 'prefix conflict handling still produced duplicate column names');
+    return renamedSeries;
+}
+/**
+ * An immutable ordered collection of typed events sharing a common schema.
+ *
+ * @example
+ * ```ts
+ * const schema = [
+ *   { name: "time", kind: "time" },
+ *   { name: "cpu", kind: "number" },
+ *   { name: "host", kind: "string" },
+ * ] as const;
+ *
+ * const series = new TimeSeries({
+ *   name: "cpu-usage",
+ *   schema,
+ *   rows: [[new Date("2025-01-01T00:00:00.000Z"), 0.42, "api-1"]],
+ * });
+ *
+ * series.first()?.get("cpu"); // 0.42
+ * series.timeRange(); // overall extent of the series
+ * series.within(new TimeRange({ start: 0, end: Date.now() })); // fully contained events
+ * series.align(Sequence.every("1m")); // uses the series range over an epoch-anchored minute grid
+ * ```
+ */
+export class TimeSeries {
+    name;
+    schema;
+    events;
+    static joinMany(series, options = {}) {
+        const prepared = prepareSeriesForJoin(series, options);
+        const [first, ...rest] = prepared;
+        let joined = first;
+        for (const next of rest) {
+            joined =
+                options.type === undefined
+                    ? joined.join(next)
+                    : joined.join(next, {
+                        type: options.type,
+                    });
+        }
+        return joined;
+    }
+    /**
+     * Example: `TimeSeries.fromJSON({ name, schema, rows, parse: { timeZone: "Europe/Madrid" } })`.
+     * Creates a typed series from JSON-style row arrays or object rows keyed by schema column names.
+     *
+     * `null` values are treated as missing values. Ambiguous local timestamp strings are parsed using
+     * the supplied `parse.timeZone`, which defaults to `UTC`.
+     */
+    static fromJSON(input) {
+        return new TimeSeries({
+            name: input.name,
+            schema: input.schema,
+            rows: parseJsonRows(input.schema, input.rows, input.parse),
+        });
+    }
+    /** Example: `new TimeSeries({ name, schema, rows })`. Creates an immutable time series from a schema and row-oriented input data. */
+    constructor(input) {
+        this.name = input.name;
+        this.schema = Object.freeze(input.schema.slice());
+        this.events = validateAndNormalize(input);
+        Object.freeze(this);
+    }
+    /** Example: `series.firstColumnKind`. Returns the first-column kind from the series schema. */
+    get firstColumnKind() {
+        return this.schema[0].kind;
+    }
+    /** Example: `series.rows`. Returns the normalized row view of the series. */
+    get rows() {
+        return toRows(this.schema, this.events);
+    }
+    /** Example: `series.at(0)`. Returns the event at the supplied zero-based position, if present. */
+    at(index) {
+        return this.events[index];
+    }
+    /** Example: `series.first()`. Returns the first event in the series, if present. */
+    first() {
+        return this.at(0);
+    }
+    /** Example: `series.last()`. Returns the last event in the series, if present. */
+    last() {
+        return this.events.length === 0
+            ? undefined
+            : this.events[this.events.length - 1];
+    }
+    /** Example: `series.map(nextSchema, event => event)`. Maps each event into a new typed schema and returns a new series. */
+    map(schema, mapper) {
+        const mappedEvents = this.events.map((event, index) => mapper(event, index));
+        return new TimeSeries({
+            name: this.name,
+            schema,
+            rows: toRows(schema, mappedEvents),
+        });
+    }
+    /** Example: `series.asTime({ at: "center" })`. Converts the series key type to `"time"` using the supplied anchor within each event extent. */
+    asTime(options = {}) {
+        const schema = Object.freeze([
+            { name: 'time', kind: 'time' },
+            ...this.schema.slice(1),
+        ]);
+        return new TimeSeries({
+            name: this.name,
+            schema,
+            rows: toRows(schema, this.events.map((event) => event.asTime(options))),
+        });
+    }
+    /** Example: `series.asTimeRange()`. Converts the series key type to `"timeRange"` while preserving each event extent. */
+    asTimeRange() {
+        const schema = Object.freeze([
+            { name: 'timeRange', kind: 'timeRange' },
+            ...this.schema.slice(1),
+        ]);
+        return new TimeSeries({
+            name: this.name,
+            schema,
+            rows: toRows(schema, this.events.map((event) => event.asTimeRange())),
+        });
+    }
+    asInterval(value) {
+        const schema = Object.freeze([
+            { name: 'interval', kind: 'interval' },
+            ...this.schema.slice(1),
+        ]);
+        const nextEvents = this.events.map((event, index) => {
+            return typeof value === 'function'
+                ? event.asInterval(() => value(event, index))
+                : event.asInterval(value);
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema,
+            rows: toRows(schema, nextEvents),
+        });
+    }
+    join(other, options = {}) {
+        const [left, right] = prepareSeriesForJoin([this, other], options);
+        const joinType = options.type ?? 'outer';
+        if (left.firstColumnKind !== right.firstColumnKind) {
+            throw new TypeError('cannot join series with different key kinds');
+        }
+        const resultSchema = Object.freeze([
+            left.schema[0],
+            ...left.schema
+                .slice(1)
+                .map((column) => ({ ...column, required: false })),
+            ...right.schema
+                .slice(1)
+                .map((column) => ({ ...column, required: false })),
+        ]);
+        const joinedEvents = [];
+        let leftIndex = 0;
+        let rightIndex = 0;
+        while (leftIndex < left.events.length || rightIndex < right.events.length) {
+            const leftEvent = left.events[leftIndex];
+            const rightEvent = right.events[rightIndex];
+            if (leftEvent && !rightEvent) {
+                if (joinType === 'left' || joinType === 'outer') {
+                    joinedEvents.push(leftEvent.merge({}));
+                }
+                leftIndex += 1;
+                continue;
+            }
+            if (rightEvent && !leftEvent) {
+                if (joinType === 'right' || joinType === 'outer') {
+                    joinedEvents.push(rightEvent.merge({}));
+                }
+                rightIndex += 1;
+                continue;
+            }
+            const comparison = leftEvent.key().compare(rightEvent.key());
+            if (comparison === 0) {
+                joinedEvents.push(leftEvent.merge(rightEvent.data()));
+                leftIndex += 1;
+                rightIndex += 1;
+            }
+            else if (comparison < 0) {
+                if (joinType === 'left' || joinType === 'outer') {
+                    joinedEvents.push(leftEvent.merge({}));
+                }
+                leftIndex += 1;
+            }
+            else {
+                if (joinType === 'right' || joinType === 'outer') {
+                    joinedEvents.push(rightEvent.merge({}));
+                }
+                rightIndex += 1;
+            }
+        }
+        return new TimeSeries({
+            name: left.name,
+            schema: resultSchema,
+            rows: toRows(resultSchema, joinedEvents),
+        });
+    }
+    /**
+     * Example: `series.align(Sequence.every("1m"))`.
+     * Aligns the series onto a `Sequence` grid or `BoundedSequence` and returns an interval-keyed series.
+     *
+     * `hold` carries forward the latest known value to each sample position. `linear` interpolates
+     * numeric columns between neighboring time-keyed events and falls back to hold behavior for
+     * non-numeric columns. Aligned columns are optional because edge buckets may have no value.
+     *
+     * Defaults:
+     * - `method`: `"hold"`
+     * - `sample`: `"begin"`
+     * - `range`: `series.timeRange()`
+     *
+     * For `Sequence` inputs, the sequence anchor still comes from the grid definition itself. For
+     * procedural sequences created with `Sequence.every(...)`, that anchor defaults to Unix epoch
+     * `0`. The `range` only decides which finite slice of that grid is bounded for this alignment.
+     *
+     * When a `BoundedSequence` is supplied, its intervals are used directly.
+     *
+     * Example:
+     * - `Sequence.every("1m")` defines an epoch-anchored minute grid
+     * - `series.align(Sequence.every("1m"))` aligns onto the slice of that minute grid spanning the
+     *   current series extent
+     */
+    align(sequence, options = {}) {
+        const method = options.method ?? 'hold';
+        const sample = options.sample ?? 'begin';
+        const range = options.range ?? this.timeRange();
+        const resultSchema = makeAlignedSchema(this.schema);
+        if (!range) {
+            return new TimeSeries({
+                name: this.name,
+                schema: resultSchema,
+                rows: [],
+            });
+        }
+        if (method === 'linear' && !isTimeKeyed(this)) {
+            throw new TypeError('linear alignment currently requires a time-keyed series');
+        }
+        const intervals = toBoundedSequence(sequence, range, sample).intervals();
+        const valueColumns = this.schema.slice(1);
+        const alignedRows = intervals.map((interval) => {
+            const t = sampleTime(interval, sample);
+            const data = method === 'linear'
+                ? this.#alignLinearAt(t, valueColumns)
+                : this.#alignHoldAt(t);
+            return Object.freeze([
+                interval,
+                ...resultSchema
+                    .slice(1)
+                    .map((column) => data[column.name]),
+            ]);
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: alignedRows,
+        });
+    }
+    /**
+     * Example: `series.aggregate(Sequence.every("1m"), { value: "avg" })`.
+     * Aggregates events into sequence buckets using built-in reducer names.
+     *
+     * Buckets use half-open membership semantics: `[begin, end)`. Point events contribute to the
+     * bucket containing their timestamp. Interval-like events contribute to every bucket they
+     * overlap under half-open overlap rules.
+     *
+     * Defaults:
+     * - `range`: `series.timeRange()`
+     *
+     * As with `align(...)`, `Sequence` defines the underlying grid and `range` selects which portion
+     * of that grid is bounded. With `Sequence.every(...)`, the default grid anchor is Unix epoch `0`,
+     * but the default aggregation range is always the source series extent. When a
+     * `BoundedSequence` is supplied, its intervals are used directly.
+     *
+     * Override `range` when you need multiple series aggregated over the same reporting window,
+     * including leading or trailing empty buckets outside an individual series extent.
+     *
+     * To align buckets to the beginning of the current series instead of epoch boundaries, override
+     * the sequence anchor rather than the aggregation range:
+     *
+     * ```ts
+     * const range = series.timeRange();
+     * if (!range) {
+     *   throw new Error("empty series");
+     * }
+     *
+     * const aggregated = series.aggregate(
+     *   Sequence.every("1m", { anchor: range.begin() }),
+     *   { value: "avg" },
+     * );
+     * ```
+     */
+    aggregate(sequence, mapping, options = {}) {
+        const range = options.range ?? this.timeRange();
+        const resultSchema = Object.freeze([
+            { name: 'interval', kind: 'interval' },
+            ...this.schema
+                .slice(1)
+                .filter((column) => column.name in mapping)
+                .map((column) => {
+                const operation = mapping[column.name];
+                return {
+                    name: column.name,
+                    kind: operation === 'sum' ||
+                        operation === 'avg' ||
+                        operation === 'count'
+                        ? 'number'
+                        : column.kind,
+                    required: false,
+                };
+            }),
+        ]);
+        if (!range) {
+            return new TimeSeries({
+                name: this.name,
+                schema: resultSchema,
+                rows: [],
+            });
+        }
+        const buckets = toBoundedSequence(sequence, range, 'begin').intervals();
+        const resultRows = buckets.map((bucket) => {
+            const contributors = this.events.filter((event) => bucketOverlapsHalfOpen(bucket, event.key()));
+            const aggregated = resultSchema.slice(1).map((column) => {
+                const operation = mapping[column.name];
+                const values = contributors.map((event) => {
+                    const data = event.data();
+                    return data[column.name];
+                });
+                return aggregateValues(operation, values);
+            });
+            return Object.freeze([bucket, ...aggregated]);
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: resultRows,
+        });
+    }
+    rolling(sequenceOrWindow, windowOrMapping, mappingOrOptions, maybeOptions = {}) {
+        const buildResultColumns = () => this.schema
+            .slice(1)
+            .filter((column) => column.name in mapping)
+            .map((column) => {
+            const operation = mapping[column.name];
+            return {
+                name: column.name,
+                kind: operation === 'sum' ||
+                    operation === 'avg' ||
+                    operation === 'count'
+                    ? 'number'
+                    : column.kind,
+                required: false,
+            };
+        });
+        let mapping;
+        let options;
+        let sequence;
+        let window;
+        if (sequenceOrWindow instanceof Sequence ||
+            sequenceOrWindow instanceof BoundedSequence) {
+            sequence = sequenceOrWindow;
+            window = windowOrMapping;
+            mapping = mappingOrOptions;
+            options = maybeOptions;
+        }
+        else {
+            window = sequenceOrWindow;
+            mapping = windowOrMapping;
+            options =
+                mappingOrOptions ??
+                    {};
+        }
+        const windowMs = parseDurationInput(window);
+        const alignment = options.alignment ?? 'trailing';
+        const anchorInWindow = (candidate, anchor) => {
+            if (alignment === 'trailing') {
+                return candidate > anchor - windowMs && candidate <= anchor;
+            }
+            if (alignment === 'leading') {
+                return candidate >= anchor && candidate < anchor + windowMs;
+            }
+            const halfWindow = windowMs / 2;
+            return (candidate >= anchor - halfWindow && candidate < anchor + halfWindow);
+        };
+        if (sequence) {
+            const sample = options.sample ?? 'begin';
+            const range = options.range ?? this.timeRange();
+            const resultSchema = Object.freeze([
+                { name: 'interval', kind: 'interval' },
+                ...buildResultColumns(),
+            ]);
+            if (!range) {
+                return new TimeSeries({
+                    name: this.name,
+                    schema: resultSchema,
+                    rows: [],
+                });
+            }
+            const buckets = toBoundedSequence(sequence, range, sample).intervals();
+            const resultRows = buckets.map((bucket) => {
+                const anchor = sampleTime(bucket, sample);
+                const contributors = this.events.filter((candidate) => anchorInWindow(candidate.begin(), anchor));
+                const aggregated = resultSchema.slice(1).map((column) => {
+                    const operation = mapping[column.name];
+                    const values = contributors.map((candidate) => {
+                        const data = candidate.data();
+                        return data[column.name];
+                    });
+                    return aggregateValues(operation, values);
+                });
+                return Object.freeze([bucket, ...aggregated]);
+            });
+            return new TimeSeries({
+                name: this.name,
+                schema: resultSchema,
+                rows: resultRows,
+            });
+        }
+        const resultSchema = Object.freeze([
+            this.schema[0],
+            ...buildResultColumns(),
+        ]);
+        const resultRows = this.events.map((event) => {
+            const anchor = event.begin();
+            const contributors = this.events.filter((candidate) => anchorInWindow(candidate.begin(), anchor));
+            const aggregated = resultSchema.slice(1).map((column) => {
+                const operation = mapping[column.name];
+                const values = contributors.map((candidate) => {
+                    const data = candidate.data();
+                    return data[column.name];
+                });
+                return aggregateValues(operation, values);
+            });
+            return Object.freeze([event.key(), ...aggregated]);
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: resultRows,
+        });
+    }
+    /**
+     * Example: `series.smooth("value", "ema", { alpha: 0.2 })`.
+     * Applies a smoothing transform to one numeric payload column while preserving the original key
+     * type, key values, and all non-target payload fields.
+     *
+     * Example: `series.smooth("value", "movingAverage", { window: "5m", alignment: "centered", output: "valueAvg" })`.
+     * Computes a moving average over the selected numeric column using anchor points derived from
+     * event keys. `Time` keys use their timestamp. `TimeRange` and `Interval` keys use the midpoint
+     * of their extent.
+     *
+     * Example: `series.smooth("value", "loess", { span: 0.75 })`.
+     * Computes a LOESS-smoothed value for the selected numeric column using local weighted linear
+     * regression over those same anchor points.
+     *
+     * When `output` is omitted, the smoothed values replace the target column. When `output` is
+     * supplied, the smoothed values are appended as a new optional numeric column.
+     */
+    smooth(column, method, options) {
+        const output = options.output;
+        const resultSchema = output === undefined
+            ? makeSmoothSchema(this.schema, column)
+            : makeSmoothSchema(this.schema, column, output);
+        const anchors = this.events.map((event) => eventAnchorTime(event.key()));
+        const sourceValues = this.events.map((event) => {
+            const raw = event.get(column);
+            return typeof raw === 'number' ? raw : undefined;
+        });
+        if (method === 'ema') {
+            if (!('alpha' in options)) {
+                throw new TypeError('ema smoothing requires an alpha option');
+            }
+            const alpha = options.alpha;
+            if (typeof alpha !== 'number' ||
+                !Number.isFinite(alpha) ||
+                alpha <= 0 ||
+                alpha > 1) {
+                throw new TypeError('ema smoothing requires alpha to be a finite number in the range (0, 1]');
+            }
+            let previous;
+            const resultRows = this.events.map((event) => {
+                const raw = event.get(column);
+                const smoothed = typeof raw !== 'number'
+                    ? undefined
+                    : previous === undefined
+                        ? raw
+                        : alpha * raw + (1 - alpha) * previous;
+                if (smoothed !== undefined) {
+                    previous = smoothed;
+                }
+                const nextEvent = output === undefined
+                    ? event.set(column, smoothed)
+                    : event.merge({ [output]: smoothed });
+                return Object.freeze([
+                    nextEvent.key(),
+                    ...resultSchema
+                        .slice(1)
+                        .map((nextColumn) => nextEvent.data()[nextColumn.name]),
+                ]);
+            });
+            return new TimeSeries({
+                name: this.name,
+                schema: resultSchema,
+                rows: resultRows,
+            });
+        }
+        if (method === 'loess') {
+            if (!('span' in options)) {
+                throw new TypeError('loess smoothing requires a span option');
+            }
+            const span = options.span;
+            if (typeof span !== 'number' ||
+                !Number.isFinite(span) ||
+                span <= 0 ||
+                span > 1) {
+                throw new TypeError('loess smoothing requires span to be a finite number in the range (0, 1]');
+            }
+            const resultRows = this.events.map((event, index) => {
+                const smoothed = loessAt(anchors[index], anchors, sourceValues, span);
+                const nextEvent = output === undefined
+                    ? event.set(column, smoothed)
+                    : event.merge({ [output]: smoothed });
+                return Object.freeze([
+                    nextEvent.key(),
+                    ...resultSchema
+                        .slice(1)
+                        .map((nextColumn) => nextEvent.data()[nextColumn.name]),
+                ]);
+            });
+            return new TimeSeries({
+                name: this.name,
+                schema: resultSchema,
+                rows: resultRows,
+            });
+        }
+        if (!('window' in options)) {
+            throw new TypeError('movingAverage smoothing requires a window option');
+        }
+        const window = options.window;
+        const windowMs = parseDurationInput(window);
+        const alignment = options.alignment ?? 'trailing';
+        const anchorInWindow = (candidate, anchor) => {
+            if (alignment === 'trailing') {
+                return candidate > anchor - windowMs && candidate <= anchor;
+            }
+            if (alignment === 'leading') {
+                return candidate >= anchor && candidate < anchor + windowMs;
+            }
+            const halfWindow = windowMs / 2;
+            return (candidate >= anchor - halfWindow && candidate < anchor + halfWindow);
+        };
+        const resultRows = this.events.map((event, index) => {
+            const anchor = anchors[index];
+            const values = sourceValues
+                .filter((_, candidateIndex) => anchorInWindow(anchors[candidateIndex], anchor))
+                .flatMap((value) => (value === undefined ? [] : [value]));
+            const smoothed = values.length === 0
+                ? undefined
+                : values.reduce((sum, value) => sum + value, 0) / values.length;
+            const nextEvent = output === undefined
+                ? event.set(column, smoothed)
+                : event.merge({ [output]: smoothed });
+            return Object.freeze([
+                nextEvent.key(),
+                ...resultSchema
+                    .slice(1)
+                    .map((nextColumn) => nextEvent.data()[nextColumn.name]),
+            ]);
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: resultRows,
+        });
+    }
+    /** Example: `series.slice(0, 10)`. Returns a positional half-open slice of the series. */
+    slice(beginIndex, endIndex) {
+        return new TimeSeries({
+            name: this.name,
+            schema: this.schema,
+            rows: toRows(this.schema, this.events.slice(beginIndex, endIndex)),
+        });
+    }
+    /** Example: `series.filter(event => event.get("active"))`. Returns a new series containing only events that match the predicate. */
+    filter(predicate) {
+        return new TimeSeries({
+            name: this.name,
+            schema: this.schema,
+            rows: toRows(this.schema, this.events.filter((event, index) => predicate(event, index))),
+        });
+    }
+    /** Example: `series.find(event => event.get("value") > 0)`. Returns the first event that matches the predicate, if any. */
+    find(predicate) {
+        return this.events.find((event, index) => predicate(event, index));
+    }
+    /** Example: `series.some(event => event.get("healthy"))`. Returns `true` when at least one event matches the predicate. */
+    some(predicate) {
+        return this.events.some((event, index) => predicate(event, index));
+    }
+    /** Example: `series.every(event => event.get("healthy"))`. Returns `true` when every event matches the predicate. */
+    every(predicate) {
+        return this.events.every((event, index) => predicate(event, index));
+    }
+    /** Example: `series.includesKey(new Time(Date.now()))`. Returns `true` when the series contains an event with an exactly matching key. */
+    includesKey(key) {
+        const normalizedKey = toKey(key);
+        return this.events.some((event) => event.key().equals(normalizedKey));
+    }
+    /** Example: `series.bisect(new Time(Date.now()))`. Returns the insertion index for the supplied key in the ordered event sequence. */
+    bisect(key) {
+        const normalizedKey = toKey(key);
+        let low = 0;
+        let high = this.events.length;
+        while (low < high) {
+            const mid = Math.floor((low + high) / 2);
+            if (this.events[mid].key().compare(normalizedKey) < 0) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    /** Example: `series.atOrBefore(new Time(Date.now()))`. Returns the event with the exact key or the nearest earlier event, if any. */
+    atOrBefore(key) {
+        const normalizedKey = toKey(key);
+        const index = this.bisect(normalizedKey);
+        if (index < this.events.length &&
+            this.events[index].key().equals(normalizedKey)) {
+            return this.events[index];
+        }
+        return index === 0 ? undefined : this.events[index - 1];
+    }
+    /** Example: `series.atOrAfter(new Time(Date.now()))`. Returns the event with the exact key or the nearest later event, if any. */
+    atOrAfter(key) {
+        return this.events[this.bisect(key)];
+    }
+    /** Example: `series.timeRange()`. Returns the overall temporal extent of the series, if the series is not empty. */
+    timeRange() {
+        const first = this.first();
+        if (!first) {
+            return undefined;
+        }
+        const start = first.begin();
+        const end = this.events.reduce((maxEnd, event) => Math.max(maxEnd, event.end()), first.end());
+        return new TimeRange({ start, end });
+    }
+    /** Example: `series.overlaps(range)`. Returns `true` when the overall series extent overlaps the supplied temporal value. */
+    overlaps(other) {
+        const range = this.timeRange();
+        const otherRange = toOptionalSeriesRange(other);
+        if (!range || !otherRange) {
+            return false;
+        }
+        return range.overlaps(otherRange);
+    }
+    /** Example: `series.contains(range)`. Returns `true` when the overall series extent fully contains the supplied temporal value. */
+    contains(other) {
+        const range = this.timeRange();
+        const otherRange = toOptionalSeriesRange(other);
+        if (!range || !otherRange) {
+            return false;
+        }
+        return range.contains(otherRange);
+    }
+    /** Example: `series.intersection(range)`. Returns the overlap between the overall series extent and the supplied temporal value, if any. */
+    intersection(other) {
+        const range = this.timeRange();
+        const otherRange = toOptionalSeriesRange(other);
+        if (!range || !otherRange) {
+            return undefined;
+        }
+        return range.intersection(otherRange);
+    }
+    /**
+     * Example: `series.overlapping(range)`.
+     * Returns the portion of the series whose event extents overlap the supplied range.
+     *
+     * Unlike `within(...)`, this keeps partially overlapping events without modifying their keys.
+     * Use `trim(...)` when you want those overlapping keys clipped to the supplied range.
+     */
+    overlapping(range) {
+        return this.filter((event) => event.overlaps(range));
+    }
+    /**
+     * Example: `series.containedBy(range)`.
+     * Returns the portion of the series whose event extents are fully contained by the supplied range.
+     *
+     * This is the strict containment selector:
+     * events must start at or after the range start and end at or before the range end.
+     * Unlike `overlapping(...)`, partially overlapping events are excluded.
+     */
+    containedBy(range) {
+        const selectionRange = toSelectionRange(range);
+        return this.filter((event) => selectionRange.contains(event));
+    }
+    /**
+     * Example: `series.trim(range)`.
+     * Returns the series trimmed to the supplied range by clipping overlapping event keys.
+     *
+     * Non-overlapping events are dropped. Overlapping `TimeRange` and `Interval` keys are clipped
+     * to the supplied range. Overlapping `Time` keys are preserved unchanged.
+     */
+    trim(range) {
+        const trimmedEvents = this.events
+            .map((event) => event.trim(range))
+            .filter((event) => event !== undefined);
+        return new TimeSeries({
+            name: this.name,
+            schema: this.schema,
+            rows: toRows(this.schema, trimmedEvents),
+        });
+    }
+    /** Example: `series.before(Date.now())`. Returns the events ending strictly before the supplied temporal boundary. */
+    before(boundary) {
+        const limit = toBoundaryTimestamp(boundary);
+        return this.filter((event) => event.end() < limit);
+    }
+    /** Example: `series.after(Date.now())`. Returns the events beginning strictly after the supplied temporal boundary. */
+    after(boundary) {
+        const limit = toBoundaryTimestamp(boundary);
+        return this.filter((event) => event.begin() > limit);
+    }
+    within(beginOrRange, end) {
+        const range = end === undefined
+            ? toSelectionRange(beginOrRange)
+            : new TimeRange({ start: beginOrRange, end });
+        return this.filter((event) => event.begin() >= range.begin() && event.end() <= range.end());
+    }
+    /** Example: `series.select("cpu", "healthy")`. Returns a new series containing only the selected payload fields. */
+    select(...keys) {
+        const firstColumn = this.schema[0];
+        const selectedColumns = this.schema
+            .slice(1)
+            .filter((column) => keys.includes(column.name));
+        const resultSchema = Object.freeze([
+            firstColumn,
+            ...selectedColumns,
+        ]);
+        const resultEvents = this.events.map((event) => {
+            const selectedEvent = event.select(...keys);
+            return selectedEvent;
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: toRows(resultSchema, resultEvents),
+        });
+    }
+    /** Example: `series.rename({ cpu: "usage" })`. Returns a new series with payload field names renamed according to the supplied mapping. */
+    rename(mapping) {
+        const firstColumn = this.schema[0];
+        const renamedColumns = this.schema.slice(1).map((column) => ({
+            ...column,
+            name: mapping[column.name] ??
+                column.name,
+        }));
+        const resultSchema = Object.freeze([
+            firstColumn,
+            ...renamedColumns,
+        ]);
+        const resultEvents = this.events.map((event) => {
+            const renamedEvent = event.rename(mapping);
+            return renamedEvent;
+        });
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: toRows(resultSchema, resultEvents),
+        });
+    }
+    collapse(keys, output, reducer, options) {
+        const nextEvents = this.events.map((event) => {
+            if (options?.append === true) {
+                return event.collapse(keys, output, reducer, { append: true });
+            }
+            return event.collapse(keys, output, reducer);
+        });
+        const firstColumn = this.schema[0];
+        const append = options?.append === true;
+        const keptColumns = append
+            ? this.schema.slice(1)
+            : this.schema
+                .slice(1)
+                .filter((column) => !keys.includes(column.name));
+        const resultSchema = Object.freeze([
+            firstColumn,
+            ...keptColumns,
+            {
+                name: output,
+                kind: typeof nextEvents[0]?.get(output) === 'number'
+                    ? 'number'
+                    : typeof nextEvents[0]?.get(output) === 'boolean'
+                        ? 'boolean'
+                        : 'string',
+            },
+        ]);
+        return new TimeSeries({
+            name: this.name,
+            schema: resultSchema,
+            rows: toRows(resultSchema, nextEvents),
+        });
+    }
+    /** Example: `series.length`. Returns the number of events in the series. */
+    get length() {
+        return this.events.length;
+    }
+    #alignHoldAt(t) {
+        const event = this.atOrBefore(new Time(t));
+        return (event?.data() ?? {});
+    }
+    #alignLinearAt(t, valueColumns) {
+        const exact = this.find((event) => event.begin() === t);
+        if (exact) {
+            return exact.data();
+        }
+        const previous = this.atOrBefore(new Time(t));
+        const next = this.atOrAfter(new Time(t));
+        if (!previous || !next || previous.begin() === next.begin()) {
+            return (previous?.data() ?? {});
+        }
+        const ratio = (t - previous.begin()) / (next.begin() - previous.begin());
+        const result = {};
+        const previousData = previous.data();
+        const nextData = next.data();
+        for (const column of valueColumns) {
+            const previousValue = previousData[column.name];
+            const nextValue = nextData[column.name];
+            if (column.kind === 'number' &&
+                typeof previousValue === 'number' &&
+                typeof nextValue === 'number') {
+                result[column.name] =
+                    previousValue + (nextValue - previousValue) * ratio;
+                continue;
+            }
+            result[column.name] = previousValue;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=TimeSeries.js.map