tessl/npm-util--promisify

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

util.promisify

Name: tessl/npm-util--promisify
Author: tessl

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;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/util.promisify@1.1.x
Publish Source: CLI
Badge