feat: add utils/delay

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

@@ -0,0 +1,206 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2022 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 number of milliseconds.
+
+<!-- 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, wait\[, ...args] )
+
+Invokes a function after a specified number of milliseconds.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+
+delay( beep, 3000 );
+// Logs 'beep' after three seconds...
+```
+
+The function accepts additional arguments to invoke the function with.
+
+```javascript
+function add( x, y ) {
+    var sum = x + y;
+    console.log( 'sum: %d', sum );
+}
+
+delay( add, 3000, 2, 3 );
+// Logs 'sum: 5' after three seconds...
+```
+
+The function returns a `timeout` object with the following properties and methods:
+
+#### timeout.clear()
+
+Clears a pending invocation of a function.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+var t = delay( beep, 3000 );
+t.clear();
+```
+
+#### timeout.invoke()
+
+Invokes a function immediately.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+var t = delay( beep, 3000 );
+t.invoke();
+// Logs 'beep' immediately...
+```
+
+#### timeout.duration
+
+Timeout duration (in milliseconds) before invoking a function.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+var t = delay( beep, 3000 );
+var duration = t.duration;
+// returns 3000
+```
+
+#### timeout.status
+
+Integer indicating the status of a timeout. The following values are possible:
+
+-   `0`: fuction has not yet been invoked.
+-   `1`: function has been invoked.
+-   `2`: function invocation has been cleared.
+
+```javascript
+function beep() {
+    console.log( 'beep' );
+}
+var t = delay( beep, 3000 );
+var status = t.status;
+// returns 0
+
+t.clear();
+status = t.status;
+// returns 2
+```
+
+</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
+
+-   The function accepts additional arguments to invoke the function with. These arguments are provided to the supplied function in the same order as provided to the `delay` function.
+-   In contrast to using `setTimeout`, which returns a timeout identifier that can be used to clear a pending invocation by calling `clearTimeout`, the `delay` function returns a `timeout` object with additional properties and methods.
+
+</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 );
+
+t1.clear();
+
+// Wait 3 seconds...
+// => beep
+
+// Wait 1 more second...
+// => baz
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- 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">
+
+</section>
+
+<!-- /.links -->