As suggested in #15.

Notes:

1. This depends on #16.
2. Currently, abort() throws an AbortError. Perhaps that behavior should be optional? I usually find myself wanting to cancel everything that follows, and I'd rather not add a catch in those cases.
3. I'm introducing a dependency on p-defer, which is lightweight, but still relevant.
4. I'm not entirely sure which issue the unhandled rejection handler originally solved, so the PR probably introduces an issue with that. I'm not getting any warnings from the tests though. Is it the known failure in the tests?

Idea from: https://github.com/ariporad/ava/blob/c7b0154f8ae181e892d58ab1d50aee6154a9a743/test/test.js#L7-L12

delay.reject(100, 'message');
delay.reject(100, new Error('message')); // equivalent to the above

If a string, it's converted to an Error, otherwise passed through.

I know the first case is not like Promise.reject(), but is there any good reason not to reject with an error?

@ariporad @jamestalmage Do you think it would be useful to have this here?

The lib reference to dom https://github.com/sindresorhus/delay/blob/34e50092c96d05f3d248130212a163a22570618f/index.d.ts#L1 prevents this from being properly usable within non-DOM contexts such as react-native.

node_modules/typescript/lib/lib.dom.d.ts:17604:6 - error TS2300: Duplicate identifier 'RequestInfo'.

17604 type RequestInfo = Request | string;
           ~~~~~~~~~~~

node_modules/@types/react-native/globals.d.ts:92:14
92 declare type RequestInfo = Request | string;
                ~~~~~~~~~~~
RequestInfo' was also declared here.

I know I modified the code a fair bit from the original. If you'd prefer I keep closer to the original code (e.g. variable names, use of p-defer, remove package-lock.json) then I will do that. I can also add any additional tests you have on your mind.

These commits avoid intermediary functions, shorten the code and deobfuscate the resolve/reject part of the code.

I'm not sure of how you feel about retouching code that works, but I thought I'd make a PR to possibly improve readability of the code.

This adds support for aborting a delay through the native AbortSignal.

This allows writing functions with async/await where the signal can just be passed down through functions without much boilerplate (in opposite to cancellable Promises). It is the cancellation mechanism used by modern APIs like fetch and WebAuthentication.

Example use:

async function pollStatus(signal) {
	while (true) {
		const status = await fetchStatus(signal)
		if (status === 'pending') {
			await delay(1000, signal)
 			continue
		}
		return status
	}
}
async function fetchStatus(signal) {
	const resp = await fetch('/api/status', { signal })
	checkStatus(resp)
	return await resp.json()
}

When the AbortSignal is aborted, it rejects with an AbortError like fetch does. This is so calling code does not continue execution and gets a chance to clean up resources in finally blocks. At the top level the error can be checked with err.name === 'AbortError'.

I chose to allow passing AbortSignal as a second parameter too, which technically prevents users from using an AbortSignal as a resolve value, but I think the chance that someone wants to do that intentionally is basically zero. It would be possible to require delay(1000, null, signal) instead, but that would probably more bugs than the alternative.

It'd be useful if I could do the following:

import { factory } from 'delay'

const delay = factory({ setTimeout, clearTimeout })

Since this binds the implementation to the timer methods I've provided, I can then safely stub the timers using say lolex and still use the delay interface.

I've been using the delay module in a typescript module (@google-cloud/profiler).

I'd previously used the type definitions from DefinitelyTyped, so @types/delay, without issue. But when I try to use version 3.1.0 of this module (and use the types from this latest version), my module no longer compiles, and I get errors like:

ts/test/test-time-profiler.ts:65:16 - error TS2349: Cannot invoke an expression whose type lacks a call signature. Type 'typeof import("/usr/local/google/home/nolanmar/cloud-profiler-nodejs-working/cloud-profiler-nodejs/node_modules/delay/index")' has no compatible call signatures.

65          await delay(2 * durationMillis);
                  ~~~~~~~~~~~~~~~~~~~~~~~~~

Is this expected? Any advice for how I can migrate to version 3.1.0 of `delay?

I came across this solution in this thread. It's more experimental and maybe we can take some ideas from it.

However, it's not 100% identical to what we had. Because when using .reject(), the value is optional, which doesn't look like I can do easily with this approach.

A second approach could be to just do this

export interface Options {
	signal?: AbortSignal,
}

export interface ValueOptions<Value> {
	value: Value
}

declare const delay: {
	(milliseconds: number, options?: Options): ClearablePromise<void>;

	<Value>(milliseconds: number, options?: Options & ValueOptions<Value>): ClearablePromise<Value>;

	reject(milliseconds: number, options?: Options & Partial<ValueOptions<Value>>): ClearablePromise<never>;
};

Wrapping it in Partial makes all the properties of that interface optional.

I would be fine with keeping it as is though. Just wanted to share my ideas.

Since this thing is only 9 hours old, I think we're safe doing it.

When used in this fashion:

promiseFn()
  .then(delay(200))

I think it should delay 200ms from the time the first promise resolves.

This started with a simple bugfix:

• DRY delay creation
• Add test for range() and createWithTimers()

Except that Node.js 6 doesn't do object spread. So I've changed this to require Node.js 10.

Which requires a breaking change, so I've removed the default export.

I'd appreciate this if this can ship without also upgrading to use ESM.

The default implementation of setTimeout can only accept values within the range of positive signed 32-bit integers. Passing a timeout greater than (2^31)-1 milliseconds (0x7FFFFFFF) yields a TimeoutOverflowWarning and causes the runtime to ignore the specified timeout, assuming a value of 1ms (which by the way seems a dangerous default, I would have opted for using the maximum supported value or straight out throw an error).

This unexpected behavior is not documented in the README, but rather than documenting this quirk of the runtime I'd like to propose a solution: instead of relying on the bare setTimeout, delay could use a wrapped version of it. Something like this:

const maxSupportedTimeout = 0x7fffffff;
type TimeoutContext = { id: ReturnType<typeof setTimeout> };
const defaultSetTimeout = (
  callback: (...args: any[]) => void,
  ms: number,
  timeoutContext?: Partial<TimeoutContext>
): TimeoutContext => {
  timeoutContext = timeoutContext || { id: undefined };
  if (ms > maxSupportedTimeout) {
    timeoutContext.id = setTimeout(
      defaultSetTimeout,
      maxSupportedTimeout,
      callback,
      ms - maxSupportedTimeout,
      timeoutContext
    );
  } else {
    timeoutContext.id = setTimeout(callback, ms);
  }
  return timeoutContext as TimeoutContext;
};
const defaultClearTimeout = (timeoutContext: TimeoutContext) =>
  clearTimeout(timeoutContext.id);

The timeoutContext is passed by reference, therefore each time defaultSetTimeout gets called the timeout id gets updated, so that defaultClearTimeout can always access the most recent value.