util.promisify Polyfill

Common errors

• ReferenceError: Promise is not defined

  cause The runtime environment does not have a global Promise constructor, which is a requirement for this polyfill.
  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.

• TypeError: util.promisify is not a function

  cause The `util.promisify/shim` was required but not called as a function, or the package was not included at all.
  fix Ensure you correctly invoke the shim: `require('util.promisify/shim')();` before attempting to use `util.promisify`.

• SyntaxError: Use of const in strict mode.

  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.
  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.

• TypeError: promisify.custom is not a function

  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.
  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`.

Warnings

• gotcha 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.
  Fix: For Node.js >= v8.0.0, remove this package and use `const { promisify } = require('util');` directly.
• gotcha 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.
  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.
• gotcha 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`.
  Fix: Always call the shim function: `require('util.promisify/shim')();`
• deprecated 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`.
  Fix: Upgrade your Node.js runtime to version 8.0.0 or higher.

Install

• npm install util.promisify npm
• yarn add util.promisify yarn
• pnpm add util.promisify pnpm

Imports

• promisify
  wrong:

  import { promisify } from 'util.promisify';

  correct:

  const promisify = require('util.promisify');

  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.
• util.promisify (after shim)
  wrong:

  require('util.promisify/shim');

  correct:

  require('util.promisify/shim')();

  The shim entry point patches the global `util` object to include `promisify`. It must be called as a function to execute the patching logic.
• util.promisify
  wrong:

  import { promisify } from 'util';

  correct:

  const { promisify } = require('util');

  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.

Quickstart

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.

import './node_modules/util.promisify/shim'; // Ensure the shim is loaded
import * as util from 'util';
import * as fs from 'fs';

// Example callback-style function
function delay(ms: number, callback: (err: Error | null, message?: string) => void): void {
  setTimeout(() => {
    if (ms < 0) {
      callback(new Error('Delay must be positive'));
    } else {
      callback(null, `Delayed for ${ms} milliseconds.`);
    }
  }, ms);
}

// Promisify the custom function
const promisifiedDelay = util.promisify(delay);

// Promisify a built-in Node.js function (e.g., fs.readFile)
const readFilePromisified = util.promisify(fs.readFile);

async function runExample() {
  try {
    console.log('Starting delay...');
    const result = await promisifiedDelay(1000);
    console.log(result); // Expected: "Delayed for 1000 milliseconds."

    // Demonstrate error handling
    await promisifiedDelay(-100);
  } catch (error: any) {
    console.error('Caught expected error:', error.message); // Expected: "Delay must be positive"
  }

  try {
    // Create a dummy file for demonstration
    fs.writeFileSync('temp.txt', 'Hello, util.promisify!');
    const data = await readFilePromisified('./temp.txt', 'utf8');
    console.log('Read temp.txt:', data);
    fs.unlinkSync('temp.txt'); // Clean up
  } catch (err: any) {
    console.error('Error reading/writing file:', err.message);
  }
}

runExample();