API · Select

`find()`

Emit the first value accepted by a synchronous predicate, then stop this branch.

Signature

find<S extends T>(fn: (value: T, context: C) => value is S): Exstream<S, C>
find(fn: (value: T, context: C) => unknown): Exstream<T, C>

Example

const firstOverdue = await exstream(invoices)
  .find((invoice) => invoice.status === 'overdue')
  .value()

Parameters

fn

Type (value, context) => unknownRequired

Runs synchronously for successful values until its first truthy result. A TypeScript type predicate narrows the output type. Declare context only when needed.

Behavior

The matching value is included. If nothing matches, the stream ends without emitting a value. find() is equivalent to filter(fn).take(1): it preserves order, adds no independent buffer, and destroys its consuming branch immediately after the match so upstream work can be cancelled when no sibling still needs it.

Record errors pass through and do not call fn. A handled error does not end the search. Context follows the matched value.

Errors

If fn throws, the failure becomes a record error for that input. find() does not await promises; a returned promise is truthy, so use asyncFilter() followed by head() for an asynchronous predicate.

Forms

stream.find(predicate)
exstream.pipeline().find(predicate)
exstream.find(predicate, stream)
stream.through(exstream.find(predicate))

filter(), findWhere(), head(), stopWhen()

find()