diff --git a/lib/node_modules/@stdlib/utils/delay/README.md b/lib/node_modules/@stdlib/utils/delay/README.md new file mode 100644 index 00000000000..a599584f3cc --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/README.md @@ -0,0 +1,289 @@ + + +# delay + +> Invoke a function after a specified duration. + + + +
+ +
+ + + + + +
+ +## 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 +``` + +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 +``` + +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 +``` + +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. + + + + + + + +
+ +## 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`. + +
+ + + + + +
+ +## Examples + + + +```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 +``` + +
+ + + +* * * + +
+ +## CLI + +
+ +### Usage + +```text +Usage: delay [options] + +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](#notes-duration-string) (e.g., `'5s'`, `'10m3s'`, `'2h'`, etc). + +
+ + + +
+ +### Examples + +```bash +$ delay 5 +``` + +
+ + + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/utils/delay/benchmark/benchmark.js b/lib/node_modules/@stdlib/utils/delay/benchmark/benchmark.js new file mode 100644 index 00000000000..7fdbd2d7d45 --- /dev/null +++ b/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' ); + } +}); diff --git a/lib/node_modules/@stdlib/utils/delay/docs/repl.txt b/lib/node_modules/@stdlib/utils/delay/docs/repl.txt new file mode 100644 index 00000000000..310b9a559ff --- /dev/null +++ b/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 ) + + > var t = {{alias}}( beep, 3000 ) + + > t.clear() + > t.invoke() + beep + > t.duration + 3000 + > t.status + 0 + + See Also + -------- diff --git a/lib/node_modules/@stdlib/utils/delay/docs/types/index.d.ts b/lib/node_modules/@stdlib/utils/delay/docs/types/index.d.ts new file mode 100644 index 00000000000..0786bffc714 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/docs/types/index.d.ts @@ -0,0 +1,55 @@ +/** +* @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. +*/ + +// TypeScript Version: 2.0 + +/** +* Invokes a function after a specified number of milliseconds. +* +* @private +* @param fcn - function to invoke +* @param wait - wait duration (in milliseconds) +* @param args - arguments with which to invoke `fcn` +* @returns timeout object +* +* @example +* function beep() { +* console.log( 'beep' ); +* } +* +* var t = delay( beep, 3000 ); +* +* var status = t.status; +* // returns 0 +* +* t.clear(); +* +* status = t.status; +* // returns 2 +* +* t.invoke(); +* +* var duration = t.duration; +* // returns 3000 +*/ +declare function delay( fcn: Function, wait: number, ...args: Array ): TimeoutObject; // tslint-disable-line max-line-length + +// EXPORTS // + +export = delay; + diff --git a/lib/node_modules/@stdlib/utils/delay/docs/types/test.ts b/lib/node_modules/@stdlib/utils/delay/docs/types/test.ts new file mode 100644 index 00000000000..69c5ac2fb2b --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/docs/types/test.ts @@ -0,0 +1,58 @@ +/** +* @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. +*/ + +import delay = require( './index' ); + + +// TESTS // + +// The function returns a timeout object... +{ + delay( () => {}, 2000 ); // $ExpectType TimeoutObject +} + +// The compiler throws an error if the function is provided a first argument which is not a function... +{ + delay( 'beep', 2000 ); // $ExpectError + delay( 5, 2000 ); // $ExpectError + delay( true, 2000 ); // $ExpectError + delay( false, 2000 ); // $ExpectError + delay( null, 2000 ); // $ExpectError + + delay( [], 2000 ); // $ExpectError + delay( {}, 2000 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a number... +{ + delay( () => {}, 'beep' ); // $ExpectError + delay( () => {}, true ); // $ExpectError + delay( () => {}, false ); // $ExpectError + delay( () => {}, null ); // $ExpectError + delay( () => {}, [] ); // $ExpectError + delay( () => {}, {} ); // $ExpectError +} + +// The compiler throws an error if the function is provided an incorrect number of arguments... +{ + delay(); // $ExpectError + delay( () => {} ); // $ExpectError + delay( () => {}, 2000, 'beep' ); // $ExpectError +} + + diff --git a/lib/node_modules/@stdlib/utils/delay/examples/index.js b/lib/node_modules/@stdlib/utils/delay/examples/index.js new file mode 100644 index 00000000000..a76982276e6 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/examples/index.js @@ -0,0 +1,43 @@ +/** +* @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'; + +var delay = require( './../lib' ); + +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 diff --git a/lib/node_modules/@stdlib/utils/delay/lib/index.js b/lib/node_modules/@stdlib/utils/delay/lib/index.js new file mode 100644 index 00000000000..3be9558ce4f --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/lib/index.js @@ -0,0 +1,44 @@ +/** +* @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'; + +/** +* Invoke a function after a specified number of milliseconds. +* +* @module @stdlib/utils/delay +* +* @example +* var delay = require( '@stdlib/utils/delay' ); +* +* function beep() { +* console.log( 'beep' ); +* } +* +* delay( beep, 3000 ); +* // Logs 'beep' after three seconds... +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/utils/delay/lib/main.js b/lib/node_modules/@stdlib/utils/delay/lib/main.js new file mode 100644 index 00000000000..43ab1a95bed --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/lib/main.js @@ -0,0 +1,64 @@ +/** +* @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 // + +// TODO: Load required modules... + + +// MAIN // + +/** +* Invokes a function after a specified number of milliseconds. +* +* @private +* @param {Function} fcn - function to invoke +* @param {NonNegativeInteger} wait - wait duration (in milliseconds) +* @param {...*} [args] - arguments with which to invoke `fcn` +* @returns {TimeoutObject} timeout object +* +* @example +* function beep() { +* console.log( 'beep' ); +* } +* +* var t = delay( beep, 3000 ); +* +* var status = t.status; +* // returns 0 +* +* t.clear(); +* +* status = t.status; +* // returns 2 +* +* t.invoke(); +* +* var duration = t.duration; +* // returns 3000 +*/ +function delay( fcn, wait ) { + // TODO: Add implementation... +} + + +// EXPORTS // + +module.exports = delay; diff --git a/lib/node_modules/@stdlib/utils/delay/package.json b/lib/node_modules/@stdlib/utils/delay/package.json new file mode 100644 index 00000000000..5ce9664c271 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/package.json @@ -0,0 +1,52 @@ +{ + "name": "@stdlib/utils/delay", + "version": "0.0.0", + "description": "", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [] +} diff --git a/lib/node_modules/@stdlib/utils/delay/test/test.js b/lib/node_modules/@stdlib/utils/delay/test/test.js new file mode 100644 index 00000000000..958097efddd --- /dev/null +++ b/lib/node_modules/@stdlib/utils/delay/test/test.js @@ -0,0 +1,139 @@ +/** +* @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 tape = require( 'tape' ); +var delay = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.equal( typeof delay, 'function', 'export is a function' ); + t.end(); +}); + +/* +tape( 'the function delays execution by a specified number of milliseconds', function test( t ) { + var out = false; + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + out = true; + clearTimeout( i ); + t.ok( true ); + t.end(); + } + if ( out ) { + t.ok( false, 'should not be invoked' ); + } +}); + +tape( 'if the function is called with additional arguments, the provided function is invoked with those arguments', function test( t ) { + var out; + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout( a, b ) { + out = a + b; + clearTimeout( i ); + t.ok( true ); + t.end(); + } + + if ( out ) { + t.ok( false, 'should not be invoked' ); + } +}); + +tape( 'the function returns a timeout object', function test( t ) { + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + clearTimeout( i ); + t.ok( true ); + t.end(); + } +}); + +tape( 'the returned timeout object exposes a `clear` method to clear a pending timeout', function test( t ) { + var out; + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + out = true; + clearTimeout( i ); + t.ok( false, 'should not be invoked' ); + t.end(); + } + + i.clear(); + + if ( out ) { + t.ok( false, 'should not be invoked' ); + } else { + t.ok( true ); + t.end(); + } +}); + +tape( 'the returned timeout object exposes an `invoke` method to invoke a function immediately', function test( t ) { + var out; + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + out = true; + clearTimeout( i ); + t.ok( true ); + t.end(); + } + + i.invoke(); + + if ( out ) { + t.ok( true ); + t.end(); + } else { + t.ok( false, 'should not be invoked' ); + t.end(); + } +}); + +tape( 'the returned timeout object exposes a property for getting the timeout duration (in milliseconds)', function test( t ) { + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + clearTimeout( i ); + t.equal( i.duration, 1000, 'returns duration' ); + t.end(); + } +}); + +tape( 'the returned timeout object exposes a property for getting the timeout status', function test( t ) { + var i = setTimeout( onTimeout, 1000 ); + + function onTimeout() { + clearTimeout( i ); + t.equal( i.status, 1, 'returns status' ); + t.end(); + } +}); +*/