API · Transform

`flatMap()`

Map each input to a value or synchronous iterable, then emit its members inline.

Signature

flatMap<U>(
  fn: (value: T, context: CallbackContext<T, C>) => U,
): Exstream<FlatValue<U>, C>

Example

const lineItems = exstream(orders).flatMap((order) => order.items)

Parameters

fn

Type (value, context) => URequired

Called synchronously for each successful input. Return any synchronous iterable to expand it. Non-iterable values and strings are emitted once. The optional context is created only when the callback declares it.

Flattening

Arrays, sets, maps, generators, and other synchronous iterables are expanded. Strings are deliberately treated as scalar values rather than sequences of characters:

exstream([1, 2])
  .flatMap((value) => [value, value * 10])
  .valuesSync()
// [1, 10, 2, 20]

exstream(['Ada'])
  .flatMap((name) => name)
  .valuesSync()
// ['Ada']

The operator is equivalent to mapping and then synchronously flattening one level. It does not flatten nested iterables recursively, await promises, or merge returned Exstreams.

When the callback requests a context, it receives context.input, the branch context.signal, and custom upstream fields. Flattening gives every emitted member its own shallow context copy, preserving those fields while preventing sibling members from sharing later mutations.

Order and pressure

Inputs remain ordered, and every member of one returned iterable is emitted before the next input is processed. The iterable is consumed synchronously under downstream demand. Very large or infinite iterables can therefore monopolize the pipeline; return bounded iterables or model asynchronous sources as streams.

Errors

A callback failure becomes a record error for its input, and existing record errors pass through. Iteration itself is synchronous and is not wrapped by the callback’s error boundary: if a returned iterator throws from next(), that exception escapes the synchronous processing turn rather than becoming a contextual record error. Return well-behaved iterables and perform fallible generation inside the callback when record-level recovery is required.

Forms

flatMap() is available on streams and reusable pipelines, plus direct and curried standalone forms:

stream.flatMap(fn)
exstream.pipeline().flatMap(fn)
exstream.flatMap(fn, stream)
stream.through(exstream.flatMap(fn))

map(), merge(), through()

flatMap()