p-locate

What is p-locate?

The p-locate package is a Node.js module that allows you to find and locate a promise that fulfills from an array of promises. It is useful for situations where you have multiple asynchronous operations and you want to find the first one that succeeds, without waiting for all of them to complete.

What are p-locate's main functionalities?

Locate a fulfilling promise

This feature allows you to iterate over an array of promises and find the first one that fulfills a condition without waiting for all promises to settle. The code sample demonstrates how to use p-locate to find a promise that resolves with the value 'third'.

const pLocate = require('p-locate');

const promises = [
  Promise.resolve('first'),
  Promise.reject(new Error('second')),
  Promise.resolve('third')
];

pLocate(promises, value => value === 'third').then(result => {
  console.log(result); //=> 'third'
});

Other packages similar to p-locate

p-any

p-any is similar to p-locate in that it is designed to find the first promise that fulfills. The difference is that p-any does not provide a way to specify a condition; it simply returns the first promise that fulfills.

p-some

p-some is like p-locate but for multiple promises. It allows you to specify a count of how many fulfilling promises you want to find before returning, whereas p-locate will only find the first one.

promise-race

promise-race is a function that behaves like Promise.race, but with an array of promises. It is similar to p-locate in that it returns the first promise that fulfills or rejects, but it does not allow for a condition to be specified.

README

p-locate

Get the first fulfilled promise that satisfies the provided testing function

Think of it like an async version of Array#find.

Install

$ npm install p-locate

Usage

Here we find the first file that exists on disk, in array order.

import {pathExists} from 'path-exists';
import pLocate from 'p-locate';

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

const foundPath = await pLocate(files, file => pathExists(file));

console.log(foundPath);
//=> 'rainbow'

The above is just an example. Use locate-path if you need this.

API

pLocate(input, tester, options?)

Returns a Promise that is fulfilled when tester resolves to true or the iterable is done, or rejects if any of the promises reject. The fulfilled value is the current iterable value or undefined if tester never resolved to true.

input

Type: Iterable<Promise | unknown>

An iterable of promises/values to test.

tester(element)

Type: Function

This function will receive resolved values from input and is expected to return a Promise<boolean> or boolean.

options

Type: object

concurrency

Type: number
Default: Infinity
Minimum: 1

The number of concurrently pending promises returned by tester.

preserveOrder

Type: boolean
Default: true

Preserve input order when searching.

Disable this to improve performance if you don't care about the order.

Related

• p-map - Map over promises concurrently
• p-filter - Filter promises concurrently
• p-any - Wait for any promise to be fulfilled
• More…

Get professional support for this package with a Tidelift subscription
_{Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.}