pond-ts 0.8.2 → 0.9.1

package/dist/TimeSeries.js

@@ -1,4 +1,3 @@
-var _a;
 import { BoundedSequence } from './BoundedSequence.js';
 import { parseTimestampString } from './calendar.js';
 import { Interval } from './Interval.js';
@@ -6,6 +5,7 @@ import { Time } from './Time.js';
 import { TimeRange } from './TimeRange.js';
 import { compareEventKeys } from './temporal.js';
 import { Event } from './Event.js';
+import { PartitionedTimeSeries } from './PartitionedTimeSeries.js';
 import { Sequence } from './Sequence.js';
 import { validateAndNormalize } from './validate.js';
 import { parseDuration } from './utils/duration.js';
@@ -553,7 +553,7 @@ export class TimeSeries {
      * the supplied `parse.timeZone`, which defaults to `UTC`.
      */
     static fromJSON(input) {
-        return new _a({
+        return new TimeSeries({
             name: input.name,
             schema: input.schema,
             rows: parseJsonRows(input.schema, input.rows, input.parse),
@@ -593,7 +593,7 @@ export class TimeSeries {
      */
     static fromEvents(events, options) {
         const sorted = [...events].sort((a, b) => compareEventKeys(a.key(), b.key()));
-        return _a.#fromTrustedEvents(options.name, options.schema, sorted);
+        return TimeSeries.#fromTrustedEvents(options.name, options.schema, sorted);
     }
     /**
      * Example: `TimeSeries.concat([s1, s2, s3])`.
@@ -659,7 +659,7 @@ export class TimeSeries {
                 allEvents.push(event);
         }
         allEvents.sort((a, b) => compareEventKeys(a.key(), b.key()));
-        return _a.#fromTrustedEvents(head.name, head.schema, allEvents);
+        return TimeSeries.#fromTrustedEvents(head.name, head.schema, allEvents);
     }
     /** Example: `new TimeSeries({ name, schema, rows })`. Creates an immutable time series from a schema and row-oriented input data. */
     constructor(input) {
@@ -717,7 +717,7 @@ export class TimeSeries {
      * order and normalized key invariants.
      */
     static #fromTrustedEvents(name, schema, events) {
-        const series = Object.create(_a.prototype);
+        const series = Object.create(TimeSeries.prototype);
         series.name = name;
         series.schema = Object.freeze(schema.slice());
         series.events = Object.freeze(events.slice());
@@ -756,7 +756,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 _a({
+        return new TimeSeries({
             name: this.name,
             schema,
             rows: toRows(schema, mappedEvents),
@@ -770,9 +770,9 @@ export class TimeSeries {
         ]);
         const resultEvents = this.events.map((event) => event.asTime(options));
         if ((options.at ?? 'begin') === 'begin') {
-            return _a.#fromTrustedEvents(this.name, schema, resultEvents);
+            return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
         }
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema,
             rows: toRows(schema, resultEvents),
@@ -785,7 +785,7 @@ export class TimeSeries {
             ...this.schema.slice(1),
         ]);
         const resultEvents = this.events.map((event) => event.asTimeRange());
-        return _a.#fromTrustedEvents(this.name, schema, resultEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
     }
     asInterval(value) {
         const schema = Object.freeze([
@@ -797,7 +797,7 @@ export class TimeSeries {
                 ? event.asInterval(() => value(event, index))
                 : event.asInterval(value);
         });
-        return _a.#fromTrustedEvents(this.name, schema, nextEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, schema, nextEvents);
     }
     join(other, options = {}) {
         const [left, right] = prepareSeriesForJoin([
@@ -856,7 +856,7 @@ export class TimeSeries {
                 rightIndex += 1;
             }
         }
-        return _a.#fromTrustedEvents(left.name, resultSchema, joinedEvents);
+        return TimeSeries.#fromTrustedEvents(left.name, resultSchema, joinedEvents);
     }
     /**
      * Example: `series.align(Sequence.every("1m"))`.
@@ -881,6 +881,13 @@ export class TimeSeries {
      * - `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
+     *
+     * **Multi-entity series:** alignment samples cross entity boundaries —
+     * `host-A`'s aligned bucket would interpolate or hold against
+     * `host-B`'s value. On a series carrying multiple entities (host,
+     * region, device id), use
+     * `series.partitionBy(col).align(...).collect()` to scope per entity.
+     * See {@link TimeSeries.partitionBy}.
      */
     align(sequence, options = {}) {
         const method = options.method ?? 'hold';
@@ -888,7 +895,7 @@ export class TimeSeries {
         const range = options.range ?? this.timeRange();
         const resultSchema = makeAlignedSchema(this.schema);
         if (!range) {
-            return new _a({
+            return new TimeSeries({
                 name: this.name,
                 schema: resultSchema,
                 rows: [],
@@ -928,7 +935,7 @@ export class TimeSeries {
                         .map((column) => data[column.name]),
                 ]);
             });
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: alignedRows,
@@ -968,7 +975,7 @@ export class TimeSeries {
             }
             bucket.push(event);
         }
-        const buildGroup = (events) => new _a({
+        const buildGroup = (events) => new TimeSeries({
             name: this.name,
             schema: this.schema,
             rows: toRows(this.schema, events),
@@ -986,6 +993,46 @@ export class TimeSeries {
         }
         return result;
     }
+    /**
+     * Example: `series.partitionBy('host').fill({ cpu: 'linear' })`.
+     * Returns a {@link PartitionedTimeSeries} view that scopes stateful
+     * transforms to within each partition. Most stateful operators
+     * (`fill`, `align`, `rolling`, `smooth`, `baseline`, `outliers`,
+     * `diff`, `rate`, `pctChange`, `cumulative`, `shift`, `aggregate`)
+     * read neighboring events when computing each output and silently
+     * cross entity boundaries on multi-entity series — `partitionBy`
+     * fixes that by running the op independently per partition and
+     * reassembling.
+     *
+     * Composite partitioning by multiple columns is supported by passing
+     * an array: `series.partitionBy(['host', 'region'])`.
+     *
+     * The return shape is always `TimeSeries`, not
+     * `PartitionedTimeSeries` — each operation is a single step. To
+     * chain another partitioned op, re-`partitionBy` after.
+     *
+     * Coming from pondjs / pandas: this is roughly the equivalent of
+     * `df.groupby(col)` returning an object whose methods auto-apply
+     * per group, but the return type is the regrouped frame, not the
+     * grouped view.
+     *
+     * @example
+     * ```ts
+     * // Per-host fill — no cross-host interpolation
+     * series.partitionBy('host').fill({ cpu: 'linear' });
+     *
+     * // Composite partitioning
+     * series.partitionBy(['host', 'region']).rolling('5m', { cpu: 'avg' });
+     *
+     * // Arbitrary composition via .apply()
+     * series.partitionBy('host').apply(g =>
+     *   g.fill({ cpu: 'linear' }).rolling('5m', { cpu: 'avg' }),
+     * );
+     * ```
+     */
+    partitionBy(by) {
+        return new PartitionedTimeSeries(this, by);
+    }
     pivotByGroup(groupCol, valueCol, options = {}) {
         if (this.schema[0].kind !== 'time') {
             throw new TypeError(`pivotByGroup requires a time-keyed series; got ${this.schema[0].kind}`);
@@ -1076,7 +1123,7 @@ export class TimeSeries {
             }
             outputRows.push(row);
         }
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: outputSchema,
             rows: outputRows,
@@ -1094,9 +1141,16 @@ export class TimeSeries {
      *
      * Example: `series.diff("requests", { drop: true })`.
      * Drops the first event instead of keeping it with undefined values.
+     *
+     * **Multi-entity series:** the "previous event" may belong to a
+     * different entity, producing meaningless deltas across entity
+     * boundaries. On a series carrying multiple entities (host, region,
+     * device id), use
+     * `series.partitionBy(col).diff(...).collect()` to scope per entity.
+     * See {@link TimeSeries.partitionBy}.
      */
     diff(columns, options) {
-        return this.#diffOrRate('diff', columns, options);
+        return TimeSeries.#diffOrRate(this, 'diff', columns, options);
     }
     /**
      * Example: `series.rate("requests")`.
@@ -1110,9 +1164,16 @@ export class TimeSeries {
      *
      * Example: `series.rate("requests", { drop: true })`.
      * Drops the first event instead of keeping it with undefined values.
+     *
+     * **Multi-entity series:** the "previous event" may belong to a
+     * different entity, producing meaningless rates across entity
+     * boundaries. On a series carrying multiple entities (host, region,
+     * device id), use
+     * `series.partitionBy(col).rate(...).collect()` to scope per entity.
+     * See {@link TimeSeries.partitionBy}.
      */
     rate(columns, options) {
-        return this.#diffOrRate('rate', columns, options);
+        return TimeSeries.#diffOrRate(this, 'rate', columns, options);
     }
     /**
      * Example: `series.pctChange("requests")`.
@@ -1120,18 +1181,31 @@ export class TimeSeries {
      * numeric columns. Non-specified columns pass through unchanged. The first
      * event gets `undefined` in affected columns unless `{ drop: true }` is
      * passed.
+     *
+     * **Multi-entity series:** the "previous event" may belong to a
+     * different entity, producing meaningless percentages across entity
+     * boundaries. On a series carrying multiple entities (host, region,
+     * device id), use
+     * `series.partitionBy(col).pctChange(...).collect()` to scope per
+     * entity. See {@link TimeSeries.partitionBy}.
      */
     pctChange(columns, options) {
-        return this.#diffOrRate('pctChange', columns, options);
-    }
-    #diffOrRate(mode, columns, options) {
+        return TimeSeries.#diffOrRate(this, 'pctChange', columns, options);
+    }
+    // Static private — the brand check is on the class itself, which
+    // exists regardless of how individual instances were constructed.
+    // This keeps the impl runtime-private (not reachable via
+    // `series.diffOrRateImpl(...)` like a TS-only `private` field would
+    // have been) while still working on instances built via
+    // `#fromTrustedEvents`.
+    static #diffOrRate(series, 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) => {
+        const outSchema = Object.freeze(series.schema.map((col, i) => {
             if (i === 0)
                 return col;
             if (targetSet.has(col.name)) {
@@ -1139,9 +1213,9 @@ export class TimeSeries {
             }
             return col;
         }));
-        const events = this.events;
+        const events = series.events;
         if (events.length === 0) {
-            return _a.#fromTrustedEvents(this.name, outSchema, []);
+            return TimeSeries.#fromTrustedEvents(series.name, outSchema, []);
         }
         const resultEvents = [];
         if (!drop) {
@@ -1177,7 +1251,7 @@ export class TimeSeries {
             }
             resultEvents.push(new Event(curr.key(), data));
         }
-        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+        return TimeSeries.#fromTrustedEvents(series.name, outSchema, resultEvents);
     }
     /**
      * Example: `series.cumulative({ requests: "sum" })`.
@@ -1186,6 +1260,13 @@ export class TimeSeries {
      *
      * Built-in accumulators: `"sum"`, `"max"`, `"min"`, `"count"`.
      * Custom accumulators: `(acc: number, value: number) => number`.
+     *
+     * **Multi-entity series:** the running accumulation interleaves
+     * across entities — `host-A`'s next event sums on top of
+     * `host-B`'s last value rather than `host-A`'s. On a series carrying
+     * multiple entities (host, region, device id), use
+     * `series.partitionBy(col).cumulative(...).collect()` to scope per
+     * entity. See {@link TimeSeries.partitionBy}.
      */
     cumulative(spec) {
         const entries = Object.entries(spec);
@@ -1203,7 +1284,7 @@ export class TimeSeries {
         }));
         const events = this.events;
         if (events.length === 0) {
-            return _a.#fromTrustedEvents(this.name, outSchema, []);
+            return TimeSeries.#fromTrustedEvents(this.name, outSchema, []);
         }
         const state = new Map();
         for (const [name, reducer] of entries) {
@@ -1255,12 +1336,19 @@ export class TimeSeries {
             }
             resultEvents.push(new Event(event.key(), data));
         }
-        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+        return TimeSeries.#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`.
+     *
+     * **Multi-entity series:** the value pulled in from N positions away
+     * may belong to a different entity, producing meaningless lagged
+     * values across entity boundaries. On a series carrying multiple
+     * entities (host, region, device id), use
+     * `series.partitionBy(col).shift(...).collect()` to scope per entity.
+     * See {@link TimeSeries.partitionBy}.
      */
     shift(columns, n) {
         const cols = typeof columns === 'string' ? [columns] : columns;
@@ -1281,7 +1369,7 @@ export class TimeSeries {
         }));
         const events = this.events;
         if (events.length === 0) {
-            return _a.#fromTrustedEvents(this.name, outSchema, []);
+            return TimeSeries.#fromTrustedEvents(this.name, outSchema, []);
         }
         const resultEvents = [];
         for (let i = 0; i < events.length; i++) {
@@ -1297,7 +1385,7 @@ export class TimeSeries {
             }
             resultEvents.push(new Event(events[i].key(), data));
         }
-        return _a.#fromTrustedEvents(this.name, outSchema, resultEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, outSchema, resultEvents);
     }
     /**
      * Example: `series.fill("hold")`.
@@ -1305,15 +1393,38 @@ export class TimeSeries {
      *
      * 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.
+     * Strategy names: `"hold"` (forward fill), `"bfill"` (backward fill),
+     * `"linear"` (time-interpolated), `"zero"` (fill with 0). A non-string
+     * value is used as a literal fill value.
+     *
+     * **Gap semantics — all-or-nothing.** A "gap" is a run of consecutive
+     * `undefined` cells in one column. For each gap:
+     * - With no options: fill the whole gap (existing default).
+     * - With `{ limit: N }`: fill only if the gap length is at most N
+     *   cells. Otherwise leave the gap fully unfilled.
+     * - With `{ maxGap: '3m' }`: fill only if the gap's *temporal* span
+     *   (from the prior known value to the next known value) is at most
+     *   the duration. Otherwise leave the gap fully unfilled.
+     * - With both: fill only if both caps are met.
+     *
+     * The all-or-nothing semantic is the v0.9.0 default. Earlier
+     * versions partially filled (`limit: 3` on a 5-cell gap filled 3,
+     * left 2 unfilled). The new semantic avoids fabricating data
+     * across what's actually a long outage — partial fills propagate
+     * stale values past their useful lifetime.
      *
-     * 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.
+     * `"linear"` requires known values on both sides of a gap; leading
+     * and trailing gaps are unfilled. `"hold"` fills any internal or
+     * trailing gap (leading has no prior value). `"bfill"` fills any
+     * internal or leading gap (trailing has no next value). `"zero"`
+     * and literal fills work on any gap that fits the size caps.
      *
-     * `"linear"` requires known values on both sides of a gap to interpolate.
-     * Leading and trailing `undefined` runs are left unfilled.
+     * **Multi-entity series:** fill walks one chronological event
+     * sequence — `host-A`'s missing cell would `linear`-interpolate or
+     * `hold`-carry against `host-B`'s neighboring value. On a series
+     * carrying multiple entities (host, region, device id), use
+     * `series.partitionBy(col).fill(...).collect()` to scope per entity.
+     * See {@link TimeSeries.partitionBy}.
      */
     fill(strategy, options) {
         if (this.events.length === 0) {
@@ -1343,6 +1454,7 @@ export class TimeSeries {
             }
         }
         const limit = options?.limit;
+        const maxGapMs = options?.maxGap === undefined ? undefined : parseDuration(options.maxGap);
         const n = this.events.length;
         const columns = {};
         for (const name of colNames) {
@@ -1358,106 +1470,110 @@ export class TimeSeries {
         for (let i = 0; i < n; i++) {
             times[i] = this.events[i].begin();
         }
+        // Walk each column and apply per-strategy fill on a per-gap basis,
+        // with all-or-nothing limit / maxGap checks.
         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;
-                            }
-                        }
-                    }
-                    break;
+            let i = 0;
+            while (i < n) {
+                if (col[i] !== undefined) {
+                    i += 1;
+                    continue;
                 }
-                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;
+                // Found the start of a gap.
+                const start = i;
+                while (i < n && col[i] === undefined)
+                    i += 1;
+                const end = i; // exclusive
+                const length = end - start;
+                const hasPrev = start > 0;
+                const hasNext = end < n;
+                // Strategy-level fillability: do we have the neighbors required?
+                let strategyOk;
+                switch (spec.mode) {
+                    case 'linear':
+                        strategyOk = hasPrev && hasNext;
+                        break;
+                    case 'hold':
+                        strategyOk = hasPrev;
+                        break;
+                    case 'bfill':
+                        strategyOk = hasNext;
+                        break;
+                    default:
+                        strategyOk = true; // zero, literal — no neighbor needed
                 }
-                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;
-                            }
-                        }
+                if (!strategyOk)
+                    continue;
+                // Size caps: count and temporal span.
+                if (limit !== undefined && length > limit)
+                    continue;
+                if (maxGapMs !== undefined) {
+                    // Span = time from the last known value to the next known
+                    // value. For internal gaps this uses both neighbors; for
+                    // edge-only gaps (hold trailing, bfill leading), use the
+                    // available neighbor and the gap's own first/last timestamp
+                    // as the other end so maxGap caps the carry-forward distance.
+                    let span;
+                    if (hasPrev && hasNext) {
+                        span = times[end] - times[start - 1];
                     }
-                    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;
-                            }
-                        }
+                    else if (hasPrev) {
+                        // trailing gap (hold): cap distance from prev known to last gap cell
+                        span = times[end - 1] - times[start - 1];
                     }
-                    break;
+                    else if (hasNext) {
+                        // leading gap (bfill): cap distance from first gap cell to next known
+                        span = times[end] - times[start];
+                    }
+                    else {
+                        span = 0; // unreachable given strategyOk above, but safe
+                    }
+                    if (span > maxGapMs)
+                        continue;
                 }
-                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;
-                                    }
-                                }
+                // Fill the gap per strategy.
+                switch (spec.mode) {
+                    case 'hold': {
+                        const v = col[start - 1];
+                        for (let j = start; j < end; j++)
+                            col[j] = v;
+                        break;
+                    }
+                    case 'bfill': {
+                        const v = col[end];
+                        for (let j = start; j < end; j++)
+                            col[j] = v;
+                        break;
+                    }
+                    case 'zero': {
+                        for (let j = start; j < end; j++)
+                            col[j] = 0;
+                        break;
+                    }
+                    case 'literal': {
+                        for (let j = start; j < end; j++)
+                            col[j] = spec.value;
+                        break;
+                    }
+                    case 'linear': {
+                        const before = col[start - 1];
+                        const after = col[end];
+                        const t0 = times[start - 1];
+                        const t1 = times[end];
+                        const tspan = t1 - t0;
+                        for (let j = start; j < end; j++) {
+                            if (tspan === 0) {
+                                col[j] = before;
+                            }
+                            else {
+                                col[j] = before + (after - before) * ((times[j] - t0) / tspan);
                             }
-                            gapStart = -1;
-                        }
-                        else if (gapStart < 0) {
-                            gapStart = i;
                         }
+                        break;
                     }
-                    break;
                 }
             }
         }
@@ -1469,7 +1585,156 @@ export class TimeSeries {
             }
             resultEvents.push(new Event(this.events[i].key(), data));
         }
-        return _a.#fromTrustedEvents(this.name, this.schema, resultEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, resultEvents);
+    }
+    /**
+     * Example: `series.dedupe()`.
+     * Collapses events that share a key. The default key is the full
+     * event key — `begin()` for time-keyed series, `begin()`+`end()` for
+     * time-range, and `begin()`+`end()`+`value` for interval-keyed
+     * series. Two events with the same full key are treated as
+     * duplicates. The default resolution is `'last'` wins.
+     *
+     * **Multi-entity series:** events from different entities at the
+     * same key collapse as if they were duplicates of each other —
+     * `host-A`@t and `host-B`@t collide on the timestamp alone. On a
+     * series carrying multiple entities (host, region, device id), use
+     * `series.partitionBy(col).dedupe(...).collect()` so the partition
+     * column is part of the duplicate identity. See
+     * {@link TimeSeries.partitionBy}.
+     *
+     * ```ts
+     * // Per-host dedupe — same time AND same host is the duplicate key.
+     * series.partitionBy('host').dedupe({ keep: 'last' }).collect();
+     * ```
+     *
+     * The `keep` option chooses the resolution policy:
+     *
+     * - `'first'` — keep the first occurrence at each key.
+     * - `'last'` — keep the last occurrence (default; matches WebSocket
+     *   replay semantics).
+     * - `'error'` — throw on the first duplicate seen. Useful for
+     *   ingestion paths that want to fail loudly on shape violations.
+     * - `'drop'` — discard *every* event at any duplicate key.
+     *   Conservative; the value of "1.5 events at this timestamp" is
+     *   rarely defensible.
+     * - `{ min: col }` / `{ max: col }` — keep the event with the
+     *   smallest / largest value at the named numeric column. Ties keep
+     *   the earliest tied event. Events with `undefined` at that column
+     *   lose to any event with a defined value.
+     * - `(events) => Event` — custom resolver. Receives all duplicates
+     *   at a single key (length ≥ 2) and returns one. The cleanest
+     *   pattern is to start from one of the input events and use
+     *   `event.set(field, value)` so the type stays narrow:
+     *
+     *   ```ts
+     *   series.dedupe({
+     *     keep: (events) => {
+     *       const last = events[events.length - 1];
+     *       const avg =
+     *         events.reduce((a, e) => a + (e.get('cpu') ?? 0), 0) /
+     *         events.length;
+     *       return last.set('cpu', avg);
+     *     },
+     *   });
+     *   ```
+     *
+     * Real-world ingest produces duplicates: WebSocket replays, Kafka
+     * at-least-once, retried HTTP fetches, polling overlaps. `dedupe()`
+     * is the post-ingest cleanup primitive.
+     */
+    dedupe(options = {}) {
+        const keep = options.keep ?? 'last';
+        if (this.events.length === 0) {
+            return this;
+        }
+        // Bucket key encoder. For time-keyed series, `begin()` alone fully
+        // identifies an event key; for time-range, both `begin()` and
+        // `end()` matter; for interval-keyed, the labeled `value` is part
+        // of identity too. A naive `begin()`-only key would silently
+        // collapse semantically distinct interval/timeRange events.
+        const firstKind = this.schema[0].kind;
+        const keyOf = (event) => {
+            if (firstKind === 'time') {
+                return `${event.begin()}`;
+            }
+            if (firstKind === 'timeRange') {
+                return `${event.begin()}:${event.end()}`;
+            }
+            // interval
+            const k = event.key();
+            return `${event.begin()}:${event.end()}:${String(k.value)}`;
+        };
+        // Single-pass bucket by full event key. Map iteration is insertion-
+        // order; since the input events are already sorted by key, each
+        // bucket corresponds to a unique key and the buckets traverse in
+        // input order. No re-sort needed.
+        const buckets = new Map();
+        for (const event of this.events) {
+            const k = keyOf(event);
+            let bucket = buckets.get(k);
+            if (!bucket) {
+                bucket = [];
+                buckets.set(k, bucket);
+            }
+            bucket.push(event);
+        }
+        const resolved = [];
+        for (const [keyStr, bucket] of buckets) {
+            if (bucket.length === 1) {
+                resolved.push(bucket[0]);
+                continue;
+            }
+            // Multiple events sharing the same key — apply the policy.
+            if (typeof keep === 'function') {
+                resolved.push(keep(bucket));
+                continue;
+            }
+            if (keep === 'first') {
+                resolved.push(bucket[0]);
+                continue;
+            }
+            if (keep === 'last') {
+                resolved.push(bucket[bucket.length - 1]);
+                continue;
+            }
+            if (keep === 'error') {
+                // Use the first event's begin() for the human-readable timestamp.
+                // For interval/timeRange-keyed series, also include the full
+                // encoded key so the failure mode names the exact collision.
+                const t = bucket[0].begin();
+                const detail = firstKind === 'time'
+                    ? `${new Date(t).toISOString()} (${t})`
+                    : `key "${keyStr}"`;
+                throw new Error(`dedupe: ${bucket.length} events at ${detail}. ` +
+                    `Specify a different 'keep' policy or fix upstream.`);
+            }
+            if (keep === 'drop') {
+                continue;
+            }
+            if ('min' in keep || 'max' in keep) {
+                const isMin = 'min' in keep;
+                const col = (isMin ? keep.min : keep.max);
+                let best = bucket[0];
+                let bestVal = best.get(col);
+                for (let i = 1; i < bucket.length; i += 1) {
+                    const candidate = bucket[i];
+                    const v = candidate.get(col);
+                    if (v === undefined)
+                        continue;
+                    if (bestVal === undefined || (isMin ? v < bestVal : v > bestVal)) {
+                        best = candidate;
+                        bestVal = v;
+                    }
+                }
+                resolved.push(best);
+                continue;
+            }
+            // Defensive fallthrough: unrecognized keep shape.
+            throw new TypeError(`dedupe: invalid keep option ${JSON.stringify(keep)}. ` +
+                `Expected 'first' | 'last' | 'error' | 'drop' | { min: col } | { max: col } | (events) => Event.`);
+        }
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, resolved);
     }
     rolling(sequenceOrWindow, windowOrMapping, mappingOrOptions, maybeOptions = {}) {
         let mapping;
@@ -1531,7 +1796,7 @@ export class TimeSeries {
                 ...resultColumnDefs,
             ]);
             if (!range) {
-                return new _a({
+                return new TimeSeries({
                     name: this.name,
                     schema: resultSchema,
                     rows: [],
@@ -1550,7 +1815,7 @@ export class TimeSeries {
                 });
                 return Object.freeze([bucket, ...aggregated]);
             });
-            return new _a({
+            return new TimeSeries({
                 name: this.name,
                 schema: resultSchema,
                 rows: resultRows,
@@ -1691,7 +1956,7 @@ export class TimeSeries {
                 groupStart = groupEnd;
             }
         }
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -1713,6 +1978,13 @@ export class TimeSeries {
      *
      * 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.
+     *
+     * **Multi-entity series:** the smoothing window pulls values from
+     * every entity into each smoothed point — `host-A`'s smoothed value
+     * is blended with `host-B`'s and `host-C`'s. On a series carrying
+     * multiple entities (host, region, device id), use
+     * `series.partitionBy(col).smooth(...).collect()` to scope per
+     * entity. See {@link TimeSeries.partitionBy}.
      */
     smooth(column, method, options) {
         const output = options.output;
@@ -1767,7 +2039,7 @@ export class TimeSeries {
                 ]);
             });
             const keptRows = warmup > 0 ? resultRows.slice(warmup) : resultRows;
-            return new _a({
+            return new TimeSeries({
                 name: this.name,
                 schema: resultSchema,
                 rows: keptRows,
@@ -1805,7 +2077,7 @@ export class TimeSeries {
                         .map((nextColumn) => nextEvent.data()[nextColumn.name]),
                 ]);
             });
-            return new _a({
+            return new TimeSeries({
                 name: this.name,
                 schema: resultSchema,
                 rows: resultRows,
@@ -1899,7 +2171,7 @@ export class TimeSeries {
                     .map((nextColumn) => nextEvent.data()[nextColumn.name]),
             ]);
         });
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -1907,11 +2179,11 @@ export class TimeSeries {
     }
     /** Example: `series.slice(0, 10)`. Returns a positional half-open slice of the series. */
     slice(beginIndex, endIndex) {
-        return _a.#fromTrustedEvents(this.name, this.schema, this.events.slice(beginIndex, endIndex));
+        return TimeSeries.#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 _a.#fromTrustedEvents(this.name, this.schema, this.events.filter((event, index) => predicate(event, index)));
+        return TimeSeries.#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) {
@@ -2032,7 +2304,7 @@ export class TimeSeries {
         const trimmedEvents = this.events
             .map((event) => event.trim(range))
             .filter((event) => event !== undefined);
-        return _a.#fromTrustedEvents(this.name, this.schema, trimmedEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, trimmedEvents);
     }
     /** Example: `series.before(Date.now())`. Returns the events ending strictly before the supplied temporal boundary. */
     before(boundary) {
@@ -2090,7 +2362,7 @@ export class TimeSeries {
             const selectedEvent = event.select(...keys);
             return selectedEvent;
         });
-        return _a.#fromTrustedEvents(this.name, resultSchema, resultEvents);
+        return TimeSeries.#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) {
@@ -2108,7 +2380,7 @@ export class TimeSeries {
             const renamedEvent = event.rename(mapping);
             return renamedEvent;
         });
-        return _a.#fromTrustedEvents(this.name, resultSchema, resultEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, resultSchema, resultEvents);
     }
     collapse(keys, output, reducer, options) {
         const nextEvents = this.events.map((event) => {
@@ -2136,7 +2408,7 @@ export class TimeSeries {
                         : 'string',
             },
         ]);
-        return _a.#fromTrustedEvents(this.name, resultSchema, nextEvents);
+        return TimeSeries.#fromTrustedEvents(this.name, resultSchema, nextEvents);
     }
     /**
      * Example: `series.arrayContains("tags", "critical")`.
@@ -2146,7 +2418,7 @@ export class TimeSeries {
      * carries a list of scalars.
      */
     arrayContains(col, value) {
-        return _a.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
             const data = event.data();
             const arr = data[col];
             return Array.isArray(arr) && arr.includes(value);
@@ -2160,7 +2432,7 @@ export class TimeSeries {
      * array are dropped.
      */
     arrayContainsAll(col, values) {
-        return _a.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
             const data = event.data();
             const arr = data[col];
             if (!Array.isArray(arr))
@@ -2179,7 +2451,7 @@ export class TimeSeries {
      * an empty series. Events with an `undefined` array are dropped.
      */
     arrayContainsAny(col, values) {
-        return _a.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, this.events.filter((event) => {
             const data = event.data();
             const arr = data[col];
             if (!Array.isArray(arr))
@@ -2219,7 +2491,7 @@ export class TimeSeries {
                 return data[column.name];
             }));
         });
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -2255,7 +2527,7 @@ export class TimeSeries {
                 }));
             }
         }
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -2356,6 +2628,15 @@ export class TimeSeries {
      *
      * Internally a single `rolling(window, { avg, sd })` pass over the
      * source; band edges are derived arithmetically per event.
+     *
+     * **Multi-entity series:** the baseline window aggregates across
+     * every entity, so `host-A`'s `avg`/`sd` reflect the cross-entity
+     * mean/spread rather than `host-A`'s own. Anomaly detection on a
+     * multi-entity baseline flags events relative to the wrong
+     * population. On a series carrying multiple entities (host, region,
+     * device id), use
+     * `series.partitionBy(col).baseline(...).collect()` to scope per
+     * entity. See {@link TimeSeries.partitionBy}.
      */
     baseline(col, options) {
         const { window, sigma, alignment } = options;
@@ -2410,7 +2691,7 @@ export class TimeSeries {
                 lowerNum,
             ]);
         });
-        return new _a({
+        return new TimeSeries({
             name: this.name,
             schema: resultSchema,
             rows: resultRows,
@@ -2439,6 +2720,14 @@ export class TimeSeries {
      * Internally: computes `rolling(window, { avg, sd })` using the
      * output-map form, zips with the source events by index, and keeps
      * events where `|value - avg| > sigma * sd`.
+     *
+     * **Multi-entity series:** the rolling baseline aggregates across
+     * every entity, so the deviation threshold reflects the wrong
+     * population — `host-A`'s "outlier" status is decided against the
+     * cross-entity mean rather than `host-A`'s own. On a series carrying
+     * multiple entities (host, region, device id), use
+     * `series.partitionBy(col).outliers(...).collect()` to scope per
+     * entity. See {@link TimeSeries.partitionBy}.
      */
     outliers(col, options) {
         const { window, sigma, alignment } = options;
@@ -2475,7 +2764,7 @@ export class TimeSeries {
                 kept.push(src);
             }
         }
-        return _a.#fromTrustedEvents(this.name, this.schema, kept);
+        return TimeSeries.#fromTrustedEvents(this.name, this.schema, kept);
     }
     /**
      * Example: `TimeSeries.fromPoints(pts, { schema: [...] })`.
@@ -2500,7 +2789,7 @@ export class TimeSeries {
             throw new TypeError(`TimeSeries.fromPoints requires a time-keyed schema; got first column kind '${schema[0].kind}'`);
         }
         const valueCols = schema.slice(1);
-        return new _a({
+        return new TimeSeries({
             name: options.name ?? 'points',
             schema,
             rows: points.map((p) => [
@@ -2510,7 +2799,6 @@ export class TimeSeries {
         });
     }
 }
-_a = TimeSeries;
 function aggregateInternal(series, sequence, mapping, options = {}) {
     const range = options.range ?? series.timeRange();
     const aggregateColumns = normalizeAggregateColumns(series.schema, mapping);