heya-async

Async

Promises and operations over them; useful utility functions.

What is inside?

Practical algorithms for node.js and browsers operating on any Promises (any then()-able will do, including ES6's Promise):

• Aggregate all asynchronous operations:
  • all() — similar to standard Promise.all(). Returns an array of results, or fails with a first failed promise.
  • par() — collects all results into an array, both normal values, and errors. Never fails.
    • Use case: collect all I/O results regardless if they failed or not.
    • Use case: wait for all asynchronous operations to finish regardless of their outcome.
• Race asynchronous operations determing a winner:
  • race() AKA one() — similar to standard Promise.race(). Resolves or fails with the first fulfilled promise.
  • any() — resolves with a first resolved promise. Failed promises are ignored unless all of them have failed. In the latter case it fails with the value of the first one in the array.
    • Use case: use the first successful I/O request, ignore services that failed.
• Orchestrate asynchronous functions:
  • seq() — a helper to run asynchronous operations sequentially one after another.
    • Use case: run operations, which depend on previous asynchronous results.
  • whilst() — a generalized asynchronous loop.
• Adapters:
  • when() — adapt any value (then()-able, or a plain value) to a promise.
  • promisify() — adapt node.js asynchronous callback-style functions to promise-based functions.
• Timeouts:
  • timeout() — resolve or reject a value after a timeout. If combine with other composition operations, like race(), it can help to implement any time-dependent conditions, e.g., timeouts on operations.
• Specialized deferreds/promises:
  • Deferred — fast deferred implementation without built-in timeouts unlike A+ Promises. Implements progress reports, and cancellations. Very helpful for debugging because it preserves call stacks.
  • FastDeferred — just like Deferred but even faster, because it doesn't convert exceptions into failed promises implicitly. It allows to JIT all of its code, and helps to debug unexpected exceptions.

How to install

With npm:

npm install --save heya-async

With bower:

bower install --save heya-async

Documentation

All documentation can be found in project's wiki.

To get more information on underlying concepts:

• Promises, deferreds, asynchronous operations.
• Differences between Promise, Deferred, and FastDeferred.

Included algorithms (work across all type of promises):

• Compositions: all(), par(), any(), one(), race().
• Generalized sequential execution of asynchronous operations: seq().
• Generalized asynchronous loop: whilst().
• The venerable when() to adapt any value to generic then()-able promises.
• Module timeout to resolve or reject promises after a timeout.

Included implementations of deferreds (can be used instead or alongside with the standard Promise):

• Module Deferred.
  • Module Deferred-ext, which adds compositions instrumented for Deferred.
• Module FastDeferred.
  • Module FastDeferred-ext, which adds compositions instrumented for FastDeferred.
• Differences between them and standard promises are described here.

License

BSD or AFL — your choice

Versions

• 1.0.1 — Removed a direct dependence on heya-ice in Micro.
• 1.0.0 — Starts the new generation.

For information on all pre-1.0.0 versions, please see the commit log.