feat: add utils/delay

lib/node_modules/@stdlib/utils/delay/README.md

@@ -0,0 +1,289 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# delay
+
+> Invoke a function after a specified duration.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var delay = require( '@stdlib/utils/delay' );
+```
+
+#### delay( fcn, duration\[, ...args] )
+
+Invokes a function after a specified duration.
+
+```javascript
+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](#notes-duration-string) (e.g., `'5s'`, `'10m3s'`, `'2h'`, etc). 
+
+```javascript
+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`.
+
+```javascript
+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.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+var t = delay( beep, 3000 );
+t.clear();
+```
+
+#### timeout.invoke()
+
+Clears a pending invocation and invokes a function immediately.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+-   In contrast to [`setTimeout`][mdn-settimeout] which returns a timeout identifier and requires passing this identifier to [`clearTimeout`][mdn-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`.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+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
+```
+
+</section>
+
+<!-- /.examples -->
+
+* * *
+
+<section class="cli">
+
+## CLI
+
+<section class="usage">
+
+### Usage
+
+```text
+Usage: delay [options] <duration>
+
+Options:
+
+  -h,    --help                Print this message.
+  -V,    --version             Print the package version.
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+### Notes
+
+-   The process sleeps for a specified duration before exiting.
+-   The `duration`  is specified in seconds or as a [duration string](#notes-duration-string) (e.g., `'5s'`, `'10m3s'`, `'2h'`, etc).
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+### Examples
+
+```bash
+$ delay 5
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.cli -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[mdn-settimeout]: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout
+
+[mdn-cleartimeout]: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/clearTimeout
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/utils/delay/benchmark/benchmark.js

@@ -0,0 +1,52 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var delay = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var t;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		t = delay( beep, 1000 );
+		if ( typeof t.status !== 'number' ) {
+			b.fail( 'should return a timeout object' );
+		}
+	}
+	b.toc();
+	if ( !isBoolean( t.status ) ) {
+		b.fail( 'should return a timeout object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+
+	function beep() {
+		console.log( 'beep' );
+	}
+});

lib/node_modules/@stdlib/utils/delay/docs/repl.txt

@@ -0,0 +1,37 @@
+
+{{alias}}( fcn, wait[, ...args] )
+    Invokes a function after a specified number of milliseconds.
+
+    Parameters
+    ----------
+    fcn: Function
+        Function to invoke.
+
+    wait: integer
+        Milliseconds to wait before invoking a function.
+
+    args: ...any
+        Additional arguments with which to invoke the function.
+
+    Returns
+    -------
+    out: Object
+        Function invocation timeout object.
+
+    Examples
+    --------
+    > function beep() { console.log( 'beep' ); };
+    > {{alias}}( beep, 3000 )
+    <timeout>
+    > var t = {{alias}}( beep, 3000 )
+    <timeout>
+    > t.clear()
+    > t.invoke()
+    beep
+    > t.duration
+    3000
+    > t.status
+    0
+
+    See Also
+    --------