API · Aggregate

`groupBy()`

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

Signature

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

Example

const byRegion = await exstream(customers).groupBy('region').value()
// { 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.

groupBy() retains every successful value and is unsuitable for unbounded input. Its result carries an aggregate context. Existing record errors pass through and are not included.

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')
exstream.groupBy((row) => row.region, stream)
stream.through(exstream.groupBy('region'))

keyBy(), sortedGroupBy(), reduce()

groupBy()