deferential: Promise/Callback Dual API Helper

1.0.0 · maintenance · verified Tue Apr 21

deferential is a lightweight JavaScript utility designed to assist in building APIs that support both Node.js-style callbacks and native ES6 Promises. It provides a `Deferred` object, which acts as an intermediate for managing the resolution or rejection of a promise, and a `nodeify` method to conditionally return a promise or invoke a callback. The package is at version 1.0.0, indicating a stable but likely infrequent release cadence given its focused scope and the maturity of native Promise implementations. Its key differentiator lies in offering a minimalistic approach to deferred patterns, avoiding the heavier overhead of full-fledged promise libraries like Q or Bluebird by leveraging native browser/Node.js ES6 Promises. It's particularly useful for adapting existing callback-based code to also expose a promise-based interface without rewriting the core logic.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require('deferential')` in a JavaScript file that Node.js interprets as an ES module (e.g., due to `.mjs` extension or `"type": "module"` in `package.json`).

fix Ensure your file is treated as a CommonJS module (e.g., `.js` extension without `"type": "module"`) or use Node.js's `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const Deferred = require('deferential');`.
```
TypeError: Deferred is not a function
```
cause This error typically occurs if `deferential` was imported incorrectly (e.g., `import { Deferred } from 'deferential';`) or if the module failed to load.

fix Verify that you are using `const Deferred = require('deferential');` in a CommonJS context, and that the package is correctly installed.
```
ReferenceError: Promise is not defined
```
cause The JavaScript environment where `deferential` is being executed does not have a native ES6 Promise implementation.

fix Add a Promise polyfill (e.g., `require('native-promise-only');`) at the entry point of your application before `deferential` is used.

Warnings

gotcha The 'deferred' pattern, while implemented by `deferential`, is often considered an anti-pattern in modern JavaScript in favor of directly constructing Promises using `new Promise((resolve, reject) => { ... })`.
Fix: For new code, consider using the `new Promise` constructor directly. For adapting callback APIs, ensure the `deferential` pattern is understood and aligns with project conventions.
gotcha This package is primarily designed for CommonJS environments. Attempting to use `import Deferred from 'deferential';` in a native ES module context in Node.js will result in errors.
Fix: Use `const Deferred = require('deferential');` in CommonJS modules. For ESM, you might need a bundler like Webpack or Rollup, or use Node.js's `createRequire` function if absolutely necessary.
gotcha The package relies on the global availability of an ES6 `Promise` constructor. In very old or non-standard JavaScript environments, a polyfill for `Promise` might be required.
Fix: If `Promise` is undefined, include a polyfill like `native-promise-only` (as shown in the `deferential` README) at the start of your application.

Install

npm install deferential npm
yarn add deferential yarn
pnpm add deferential pnpm

Imports

Deferred
wrong:
```
import Deferred from 'deferential';
```
correct:
```
const Deferred = require('deferential');
```
This package is primarily designed for CommonJS environments. While bundlers might process ESM `import` statements, direct use in Node.js ESM modules will likely fail without `createRequire`.
Deferred()
wrong:
```
const d = new Deferred();
```
correct:
```
const d = Deferred();
```
The `Deferred` function is invoked directly to create an instance, not with `new`.
d.resolver()
wrong:
```
fs.readFile(fileName, 'utf8', d.resolve);
```
correct:
```
fs.readFile(fileName, 'utf8', d.resolver());
```
`resolver()` returns a thunk that handles Node.js-style (err, data) callbacks, automatically resolving or rejecting the deferred promise.

Quickstart

This code demonstrates how to create a function (`getFile`) that can be consumed with both Node.js-style callbacks and native ES6 Promises using `deferential`.

const Promise = require('native-promise-only'); // Polyfill for older environments
const fs = require('fs');
const Deferred = require('deferential');

function getFile(fileName, cb) {
  const d = Deferred();
  fs.readFile(fileName, 'utf8', d.resolver());
  return d.nodeify(cb);
}

// Example usage with callback
getFile('myfile.text', function (err, data) {
  if (err) return console.error('Callback error:', err.message);
  console.log('Callback data:', data.substring(0, 50) + '...');
});

// Example usage with Promise
getFile('myfile.txt')
  .then(function (data) {
    console.log('Promise data:', data.substring(0, 50) + '...');
  })
  .catch(function (err) {
    console.error('Promise error:', err.message);
  });

// To make the example runnable, create a dummy file
fs.writeFileSync('myfile.text', 'This is some dummy content for the deferential example file. It demonstrates how the package can handle both callback-based and promise-based APIs simultaneously. This makes it easier to migrate or support legacy code while offering modern promise interfaces.');
fs.writeFileSync('myfile.txt', 'This is some dummy content for the deferential example file. It demonstrates how the package can handle both callback-based and promise-based APIs simultaneously. This makes it easier to migrate or support legacy code while offering modern promise interfaces.');

view raw JSON →