pond-ts 0.2.0 → 0.3.0

package/dist/TimeSeries.js

@@ -1,10 +1,13 @@
+var _a;
 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 { Event } from './Event.js';
 import { Sequence } from './Sequence.js';
 import { validateAndNormalize } from './validate.js';
+import { resolveReducer, } from './reducers/index.js';
 function isObjectRow(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -89,6 +92,23 @@ function parseJsonRows(schema, rows, options = {}) {
         }));
     });
 }
+function serializeJsonKey(kind, key, rowFormat) {
+    if (kind === 'time') {
+        return key.begin();
+    }
+    if (kind === 'timeRange') {
+        return rowFormat === 'object'
+            ? { start: key.begin(), end: key.end() }
+            : [key.begin(), key.end()];
+    }
+    const interval = key;
+    return rowFormat === 'object'
+        ? { value: interval.value, start: interval.begin(), end: interval.end() }
+        : [interval.value, interval.begin(), interval.end()];
+}
+function serializeJsonValue(value) {
+    return value === undefined ? null : value;
+}
 function toRows(schema, events) {
     return events.map((event) => {
         const data = event.data();
@@ -100,6 +120,20 @@ function toRows(schema, events) {
         ]);
     });
 }
+function toObjects(schema, events) {
+    const keyColumn = schema[0];
+    const dataColumns = schema.slice(1);
+    return events.map((event) => {
+        const row = {
+            [keyColumn.name]: event.key(),
+        };
+        const data = event.data();
+        for (const column of dataColumns) {
+            row[column.name] = data[column.name];
+        }
+        return Object.freeze(row);
+    });
+}
 function isEventKey(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -316,254 +350,60 @@ function bucketOverlapsHalfOpen(bucket, event) {
 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];
+    return resolveReducer(operation).reduce(defined, numeric);
+}
+function isBuiltInAggregateReducer(reducer) {
+    return typeof reducer === 'string';
+}
+function applyAggregateReducer(reducer, values) {
+    return isBuiltInAggregateReducer(reducer)
+        ? aggregateValues(reducer, values)
+        : reducer(values);
+}
+function isAggregateOutputSpec(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'from' in value &&
+        'using' in value);
+}
+function normalizeAggregateColumns(schema, mapping) {
+    const columnsByName = new Map(schema.slice(1).map((column) => [column.name, column]));
+    const normalized = [];
+    for (const [outputName, raw] of Object.entries(mapping)) {
+        const sourceName = isAggregateOutputSpec(raw) ? raw.from : outputName;
+        const sourceColumn = columnsByName.get(sourceName);
+        if (!sourceColumn) {
+            throw new TypeError(`aggregate mapping references unknown source column '${sourceName}'`);
+        }
+        if (sourceColumn.kind !== 'number' &&
+            sourceColumn.kind !== 'string' &&
+            sourceColumn.kind !== 'boolean') {
+            throw new TypeError(`aggregate source column '${sourceName}' must be a scalar value column`);
+        }
+        const reducer = isAggregateOutputSpec(raw) ? raw.using : raw;
+        if (typeof reducer !== 'string' && typeof reducer !== 'function') {
+            throw new TypeError(`aggregate reducer for '${outputName}' must be a built-in name or function`);
+        }
+        const explicitKind = isAggregateOutputSpec(raw) ? raw.kind : undefined;
+        const resolvedKind = explicitKind ??
+            (typeof reducer === 'string' &&
+                resolveReducer(reducer).outputKind === 'number'
+                ? 'number'
+                : sourceColumn.kind);
+        normalized.push({
+            output: outputName,
+            source: sourceName,
+            reducer,
+            kind: resolvedKind,
+        });
     }
+    return normalized;
 }
 function createAggregateBucketState(operation) {
-    if (operation === 'count') {
-        let definedCount = 0;
-        return {
-            add(value) {
-                if (value !== undefined) {
-                    definedCount += 1;
-                }
-            },
-            snapshot() {
-                return definedCount;
-            },
-        };
-    }
-    if (operation === 'sum') {
-        let numericSum = 0;
-        return {
-            add(value) {
-                if (typeof value === 'number') {
-                    numericSum += value;
-                }
-            },
-            snapshot() {
-                return numericSum;
-            },
-        };
-    }
-    if (operation === 'avg') {
-        let numericSum = 0;
-        let numericCount = 0;
-        return {
-            add(value) {
-                if (typeof value === 'number') {
-                    numericSum += value;
-                    numericCount += 1;
-                }
-            },
-            snapshot() {
-                return numericCount === 0 ? undefined : numericSum / numericCount;
-            },
-        };
-    }
-    if (operation === 'min') {
-        let numericValue;
-        return {
-            add(value) {
-                if (typeof value !== 'number') {
-                    return;
-                }
-                numericValue =
-                    numericValue === undefined || value < numericValue
-                        ? value
-                        : numericValue;
-            },
-            snapshot() {
-                return numericValue;
-            },
-        };
-    }
-    if (operation === 'max') {
-        let numericValue;
-        return {
-            add(value) {
-                if (typeof value !== 'number') {
-                    return;
-                }
-                numericValue =
-                    numericValue === undefined || value > numericValue
-                        ? value
-                        : numericValue;
-            },
-            snapshot() {
-                return numericValue;
-            },
-        };
-    }
-    if (operation === 'first') {
-        let firstValue;
-        return {
-            add(value) {
-                if (firstValue === undefined && value !== undefined) {
-                    firstValue = value;
-                }
-            },
-            snapshot() {
-                return firstValue;
-            },
-        };
-    }
-    if (operation === 'last') {
-        let lastValue;
-        return {
-            add(value) {
-                if (value !== undefined) {
-                    lastValue = value;
-                }
-            },
-            snapshot() {
-                return lastValue;
-            },
-        };
-    }
-    throw new TypeError(`unsupported aggregate reducer: ${operation}`);
+    return resolveReducer(operation).bucketState();
 }
 function createRollingReducerState(operation) {
-    const compact = (entries, head) => {
-        if (head > 0 && head * 2 >= entries.length) {
-            return [entries.slice(head), 0];
-        }
-        return [entries, head];
-    };
-    if (operation === 'count') {
-        let definedCount = 0;
-        return {
-            add(_index, value) {
-                if (value !== undefined) {
-                    definedCount += 1;
-                }
-            },
-            remove(_index, value) {
-                if (value !== undefined) {
-                    definedCount -= 1;
-                }
-            },
-            snapshot() {
-                return definedCount;
-            },
-        };
-    }
-    if (operation === 'sum') {
-        let numericSum = 0;
-        return {
-            add(_index, value) {
-                if (typeof value === 'number') {
-                    numericSum += value;
-                }
-            },
-            remove(_index, value) {
-                if (typeof value === 'number') {
-                    numericSum -= value;
-                }
-            },
-            snapshot() {
-                return numericSum;
-            },
-        };
-    }
-    if (operation === 'avg') {
-        let numericSum = 0;
-        let numericCount = 0;
-        return {
-            add(_index, value) {
-                if (typeof value === 'number') {
-                    numericSum += value;
-                    numericCount += 1;
-                }
-            },
-            remove(_index, value) {
-                if (typeof value === 'number') {
-                    numericSum -= value;
-                    numericCount -= 1;
-                }
-            },
-            snapshot() {
-                return numericCount === 0 ? undefined : numericSum / numericCount;
-            },
-        };
-    }
-    if (operation === 'min' || operation === 'max') {
-        let entries = [];
-        let head = 0;
-        return {
-            add(index, value) {
-                if (typeof value !== 'number') {
-                    return;
-                }
-                while (entries.length > head) {
-                    const last = entries[entries.length - 1];
-                    if (operation === 'min' ? last.value <= value : last.value >= value) {
-                        break;
-                    }
-                    entries.pop();
-                }
-                entries.push({ index, value });
-            },
-            remove(index, value) {
-                if (typeof value !== 'number') {
-                    return;
-                }
-                if (entries[head]?.index === index) {
-                    head += 1;
-                    [entries, head] = compact(entries, head);
-                }
-            },
-            snapshot() {
-                return entries[head]?.value;
-            },
-        };
-    }
-    if (operation === 'first' || operation === 'last') {
-        let entries = [];
-        let head = 0;
-        return {
-            add(index, value) {
-                if (value !== undefined) {
-                    entries.push({ index, value });
-                }
-            },
-            remove(index, value) {
-                if (value === undefined) {
-                    return;
-                }
-                if (entries[head]?.index === index) {
-                    head += 1;
-                    [entries, head] = compact(entries, head);
-                }
-            },
-            snapshot() {
-                return operation === 'first'
-                    ? entries[head]?.value
-                    : entries[entries.length - 1]?.value;
-            },
-        };
-    }
-    throw new TypeError(`unsupported rolling reducer: ${operation}`);
+    return resolveReducer(operation).rollingState();
 }
 function parseDurationInput(value) {
     if (typeof value === 'number') {
@@ -697,7 +537,7 @@ export class TimeSeries {
      * the supplied `parse.timeZone`, which defaults to `UTC`.
      */
     static fromJSON(input) {
-        return new TimeSeries({
+        return new _a({
             name: input.name,
             schema: input.schema,
             rows: parseJsonRows(input.schema, input.rows, input.parse),
@@ -710,6 +550,48 @@ export class TimeSeries {
         this.events = validateAndNormalize(input);
         Object.freeze(this);
     }
+    /**
+     * Example: `series.toJSON({ rowFormat: "object" })`.
+     * Serializes the series into the JSON-friendly shape accepted by `TimeSeries.fromJSON(...)`.
+     *
+     * Timestamps are emitted as numbers to avoid time zone ambiguity. Missing payload values are
+     * emitted as `null`. By default rows are emitted as arrays; use `rowFormat: "object"` for rows
+     * keyed by schema column names.
+     */
+    toJSON(options = {}) {
+        const rowFormat = options.rowFormat ?? 'array';
+        const dataColumns = this.schema.slice(1);
+        if (rowFormat === 'object') {
+            const keyColumn = this.schema[0];
+            const rows = this.events.map((event) => {
+                const row = {
+                    [keyColumn.name]: serializeJsonKey(keyColumn.kind, event.key(), rowFormat),
+                };
+                const data = event.data();
+                for (const column of dataColumns) {
+                    row[column.name] = serializeJsonValue(data[column.name]);
+                }
+                return Object.freeze(row);
+            });
+            return {
+                name: this.name,
+                schema: this.schema,
+                rows,
+            };
+        }
+        const rows = this.events.map((event) => {
+            const data = event.data();
+            return Object.freeze([
+                serializeJsonKey(this.schema[0].kind, event.key(), rowFormat),
+                ...dataColumns.map((column) => serializeJsonValue(data[column.name])),
+            ]);
+        });
+        return {
+            name: this.name,
+            schema: this.schema,
+            rows,
+        };
+    }
     /**
      * Builds a series from event data that has already been validated and ordered by the caller.
      *
@@ -717,7 +599,7 @@ export class TimeSeries {
      * order and normalized key invariants.
      */
     static #fromTrustedEvents(name, schema, events) {
-        const series = Object.create(TimeSeries.prototype);
+        const series = Object.create(_a.prototype);
         series.name = name;
         series.schema = Object.freeze(schema.slice());
         series.events = Object.freeze(events.slice());
@@ -731,6 +613,14 @@ export class TimeSeries {
     get rows() {
         return toRows(this.schema, this.events);
     }
+    /** Example: `series.toRows()`. Returns normalized row arrays using `Time`/`TimeRange`/`Interval` keys and `undefined` for missing payload values. */
+    toRows() {
+        return this.rows;
+    }
+    /** Example: `series.toObjects()`. Returns normalized schema-keyed object rows using temporal key objects and `undefined` for missing payload values. */
+    toObjects() {
+        return toObjects(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];
@@ -748,7 +638,7 @@ export class TimeSeries {
     /** 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({
+        return new _a({
             name: this.name,
             schema,
             rows: toRows(schema, mappedEvents),
@@ -762,9 +652,9 @@ export class TimeSeries {
         ]);
         const resultEvents = this.events.map((event) => event.asTime(options));
         if ((options.at ?? 'begin') === 'begin') {
-            return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
+            return _a.#fromTrustedEvents(this.name, schema, resultEvents);
         }
-        return new TimeSeries({
+        return new _a({
             name: this.name,
             schema,
             rows: toRows(schema, resultEvents),
@@ -777,7 +667,7 @@ export class TimeSeries {
             ...this.schema.slice(1),
         ]);
         const resultEvents = this.events.map((event) => event.asTimeRange());
-        return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
+        return _a.#fromTrustedEvents(this.name, schema, resultEvents);
     }
     asInterval(value) {
         const schema = Object.freeze([
@@ -789,10 +679,13 @@ export class TimeSeries {
                 ? event.asInterval(() => value(event, index))
                 : event.asInterval(value);
         });
-        return TimeSeries.#fromTrustedEvents(this.name, schema, nextEvents);
+        return _a.#fromTrustedEvents(this.name, schema, nextEvents);
     }
     join(other, options = {}) {
-        const [left, right] = prepareSeriesForJoin([this, 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');
@@ -845,7 +738,7 @@ export class TimeSeries {
                 rightIndex += 1;
             }
         }
-        return TimeSeries.#fromTrustedEvents(left.name, resultSchema, joinedEvents);
+        return _a.#fromTrustedEvents(left.name, resultSchema, joinedEvents);
     }
     /**
      * Example: `series.align(Sequence.every("1m"))`.
@@ -877,7 +770,7 @@ export class TimeSeries {
         const range = options.range ?? this.timeRange();
         const resultSchema = makeAlignedSchema(this.schema);
         if (!range) {
-            return new TimeSeries({
+            return new _a({
                 name: this.name,
                 schema: resultSchema,
                 rows: [],
@@ -896,7 +789,7 @@ export class TimeSeries {
                 for (let i = 0; i < intervals.length; i += 1) {
                     const interval = intervals[i];
                     const t = sampleTime(interval, sample);
-                    const data = this.#alignLinearAt(t, valueColumns, cursor);
+                    const data = alignLinearAt(this, t, valueColumns, cursor);
                     const row = new Array(resultColumns.length + 1);
                     row[0] = interval;
                     for (let j = 0; j < resultColumns.length; j += 1) {
@@ -909,7 +802,7 @@ export class TimeSeries {
             })()
             : intervals.map((interval) => {
                 const t = sampleTime(interval, sample);
-                const data = this.#alignHoldAt(t);
+                const data = alignHoldAt(this, t);
                 return Object.freeze([
                     interval,
                     ...resultSchema
@@ -917,126 +810,452 @@ export class TimeSeries {
                         .map((column) => data[column.name]),
                 ]);
             });
-        return new TimeSeries({
+        return new _a({
             name: this.name,
             schema: resultSchema,
             rows: alignedRows,
         });
     }
+    aggregate(sequence, mapping, options = {}) {
+        return aggregateInternal(this, sequence, mapping, options);
+    }
+    reduce(columnOrMapping, reducer) {
+        if (typeof columnOrMapping === 'string') {
+            const values = this.events.map((event) => {
+                const data = event.data();
+                return data[columnOrMapping];
+            });
+            return applyAggregateReducer(reducer, values);
+        }
+        const columns = normalizeAggregateColumns(this.schema, columnOrMapping);
+        const result = {};
+        for (const col of columns) {
+            const values = this.events.map((event) => {
+                const data = event.data();
+                return data[col.source];
+            });
+            result[col.output] = applyAggregateReducer(col.reducer, values);
+        }
+        return result;
+    }
+    groupBy(column, transform) {
+        const buckets = new Map();
+        for (const event of this.events) {
+            const raw = event.data()[column];
+            const key = raw === undefined ? 'undefined' : String(raw);
+            let bucket = buckets.get(key);
+            if (!bucket) {
+                bucket = [];
+                buckets.set(key, bucket);
+            }
+            bucket.push(event);
+        }
+        const buildGroup = (events) => new _a({
+            name: this.name,
+            schema: this.schema,
+            rows: toRows(this.schema, events),
+        });
+        if (transform) {
+            const result = new Map();
+            for (const [key, events] of buckets) {
+                result.set(key, transform(buildGroup(events), key));
+            }
+            return result;
+        }
+        const result = new Map();
+        for (const [key, events] of buckets) {
+            result.set(key, buildGroup(events));
+        }
+        return result;
+    }
     /**
-     * Example: `series.aggregate(Sequence.every("1m"), { value: "avg" })`.
-     * Aggregates events into sequence buckets using built-in reducer names.
+     * Example: `series.diff("requests")`.
+     * Computes per-event differences for the specified numeric columns.
+     * Non-specified columns pass through unchanged. The first event gets
+     * `undefined` in affected columns unless `{ drop: true }` is passed,
+     * which removes the first event entirely.
      *
-     * 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.
+     * Example: `series.diff(["requests", "cpu"])`.
+     * Multiple columns can be diffed in a single call.
      *
-     * Defaults:
-     * - `range`: `series.timeRange()`
+     * Example: `series.diff("requests", { drop: true })`.
+     * Drops the first event instead of keeping it with undefined values.
+     */
+    diff(columns, options) {
+        return this.#diffOrRate('diff', columns, options);
+    }
+    /**
+     * Example: `series.rate("requests")`.
+     * Computes the per-second rate of change for the specified numeric columns.
+     * Non-specified columns pass through unchanged. The first event gets
+     * `undefined` in affected columns unless `{ drop: true }` is passed,
+     * which removes the first event entirely.
      *
-     * 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.
+     * Example: `series.rate(["requests", "cpu"])`.
+     * Multiple columns can be rated in a single call.
      *
-     * Override `range` when you need multiple series aggregated over the same reporting window,
-     * including leading or trailing empty buckets outside an individual series extent.
+     * Example: `series.rate("requests", { drop: true })`.
+     * Drops the first event instead of keeping it with undefined values.
+     */
+    rate(columns, options) {
+        return this.#diffOrRate('rate', columns, options);
+    }
+    /**
+     * Example: `series.pctChange("requests")`.
+     * Computes the percentage change `(curr - prev) / prev` for the specified
+     * numeric columns. Non-specified columns pass through unchanged. The first
+     * event gets `undefined` in affected columns unless `{ drop: true }` is
+     * passed.
+     */
+    pctChange(columns, options) {
+        return this.#diffOrRate('pctChange', columns, options);
+    }
+    #diffOrRate(mode, columns, options) {
+        const cols = typeof columns === 'string' ? [columns] : columns;
+        const drop = options?.drop === true;
+        if (cols.length === 0) {
+            throw new Error(`${mode}() requires at least one column name`);
+        }
+        const targetSet = new Set(cols);
+        const outSchema = Object.freeze(this.schema.map((col, i) => {
+            if (i === 0)
+                return col;
+            if (targetSet.has(col.name)) {
+                return { ...col, kind: 'number', required: false };
+            }
+            return col;
+        }));
+        const events = this.events;
+        if (events.length === 0) {
+            return _a.#fromTrustedEvents(this.name, outSchema, []);
+        }
+        const resultEvents = [];
+        if (!drop) {
+            const firstData = { ...events[0].data() };
+            for (const col of cols) {
+                firstData[col] = undefined;
+            }
+            resultEvents.push(new Event(events[0].key(), firstData));
+        }
+        for (let i = 1; i < events.length; i++) {
+            const prev = events[i - 1];
+            const curr = events[i];
+            const data = { ...curr.data() };
+            const dt = mode === 'rate' ? (curr.begin() - prev.begin()) / 1000 : undefined;
+            for (const col of cols) {
+                const prevVal = prev.data()[col];
+                const currVal = data[col];
+                if (typeof currVal === 'number' && typeof prevVal === 'number') {
+                    const delta = currVal - prevVal;
+                    if (mode === 'pctChange') {
+                        data[col] = prevVal !== 0 ? delta / prevVal : undefined;
+                    }
+                    else if (mode === 'rate') {
+                        data[col] = dt !== 0 ? delta / dt : undefined;
+                    }
+                    else {
+                        data[col] = delta;
+                    }
+                }
+                else {
+                    data[col] = undefined;
+                }
+            }
+            resultEvents.push(new Event(curr.key(), data));
+        }
+        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+    }
+    /**
+     * Example: `series.cumulative({ requests: "sum" })`.
+     * Computes running accumulations for the specified numeric columns.
+     * Non-accumulated columns pass through unchanged.
+     *
+     * Built-in accumulators: `"sum"`, `"max"`, `"min"`, `"count"`.
+     * Custom accumulators: `(acc: number, value: number) => number`.
+     */
+    cumulative(spec) {
+        const entries = Object.entries(spec);
+        if (entries.length === 0) {
+            throw new Error('cumulative() requires at least one column');
+        }
+        const targetSet = new Set(entries.map(([name]) => name));
+        const outSchema = Object.freeze(this.schema.map((col, i) => {
+            if (i === 0)
+                return col;
+            if (targetSet.has(col.name)) {
+                return { ...col, kind: 'number', required: false };
+            }
+            return col;
+        }));
+        const events = this.events;
+        if (events.length === 0) {
+            return _a.#fromTrustedEvents(this.name, outSchema, []);
+        }
+        const state = new Map();
+        for (const [name, reducer] of entries) {
+            if (typeof reducer === 'function') {
+                const fn = reducer;
+                state.set(name, {
+                    acc: undefined,
+                    apply: (acc, v) => (acc === undefined ? v : fn(acc, v)),
+                });
+            }
+            else {
+                switch (reducer) {
+                    case 'sum':
+                        state.set(name, {
+                            acc: undefined,
+                            apply: (acc, v) => (acc ?? 0) + v,
+                        });
+                        break;
+                    case 'count':
+                        state.set(name, { acc: undefined, apply: (acc) => (acc ?? 0) + 1 });
+                        break;
+                    case 'max':
+                        state.set(name, {
+                            acc: undefined,
+                            apply: (acc, v) => (acc === undefined || v > acc ? v : acc),
+                        });
+                        break;
+                    case 'min':
+                        state.set(name, {
+                            acc: undefined,
+                            apply: (acc, v) => (acc === undefined || v < acc ? v : acc),
+                        });
+                        break;
+                }
+            }
+        }
+        const resultEvents = [];
+        for (const event of events) {
+            const data = { ...event.data() };
+            for (const [name, s] of state) {
+                const raw = data[name];
+                if (typeof raw === 'number') {
+                    s.acc = s.apply(s.acc, raw);
+                    data[name] = s.acc;
+                }
+                else {
+                    data[name] = s.acc;
+                }
+            }
+            resultEvents.push(new Event(event.key(), data));
+        }
+        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+    }
+    /**
+     * Example: `series.shift("value", 1)`.
+     * Lags column values by N events (positive N) or leads them (negative N).
+     * Vacated positions get `undefined`.
+     */
+    shift(columns, n) {
+        const cols = typeof columns === 'string' ? [columns] : columns;
+        if (cols.length === 0) {
+            throw new Error('shift() requires at least one column name');
+        }
+        if (!Number.isInteger(n)) {
+            throw new Error('shift() requires an integer offset');
+        }
+        const targetSet = new Set(cols);
+        const outSchema = Object.freeze(this.schema.map((col, i) => {
+            if (i === 0)
+                return col;
+            if (targetSet.has(col.name)) {
+                return { ...col, kind: 'number', required: false };
+            }
+            return col;
+        }));
+        const events = this.events;
+        if (events.length === 0) {
+            return _a.#fromTrustedEvents(this.name, outSchema, []);
+        }
+        const resultEvents = [];
+        for (let i = 0; i < events.length; i++) {
+            const data = { ...events[i].data() };
+            const srcIdx = i - n;
+            for (const col of cols) {
+                if (srcIdx >= 0 && srcIdx < events.length) {
+                    data[col] = events[srcIdx].data()[col];
+                }
+                else {
+                    data[col] = undefined;
+                }
+            }
+            resultEvents.push(new Event(events[i].key(), data));
+        }
+        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+    }
+    /**
+     * Example: `series.fill("hold")`.
+     * Fills `undefined` values using the given strategy for all payload columns.
      *
-     * To align buckets to the beginning of the current series instead of epoch boundaries, override
-     * the sequence anchor rather than the aggregation range:
+     * Example: `series.fill({ cpu: "linear", host: "hold" })`.
+     * Per-column fill strategies. Unmentioned columns are left as-is.
+     * Strategy names: `"hold"` (forward fill), `"linear"` (time-interpolated),
+     * `"zero"` (fill with 0). A non-string value is used as a literal fill value.
      *
-     * ```ts
-     * const range = series.timeRange();
-     * if (!range) {
-     *   throw new Error("empty series");
-     * }
+     * Example: `series.fill("hold", { limit: 3 })`.
+     * Caps consecutive fills per column. After `limit` consecutive fills, further
+     * `undefined` values are left as-is until a real value resets the counter.
      *
-     * const aggregated = series.aggregate(
-     *   Sequence.every("1m", { anchor: range.begin() }),
-     *   { value: "avg" },
-     * );
-     * ```
+     * `"linear"` requires known values on both sides of a gap to interpolate.
+     * Leading and trailing `undefined` runs are left unfilled.
      */
-    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: [],
-            });
+    fill(strategy, options) {
+        if (this.events.length === 0) {
+            return this;
         }
-        const buckets = toBoundedSequence(sequence, range, 'begin').intervals();
-        const resultColumns = resultSchema.slice(1);
-        if (isTimeKeyed(this)) {
-            const columns = resultColumns.map((column) => ({
-                name: column.name,
-                operation: mapping[column.name],
-            }));
-            let eventIndex = 0;
-            const resultRows = buckets.map((bucket) => {
-                const states = columns.map((column) => createAggregateBucketState(column.operation));
-                while (eventIndex < this.events.length &&
-                    this.events[eventIndex].begin() < bucket.begin()) {
-                    eventIndex += 1;
+        const colNames = this.schema.slice(1).map((c) => c.name);
+        const specs = new Map();
+        if (typeof strategy === 'string') {
+            for (const name of colNames) {
+                specs.set(name, { mode: strategy });
+            }
+        }
+        else {
+            const strategies = new Set([
+                'hold',
+                'bfill',
+                'linear',
+                'zero',
+            ]);
+            for (const [name, spec] of Object.entries(strategy)) {
+                if (typeof spec === 'string' && strategies.has(spec)) {
+                    specs.set(name, { mode: spec });
                 }
-                let scanIndex = eventIndex;
-                while (scanIndex < this.events.length &&
-                    this.events[scanIndex].begin() < bucket.end()) {
-                    const data = this.events[scanIndex].data();
-                    for (let index = 0; index < columns.length; index += 1) {
-                        const column = columns[index];
-                        states[index].add(data[column.name]);
+                else {
+                    specs.set(name, { mode: 'literal', value: spec });
+                }
+            }
+        }
+        const limit = options?.limit;
+        const n = this.events.length;
+        const columns = {};
+        for (const name of colNames) {
+            columns[name] = new Array(n);
+        }
+        for (let i = 0; i < n; i++) {
+            const data = this.events[i].data();
+            for (const name of colNames) {
+                columns[name][i] = data[name];
+            }
+        }
+        const times = new Array(n);
+        for (let i = 0; i < n; i++) {
+            times[i] = this.events[i].begin();
+        }
+        for (const [name, spec] of specs) {
+            const col = columns[name];
+            if (!col)
+                continue;
+            switch (spec.mode) {
+                case 'hold': {
+                    let last;
+                    let consecutive = 0;
+                    for (let i = 0; i < n; i++) {
+                        if (col[i] !== undefined) {
+                            last = col[i];
+                            consecutive = 0;
+                        }
+                        else if (last !== undefined) {
+                            consecutive++;
+                            if (limit === undefined || consecutive <= limit) {
+                                col[i] = last;
+                            }
+                        }
                     }
-                    scanIndex += 1;
+                    break;
                 }
-                eventIndex = scanIndex;
-                return Object.freeze([
-                    bucket,
-                    ...states.map((state) => state.snapshot()),
-                ]);
-            });
-            return new TimeSeries({
-                name: this.name,
-                schema: resultSchema,
-                rows: resultRows,
-            });
+                case 'bfill': {
+                    let next;
+                    let consecutive = 0;
+                    for (let i = n - 1; i >= 0; i--) {
+                        if (col[i] !== undefined) {
+                            next = col[i];
+                            consecutive = 0;
+                        }
+                        else if (next !== undefined) {
+                            consecutive++;
+                            if (limit === undefined || consecutive <= limit) {
+                                col[i] = next;
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'zero': {
+                    let consecutive = 0;
+                    for (let i = 0; i < n; i++) {
+                        if (col[i] !== undefined) {
+                            consecutive = 0;
+                        }
+                        else {
+                            consecutive++;
+                            if (limit === undefined || consecutive <= limit) {
+                                col[i] = 0;
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'literal': {
+                    let consecutive = 0;
+                    for (let i = 0; i < n; i++) {
+                        if (col[i] !== undefined) {
+                            consecutive = 0;
+                        }
+                        else {
+                            consecutive++;
+                            if (limit === undefined || consecutive <= limit) {
+                                col[i] = spec.value;
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'linear': {
+                    let gapStart = -1;
+                    for (let i = 0; i < n; i++) {
+                        if (col[i] !== undefined) {
+                            if (gapStart >= 0 && gapStart > 0) {
+                                const before = col[gapStart - 1];
+                                const after = col[i];
+                                const t0 = times[gapStart - 1];
+                                const t1 = times[i];
+                                const span = t1 - t0;
+                                const gapLen = i - gapStart;
+                                for (let j = gapStart; j < i; j++) {
+                                    const fillIndex = j - gapStart + 1;
+                                    if (limit !== undefined && fillIndex > limit)
+                                        break;
+                                    if (span === 0) {
+                                        col[j] = before;
+                                    }
+                                    else {
+                                        const ratio = (times[j] - t0) / span;
+                                        col[j] = before + (after - before) * ratio;
+                                    }
+                                }
+                            }
+                            gapStart = -1;
+                        }
+                        else if (gapStart < 0) {
+                            gapStart = i;
+                        }
+                    }
+                    break;
+                }
+            }
         }
-        const resultRows = buckets.map((bucket) => {
-            const contributors = this.events.filter((event) => bucketOverlapsHalfOpen(bucket, event.key()));
-            const aggregated = resultColumns.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,
-        });
+        const resultEvents = [];
+        for (let i = 0; i < n; i++) {
+            const data = {};
+            for (const name of colNames) {
+                data[name] = columns[name][i];
+            }
+            resultEvents.push(new Event(this.events[i].key(), data));
+        }
+        return _a.#fromTrustedEvents(this.name, this.schema, resultEvents);
     }
     rolling(sequenceOrWindow, windowOrMapping, mappingOrOptions, maybeOptions = {}) {
         const buildResultColumns = () => this.schema
@@ -1092,7 +1311,7 @@ export class TimeSeries {
                 ...buildResultColumns(),
             ]);
             if (!range) {
-                return new TimeSeries({
+                return new _a({
                     name: this.name,
                     schema: resultSchema,
                     rows: [],
@@ -1103,16 +1322,16 @@ export class TimeSeries {
                 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 reducer = mapping[column.name];
                     const values = contributors.map((candidate) => {
                         const data = candidate.data();
                         return data[column.name];
                     });
-                    return aggregateValues(operation, values);
+                    return applyAggregateReducer(reducer, values);
                 });
                 return Object.freeze([bucket, ...aggregated]);
             });
-            return new TimeSeries({
+            return new _a({
                 name: this.name,
                 schema: resultSchema,
                 rows: resultRows,
@@ -1123,7 +1342,12 @@ export class TimeSeries {
             this.schema[0],
             ...resultColumns,
         ]);
-        const reducerStates = resultColumns.map((column) => createRollingReducerState(mapping[column.name]));
+        const reducerStates = resultColumns.map((column) => {
+            const reducer = mapping[column.name];
+            return isBuiltInAggregateReducer(reducer)
+                ? createRollingReducerState(reducer)
+                : null;
+        });
         const beginTimes = this.events.map((event) => event.begin());
         const resultRows = new Array(this.events.length);
         let windowStart = 0;
@@ -1131,19 +1355,38 @@ export class TimeSeries {
         const addEvent = (index) => {
             const event = this.events[index];
             const data = event.data();
-            for (let reducerIndex = 0; reducerIndex < reducerStates.length; reducerIndex++) {
-                const column = resultColumns[reducerIndex];
-                reducerStates[reducerIndex].add(index, data[column.name]);
+            for (let i = 0; i < reducerStates.length; i++) {
+                const state = reducerStates[i];
+                if (state) {
+                    const column = resultColumns[i];
+                    state.add(index, data[column.name]);
+                }
             }
         };
         const removeEvent = (index) => {
             const event = this.events[index];
             const data = event.data();
-            for (let reducerIndex = 0; reducerIndex < reducerStates.length; reducerIndex++) {
-                const column = resultColumns[reducerIndex];
-                reducerStates[reducerIndex].remove(index, data[column.name]);
+            for (let i = 0; i < reducerStates.length; i++) {
+                const state = reducerStates[i];
+                if (state) {
+                    const column = resultColumns[i];
+                    state.remove(index, data[column.name]);
+                }
             }
         };
+        const snapshotWindow = () => resultColumns.map((column, i) => {
+            const state = reducerStates[i];
+            if (state)
+                return state.snapshot();
+            const reducer = mapping[column.name];
+            const values = this.events
+                .slice(windowStart, windowEnd)
+                .map((event) => {
+                const data = event.data();
+                return data[column.name];
+            });
+            return applyAggregateReducer(reducer, values);
+        });
         if (alignment === 'trailing') {
             for (let groupStart = 0; groupStart < this.events.length;) {
                 const anchor = beginTimes[groupStart];
@@ -1163,7 +1406,7 @@ export class TimeSeries {
                     removeEvent(windowStart);
                     windowStart += 1;
                 }
-                const aggregated = reducerStates.map((state) => state.snapshot());
+                const aggregated = snapshotWindow();
                 for (let index = groupStart; index < groupEnd; index++) {
                     resultRows[index] = Object.freeze([
                         this.events[index].key(),
@@ -1193,7 +1436,7 @@ export class TimeSeries {
                     addEvent(windowEnd);
                     windowEnd += 1;
                 }
-                const aggregated = reducerStates.map((state) => state.snapshot());
+                const aggregated = snapshotWindow();
                 for (let index = groupStart; index < groupEnd; index++) {
                     resultRows[index] = Object.freeze([
                         this.events[index].key(),
@@ -1224,7 +1467,7 @@ export class TimeSeries {
                     addEvent(windowEnd);
                     windowEnd += 1;
                 }
-                const aggregated = reducerStates.map((state) => state.snapshot());
+                const aggregated = snapshotWindow();
                 for (let index = groupStart; index < groupEnd; index++) {
                     resultRows[index] = Object.freeze([
                         this.events[index].key(),
@@ -1234,7 +1477,7 @@ export class TimeSeries {
                 groupStart = groupEnd;
             }
         }
-        return new TimeSeries({
+        return new _a({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -1299,7 +1542,7 @@ export class TimeSeries {
                         .map((nextColumn) => nextEvent.data()[nextColumn.name]),
                 ]);
             });
-            return new TimeSeries({
+            return new _a({
                 name: this.name,
                 schema: resultSchema,
                 rows: resultRows,
@@ -1337,7 +1580,7 @@ export class TimeSeries {
                         .map((nextColumn) => nextEvent.data()[nextColumn.name]),
                 ]);
             });
-            return new TimeSeries({
+            return new _a({
                 name: this.name,
                 schema: resultSchema,
                 rows: resultRows,
@@ -1431,7 +1674,7 @@ export class TimeSeries {
                     .map((nextColumn) => nextEvent.data()[nextColumn.name]),
             ]);
         });
-        return new TimeSeries({
+        return new _a({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -1439,11 +1682,11 @@ export class TimeSeries {
     }
     /** Example: `series.slice(0, 10)`. Returns a positional half-open slice of the series. */
     slice(beginIndex, endIndex) {
-        return TimeSeries.#fromTrustedEvents(this.name, this.schema, this.events.slice(beginIndex, endIndex));
+        return _a.#fromTrustedEvents(this.name, 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 TimeSeries.#fromTrustedEvents(this.name, this.schema, this.events.filter((event, index) => predicate(event, index)));
+        return _a.#fromTrustedEvents(this.name, 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) {
@@ -1564,7 +1807,7 @@ export class TimeSeries {
         const trimmedEvents = this.events
             .map((event) => event.trim(range))
             .filter((event) => event !== undefined);
-        return TimeSeries.#fromTrustedEvents(this.name, this.schema, trimmedEvents);
+        return _a.#fromTrustedEvents(this.name, this.schema, trimmedEvents);
     }
     /** Example: `series.before(Date.now())`. Returns the events ending strictly before the supplied temporal boundary. */
     before(boundary) {
@@ -1596,7 +1839,7 @@ export class TimeSeries {
             const selectedEvent = event.select(...keys);
             return selectedEvent;
         });
-        return TimeSeries.#fromTrustedEvents(this.name, resultSchema, resultEvents);
+        return _a.#fromTrustedEvents(this.name, resultSchema, resultEvents);
     }
     /** Example: `series.rename({ cpu: "usage" })`. Returns a new series with payload field names renamed according to the supplied mapping. */
     rename(mapping) {
@@ -1614,7 +1857,7 @@ export class TimeSeries {
             const renamedEvent = event.rename(mapping);
             return renamedEvent;
         });
-        return TimeSeries.#fromTrustedEvents(this.name, resultSchema, resultEvents);
+        return _a.#fromTrustedEvents(this.name, resultSchema, resultEvents);
     }
     collapse(keys, output, reducer, options) {
         const nextEvents = this.events.map((event) => {
@@ -1642,54 +1885,138 @@ export class TimeSeries {
                         : 'string',
             },
         ]);
-        return TimeSeries.#fromTrustedEvents(this.name, resultSchema, nextEvents);
+        return _a.#fromTrustedEvents(this.name, 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() ?? {});
+}
+_a = TimeSeries;
+function aggregateInternal(series, sequence, mapping, options = {}) {
+    const range = options.range ?? series.timeRange();
+    const aggregateColumns = normalizeAggregateColumns(series.schema, mapping);
+    const resultSchema = Object.freeze([
+        { name: 'interval', kind: 'interval' },
+        ...aggregateColumns.map((column) => ({
+            name: column.output,
+            kind: column.kind,
+            required: false,
+        })),
+    ]);
+    if (!range) {
+        return new TimeSeries({
+            name: series.name,
+            schema: resultSchema,
+            rows: [],
+        });
     }
-    #alignLinearAt(t, valueColumns, cursor) {
-        const events = this.events;
-        const hasCursor = cursor !== undefined;
-        let index = hasCursor ? cursor.index : this.bisect(t);
-        if (hasCursor) {
-            while (index < events.length && events[index].begin() < t) {
-                index += 1;
+    const buckets = toBoundedSequence(sequence, range, 'begin').intervals();
+    const columns = aggregateColumns;
+    if (isTimeKeyed(series)) {
+        const builtInOnly = columns.every((column) => isBuiltInAggregateReducer(column.reducer));
+        let eventIndex = 0;
+        const resultRows = buckets.map((bucket) => {
+            const states = builtInOnly
+                ? columns.map((column) => createAggregateBucketState(column.reducer))
+                : undefined;
+            while (eventIndex < series.events.length &&
+                series.events[eventIndex].begin() < bucket.begin()) {
+                eventIndex += 1;
             }
-            cursor.index = index;
-        }
-        if (index < events.length && events[index].begin() === t) {
-            return events[index].data();
-        }
-        if (index === 0) {
-            return {};
-        }
-        const previous = events[index - 1];
-        const next = events[index];
-        if (!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;
+            const bucketStart = eventIndex;
+            let scanIndex = bucketStart;
+            while (scanIndex < series.events.length &&
+                series.events[scanIndex].begin() < bucket.end()) {
+                if (states) {
+                    const data = series.events[scanIndex].data();
+                    for (let index = 0; index < columns.length; index += 1) {
+                        const column = columns[index];
+                        states[index].add(data[column.source]);
+                    }
+                }
+                scanIndex += 1;
+            }
+            eventIndex = scanIndex;
+            if (states) {
+                return Object.freeze([
+                    bucket,
+                    ...states.map((state) => state.snapshot()),
+                ]);
             }
-            result[column.name] = previousValue;
+            const contributors = series.events.slice(bucketStart, scanIndex);
+            const aggregated = columns.map((column) => {
+                const values = contributors.map((event) => {
+                    const data = event.data();
+                    return data[column.source];
+                });
+                return applyAggregateReducer(column.reducer, values);
+            });
+            return Object.freeze([bucket, ...aggregated]);
+        });
+        return new TimeSeries({
+            name: series.name,
+            schema: resultSchema,
+            rows: resultRows,
+        });
+    }
+    const resultRows = buckets.map((bucket) => {
+        const contributors = series.events.filter((event) => bucketOverlapsHalfOpen(bucket, event.key()));
+        const aggregated = columns.map((column) => {
+            const values = contributors.map((event) => {
+                const data = event.data();
+                return data[column.source];
+            });
+            return applyAggregateReducer(column.reducer, values);
+        });
+        return Object.freeze([bucket, ...aggregated]);
+    });
+    return new TimeSeries({
+        name: series.name,
+        schema: resultSchema,
+        rows: resultRows,
+    });
+}
+function alignHoldAt(series, t) {
+    const event = series.atOrBefore(new Time(t));
+    return (event?.data() ?? {});
+}
+function alignLinearAt(series, t, valueColumns, cursor) {
+    const events = series.events;
+    const hasCursor = cursor !== undefined;
+    let index = hasCursor ? cursor.index : series.bisect(t);
+    if (hasCursor) {
+        while (index < events.length && events[index].begin() < t) {
+            index += 1;
         }
-        return result;
+        cursor.index = index;
+    }
+    if (index < events.length && events[index].begin() === t) {
+        return events[index].data();
+    }
+    if (index === 0) {
+        return {};
+    }
+    const previous = events[index - 1];
+    const next = events[index];
+    if (!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