Delays the chaining of a promise by a specified time in milliseconds.

waitInPromise.js

/**
 * Part of [Canivete](http://canivete.leofavre.com/#waitinpromise)
 *
 * Delays the chaining of a promise by a specified
 * time in milliseconds.
 *
 * The function is curried so as to be used inside
 * the `.then()` method, passing along the resolved
 * value from the previous promise step to the next.
 *
 * Note that if a non-numeric parameter is passed,
 * the promise resolves without delay, skipping the
 * internal `setTimeout()`.
 * 
 * @category Promise
 *
 * @param  {number} delay The delay in milliseconds.
 * @return {Promise} When fulfilled, returns the resolved value from the previous step.
 * @public
 *
 * @example
 * Promise.resolve("waiting")
 * 	.then(waitInPromise(1000))
 * 	.then(doSomethingAfterOneSecond);
 */
const waitInPromise = delay => arg =>
	(Number.isFinite(delay) && delay > 0) ?
	new Promise(resolve => setTimeout(() => resolve(arg), delay)) :
	Promise.resolve(arg);

export default waitInPromise;

Seems to have exactly the same effect as writing a then() containing an explicit ordinary Promise-converted setTimeout, except that the timeout duration is tested to be sure it is reasonable, in case such a check is needed. Myself, I'd rather have the delay written explicitly, since I would not use this functionality often.

Side comment: A perhaps rare use case for such an explicit delay is in browser notification modal boxes: Firefox creates them asynchronously and returns a Promise (using the browser.notifications.create function), but resolves the Promise too early, so multiple notifications created too quickly misbehave. An explicit delay of 500 msec in a surrounding Promise or in a then() works well to give enough time to allow the box to be displayed; an additional overlapping or sequential 2000 msec delay can also be written if you would like the notification box to disappear automatically instead of waiting for the user to click the box to dismiss it. The result is perfect behavior for multiple notification boxes.