{"id":15257,"library":"util-promisify","title":"Node.js Promisify Polyfill","description":"util-promisify is a JavaScript package that provides the `util.promisify` function from Node.js core as a standalone module. It was originally created to enable the use of `async/await` patterns with callback-based Node.js APIs in environments prior to Node.js 8, where `util.promisify` was initially introduced. While the current stable version is 3.0.0, the package's core functionality is now standard and natively available in all actively supported Node.js versions (v8.0.0 and later). Consequently, this package primarily serves as a polyfill for legacy Node.js environments. Its release cadence is infrequent, typically limited to minor maintenance updates or compatibility adjustments, rather than active feature development. The key differentiator at its inception was providing early access to this crucial utility for modernizing asynchronous code, though its necessity has significantly diminished due to its universal inclusion in recent Node.js runtimes. Developers targeting Node.js versions older than 8.0.0 would find this module essential, otherwise, the native `util.promisify` should be preferred for better performance and reduced dependency count.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/juliangruber/util-promisify","tags":["javascript"],"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":"Primary usage is CommonJS. While bundlers may handle ESM, the package is CommonJS-first.","wrong":"import promisify from 'util-promisify';","symbol":"promisify","correct":"const promisify = require('util-promisify');"},{"note":"When used with ESM-aware bundlers or Node.js ESM, `promisify` is a default export, not a named one.","wrong":"import { promisify } from 'util-promisify';","symbol":"promisify","correct":"import promisify from 'util-promisify';"},{"note":"`custom` is a Symbol property on the exported `promisify` function, not a separate named export.","wrong":"import { custom } from 'util-promisify';","symbol":"promisify.custom","correct":"const promisify = require('util-promisify');\nconst customSymbol = promisify.custom;"}],"quickstart":{"code":"import promisify from 'util-promisify'; // Use const promisify = require('util-promisify'); for CommonJS\nimport * as fs from 'fs';\nimport { join } from 'path';\n\nconst statAsync = promisify(fs.stat);\nconst readFileAsync = promisify(fs.readFile);\nconst writeFileAsync = promisify(fs.writeFile);\n\nasync function demonstratePromisify() {\n  const tempFilePath = join(process.cwd(), `temp_file_${Date.now()}.txt`);\n  const fileContent = `Hello, util-promisify! This is a test content written at ${new Date().toISOString()}`; \n\n  try {\n    console.log(`Attempting to write to: ${tempFilePath}`);\n    await writeFileAsync(tempFilePath, fileContent, 'utf8');\n    console.log(`Successfully wrote ${fileContent.length} bytes to ${tempFilePath}`);\n\n    const stats = await statAsync(tempFilePath);\n    console.log(`File stats: size=${stats.size} bytes, isFile=${stats.isFile()}`);\n\n    const content = await readFileAsync(tempFilePath, 'utf8');\n    console.log(`File content read: \"${content}\"`);\n\n    // Example of error handling: trying to stat a non-existent file\n    console.log('\\nAttempting to stat a non-existent file for error demonstration...');\n    await statAsync('/path/to/definitely/nonexistent/file.xyz');\n  } catch (error: any) {\n    if (error.code === 'ENOENT') {\n      console.error(`Expected error: File or directory not found. Message: ${error.message}`);\n    } else {\n      console.error(`An unexpected error occurred: ${error.message}`);\n    }\n  } finally {\n    if (fs.existsSync(tempFilePath)) {\n      await promisify(fs.unlink)(tempFilePath);\n      console.log(`Cleaned up temporary file: ${tempFilePath}`);\n    } else {\n      console.log(`No temporary file to clean up at ${tempFilePath}`);\n    }\n  }\n}\n\ndemonstratePromisify().catch(err => {\n  console.error(\"A fatal error occurred during the demonstration:\", err);\n});","lang":"typescript","description":"Demonstrates how to use `util-promisify` to convert Node.js callback-style functions (`fs.stat`, `fs.readFile`, `fs.writeFile`) into Promise-based equivalents, including basic file operations and error handling within an async function. Note that type definitions are typically provided by `@types/util-promisify`."},"warnings":[{"fix":"For Node.js v8.0.0 or newer, use `const { promisify } = require('util');` (CommonJS) or `import { promisify } from 'util';` (ESM) instead.","message":"The `util.promisify` function has been natively available in Node.js core since version 8.0.0. For modern Node.js applications (v8 and newer), directly importing `util` and using `util.promisify` is generally preferred over this standalone module, as it avoids an unnecessary dependency.","severity":"gotcha","affected_versions":"<8.0.0 Node.js (package is useful here), >=8.0.0 Node.js (package is redundant)"},{"fix":"No functional code changes are required when upgrading from v2 to v3.","message":"Version 3.0.0 did not introduce functional breaking changes, but focused on license updates and Travis CI configurations, including updating to Node 10 in CI. The API remained consistent with previous versions and Node.js core's `util.promisify`.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are importing/requiring the module correctly: `const promisify = require('util-promisify');` for CommonJS or `import promisify from 'util-promisify';` for ESM. If targeting Node.js < 8, ensure this package is installed and imported. If targeting Node.js >= 8, use `const { promisify } = require('util');` instead.","cause":"Attempting to import `promisify` incorrectly, or `require`ing it in a way that doesn't yield the function directly (e.g., trying `require('util-promisify').promisify` when it's a default export). This can also happen if attempting to use `util.promisify` on Node.js versions older than 8.0.0 without the `util-promisify` polyfill.","error":"TypeError: promisify is not a function"},{"fix":"Ensure that the argument passed to `promisify` is always a valid function. For object methods, you might need to bind the context: `promisify(myObject.method.bind(myObject))` or use a wrapper function `promisify((...args) => myObject.method(...args))`. Always check that the function you intend to promisify is actually defined and accessible.","cause":"The `promisify` function was called with an argument that is not a function. This often occurs when passing a method directly from an object without binding its context, or passing an undefined/null value.","error":"ERR_INVALID_ARG_TYPE: The \"original\" argument must be of type function. Received an instance of Object"}],"ecosystem":"npm"}