feat: add status object utils/async/any-by

etc/eslint/rules/spellcheck.js

@@ -80,9 +80,9 @@ rules[ '@cspell/spellchecker' ] = [ 'warn', {
 			'dilogarithm',
 			'dtype',
 			'dtypes',
-			'exponentiated',
 			'evalpoly',
 			'evalrational',
+			'exponentiated',
 			'hommel',
 			'iget',
 			'iset',
@@ -95,11 +95,14 @@ rules[ '@cspell/spellchecker' ] = [ 'warn', {
 			'napi',
 			'nargs',
 			'ncols',
-			'ndims',
-			'ndim',
-			'nout',
 			'ndarray',
 			'ndarrays',
+			'ndim',
+			'ndims',
+			'ndone',
+			'nerrors',
+			'nout',
+			'nprocessed',
 			'nrows',
 			'nsubmodes',
 			'pvalues',
@@ -116,6 +119,7 @@ rules[ '@cspell/spellchecker' ] = [ 'warn', {
 			'trigamma',
 			'uncapitalize',
 			'unregularized',
+			'zalgo',
 			'Fréchet'
 		]
 	}

lib/node_modules/@stdlib/assert/is-biguint64array/examples/index.js

@@ -74,7 +74,9 @@ bool = isBigUint64Array( new Float32Array( 10 ) );
 console.error( bool );
 // => false
 
-bool = isBigUint64Array( new Array( 10 ) );
+var arr = [];
+arr.push( 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 );
+bool = isBigUint64Array( arr );
 console.error( bool );
 // => false
 

lib/node_modules/@stdlib/math/strided/special/acoversin-by/test/test.main.js

@@ -74,15 +74,17 @@ tape( 'the function computes the inverse coversed sine via a callback function',
 	acoversinBy( x.length, x, 1, y, 1, accessor );
 	t.deepEqual( y, expected, 'deep equal' );
 
-	x = new Array( 5 ); // sparse array
+	x = []; // sparse array
+	x.length = 5;
 	y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
 
 	expected = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
 
 	acoversinBy( x.length, x, 1, y, 1, accessor );
 	t.deepEqual( y, expected, 'deep equal' );
 
-	x = new Array( 5 ); // sparse array
+	x = []; // sparse array
+	x.length = 5;
 	x[ 2 ] = rand();
 	y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ];
 

lib/node_modules/@stdlib/utils/async/any-by/lib/factory.js

@@ -33,11 +33,6 @@ var limit = require( './limit.js' );
 /**
 * Returns a function for testing whether at least one element in a collection passes a test implemented by a predicate function.
 *
-* ## Notes
-*
-* -   If a predicate function calls the provided callback with a truthy error argument, the function suspends execution and immediately calls the `done` callback for subsequent error handling.
-* -   This function does **not** guarantee that execution is asynchronous. To do so, wrap the `done` callback in a function which either executes at the end of the current stack (e.g., `nextTick`) or during a subsequent turn of the event loop (e.g., `setImmediate`, `setTimeout`).
-*
 * @param {Options} [options] - function options
 * @param {*} [options.thisArg] - execution context
 * @param {PositiveInteger} [options.limit] - maximum number of pending invocations at any one time
@@ -126,16 +121,78 @@ function factory( options, predicate ) {
 	* @param {Callback} done - function to invoke upon completion
 	* @throws {TypeError} first argument must be a collection
 	* @throws {TypeError} last argument must be a function
-	* @returns {void}
+	* @returns {Object} status object
 	*/
 	function anyByAsync( collection, done ) {
+		var status;
+		var i;
+
 		if ( !isCollection( collection ) ) {
 			throw new TypeError( format( 'invalid argument. First argument must be a collection. Value: `%s`.', collection ) );
 		}
 		if ( !isFunction( done ) ) {
 			throw new TypeError( format( 'invalid argument. Last argument must be a function. Value: `%s`.', done ) );
 		}
-		return limit( collection, opts, f, clbk );
+
+		// Create status object:
+		status = {
+			'nprocessed': 0,
+			'ndone': 0,
+			'nerrors': 0,
+			'total': collection.length,
+			'operations': []
+		};
+		for ( i = 0; i < collection.length; i++ ) {
+			status.operations.push({
+				'index': i,
+				'status': 'pending'
+			});
+		}
+
+		limit( collection, opts, wrapper, clbk );
+
+		return status;
+
+		/**
+		* Wrapper function to intercept per-element completion and update status.
+		*
+		* @private
+		* @param {*} value - collection value
+		* @param {NonNegativeInteger} index - collection index
+		* @param {Collection} col - input collection
+		* @param {Callback} next - callback to invoke upon completion
+		* @returns {void}
+		*/
+		function wrapper( value, index, col, next ) {
+			/**
+			* Callback invoked upon predicate completion.
+			*
+			* @private
+			* @param {*} error - error argument
+			* @param {boolean} bool - test result
+			* @returns {void}
+			*/
+			function onNext( error, bool ) {
+				if ( error ) {
+					status.nerrors += 1;
+					status.operations[ index ].status = 'fail';
+				} else {
+					status.operations[ index ].status = 'ok';
+				}
+				status.ndone += 1;
+				status.nprocessed += 1;
+				next( error, bool );
+			}
+			if ( f.length === 1 || f.length === 0 ) {
+				f.call( opts.thisArg, value, index, col, onNext );
+			} else if ( f.length === 2 ) {
+				f.call( opts.thisArg, value, onNext );
+			} else if ( f.length === 3 ) {
+				f.call( opts.thisArg, value, index, onNext );
+			} else {
+				f.call( opts.thisArg, value, index, col, onNext );
+			}
+		}
 
 		/**
 		* Callback invoked upon completion.

lib/node_modules/@stdlib/utils/async/any-by/test/test.factory.js

@@ -1011,3 +1011,97 @@ tape( 'the returned function does not guarantee asynchronous execution', functio
 		t.end();
 	}
 });
+tape( 'the returned function returns a status object', function test( t ) {
+	var anyByAsync;
+	var status;
+	var arr;
+
+	function predicate( value, next ) {
+		setTimeout( onTimeout, 0 );
+
+		function onTimeout() {
+			next( null, false );
+		}
+	}
+
+	function done( err, bool ) {
+		if ( err ) {
+			t.fail( err.message );
+			return t.end();
+		}
+		t.strictEqual( status.ndone, arr.length, 'ndone equals collection length' );
+		t.strictEqual( status.nprocessed, arr.length, 'nprocessed equals collection length' );
+		t.strictEqual( status.nerrors, 0, 'no errors' );
+		t.strictEqual( bool, false, 'returns expected value' );
+		t.end();
+	}
+
+	anyByAsync = factory( predicate );
+	arr = [ 1, 2, 3 ];
+	status = anyByAsync( arr, done );
+
+	t.strictEqual( typeof status, 'object', 'returns an object' );
+	t.strictEqual( typeof status.nprocessed, 'number', 'has nprocessed property' );
+	t.strictEqual( typeof status.ndone, 'number', 'has ndone property' );
+	t.strictEqual( typeof status.nerrors, 'number', 'has nerrors property' );
+	t.strictEqual( status.total, arr.length, 'has correct total' );
+	t.strictEqual( Array.isArray( status.operations ), true, 'has operations array' );
+});
+
+tape( 'the status object tracks in-flight operations', function test( t ) {
+	var anyByAsync;
+	var status;
+	var arr;
+
+	function predicate( value, next ) {
+		setTimeout( onTimeout, 0 );
+
+		function onTimeout() {
+			next( null, false );
+		}
+	}
+
+	function done( err, bool ) {
+		if ( err ) {
+			t.fail( err.message );
+			return t.end();
+		}
+		t.strictEqual( bool, false, 'returns expected value' );
+		t.end();
+	}
+
+	anyByAsync = factory( predicate );
+	arr = [ 1, 2, 3 ];
+	status = anyByAsync( arr, done );
+
+	t.strictEqual( status.operations[ 0 ].status, 'pending', 'first operation is pending' );
+	t.strictEqual( status.operations[ 1 ].status, 'pending', 'second operation is pending' );
+	t.strictEqual( status.operations[ 2 ].status, 'pending', 'third operation is pending' );
+	t.strictEqual( status.ndone, 0, 'none done yet' );
+});
+
+tape( 'the status object tracks errors', function test( t ) {
+	var anyByAsync;
+	var status;
+	var arr;
+
+	function predicate( value, next ) {
+		setTimeout( onTimeout, 0 );
+
+		function onTimeout() {
+			next( new Error( 'beep' ) );
+		}
+	}
+
+	function done( err ) {
+		t.ok( err, 'returns an error' );
+		t.strictEqual( status.nerrors, 1, 'nerrors is 1' );
+		t.end();
+	}
+
+	anyByAsync = factory({
+		'series': true
+	}, predicate );
+	arr = [ 1, 2, 3 ];
+	status = anyByAsync( arr, done );
+});