parallel

Parallelize async operations while managing load

Usage

The parallel function processes an array with an async callback. The first argument controls how many array items are processed at one time. Similar to Promise.all, an ordered array of results is returned.

import * as 
import _
_ from 'radashi'

const 
const userIds: number[]
userIds = [1, 2, 3, 4, 5, 6, 7, 8, 9]

// Will run the find user async function 3 at a time
// starting another request when one of the 3 is freed
const 
const users: any[]
users = await 
import _
_.
parallel<number, any>(options: _.ParallelOptions | number, array: readonly number[], func: (item: number) => Promise<any>): Promise<any[]>
export parallel
Executes many async functions in parallel. Returns the results from
all functions as an array. After all functions have resolved, if
any errors were thrown, they are rethrown in an instance of
AggregateError. The operation can be aborted by passing optional AbortSignal,
which will throw an Error if aborted.
@see ― https://radashi.js.org/reference/async/parallel
@example 
// Process images concurrently, resizing each image to a standard size.
const abortController = new AbortController();
const images = await parallel(
{
 limit: 2,
 signal: abortController.signal,
},
 imageFiles,
 async file => {
  return await resizeImage(file)
})

// To abort the operation:
// abortController.abort()
@version ― 12.1.0
parallel(3, 
const userIds: number[]
userIds, async 
userId: number
userId => {
  return await 
const api: {
    users: {
        find: (id: number) => Promise<any>;
        throw: Error;
    };
}
api.
users: {
    find: (id: number) => Promise<any>;
    throw: Error;
}
users.
find: (id: number) => Promise<any>
find(
userId: number
userId)
})

Since v12.3.0, if the limit is greater than the array length, it will be clamped to the array length. Similarly, if the limit is less than 1, it will be clamped to 1.

Interrupting

Since v12.3.0, processing can be manually interrupted. Pass an AbortController.signal via the signal option. When the signal is aborted, no more calls to your callback will be made. Any in-progress calls will continue to completion, unless you manually connect the signal inside your callback. In other words, parallel is only responsible for aborting the array loop, not the async operations themselves.

When parallel is interrupted by the signal, it throws a DOMException (even in Node.js) with the message This operation was aborted and name AbortError.

import * as 
import _
_ from 'radashi'

const 
const abortController: AbortController
abortController = new 
var AbortController: new () => AbortController
A controller object that allows you to abort one or more DOM requests as and when desired.
AbortController()
const 
const signal: AbortSignal
signal = 
const abortController: AbortController
abortController.
AbortController.signal: AbortSignal
Returns the AbortSignal object associated with this object.
signal

// Pass in the signal:
const 
const pizzas: any[]
pizzas = await 
import _
_.
parallel<string, any>(options: _.ParallelOptions | number, array: readonly string[], func: (item: string) => Promise<any>): Promise<any[]>
export parallel
Executes many async functions in parallel. Returns the results from
all functions as an array. After all functions have resolved, if
any errors were thrown, they are rethrown in an instance of
AggregateError. The operation can be aborted by passing optional AbortSignal,
which will throw an Error if aborted.
@see ― https://radashi.js.org/reference/async/parallel
@example 
// Process images concurrently, resizing each image to a standard size.
const abortController = new AbortController();
const images = await parallel(
{
 limit: 2,
 signal: abortController.signal,
},
 imageFiles,
 async file => {
  return await resizeImage(file)
})

// To abort the operation:
// abortController.abort()
@version ― 12.1.0
parallel(
  { 
limit: number
The maximum number of functions to run concurrently. If a
negative number is passed, only one function will run at a time.
If a number bigger than the array length is passed, the array
length will be used.
limit: 2, 
signal?: AbortSignal$1
signal },
  ['pepperoni', 'cheese', 'mushroom'],
  async 
topping: string
topping => {
    return await 
any
bakePizzaInWoodFiredOven(
topping: string
topping) // each pizza takes 10 minutes!
  },
)

// Later on, if you need to abort:
const abortController: AbortController
abortController.
AbortController.abort(reason?: any): void
Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
abort()

Aggregate Errors

Once the whole array has been processed, parallel will check for errors. If any errors occurred during processing, they are combined into a single AggregateError. The AggregateError has an errors array property which contains all the individual errors that were thrown.

import * as 
import _
_ from 'radashi'

const 
const userIds: number[]
userIds = [1, 2, 3]

const [
const err: Error | undefined
err, 
const users: never[] | undefined
users] = await 
import _
_.
tryit<[options: number | _.ParallelOptions, array: readonly T[], func: (item: T) => Promise<K>], Promise<K[]>, Error>(func: (options: number | _.ParallelOptions, array: readonly T[], func: (item: T) => Promise<K>) => Promise<...>): <T, K>(options: number | _.ParallelOptions, array: readonly T[], func: (item: T) => Promise<K>) => _.ResultPromise<...>
export tryit
A helper to try an async function without forking the control flow.
Returns an error-first callback-like array response as [Error, result]
tryit(
import _
_.
function parallel<T, K>(options: _.ParallelOptions | number, array: readonly T[], func: (item: T) => Promise<K>): Promise<K[]>
export parallel
Executes many async functions in parallel. Returns the results from
all functions as an array. After all functions have resolved, if
any errors were thrown, they are rethrown in an instance of
AggregateError. The operation can be aborted by passing optional AbortSignal,
which will throw an Error if aborted.
@see ― https://radashi.js.org/reference/async/parallel
@example 
// Process images concurrently, resizing each image to a standard size.
const abortController = new AbortController();
const images = await parallel(
{
 limit: 2,
 signal: abortController.signal,
},
 imageFiles,
 async file => {
  return await resizeImage(file)
})

// To abort the operation:
// abortController.abort()
@version ― 12.1.0
parallel)(3, 
const userIds: number[]
userIds, async 
userId: number
userId => {
  throw new 
var Error: ErrorConstructor
new (message?: string) => Error
Error(`No, I don\'t want to find user ${
userId: number
userId}`)
})

var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const err: Error | undefined
err) // => AggregateError
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const err: Error | undefined
err.
any
errors) // => [Error, Error, Error]
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const err: Error | undefined
err.
any
errors[1].
any
message) // => "No, I don't want to find user 2"