async-done

What is async-done?

The async-done npm package is a utility for handling asynchronous tasks in Node.js. It provides a simple way to manage callbacks, promises, observables, and streams, making it easier to work with various types of asynchronous operations.

What are async-done's main functionalities?

Handling Callbacks

This feature allows you to handle asynchronous tasks that use callbacks. The `asyncDone` function takes a task function and a callback to handle the result or error.

const asyncDone = require('async-done');

function callbackTask(done) {
  setTimeout(() => {
    done(null, 'Callback Task Completed');
  }, 1000);
}

asyncDone(callbackTask, (err, result) => {
  if (err) throw err;
  console.log(result); // Output: Callback Task Completed
});

Handling Promises

This feature allows you to handle asynchronous tasks that return promises. The `asyncDone` function can manage the promise and handle the result or error.

const asyncDone = require('async-done');

function promiseTask() {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve('Promise Task Completed');
    }, 1000);
  });
}

asyncDone(promiseTask, (err, result) => {
  if (err) throw err;
  console.log(result); // Output: Promise Task Completed
});

Handling Observables

This feature allows you to handle asynchronous tasks that return observables. The `asyncDone` function can manage the observable and handle the result or error.

const asyncDone = require('async-done');
const { Observable } = require('rxjs');

function observableTask() {
  return new Observable((observer) => {
    setTimeout(() => {
      observer.next('Observable Task Completed');
      observer.complete();
    }, 1000);
  });
}

asyncDone(observableTask, (err, result) => {
  if (err) throw err;
  console.log(result); // Output: Observable Task Completed
});

Handling Streams

This feature allows you to handle asynchronous tasks that return streams. The `asyncDone` function can manage the stream and handle the result or error.

const asyncDone = require('async-done');
const { Readable } = require('stream');

function streamTask() {
  const stream = new Readable();
  stream._read = () => {};
  setTimeout(() => {
    stream.push('Stream Task Completed');
    stream.push(null);
  }, 1000);
  return stream;
}

asyncDone(streamTask, (err, result) => {
  if (err) throw err;
  console.log(result); // Output: Stream Task Completed
});

Other packages similar to async-done

async

The async package provides a collection of functions for working with asynchronous JavaScript. It offers utilities for handling asynchronous control flow using callbacks, promises, and async/await. Compared to async-done, async provides a broader range of utilities for managing complex asynchronous workflows.

bluebird

Bluebird is a fully-featured promise library for JavaScript. It provides advanced promise management features, including cancellation, iteration, and resource management. Compared to async-done, Bluebird focuses specifically on promises and offers more advanced promise-related functionalities.

rxjs

RxJS is a library for reactive programming using observables. It provides powerful operators for composing asynchronous and event-based programs. Compared to async-done, RxJS focuses on observables and offers a comprehensive set of tools for working with reactive streams.

README

async-done

Allows libraries to handle various caller provided asynchronous functions uniformly. Maps promises, observables, child processes and streams, and callbacks to callback style.

As async conventions evolve, it is useful to be able to deal with several different styles of async completion uniformly. With this module you can handle completion using a node-style callback, regardless of a return value that's a promise, observable, child process or stream.

Usage

Successful completion

var asyncDone = require('async-done');

asyncDone(
  function (done) {
    // do async things
    done(null, 2);
  },
  function (error, result) {
    // `error` will be null on successful execution of the first function.
    // `result` will be the result from the first function.
  }
);

Failed completion

var asyncDone = require('async-done');

asyncDone(
  function (done) {
    // do async things
    done(new Error('Some Error Occurred'));
  },
  function (error, result) {
    // `error` will be an error from the first function.
    // `result` will be undefined on failed execution of the first function.
  }
);

API

asyncDone(fn, callback)

Takes a function to execute (fn) and a function to call on completion (callback).

fn([done])

Optionally takes a callback to call when async tasks are complete.

Completion and Error Resolution

• Callback (done) called
  • Completion: called with null error
  • Error: called with non-null error
• Stream or EventEmitter returned
  • Completion: end-of-stream module
  • Error: domains
  • Note: Only actual streams are supported, not faux-streams; Therefore, modules like event-stream are not supported.
• Child Process returned
  • Completion end-of-stream module
  • Error: domains
• Promise returned
  • Completion: onFulfilled method called
  • Error: onRejected method called
• Observable (e.g. from RxJS v5 or RxJS v4) returned
  • Completion: complete method called
  • Error: error method called

Warning: Sync tasks are not supported and your function will never complete if the one of the above strategies is not used to signal completion. However, thrown errors will be caught by the domain.

callback(error, result)

If an error doesn't occur in the execution of the fn function, the callback method will receive the results as its second argument. Note: Some streams don't received any results.

If an error occurred in the execution of the fn function, The callback method will receive an error as its first argument.

Errors can be caused by:

• A thrown error
• An error passed to a done callback
• An error event emitted on a returned Stream, EventEmitter or Child Process
• A rejection of a returned Promise - If the Promise is not rejected with a value, we generate a new Error
• The onError handler being called on an Observable

License

MIT

Changelog

2.0.0 (2022-06-25)

⚠ BREAKING CHANGES

• Allow end-of-stream to handle the stream error states
• Normalize repository, dropping node <10.13 support (#54)

Bug Fixes

• Allow end-of-stream to handle the stream error states (7b37da4)
• Ensure the Observable failure test works (#59) (dfa4f0b)

Miscellaneous Chores

• Normalize repository, dropping node <10.13 support (#54) (66f987f)