{"id":12330,"library":"util.promisify","title":"util.promisify Polyfill","description":"This package provides a polyfill or shim for the `util.promisify` function, which was introduced natively in Node.js v8.0.0. For environments running Node.js versions older than 8, it supplies its own implementation, enabling the use of Promise-based asynchronous patterns for callback-style functions. In Node.js v8.0.0 and later, it effectively becomes a passthrough, exporting the built-in `util.promisify`. The current stable version is 1.1.3. As a polyfill for a long-established native feature, its release cadence is very slow, primarily for bug fixes or to align with ancient Node.js environments. Its key differentiator is providing this core Node.js utility in environments where it's otherwise absent, making it crucial for maintaining compatibility across a wide range of Node.js versions, particularly in legacy applications that cannot upgrade past Node.js 7.x or older.","status":"maintenance","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/ljharb/util.promisify","tags":["javascript","promisify","promise","util","polyfill","shim","util.promisify"],"install":[{"cmd":"npm install util.promisify","lang":"bash","label":"npm"},{"cmd":"yarn add util.promisify","lang":"bash","label":"yarn"},{"cmd":"pnpm add util.promisify","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily intended for CommonJS environments (Node < v8) and older browser environments that lack native Promise support. Modern Node.js environments (v8+) should use the native util.promisify directly.","wrong":"import { promisify } from 'util.promisify';","symbol":"promisify","correct":"const promisify = require('util.promisify');"},{"note":"The shim entry point patches the global `util` object to include `promisify`. It must be called as a function to execute the patching logic.","wrong":"require('util.promisify/shim');","symbol":"util.promisify (after shim)","correct":"require('util.promisify/shim')();"},{"note":"This accesses the `util.promisify` function after it has been defined, either natively in Node.js >= v8, or by calling the 'util.promisify/shim' entrypoint in older environments. Using `import` will only work in ESM contexts, which might not be available in environments needing this polyfill.","wrong":"import { promisify } from 'util';","symbol":"util.promisify","correct":"const { promisify } = require('util');"}],"quickstart":{"code":"import './node_modules/util.promisify/shim'; // Ensure the shim is loaded\nimport * as util from 'util';\nimport * as fs from 'fs';\n\n// Example callback-style function\nfunction delay(ms: number, callback: (err: Error | null, message?: string) => void): void {\n  setTimeout(() => {\n    if (ms < 0) {\n      callback(new Error('Delay must be positive'));\n    } else {\n      callback(null, `Delayed for ${ms} milliseconds.`);\n    }\n  }, ms);\n}\n\n// Promisify the custom function\nconst promisifiedDelay = util.promisify(delay);\n\n// Promisify a built-in Node.js function (e.g., fs.readFile)\nconst readFilePromisified = util.promisify(fs.readFile);\n\nasync function runExample() {\n  try {\n    console.log('Starting delay...');\n    const result = await promisifiedDelay(1000);\n    console.log(result); // Expected: \"Delayed for 1000 milliseconds.\"\n\n    // Demonstrate error handling\n    await promisifiedDelay(-100);\n  } catch (error: any) {\n    console.error('Caught expected error:', error.message); // Expected: \"Delay must be positive\"\n  }\n\n  try {\n    // Create a dummy file for demonstration\n    fs.writeFileSync('temp.txt', 'Hello, util.promisify!');\n    const data = await readFilePromisified('./temp.txt', 'utf8');\n    console.log('Read temp.txt:', data);\n    fs.unlinkSync('temp.txt'); // Clean up\n  } catch (err: any) {\n    console.error('Error reading/writing file:', err.message);\n  }\n}\n\nrunExample();","lang":"typescript","description":"Demonstrates how to apply `util.promisify` to both a custom callback-style function and a Node.js built-in function like `fs.readFile`, showcasing basic usage and error handling."},"warnings":[{"fix":"For Node.js >= v8.0.0, remove this package and use `const { promisify } = require('util');` directly.","message":"This polyfill is primarily intended for Node.js environments older than v8.0.0. If you are using Node.js v8 or newer, the `util.promisify` function is built-in and does not require this package.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your environment provides a global `Promise` constructor (e.g., via a polyfill like `core-js` or by targeting a modern JavaScript environment) and supports ES5 features.","message":"The package explicitly requires a native ES5 environment and for the `Promise` global to be available. It will throw an error upon requiring if these prerequisites are not met.","severity":"gotcha","affected_versions":"all"},{"fix":"Always call the shim function: `require('util.promisify/shim')();`","message":"When using the shim (`require('util.promisify/shim')`), it must be invoked as a function (`shim()`) to apply the patch to the `util` module. Merely requiring it without calling the function will not define `util.promisify`.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade your Node.js runtime to version 8.0.0 or higher.","message":"While still functional, the need for this package diminishes with each passing year as older Node.js versions become less common. Projects should aim to upgrade Node.js to v8 or higher to rely on the native `util.promisify`.","severity":"deprecated","affected_versions":"<8.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Provide a Promise polyfill (e.g., `core-js/es6/promise`) before requiring `util.promisify` or ensure running in an environment with native Promise support.","cause":"The runtime environment does not have a global Promise constructor, which is a requirement for this polyfill.","error":"ReferenceError: Promise is not defined"},{"fix":"Ensure you correctly invoke the shim: `require('util.promisify/shim')();` before attempting to use `util.promisify`.","cause":"The `util.promisify/shim` was required but not called as a function, or the package was not included at all.","error":"TypeError: util.promisify is not a function"},{"fix":"Update your JavaScript runtime or compilation target to fully support ES5. If targeting extremely old browsers, additional transpilation might be necessary for other parts of your codebase.","cause":"This error or similar ES6+ syntax errors occur when the package is run in an extremely old JavaScript environment that does not fully support ES5, even though the package states it requires ES5.","error":"SyntaxError: Use of const in strict mode."},{"fix":"If custom promisification is needed, ensure you are using a Node.js environment >= v8 where the native `util.promisify` (which has `promisify.custom`) is available, or use the `util.promisify/shim` and access it via `util.promisify`.","cause":"Attempting to access `promisify.custom` (a Symbol used for custom promisification behavior) on the direct `promisify` export from this polyfill, instead of the native `util.promisify` or the shimmed `util.promisify` which supports the Symbol.","error":"TypeError: promisify.custom is not a function"}],"ecosystem":"npm"}