Observable: find() method

Syntax

find(predicate)
find(predicate, options)

Parameters

predicate

A function to execute for each value emitted by the source observable. It should return a truthy value to indicate the value passes the test, and a falsy value otherwise. The function is called with the following arguments:

value

The current value being processed.

index

The index of the current value being processed, starting from 0.

options Optional

An options object containing the following properties:

signal Optional

An AbortSignal that can be used to cancel the operation. Aborting the signal unsubscribes from the source and rejects the promise with the signal's reason. If the signal is already aborted, the promise rejects without subscribing to the source.

Return value

A Promise that resolves to the first value for which predicate returns a truthy value. If the source completes without a matching value, the promise fulfills with undefined.

If the source errors or predicate throws an exception, the promise rejects with that error. If the operation is aborted, the promise rejects with the abort reason.

Description

Like other promise-returning operators, this method subscribes to the source immediately when called. It does not require a separate call to subscribe().

When predicate returns a truthy value, find() unsubscribes from the source without waiting for it to complete. If the source never completes and no value passes the test, the promise remains pending unless the operation errors or is aborted.

The return value of predicate is converted to a boolean without awaiting it. An async function returns a truthy promise object regardless of its eventual result, so it cannot be used as an asynchronous test.

If predicate throws an exception, the operation unsubscribes from the source.

If the selected value is a promise, the returned promise adopts its eventual state rather than fulfilling with the promise object itself.

Examples

Using find()

This example finds the first Shift-click among up to three button clicks and displays its coordinates. If no click matches, it displays a message instead. Click Restart after the stream ends to try again.

<button>Click me</button>
<p>Waiting for clicks</p>
<button id="restart" disabled>Restart</button>

const btn = document.querySelector("button");
const output = document.querySelector("p");

const restart = document.querySelector("#restart");

function start() {
  restart.disabled = true;
  output.textContent = "Waiting for clicks";
  btn
    .when("click")
    .take(3)
    .find((event) => event.shiftKey)
    .then((result) => {
      restart.disabled = false;
      output.textContent = result
        ? `${result.clientX},${result.clientY}`
        : "No Shift-click found.";
    });
}

restart.when("click").subscribe(start);
start();

Specifications

Browser compatibility

See also

• Observable.every()
• Observable.some()
• Using observables
• Observable explainer