@stdlib/utils-async-parallel 0.1.0

package/docs/types/index.d.ts

@@ -0,0 +1,312 @@
+/*
+* @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: 4.1
+
+/**
+* Interface defining function options.
+*/
+interface Options<T> {
+	/**
+	* The maximum number of pending invocations at any one time.
+	*/
+	limit?: number;
+
+	/**
+	* Execution context.
+	*/
+	thisArg?: ThisParameterType<Callback<T>>;
+}
+
+/**
+* Callback invoked upon completion.
+*/
+type Nullary = () => void;
+
+/**
+* Callback invoked upon completion.
+*
+* @param error - encountered error
+*/
+type Unary = ( error: Error ) => void;
+
+/**
+* Callback invoked upon completion.
+*
+* @param error - encountered error
+* @param out - output results
+*/
+type Binary<T> = ( error: Error | null, out: Array<T> ) => void;
+
+/**
+* Callback invoked upon completion.
+*
+* @param error - encountered error
+* @param out - output results
+*/
+type Callback<T> = Nullary | Unary | Binary<T>;
+
+/**
+* Executes a set of functions in parallel.
+*/
+type ParallelFunction<T> = ( done: Callback<T> ) => void;
+
+/**
+* Interface for `parallel`.
+*/
+interface Parallel {
+	/**
+	* Executes a set of functions in parallel.
+	*
+	* @param fcns - array of functions
+	* @param options - function options
+	* @param options.thisArg - function context
+	* @param options.limit - number of functions to execute concurrently
+	* @param clbk - callback to invoke upon completion
+	*
+	* @example
+	* var parallel = require( '@stdlib/utils-async-parallel' );
+	*
+	* function foo( clbk ) {
+	*     setTimeout( onTimeout, 300 );
+	*     function onTimeout() {
+	*         clbk( null, 'one' );
+	*     }
+	* }
+	*
+	* function bar( clbk ) {
+	*     setTimeout( onTimeout, 100 );
+	*     function onTimeout() {
+	*         clbk( null, 'two' );
+	*     }
+	* }
+	*
+	* function done( error, results ) {
+	*     if ( error ) {
+	*         throw error;
+	*     }
+	*     console.log( results );
+	*     // => [ 'one', 'two' ]
+	* }
+	*
+	* var fcns = [ foo, bar ];
+	*
+	* var opts = {
+	* 	'thisArg': {},
+	* 	'limit': 2
+	* }
+	*
+	* parallel( fcns, opts, done );
+	*/
+	<T = unknown>( fcns: ArrayLike<Function>, options: Options<T>, clbk: Callback<T> ): void;
+
+	/**
+	* Executes a set of functions in parallel.
+	*
+	* @param fcns - array of functions
+	* @param clbk - callback to invoke upon completion
+	*
+	* @example
+	* var parallel = require( '@stdlib/utils-async-parallel' );
+	*
+	* function foo( clbk ) {
+	*     setTimeout( onTimeout, 300 );
+	*     function onTimeout() {
+	*         clbk( null, 'one' );
+	*     }
+	* }
+	*
+	* function bar( clbk ) {
+	*     setTimeout( onTimeout, 100 );
+	*     function onTimeout() {
+	*         clbk( null, 'two' );
+	*     }
+	* }
+	*
+	* function done( error, results ) {
+	*     if ( error ) {
+	*         throw error;
+	*     }
+	*     console.log( results );
+	*     // => [ 'one', 'two' ]
+	* }
+	*
+	* var fcns = [ foo, bar ];
+	*
+	* parallel( fcns, done );
+	*/
+	<T = unknown>( fcns: ArrayLike<Function>, clbk: Callback<T> ): void;
+
+	/**
+	* Returns a reusable parallel function.
+	*
+	* @param fcns - array of functions
+	* @param options - function options
+	* @param options.thisArg - function context
+	* @param options.limit - number of functions to execute concurrently
+	* @param clbk - callback to invoke upon completion
+	* @returns parallel function
+	*
+	* @example
+	* function a( clbk ) {
+	*     setTimeout( onTimeout, 0 );
+	*     function onTimeout() {
+	*         clbk( null, 2 );
+	*     }
+	* }
+	*
+	* function b( clbk ) {
+	*     setTimeout( onTimeout, 0 );
+	*     function onTimeout() {
+	*         clbk( null, 4 );
+	*     }
+	* }
+	*
+	* function done( error, out ) {
+	*     if ( error ) {
+	*         throw error;
+	*     }
+	*     console.log( out );
+	*     // => [ 2, 4 ]
+	* }
+	*
+	* var fcns = [ a, b ];
+	* var run = parallel.factory( fcns );
+	*
+	* // ...
+	*
+	* run( done );
+	*
+	* @example
+	* function a( clbk ) {
+	*     setTimeout( onTimeout, 0 );
+	*     function onTimeout() {
+	*         clbk( null, 2 );
+	*     }
+	* }
+	*
+	* function b( clbk ) {
+	*     setTimeout( onTimeout, 0 );
+	*     function onTimeout() {
+	*         clbk( null, 4 );
+	*     }
+	* }
+	*
+	* function done( error, out ) {
+	*     if ( error ) {
+	*         throw error;
+	*     }
+	*     console.log( out );
+	*     // => [ 2, 4 ]
+	* }
+	*
+	* var fcns = [ a, b ];
+	*
+	* var opts = {
+	* 	'thisArg': {},
+	* 	'limit': 2
+	* }
+	*
+	* var run = parallel.factory( fcns, opts );
+	*
+	* // ...
+	*
+	* run( done );
+	*/
+	factory<T = unknown>( fcns: ArrayLike<Function>, options?: Options<T> ): ParallelFunction<T>;
+}
+
+/**
+* Executes a set of functions in parallel and passes the results of all functions to a provided callback.
+*
+* ## Notes
+*
+* -   This function is intended to start asynchronous tasks so that execution of each task runs concurrently. If provided a function which does not perform asynchronous tasks, the function will execute synchronously.
+* -   The function executes provided functions in the same thread. Accordingly, the function does **not** spawn new threads.
+*
+* @param fcns - array of functions
+* @param options - function options
+* @param options.thisArg - function context
+* @param options.limit - number of functions to execute concurrently
+* @param clbk - callback to invoke upon completion
+*
+* @example
+* var parallel = require( '@stdlib/utils-async-parallel' );
+*
+* function foo( clbk ) {
+*     setTimeout( onTimeout, 300 );
+*     function onTimeout() {
+*         clbk( null, 'one' );
+*     }
+* }
+*
+* function bar( clbk ) {
+*     setTimeout( onTimeout, 100 );
+*     function onTimeout() {
+*         clbk( null, 'two' );
+*     }
+* }
+*
+* function done( error, results ) {
+*     if ( error ) {
+*         throw error;
+*     }
+*     console.log( results );
+*     // => [ 'one', 'two' ]
+* }
+*
+* var fcns = [ foo, bar ];
+*
+* parallel( fcns, done );
+*
+* @example
+* function a( clbk ) {
+*     setTimeout( onTimeout, 0 );
+*     function onTimeout() {
+*         clbk( null, 2 );
+*     }
+* }
+*
+* function b( clbk ) {
+*     setTimeout( onTimeout, 0 );
+*     function onTimeout() {
+*         clbk( null, 4 );
+*     }
+* }
+*
+* function done( error, out ) {
+*     if ( error ) {
+*         throw error;
+*     }
+*     console.log( out );
+*     // => [ 2, 4 ]
+* }
+*
+* var fcns = [ a, b ];
+* var run = parallel.factory( fcns );
+*
+* // ...
+*
+* run( done );
+*/
+declare var parallel: Parallel;
+
+
+// EXPORTS //
+
+export = parallel;

package/lib/factory.js

@@ -0,0 +1,126 @@
+/**
+* @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 isFunctionArray = require( '@stdlib/assert-is-function-array' );
+var isFunction = require( '@stdlib/assert-is-function' );
+var format = require( '@stdlib/string-format' );
+var PINF = require( '@stdlib/constants-float64-pinf' );
+var validate = require( './validate.js' );
+var limit = require( './limit.js' );
+
+
+// MAIN //
+
+/**
+* Returns a function to execute a set of functions in parallel.
+*
+* @param {FunctionArray} fcns - array of functions
+* @param {Options} [options] - function options
+* @param {*} [options.thisArg] - execution context
+* @param {PositiveInteger} [options.limit] - maximum number of pending invocations at any one time
+* @throws {TypeError} first argument must be an array of functions
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {Function} parallel function
+*
+* @example
+* function a( resolve ) {
+*     setTimeout( onTimeout, 0 );
+*     function onTimeout() {
+*         resolve( null, 2 );
+*     }
+* }
+*
+* function b( resolve ) {
+*     setTimeout( onTimeout, 0 );
+*     function onTimeout() {
+*         resolve( null, 4 );
+*     }
+* }
+*
+* function done( error, out ) {
+*     if ( error ) {
+*         throw error;
+*     }
+*     console.log( out );
+*     // => [ 2, 4 ]
+* }
+*
+* var fcns = [ a, b ];
+*
+* var run = parallel.factory( fcns );
+*
+* run( done );
+*/
+function factory( fcns, options ) {
+	var opts;
+	var err;
+
+	if ( !isFunctionArray( fcns ) ) {
+		throw new TypeError( format( 'invalid argument. First argument must be an array of functions. Value: `%s`.', fcns ) );
+	}
+	opts = {
+		'limit': PINF
+	};
+	if ( arguments.length > 1 ) {
+		err = validate( opts, options );
+		if ( err ) {
+			throw err;
+		}
+	}
+	return parallel;
+
+	/**
+	* Executes a set of functions in parallel and returns an array of results.
+	*
+	* @private
+	* @param {Callback} done - function to invoke upon completion
+	* @throws {TypeError} must provide a function
+	* @returns {void}
+	*/
+	function parallel( done ) {
+		if ( !isFunction( done ) ) {
+			throw new TypeError( format( 'invalid argument. Callback argument must be a function. Value: `%s`.', done ) );
+		}
+		return limit( fcns, opts, clbk );
+
+		/**
+		* Callback invoked upon completion.
+		*
+		* @private
+		* @param {*} [error] - error
+		* @param {Array} [out] - output array
+		* @returns {void}
+		*/
+		function clbk( error, out ) {
+			if ( error ) {
+				return done( error );
+			}
+			done( null, out );
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;

package/lib/index.js

@@ -0,0 +1,70 @@
+/**
+* @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';
+
+/**
+* Execute a set of functions in parallel.
+*
+* @module @stdlib/utils-async-parallel
+*
+* @example
+* var parallel = require( '@stdlib/utils-async-parallel' );
+*
+* function foo( resolve ) {
+*     setTimeout( onTimeout, 300 );
+*     function onTimeout() {
+*         resolve( null, 'one' );
+*     }
+* }
+*
+* function bar( resolve ) {
+*     setTimeout( onTimeout, 100 );
+*     function onTimeout() {
+*         resolve( null, 'two' );
+*     }
+* }
+*
+* function done( error, results ) {
+*     if ( error ) {
+*         throw error;
+*     }
+*     console.log( results );
+*     // => [ 'one', 'two' ]
+* }
+*
+* var fcns = [ foo, bar ];
+*
+* parallel( fcns, done );
+*/
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var main = require( './main.js' );
+var factory = require( './factory.js' );
+
+
+// MAIN //
+
+setReadOnly( main, 'factory', factory );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/limit.js

@@ -0,0 +1,138 @@
+/**
+* @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 logger = require( 'debug' );
+
+
+// VARIABLES //
+
+var debug = logger( 'parallel-async:limit' );
+
+
+// MAIN //
+
+/**
+* Invokes functions in a provided array, limiting the number of concurrently pending functions.
+*
+* @private
+* @param {FunctionArray} fcns - array of functions
+* @param {Options} opts - function options
+* @param {*} [opts.thisArg] - execution context
+* @param {PositiveInteger} [opts.limit] - maximum number of pending function invocations
+* @param {Callback} done - function to invoke upon completion or upon encountering an error
+* @returns {void}
+*/
+function limit( fcns, opts, done ) {
+	var maxIndex;
+	var count;
+	var flg;
+	var lim;
+	var len;
+	var idx;
+	var out;
+	var i;
+
+	len = fcns.length;
+	debug( 'Number of functions: %d', len );
+
+	out = new Array( len );
+	if ( len < opts.limit ) {
+		lim = len;
+	} else {
+		lim = opts.limit;
+	}
+	debug( 'Concurrency limit: %d', lim );
+
+	maxIndex = len - 1;
+	count = 0;
+	idx = -1;
+	for ( i = 0; i < lim; i++ ) {
+		// This guard is necessary to protect against synchronous functions...
+		if ( idx < maxIndex ) {
+			next(); // eslint-disable-line node/callback-return
+		}
+	}
+	/**
+	* Callback to invoke the next function.
+	*
+	* @private
+	*/
+	function next() {
+		var i;
+
+		idx += 1;
+
+		// Cache the current index value to allow storing results later:
+		i = idx;
+
+		fcns[ idx ].call( opts.thisArg, resolve );
+
+		/**
+		* Callback invoked once a provided function finishes.
+		*
+		* @private
+		* @param {*} [error] - error
+		* @param {*} [results] - results
+		* @returns {void}
+		*/
+		function resolve( error, results ) {
+			if ( flg ) {
+				// Prevent further processing:
+				return;
+			}
+			if ( error ) {
+				flg = true;
+				return clbk( error );
+			}
+			out[ i ] = results;
+			clbk();
+		}
+	}
+
+	/**
+	* Callback invoked once ready to process the next function.
+	*
+	* @private
+	* @param {*} [error] - error
+	* @returns {void}
+	*/
+	function clbk( error ) {
+		if ( error ) {
+			debug( 'Encountered an error: %s', error.message );
+			return done( error );
+		}
+		count += 1;
+		debug( 'Processed %d of %d functions.', count, len );
+		if ( idx < maxIndex ) {
+			return next();
+		}
+		if ( count === len ) {
+			debug( 'Finished processing the functions.' );
+			return done( null, out );
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = limit;

package/lib/main.js

@@ -0,0 +1,81 @@
+/**
+* @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 factory = require( './factory.js' );
+
+
+// MAIN //
+
+/**
+* Executes a set of functions in parallel.
+*
+* @param {FunctionArray} fcns - array of functions
+* @param {Options} [options] - function options
+* @param {*} [options.thisArg] - execution context
+* @param {PositiveInteger} [options.limit] - maximum number of pending invocations at any one time
+* @param {Callback} done - function to invoke upon completion
+* @throws {TypeError} first argument must be an array of functions
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @throws {TypeError} callback argument must be a function
+* @returns {void}
+*
+* @example
+* var parallel = require( '@stdlib/utils-async-parallel' );
+*
+* function foo( resolve ) {
+*     setTimeout( onTimeout, 300 );
+*     function onTimeout() {
+*         resolve( null, 'one' );
+*     }
+* }
+*
+* function bar( resolve ) {
+*     setTimeout( onTimeout, 100 );
+*     function onTimeout() {
+*         resolve( null, 'two' );
+*     }
+* }
+*
+* function done( error, results ) {
+*     if ( error ) {
+*         throw error;
+*     }
+*     console.log( results );
+*     // => [ 'one', 'two' ]
+* }
+*
+* var fcns = [ foo, bar ];
+*
+* parallel( fcns, done );
+*/
+function parallel( fcns, options, done ) {
+	if ( arguments.length < 3 ) {
+		return factory( fcns )( options );
+	}
+	factory( fcns, options )( done );
+}
+
+
+// EXPORTS //
+
+module.exports = parallel;