API · Context

`withContext()`

Materialize a record context and add synchronous metadata without changing the value.

Signature

withContext(): Exstream<T, C>
withContext<A extends object | void>(
  fn: (value: T, context: CallbackContext<T, C>) => A,
): Exstream<T, MaterializedContext<C, T> & ContextAddition<A>>

Example

const traced = exstream(rows).withContext((row) => ({
  traceId: `row-${row.id}`,
  receivedAt: Date.now(),
}))

traced.map((row, context) => ({ row, traceId: context.traceId }))

Parameters

fn

Type (value, context) => object | undefinedDefault undefined

A synchronous initializer. Its enumerable own properties are assigned to the context. Omitting it materializes context without custom fields.

Context rules

For a value without context, Exstream creates { input, signal }. At this operator boundary an existing context is copied, so later mutations in this branch do not modify the upstream object. Enumerable string fields are copied; input remains the original value and signal is rebound to this branch.

The callback may return a plain object or undefined. Arrays, null, primitives, and an object with its own signal property are rejected. Other keys, including input, can currently be assigned; avoid overriding framework fields.

Execution and errors

The callback is synchronous and runs once per successful value. Order, values, and pressure are unchanged. A thrown callback or invalid return becomes a contextual record error with stage withContext; later inputs continue when handled. Existing record errors pass through without initialization.

Forms

stream.withContext(initializer)
exstream.pipeline().withContext(initializer)
exstream.withContext(initializer, stream)
stream.through(exstream.withContext(initializer))

extendContext(), map(), fork()

withContext()