API · Aggregate

`groupBy()`

Collect the entire stream into an object whose keys map to arrays of matching values.

Example

const byRegion = await exstream(customers).groupBy('region').single()
// { eu: [...], us: [...] }

Parameters

selector

Type function | string fieldRequired

A synchronous key callback or string field path. String selectors support dot/bracket traversal. The declaration currently permits any property key, but the runtime shorthand recognizes strings only; use a callback for number or symbol fields. Returned keys should be strings, numbers, or symbols; objects are coerced by normal property assignment.

Behavior

All successful input is consumed before one grouped object is emitted. Values inside each group retain input order. A null, undefined, or missing key is stored under Exstream’s nil symbol, so it is accessible through symbol enumeration but omitted by ordinary JSON serialization.

The result carries an aggregate context. Existing record errors pass through and are not included.

Buffering

groupBy() retains every successful value in its group until the source ends. It needs the end signal before it can know that the grouped object is complete, so memory use grows with the entire input and unbounded streams never produce a result.

Use sortedGroupBy() when equal keys are adjacent: it emits each completed group incrementally and only retains the current group.

Errors

A selector failure becomes a record error and terminates the underlying reduction without a grouped result. Promise keys are not awaited.

Forms

stream.groupBy('region')
exstream.pipeline().groupBy('region')

Signature

groupBy<K extends PropertyKey>(
  selector: ((value: T, context: C) => K) | keyof T,
): Exstream<Record<K, T[]>, AggregateContext<Record<K, T[]>, C>>

keyBy(), sortedGroupBy(), reduce()

groupBy()