{"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,"search_vec":"'1.0.0':65 'act':34 'adapt':122 'also':129 'api':4,17 'approach':93 'assist':14 'avoid':97 'base':126,134 'bluebird':110 'browser/node.js':114 'build':16 'cadenc':73 'callback':23,59,125,146 'callback-bas':124 'cb':148 'code':127 'condit':52 'core':139 'defer':31,95,144,145 'deferenti':1,6 'design':12 'differenti':87 'dual':3 'es6':26,115 'exist':123 'expos':130 'fledg':104 'focus':76 'full':103 'full-fledg':102 'given':74 'heavier':99 'helper':5 'implement':84 'indic':66 'infrequ':71 'interfac':135 'intermedi':37 'invok':57 'javascript':10,141 'key':86 'leverag':112 'librari':106 'lie':88 'lightweight':9 'like':70,107 'logic':140 'manag':39 'matur':80 'method':50 'minimalist':92 'nativ':25,82,113 'node.js':21 'nodeback':147 'nodeifi':49 'object':32 'offer':90 'overhead':100 'packag':61 'particular':119 'pattern':96 'promis':27,46,55,83,105,116,133,142,143 'promise-bas':132 'promise/callback':2 'provid':29 'q':108 'reject':43 'releas':72 'resolut':41 'return':53 'rewrit':137 'scope':77 'stabl':68 'style':22 'support':19 'use':120 'util':11 'version':64 'without':136","created_at":"2026-04-21T05:53:32.272459+00:00","updated_at":"2026-04-21T05:53:32.272459+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/eugeneware/deferential","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/deferential","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}