README.md

delay

Invoke a function after a specified duration.

Usage

var delay = require( '@stdlib/utils/delay' );

delay( fcn, duration[, ...args] )

Invokes a function after a specified duration.

function beep() {
    console.log( 'beep' );
}

// Invoke a function after 3 seconds:
var t = delay( beep, 3000 );
// returns <Object>

The duration parameter may be specified in milliseconds or as a duration string (e.g., '5s', '10m3s', '2h', etc).

function beep() {
    console.log( 'beep' );
}

// Invoke a function after 3 seconds:
var t = delay( beep, '3s' );
// returns <Object>

The function supports providing additional arguments to pass through to the delayed function upon invocation. The delayed function receives additional arguments in the same order in which they are provided to delay.

function add( x, y ) {
    var sum = x + y;
    console.log( 'sum: %d', sum );
}

var t = delay( add, 3000, 2, 3 );
// returns <Object>

The function returns a timeout object having properties and methods as documented below.

timeout.clear()

Clears a pending invocation of a function.

function beep() {
    console.log( 'beep' );
}
var t = delay( beep, 3000 );
t.clear();

timeout.invoke()

Clears a pending invocation and invokes a function immediately.

function beep() {
    console.log( 'beep' );
}
var t = delay( beep, 3000 );
t.invoke();

timeout.duration

Read-only value specifying the duration (in milliseconds) before invoking a delayed function.

function beep() {
    console.log( 'beep' );
}
var t = delay( beep, 3000 );

var duration = t.duration;
// returns 3000

timeout.status

Read-only integer value indicating the status of a delayed function.

function beep() {
    console.log( 'beep' );
}
var t = delay( beep, 3000 );

var status = t.status;
// returns 0

t.clear();
status = t.status;
// returns 2

A status may be one of the following values:

• 0: function invocation is pending.
• 1: function invocation is complete.
• 2: function invocation has been cleared.

Notes

• In contrast to setTimeout which returns a timeout identifier and requires passing this identifier to clearTimeout in order to clear a pending invocation, the delay function returns a timeout object with additional properties and methods.

• Browsers internally limit the maximum duration of a timeout to 32-bit signed integers (approximately 24.8 days). If a duration exceeds this limit, the function will invoke a provided function after the maximum duration.

• A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported:

  • d: days
  • h: hours
  • m: minutes
  • s: seconds
  • ms: milliseconds

  For example, the string 1m3s10ms is a duration string containing three time units: 1m (1 minute), 3s (3 seconds), and 10ms (10 milliseconds). The string 60m is a duration string containing a single time unit: 60m (60 minutes).

• Duration strings are case insensitive. For example, the string 1M3S10MS is equivalent to 1m3s10ms.

Examples

var delay = require( '@stdlib/utils/delay' );

function beep() {
    console.log( 'beep' );
}
function boop() {
    console.log( 'boop' );
}
function baz() {
    console.log( 'baz' );
}

var t1 = delay( beep, 3000 );
var t2 = delay( boop, 1000 );
var t3 = delay( baz, 4000 );

t2.clear();

// Wait 3 seconds...
// => beep

// Wait 1 more second...
// => baz

---

CLI

Usage

Usage: delay [options] <duration>

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.

Notes

• The process sleeps for a specified duration before exiting.
• The duration is specified in seconds or as a duration string (e.g., '5s', '10m3s', '2h', etc).

Examples

$ delay 5