pond-ts API Reference (core)
    Preparing search index...

    Class LivePartitionedSeries<S, K>

    Live counterpart to PartitionedTimeSeries. Routes events from a source LiveSource<S> into per-partition LiveSeries<S> sub-buffers, each with its own retention, grace window, and stateful operator pipeline.

    Per-partition semantics (settled in the v0.11 design pass):

    • Retention applies to each partition independently. A chatty host can't squeeze a quiet one out of the buffer.
    • Grace windows apply per partition. A late event for host-A does not perturb host-B's emission. Caveat: per-partition grace is bounded by the source's grace window. If the source rejects an event (because it's older than the source's grace), it never reaches the partitioned view. Setting partitionBy('host', { graceWindow: '10m' }) on a source with graceWindow: '1m' silently uses the smaller window.
    • Aggregation timing is per-partition. host-A's rolling avg fires when host-A has enough data, regardless of host-B.
    • Auto-spawn on new partition values: the first time a value not seen before arrives, allocate a sub-buffer. Optional { groups } upfront declares the expected set (mirrors the batch typed-groups pattern); when set, unknown partition values throw on ingest.

    v0.11 PR 1 scope — foundation only. Compose operators per partition via apply((sub) => sub.fill(...).rolling(...)). Typed chainable sugar methods (fill(...).rolling(...).collect()) arrive in v0.11 PR 2.

    const live = new LiveSeries({ ... });

    // Per-host event lookup — direct subscription per partition.
    const byHost = live.partitionBy('host').toMap();
    byHost.get('api-1')?.on('event', (e) => { ... });

    // Apply a chain of live operators per partition; collect into a
    // unified LiveSeries.
    const cpuSmoothed = live.partitionBy('host').apply((sub) =>
      sub.fill({ cpu: 'hold' }).rolling('1m', { cpu: 'avg' }),
    );

    Type Parameters

    Index

    Constructors

    constructor

    Properties

    by groups? name schema

    Methods

    _addDisposer apply collect cumulative diff dispose fill pctChange rate rolling toMap

    Constructors

    Properties

    by: keyof EventDataForSchema<S> & string
    groups?: readonly K[]
    name: string
    schema: S

    Methods

    _addDisposer

    • _addDisposer(fn: () => void): void
      Internal

      — register a cleanup callback to be fired when this root partitioned series is disposed. Used by LivePartitionedView.toMap() to track factory-output subscriptions that would otherwise leak across repeated calls.

      Parameters

      • fn: () => void

      Returns void

    • Apply factory per-partition and fan in the outputs into a single unified LiveSeries<R>. The factory is called once per partition (current and future); each call receives the partition's LiveSource<S> and should return a LiveSource<R> derived from it (typically by composing LiveSeries-style operators like sub.fill(...).rolling(...)).

      The unified series subscribes to every factory output and pushes events as they arrive. Auto-spawn propagates: a new partition value triggers a fresh factory invocation and the resulting LiveSource is subscribed to.

      Append-only semantics. Same as collect() — this is a fan-in sink. Per-partition output evictions (e.g. from a window operator inside the factory) are NOT propagated to the unified buffer. Use the options argument to set the unified buffer's own retention.

      History replay. When apply() is called on a partitioned view that already has events distributed across multiple partitions, existing factory-output events are gathered from every output, sorted globally by time, and pushed into the unified buffer in time order. This preserves strict ordering for the unified buffer.

      Factory contract. The factory must be pure and re-runnable: side-effect-free, no closure-captured state that mutates across calls, no external subscriptions on the input or output. The implementation invokes the factory once upfront on a stub LiveSeries<S> (to capture the output schema synchronously) and again once per partition (current and future). Factories that don't satisfy the contract may leak state across the stub call and the real per-partition calls.

      Ordering caveat: same as collect() — pass { ordering: 'reorder' } if the source uses reorder mode and reordered events will reach the unified buffer.

      Type Parameters

      Parameters

      Returns LiveSeries<R>

    • Fan in events from every partition into a single unified LiveSeries<S>. Subscribes to per-partition output 'event' streams and pushes each event into the unified buffer.

      Append-only semantics. This is a fan-in sink, not a mirrored materialization. When per-partition retention or grace evicts events from a sub-buffer, those evictions are NOT propagated to the unified buffer. The unified buffer keeps every event it ever received until evicted by its own retention. To control its size, pass a retention option to collect. To inspect the current per-partition state, use toMap() and snapshot each partition independently.

      Ordering caveat: the unified LiveSeries defaults to 'strict' ordering. If the source uses ordering: 'reorder' (i.e., accepts late events out-of-order), reordered events will arrive at the unified buffer out of order and throw. Pass { ordering: 'reorder', graceWindow: ... } to collect when the source is in reorder mode.

      Parameters

      Returns LiveSeries<S>

    • Per-partition cumulative. See LiveSeries.cumulative.

      Type Parameters

      • const Targets extends string

      Parameters

      • spec: {
            [P in string]:
                | "sum"
                | "count"
                | "min"
                | "max"
                | ((acc: number, value: number) => number)
        }

      Returns LivePartitionedView<
          S,
          readonly [S[0], ReplaceSmoothedColumn<ValueColumnsForSchema<S>, Targets>],
          K,
      >

    • Dispose of the partitioned view: unsubscribe from the source, disconnect every per-partition pipeline subscriber (created by collect() and apply()), and drop spawn listeners. Safe to call multiple times.

      Note: this does not clear the per-partition LiveSeries sub-buffers themselves. Their event arrays linger until the LivePartitionedSeries instance becomes unreferenced and is garbage-collected. If you want to free the sub-buffer memory eagerly, drop your reference to the LivePartitionedSeries after dispose().

      Returns void

    • Per-partition rolling. See LiveSeries.rolling.

      Partition column drops by default. rolling's output schema only retains columns named in mapping. Without including the partition column, the unified output of the chain loses the partition tag (e.g. host becomes undefined). To keep the partition column visible, include it in mapping with a passthrough reducer:

      partitioned.rolling('5m', { cpu: 'avg', host: 'last' })
      //                                       ^^^^^^^^^^^^^^

      Type Parameters

      • const M extends Readonly<AggregateMapEntries<S>>

      Parameters

      Returns LivePartitionedView<
          S,
          readonly [S[0], AggregateColumns<ValueColumnsForSchema<S>, M>],
          K,
      >

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods