thenify

What is thenify?

The thenify npm package is designed to convert Node.js callback-style functions to functions that return a promise. This is particularly useful when working with older Node.js APIs or third-party libraries that do not natively support promises, allowing developers to write cleaner, more modern asynchronous code using async/await or .then() syntax.

What are thenify's main functionalities?

Converting a callback-style function to a promise-returning function

This feature allows you to wrap a traditional Node.js callback-style function, such as `fs.readFile`, in a way that it returns a promise. This enables the use of `.then()` and `.catch()` for cleaner asynchronous control flow.

const thenify = require('thenify');
const fs = require('fs');
const readFile = thenify(fs.readFile);

readFile('example.txt', 'utf8').then(contents => {
  console.log(contents);
}).catch(err => {
  console.error(err);
});

Other packages similar to thenify

util.promisify

Introduced in Node.js 8, `util.promisify` is a built-in function that converts a callback-based function into a promise-based one. It serves a similar purpose to thenify but is built into the Node.js runtime. Unlike thenify, it does not need to be installed as an external package, offering a more integrated solution for modern Node.js versions.

bluebird

Bluebird is a comprehensive promise library that offers a wide range of features for working with promises, including but not limited to converting callback-style functions into promises. It provides a method called `.promisify()` which is similar to thenify's functionality. Bluebird promises are known for their performance and additional utility methods not found in native promises, making it a more feature-rich, albeit heavier, alternative.

pify

Pify is another npm package that converts callback-based functions into promises. It offers a simple and lightweight approach similar to thenify but with additional options for customizing the behavior of the promisified function, such as the ability to handle multiple callback arguments or to exclude certain functions from promisification. Pify provides a balance between simplicity and configurability.

README

thenify

Promisify a callback-based function using any-promise.

• Preserves function names
• Uses a native promise implementation if available and tries to fall back to a promise implementation such as bluebird
• Converts multiple arguments from the callback into an Array, also support change the behavior by options.multiArgs
• Resulting function never deoptimizes
• Supports both callback and promise style

An added benefit is that thrown errors in that async function will be caught by the promise!

API

fn = thenify(fn, options)

Promisifies a function.

Options

options are optional.

• options.withCallback - support both callback and promise style, default to false.

• options.multiArgs - change the behavior when callback have multiple arguments. default to true.

  • true - converts multiple arguments to an array
  • false- always use the first argument
  • Array - converts multiple arguments to an object with keys provided in options.multiArgs

• Turn async functions into promises

var thenify = require('thenify');

var somethingAsync = thenify(function somethingAsync(a, b, c, callback) {
  callback(null, a, b, c);
});

• Backward compatible with callback

var thenify = require('thenify');

var somethingAsync = thenify(function somethingAsync(a, b, c, callback) {
  callback(null, a, b, c);
}, { withCallback: true });

// somethingAsync(a, b, c).then(onFulfilled).catch(onRejected);
// somethingAsync(a, b, c, function () {});

or use thenify.withCallback()

var thenify = require('thenify').withCallback;

var somethingAsync = thenify(function somethingAsync(a, b, c, callback) {
  callback(null, a, b, c);
});

// somethingAsync(a, b, c).then(onFulfilled).catch(onRejected);
// somethingAsync(a, b, c, function () {});

• Always return the first argument in callback

var thenify = require('thenify');

var promise = thenify(function (callback) {
  callback(null, 1, 2, 3);
}, { multiArgs: false });

// promise().then(function onFulfilled(value) {
//   assert.equal(value, 1);
// });

• Converts callback arguments to an object

var thenify = require('thenify');

var promise = thenify(function (callback) {
  callback(null, 1, 2, 3);
}, { multiArgs: [ 'one', 'tow', 'three' ] });

// promise().then(function onFulfilled(value) {
//   assert.deepEqual(value, {
//     one: 1,
//     tow: 2,
//     three: 3
//   });
// });