[RFC]: add utils/async/parallel

[nightknighto]

Description

This RFC proposes adding utils/async/parallel to run a set of asynchronous code in parallel, corresponding to async.js parallel and async.js parallelLimit

Related Issues

Related to the project idea stdlib-js/google-summer-of-code#9

Questions

No.

Other

The implementation will be inspired by utils/async/map-values.

The API interface would be parallel( functionArray [, options] [, done] ).

Params:

• functionArray: an array of functions to be executed in parallel. The functions should be async, or else they would run sequentially.
• options will accept:
  • thisArg: execution context
  • limit: maximum number of pending invocations with default infinity. (Will replace the need for a separate function for parallelLimit)
• done: a callback function with (err, result) parameters that is called when the execution is finished.
  • err: will be truthy if an error happened, for error-handling.
  • result: will be an array of the return values of each function.

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

[stdlib-bot]

👋 Hi there! 👋

And thank you for opening your first issue! We will get back to you shortly. 🏃 💨

[nightknighto]

I'd like to work on it ASAP as part of my proposal for the mentioned project.

[kgryte]

@Deadreyo This is looking good. I suggest making done a mandatory argument. In your OP, you have it as optional, based on the proposed signature.

The functions should be async, or else they would run sequentially.

I don't think this should be required, and I don't think we have a way to enforce this. So long as each provided function calls a provided callback function and we invoke done on completion, that is the best we can do. Up to consumers to avoid releasing the zalgo.

options.limit

This makes sense to me. I don't see an imperative to have two separate APIs.

functionArray

Should we also support providing an object, similar to async.js or only an array-like object containing functions? I can see the argument for supporting both.

[nightknighto]

I agree with all your points.

Should we also support providing an object, similar to async.js or only an array-like object containing functions? I can see the argument for supporting both.

Comparing with waterfall as I consider these two to be of the same class, waterfall only supports the array. I suggest we have them consistent in this aspect, and if needed later on we can add support for both together.

[kgryte]

For waterfall, it makes sense to only support an input array, as there's no "results" value. It's different with parallel, where you want the results of all async functions. And there I can see an argument for "naming" the results. That same argument does not apply to waterfall.

[nightknighto]

Alright I now understand what you mean, this example:

async.parallel({
    one: function(callback) {
        setTimeout(function() {
            callback(null, 1);
        }, 200);
    },
    two: function(callback) {
        setTimeout(function() {
            callback(null, 2);
        }, 100);
    }
}, function(err, results) {
    console.log(results);
    // results is equal to: { one: 1, two: 2 }
});

It's fine by me either of the decisions, implementing both at this moment, or implementing only the array now and pushing the object to a separate issue/task, where we can discuss the arguments for both sides more freely.

[nightknighto]

For the functions in the functionArray, they should have a resolve or callback function which acts like return like the example above.
To ensure some kind of proper use, we can do some checks on each of provided functions:

• If number of parameters is less than 1, throw an error
• If number of parameters is 1 or more, pass the callback in the first param. An alternative would be to throw an error if more than 1 param but I think it should be more flexible.

[kgryte]

I don't think we should require a particular arity for functions in the function array. Users should be able to provide a function of any arity; we don't really care. We always pass in a clbk function to each function in the function array which has the signature:

// Callback function provided by the `parallel` implementation to each function in the function array...
function clbk( error, result ) {
	if ( error ) {
		// ... handle error
		return;
	}
	// ...handle result
}

The onus is on users to ensure they call the callback. And if the arity is zero, they are responsible for extracting the callback from arguments.

[nightknighto]

Great. I think everything is set. I will start on it

[kgryte]

Awesome. Thanks!

[nightknighto]

Finished and opened the PR