Methods

batch(values, optionsopt) → {external:Promise}

Settles (resolves or rejects) every mixed value in the input array.

The method resolves with an array of results, the same as the standard promise.all, while providing comprehensive error details in case of a reject, in the form of type BatchError.

Parameters:
Name Type Attributes Description
values Array

Array of mixed values (it can be empty), to be resolved asynchronously, in no particular order.

Passing in anything other than an array will reject with TypeError = Method 'batch' requires an array of values.
options Object <optional>

Optional Parameters.

Properties
Name Type Attributes Description
cb function | generator <optional>

Optional callback (or generator) to receive the result for each settled value.

Callback Parameters:

  • index = index of the value in the source array
  • success - indicates whether the value was resolved (true), or rejected (false)
  • result = resolved data, if success=true, or else the rejection reason
  • delay = number of milliseconds since the last call (undefined when index=0)

The function inherits this context from the calling method.

It can optionally return a promise to indicate that notifications are handled asynchronously. And if the returned promise resolves, it signals a successful handling, while any resolved data is ignored.

If the function returns a rejected promise or throws an error, the entire method rejects with BatchError where the corresponding value in property data is set to {success, result, origin}:

  • success = false
  • result = the rejection reason or the error thrown by the notification callback
  • origin = the original data passed into the callback as object {success, result}
Source:
Returns:

The method resolves with an array of individual resolved results, the same as the standard promise.all. In addition, the array is extended with a hidden read-only property duration - number of milliseconds spent resolving all the data.

The method rejects with BatchError when any of the following occurs:

  • one or more values rejected or threw an error while being resolved as a mixed value
  • notification callback cb returned a rejected promise or threw an error
Type
external:Promise

page(source, optionsopt) → {external:Promise}

Resolves a dynamic sequence of pages/arrays with mixed values.

The method acquires pages (arrays of mixed values) from the source function, one by one, and resolves each page as a batch, till no more pages left or an error/reject occurs.

Parameters:
Name Type Attributes Description
source function | generator

Expected to return a mixed value that resolves with the next page of data (array of mixed values). Returning or resolving with undefined ends the sequence, and the method resolves.

The function inherits this context from the calling method.

Parameters:

  • index = index of the page being requested
  • data = previously returned page, resolved as a batch (undefined when index=0)
  • delay = number of milliseconds since the last call (undefined when index=0)

If the function throws an error or returns a rejected promise, the method rejects with PageError, which will have property source set.

And if the function returns or resolves with anything other than an array or undefined, the method rejects with the same PageError, but with error set to Unexpected data returned from the source.

Passing in anything other than a function will reject with TypeError = Parameter 'source' must be a function.
options Object <optional>

Optional Parameters.

Properties
Name Type Attributes Default Description
dest function | generator <optional>

Optional destination function (or generator), to receive a resolved batch of data for each page, process it and respond as required.

Parameters:

  • index = page index in the sequence
  • data = page data resolved as a batch
  • delay = number of milliseconds since the last call (undefined when index=0)

The function inherits this context from the calling method.

It can optionally return a promise object, if notifications are handled asynchronously. And if a promise is returned, the method will not request another page from the source function until the promise has been resolved.

If the function throws an error or returns a rejected promise, the sequence terminates, and the method rejects with PageError, which will have property dest set.
limit Number <optional>
 0

Limits the maximum number of pages to be requested from the source. If the value is greater than 0, the method will successfully resolve once the specified limit has been reached.

When limit isn't specified (default), the sequence is unlimited, and it will continue till one of the following occurs:

  • source returns or resolves with undefined or an invalid value (non-array)
  • either source or dest functions throw an error or return a rejected promise
Source:
Returns:

When successful, the method resolves with object {pages, total, duration}:

  • pages = number of pages resolved
  • total = the sum of all page sizes (total number of values resolved)
  • duration = number of milliseconds consumed by the method

When the method fails, it rejects with PageError.

Type
external:Promise

sequence(source, optionsopt) → {external:Promise}

Resolves a dynamic sequence of mixed values.

The method acquires mixed values from the source function, one at a time, and resolves them, till either no more values left in the sequence or an error/reject occurs.

It supports both linked and detached sequencing.

Parameters:
Name Type Attributes Description
source function | generator

Expected to return the next mixed value to be resolved. Returning or resolving with undefined ends the sequence, and the method resolves.

Parameters:

  • index = current request index in the sequence
  • data = resolved data from the previous call (undefined when index=0)
  • delay = number of milliseconds since the last call (undefined when index=0)

The function inherits this context from the calling method.

If the function throws an error or returns a rejected promise, the sequence terminates, and the method rejects with SequenceError, which will have property source set.

Passing in anything other than a function will reject with TypeError = Parameter 'source' must be a function.
options Object <optional>

Optional Parameters.

Properties
Name Type Attributes Default Description
dest function | generator <optional>
 null

Optional destination function (or generator), to receive resolved data for each index, process it and respond as required.

Parameters:

  • index = index of the resolved data in the sequence
  • data = the data resolved
  • delay = number of milliseconds since the last call (undefined when index=0)

The function inherits this context from the calling method.

It can optionally return a promise object, if data processing is done asynchronously. If a promise is returned, the method will not request another value from the source function, until the promise has been resolved (the resolved value is ignored).

If the function throws an error or returns a rejected promise, the sequence terminates, and the method rejects with SequenceError, which will have property dest set.
limit Number <optional>
 0

Limits the maximum size of the sequence. If the value is greater than 0, the method will successfully resolve once the specified limit has been reached.

When limit isn't specified (default), the sequence is unlimited, and it will continue till one of the following occurs:

  • source either returns or resolves with undefined
  • either source or dest functions throw an error or return a rejected promise
track Boolean <optional>
 false

Changes the type of data to be resolved by this method. By default, it is false (see the return result). When set to be true, the method tracks/collects all resolved data into an array internally, and resolves with that array once the method has finished successfully.

It must be used with caution, as to the size of the sequence, because accumulating data for a very large sequence can result in consuming too much memory.
Source:
Returns:

When successful, the resolved data depends on parameter track. When track is false (default), the method resolves with object {total, duration}:

  • total = number of values resolved by the sequence
  • duration = number of milliseconds consumed by the method

When track is true, the method resolves with an array of all the data that has been resolved, the same way that the standard promise.all resolves. In addition, the array comes extended with a hidden read-only property duration - number of milliseconds consumed by the method.

When the method fails, it rejects with SequenceError.

Type
external:Promise