{"id":15421,"library":"deferential","title":"deferential: Promise/Callback Dual API Helper","description":"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.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/eugeneware/deferential","tags":["javascript","promise","promises","defer","deferred","callback","nodeback","cb"],"install":[{"cmd":"npm install deferential","lang":"bash","label":"npm"},{"cmd":"yarn add deferential","lang":"bash","label":"yarn"},{"cmd":"pnpm add deferential","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import Deferred from 'deferential';","symbol":"Deferred","correct":"const Deferred = require('deferential');"},{"note":"The `Deferred` function is invoked directly to create an instance, not with `new`.","wrong":"const d = new Deferred();","symbol":"Deferred()","correct":"const d = Deferred();"},{"note":"`resolver()` returns a thunk that handles Node.js-style (err, data) callbacks, automatically resolving or rejecting the deferred promise.","wrong":"fs.readFile(fileName, 'utf8', d.resolve);","symbol":"d.resolver()","correct":"fs.readFile(fileName, 'utf8', d.resolver());"}],"quickstart":{"code":"const Promise = require('native-promise-only'); // Polyfill for older environments\nconst fs = require('fs');\nconst Deferred = require('deferential');\n\nfunction getFile(fileName, cb) {\n  const d = Deferred();\n  fs.readFile(fileName, 'utf8', d.resolver());\n  return d.nodeify(cb);\n}\n\n// Example usage with callback\ngetFile('myfile.text', function (err, data) {\n  if (err) return console.error('Callback error:', err.message);\n  console.log('Callback data:', data.substring(0, 50) + '...');\n});\n\n// Example usage with Promise\ngetFile('myfile.txt')\n  .then(function (data) {\n    console.log('Promise data:', data.substring(0, 50) + '...');\n  })\n  .catch(function (err) {\n    console.error('Promise error:', err.message);\n  });\n\n// To make the example runnable, create a dummy file\nfs.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.');\nfs.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.');","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"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) => { ... })`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If `Promise` is undefined, include a polyfill like `native-promise-only` (as shown in the `deferential` README) at the start of your application.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`.","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`).","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Verify that you are using `const Deferred = require('deferential');` in a CommonJS context, and that the package is correctly installed.","cause":"This error typically occurs if `deferential` was imported incorrectly (e.g., `import { Deferred } from 'deferential';`) or if the module failed to load.","error":"TypeError: Deferred is not a function"},{"fix":"Add a Promise polyfill (e.g., `require('native-promise-only');`) at the entry point of your application before `deferential` is used.","cause":"The JavaScript environment where `deferential` is being executed does not have a native ES6 Promise implementation.","error":"ReferenceError: Promise is not defined"}],"ecosystem":"npm"}