@broofa/asyncproxy

asyncProxy

A simple, intuitive solution for converting node-style APIs to Promises.

This module is similar to utilities such as bluebird.promisifyAll and promiseproxy. The main difference is that it's behavior is driven by calling code rather than magical introspection or ad-hoc configuration options.

Key features ...

• Tiny. No dependencies, ~0.3KB when minified/compressed.
• Zero API footprint. Does not modify the original API.
• Drop-in replacement. asyncProxy objects are literal proxies for the original API. Treat them exactly as you would the original API.
• Simple promisification logic. Just add "Async" to method name. api.fooAsync() == api.foo()-promisified.
• Simple multi-args logic. API callback takes more than one argument? Array destructuring, FTW!

Installation

You know the drill ...

npm i @broofa/asyncproxy

const asyncProxy = require('@broofa/asyncproxy');

Example: Promisify fs.readFile (basic usage)

// Wrap api in asyncProxy()
const fs = asyncProxy(require('fs'));

// An asyncProxy-ified apis is *identical* to the original api
console.log(fs === require('fs'));  // ==> true

// ... but promisifies any method invoked as `${methodName}Async`
const fileContents = await fs.readFileAsync('README.md', 'utf8');

Example: Promisify child.exec (multiple callback arguments)

Anytime 2+ arguments are passed to a callback, the Promise resolves to an argument Array:

// Promisified `exec` method
const child_process = asyncProxy(require('child_process'));

// Use array destructuring to extract result values
let [stdout, stderr] = await execAsync('ls');

Example: Custom method name pattern

Appending Async to indicate a promise-returning method is the general convention, but this may not always be desirable. The methodRegex option is used to detect which methods should be promisified.

E.g. To use an "async_"-prefix:

const fs = asyncProxy(require('fs'), {methodRegex: /^async_/});

const fileContents = await fs.async_readFile('README.md', 'utf8');