0
# util.promisify
1

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

4
## Package Information
5

6
- **Package Name**: util.promisify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install util.promisify`
10

11
## Core Imports
12

13
**Main entry point** (provides promisify function with all properties):
14
```javascript
15
const promisify = require('util.promisify');
16
// promisify.custom, promisify.getPolyfill, etc. are all available as properties
17
```
18

19
**Shim installation** (installs on util object):
20
```javascript
21
require('util.promisify/shim')();
22
const util = require('util');
23
// Now util.promisify is available
24
```
25

26
**Auto installation** (automatically installs shim):
27
```javascript
28
require('util.promisify/auto');
29
const util = require('util');
30
// Now util.promisify is available (automatically installed)
31
```
32

33
**Direct module access**:
34
```javascript
35
const getPolyfill = require('util.promisify/polyfill');
36
const implementation = require('util.promisify/implementation');
37
const shim = require('util.promisify/shim');
38
```
39

40
## Basic Usage
41

42
```javascript
43
const promisify = require('util.promisify');
44
const fs = require('fs');
45

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

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

54
// Or with async/await
55
async function example() {
56
  try {
57
    const content = await readFile('file.txt', 'utf8');
58
    console.log(content);
59
  } catch (err) {
60
    console.error(err);
61
  }
62
}
63
```
64

65
## Architecture
66

67
The package provides multiple ways to access promisify functionality:
68

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

74
## Requirements
75

76
- **Environment**: Requires a true ES5+ environment with `__proto__` support
77
- **Promise**: Global Promise constructor must be available
78
- **Node.js**: >= 0.8 (for package compatibility)
79

80
## Capabilities
81

82
### Main Promisify Function
83

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

86
```javascript { .api }
87
/**
88
 * Convert a callback-based function to a Promise-based function
89
 * @param {Function} original - The original callback-based function
90
 * @returns {Function} Promise-based version of the function
91
 * @throws {TypeError} If original is not a function or custom property is not a function
92
 */
93
function promisify(original);
94

95
// Properties available on the main promisify function:
96
promisify.custom; // Symbol for custom promisify implementation
97
promisify.customPromisifyArgs; // Symbol for callback argument names
98
promisify.getPolyfill; // Function that returns appropriate implementation
99
promisify.implementation; // Core implementation function
100
promisify.shim; // Function that installs promisify on util object
101
```
102

103
**Usage Example:**
104

105
```javascript
106
const promisify = require('util.promisify');
107
const fs = require('fs');
108

109
const readFile = promisify(fs.readFile);
110
const result = await readFile('path/to/file.txt', 'utf8');
111
```
112

113
### Custom Promisification
114

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

117
```javascript { .api }
118
/**
119
 * Global symbol for custom promisify implementation
120
 * Value: Symbol.for('nodejs.util.promisify.custom')
121
 * @type {Symbol}
122
 */
123
promisify.custom;
124

125
/**
126
 * Symbol for specifying callback argument names for multi-argument callbacks
127
 * @type {Symbol}
128
 */
129
promisify.customPromisifyArgs;
130
```
131

132
**Usage Example:**
133

134
```javascript
135
const promisify = require('util.promisify');
136

137
function customFunction(callback) {
138
  // Custom implementation
139
}
140

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

146
const promisified = promisify(customFunction);
147
// Uses the custom implementation instead of the default promisify logic
148
```
149

150
### Multi-Argument Callback Support
151

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

154
```javascript { .api }
155
/**
156
 * Attach argument names to original function for multi-argument callback support
157
 * @param {Function} original - Function to attach names to
158
 * @param {string[]} names - Array of argument names for callback parameters
159
 */
160
original[promisify.customPromisifyArgs] = ['arg1', 'arg2'];
161
```
162

163
**Usage Example:**
164

165
```javascript
166
const promisify = require('util.promisify');
167

168
function multiArgCallback(callback) {
169
  callback(null, 'value1', 'value2');
170
}
171

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

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

179
### Polyfill Detection
180

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

183
```javascript { .api }
184
/**
185
 * Returns the native util.promisify if available and compatible, otherwise returns polyfill
186
 * @returns {Function} The promisify implementation to use (either native or polyfill)
187
 */
188
promisify.getPolyfill();
189
```
190

191
### Implementation Access
192

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

195
```javascript { .api }
196
/**
197
 * Core promisify implementation function (always uses polyfill implementation)
198
 * @param {Function} original - The original callback-based function  
199
 * @returns {Function} Promise-based version of the function
200
 * @throws {TypeError} If original is not a function or environment requirements not met
201
 */
202
promisify.implementation;
203
```
204

205
### Shimming
206

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

209
```javascript { .api }
210
/**
211
 * Install promisify polyfill on util.promisify if not natively available or compatible
212
 * @returns {Function} The installed promisify function (native or polyfill)
213
 */
214
promisify.shim();
215
```
216

217
**Usage Example:**
218

219
```javascript
220
require('util.promisify/shim')();
221
const util = require('util');
222

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

227
## Error Handling
228

229
The package throws specific errors for invalid usage:
230

231
- **TypeError**: Thrown when the original argument is not a function
232
- **TypeError**: Thrown when custom promisify property is not a function  
233
- **TypeError**: Thrown when Promise is not globally available
234
- **TypeError**: Thrown when environment doesn't support required ES5+ features
235

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

238
## Types
239

240
```javascript { .api }
241
/**
242
 * Error interface for promisify-specific errors
243
 * All promisify errors extend TypeError and include specific error codes
244
 */
245
interface PromisifyError extends TypeError {
246
  /** Error code, typically 'ERR_INVALID_ARG_TYPE' */
247
  code: string;
248
  /** Custom toString implementation that includes code in output */
249
  toString(): string;
250
}
251

252
/**
253
 * Multi-argument callback result when customPromisifyArgs is used
254
 * Keys correspond to the names specified in customPromisifyArgs array
255
 */
256
interface MultiArgResult {
257
  [key: string]: any;
258
}
259
```