LRH5354 / promise-fun

Promise packages, patterns, chat, and tutorials

promise-fun

I intend to use this space to document my promise modules, useful promise patterns, and how to solve common problems. For now though, you can see all my promise modules below.

Contents

• Packages
• FAQ

Packages

Not accepting additions, but happy to take requests.

• pify: Promisify a callback-style function
• delay: Delay a promise a specified amount of time
• yoctodelay: Delay a promise a specified amount of time
• p-map: Map over promises concurrently
• p-all: Run promise-returning & async functions concurrently with optional limited concurrency
• p-queue: Promise queue with concurrency control
• p-event: Promisify an event by waiting for it to be emitted
• p-debounce: Debounce promise-returning & async functions
• p-throttle: Throttle promise-returning & async functions
• p-timeout: Timeout a promise after a specified amount of time
• p-retry: Retry a promise-returning or async function
• p-any: Wait for any promise to be fulfilled
• p-some: Wait for a specified number of promises to be fulfilled
• p-locate: Get the first fulfilled promise that satisfies the provided testing function
• p-limit: Run multiple promise-returning & async functions with limited concurrency
• p-series: Run promise-returning & async functions in series
• p-memoize: Memoize promise-returning & async functions
• p-pipe: Compose promise-returning & async functions into a reusable pipeline
• p-props: Like Promise.all() but for Map and Object
• p-waterfall: Run promise-returning & async functions in series, each passing its result to the next
• p-cancelable: Create a promise that can be canceled
• p-progress: Create a promise that reports progress
• p-reflect: Make a promise always fulfill with its actual fulfillment value or rejection reason
• p-filter: Filter promises concurrently
• p-reduce: Reduce a list of values using promises into a promise for a value
• p-settle: Settle promises concurrently and get their fulfillment value or rejection reason
• p-every: Test whether all promises passes a testing function
• p-one: Test whether some promise passes a testing function
• p-map-series: Map over promises serially
• p-each-series: Iterate over promises serially
• p-times: Run promise-returning & async functions a specific number of times concurrently
• p-lazy: Create a lazy promise that defers execution until .then() or .catch() is called
• p-whilst: While a condition returns true, calls a function repeatedly, and then resolves the promise
• p-do-whilst: Calls a function repeatedly while a condition returns true and then resolves the promise
• p-forever: Run promise-returning & async functions repeatedly until you end it
• p-wait-for: Wait for a condition to be true
• p-min-delay: Delay a promise a minimum amount of time
• p-try: Promise.try() ponyfill - Starts a promise chain
• p-race: A better Promise.race()
• p-immediate: Returns a promise resolved in the next event loop - think setImmediate()
• p-time: Measure the time a promise takes to resolve
• p-defer: Create a deferred promise
• p-is-promise: Check if something is a promise
• p-state: Inspect the state of a promise
• make-synchronous: Make an asynchronous function synchronous

.then/.catch-based packages

You should generally avoid using .then except in edge cases.

• p-catch-if: Conditional promise catch handler
• p-if: Conditional promise chains
• p-tap: Tap into a promise chain without affecting its value or state
• p-log: Log the value/error of a promise
• p-break: Break out of a promise chain

FAQ

How can I run 100 async/promise-returning functions with only 5 running at once?

This is a good use-case for p-map. You might ask why you can't just specify an array of promises. Promises represent values of a computation and not the computation itself - they are eager. So by the time p-map starts reading the array, all the actions creating those promises have already started running. p-map works by executing a promise-returning function in a mapper function. This way the promises are created lazily and can be concurrency limited. Check out p-all instead if you're using different functions to get each promise.

const pMap = require('p-map');

const urls = [
	'https://sindresorhus.com',
	'https://avajs.dev',
	'https://github.com',
	…
];

console.log(urls.length);
//=> 100

const mapper = url => fetchStats(url); //=> Promise

const result = await pMap(urls, mapper, {concurrency: 5});

console.log(result);
//=> [{url: 'https://sindresorhus.com', stats: {…}}, …]