or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-util--promisify

Polyfill/shim for util.promisify in node versions < v8

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/util.promisify@1.1.x

To install, run

npx @tessl/cli install tessl/npm-util--promisify@1.1.0

index.mddocs/

util.promisify

util.promisify is a polyfill/shim for the built-in util.promisify function that was introduced in Node.js v8.0.0. It enables developers to use promisify functionality in older Node.js versions by providing the same API as the native implementation.

Package Information

  • Package Name: util.promisify
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install util.promisify

Core Imports

Main entry point (provides promisify function with all properties):

const promisify = require('util.promisify');
// promisify.custom, promisify.getPolyfill, etc. are all available as properties

Shim installation (installs on util object):

require('util.promisify/shim')();
const util = require('util');
// Now util.promisify is available

Auto installation (automatically installs shim):

require('util.promisify/auto');
const util = require('util');
// Now util.promisify is available (automatically installed)

Direct module access:

const getPolyfill = require('util.promisify/polyfill');
const implementation = require('util.promisify/implementation');
const shim = require('util.promisify/shim');

Basic Usage

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

// Convert callback-based function to promise-based
const readFile = promisify(fs.readFile);

// Use as promise
readFile('file.txt', 'utf8')
  .then(content => console.log(content))
  .catch(err => console.error(err));

// Or with async/await
async function example() {
  try {
    const content = await readFile('file.txt', 'utf8');
    console.log(content);
  } catch (err) {
    console.error(err);
  }
}

Architecture

The package provides multiple ways to access promisify functionality:

  • Direct Usage: Import and use the promisify function directly
  • Shimming: Install the polyfill on the native util object
  • Auto Installation: Automatically install the shim when the module is required
  • Polyfill Detection: Automatically uses native implementation when available in Node.js >= 8

Requirements

  • Environment: Requires a true ES5+ environment with __proto__ support
  • Promise: Global Promise constructor must be available
  • Node.js: >= 0.8 (for package compatibility)

Capabilities

Main Promisify Function

Converts a Node.js callback-based function to a Promise-based function. The returned function has the same prototype and properties as the original.

/**
 * Convert a callback-based function to a Promise-based function
 * @param {Function} original - The original callback-based function
 * @returns {Function} Promise-based version of the function
 * @throws {TypeError} If original is not a function or custom property is not a function
 */
function promisify(original);

// Properties available on the main promisify function:
promisify.custom; // Symbol for custom promisify implementation
promisify.customPromisifyArgs; // Symbol for callback argument names
promisify.getPolyfill; // Function that returns appropriate implementation
promisify.implementation; // Core implementation function
promisify.shim; // Function that installs promisify on util object

Usage Example:

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

const readFile = promisify(fs.readFile);
const result = await readFile('path/to/file.txt', 'utf8');

Custom Promisification

Support for custom promisification using Node.js standard symbols. These are Symbol values used for attaching custom behavior to functions.

/**
 * Global symbol for custom promisify implementation
 * Value: Symbol.for('nodejs.util.promisify.custom')
 * @type {Symbol}
 */
promisify.custom;

/**
 * Symbol for specifying callback argument names for multi-argument callbacks
 * @type {Symbol}
 */
promisify.customPromisifyArgs;

Usage Example:

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

function customFunction(callback) {
  // Custom implementation
}

// Attach custom promisify behavior using the standard symbol
customFunction[promisify.custom] = function() {
  return Promise.resolve('custom result');
};

const promisified = promisify(customFunction);
// Uses the custom implementation instead of the default promisify logic

Multi-Argument Callback Support

Support for callbacks that receive multiple arguments by specifying argument names. When specified, the promisified function resolves to an object with named properties instead of a single value.

/**
 * Attach argument names to original function for multi-argument callback support
 * @param {Function} original - Function to attach names to
 * @param {string[]} names - Array of argument names for callback parameters
 */
original[promisify.customPromisifyArgs] = ['arg1', 'arg2'];

Usage Example:

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

function multiArgCallback(callback) {
  callback(null, 'value1', 'value2');
}

// Specify argument names
multiArgCallback[promisify.customPromisifyArgs] = ['first', 'second'];

const promisified = promisify(multiArgCallback);
const result = await promisified(); // { first: 'value1', second: 'value2' }

Polyfill Detection

Get the appropriate promisify implementation, preferring native util.promisify when available and compatible.

/**
 * Returns the native util.promisify if available and compatible, otherwise returns polyfill
 * @returns {Function} The promisify implementation to use (either native or polyfill)
 */
promisify.getPolyfill();

Implementation Access

Access to the core promisify implementation function, bypassing polyfill detection.

/**
 * Core promisify implementation function (always uses polyfill implementation)
 * @param {Function} original - The original callback-based function  
 * @returns {Function} Promise-based version of the function
 * @throws {TypeError} If original is not a function or environment requirements not met
 */
promisify.implementation;

Shimming

Install the polyfill on the native util object if the native implementation is not available or incompatible.

/**
 * Install promisify polyfill on util.promisify if not natively available or compatible
 * @returns {Function} The installed promisify function (native or polyfill)
 */
promisify.shim();

Usage Example:

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

// util.promisify is now available regardless of Node.js version
const readFile = util.promisify(require('fs').readFile);

Error Handling

The package throws specific errors for invalid usage:

  • TypeError: Thrown when the original argument is not a function
  • TypeError: Thrown when custom promisify property is not a function
  • TypeError: Thrown when Promise is not globally available
  • TypeError: Thrown when environment doesn't support required ES5+ features

All errors include a code property with value 'ERR_INVALID_ARG_TYPE' when applicable.

Types

/**
 * Error interface for promisify-specific errors
 * All promisify errors extend TypeError and include specific error codes
 */
interface PromisifyError extends TypeError {
  /** Error code, typically 'ERR_INVALID_ARG_TYPE' */
  code: string;
  /** Custom toString implementation that includes code in output */
  toString(): string;
}

/**
 * Multi-argument callback result when customPromisifyArgs is used
 * Keys correspond to the names specified in customPromisifyArgs array
 */
interface MultiArgResult {
  [key: string]: any;
}