0
# Thenify
1

2
## Overview
3

4
Thenify is a Node.js library that converts callback-based functions into Promise-based functions using any-promise. It preserves function names, handles multiple callback arguments, supports both callback and promise styles, and ensures optimal performance by avoiding function deoptimization.
5

6
## Package Information
7

8
- **Package Name**: thenify
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install thenify`
12

13
## Core Imports
14

15
```javascript
16
const thenify = require('thenify');
17
```
18

19
Note: This package uses CommonJS and does not support ESM imports.
20

21
## Basic Usage
22

23
```javascript
24
const thenify = require('thenify');
25

26
// Convert a callback-based function to promise-based
27
const somethingAsync = thenify(function somethingAsync(a, b, c, callback) {
28
  callback(null, a, b, c);
29
});
30

31
// Use as promise
32
somethingAsync(1, 2, 3).then(function(result) {
33
  console.log(result); // [1, 2, 3]
34
});
35

36
// Backward compatible version that supports both callbacks and promises
37
const backwardCompatible = thenify.withCallback(function(callback) {
38
  callback(null, 'success');
39
});
40

41
// Both styles work:
42
backwardCompatible().then(result => console.log(result)); // 'success'
43
backwardCompatible(function(err, result) { console.log(result); }); // 'success'
44
```
45

46
## Capabilities
47

48
### Basic Promisification
49

50
Converts callback-based functions to promise-based functions.
51

52
```javascript { .api }
53
/**
54
 * Promisifies a callback-based function
55
 * @param {Function} fn - The callback-based function to promisify
56
 * @param {Object} [options] - Configuration options
57
 * @returns {Function} Promisified function that returns a Promise
58
 */
59
function thenify(fn, options);
60
```
61

62
**Usage Examples:**
63

64
```javascript
65
const thenify = require('thenify');
66

67
// Basic promisification
68
const readFileAsync = thenify(require('fs').readFile);
69
readFileAsync('file.txt').then(data => console.log(data));
70

71
// Function with multiple arguments becomes array
72
const multiArg = thenify(function(callback) {
73
  callback(null, 1, 2, 3);
74
});
75
multiArg().then(result => console.log(result)); // [1, 2, 3]
76
```
77

78
### Backward Compatible Promisification
79

80
Promisifies a function while maintaining backward compatibility with callback style.
81

82
```javascript { .api }
83
/**
84
 * Promisifies a function with backward compatibility for callback style
85
 * @param {Function} fn - The callback-based function to promisify
86
 * @param {Object} [options] - Configuration options
87
 * @returns {Function} Function that supports both promise and callback styles
88
 */
89
thenify.withCallback(fn, options);
90
```
91

92
**Usage Examples:**
93

94
```javascript
95
const thenify = require('thenify');
96

97
// Using the method directly
98
const flexible = thenify.withCallback(function(callback) {
99
  callback(null, 'result');
100
});
101

102
// Promise style
103
flexible().then(result => console.log(result));
104

105
// Callback style
106
flexible(function(err, result) {
107
  console.log(result);
108
});
109

110
// Alternative import pattern
111
const withCallback = require('thenify').withCallback;
112
const anotherFunction = withCallback(someCallbackFunction);
113
```
114

115
## Configuration Options
116

117
### withCallback Option
118

119
Controls whether the resulting function supports both callback and promise styles.
120

121
**Usage:**
122

123
```javascript
124
const hybrid = thenify(someFunction, { withCallback: true });
125
// Same as: thenify.withCallback(someFunction)
126
```
127

128
### multiArgs Option
129

130
Controls how multiple callback arguments are handled.
131

132
**Usage Examples:**
133

134
```javascript
135
// Default behavior - multiple args become array
136
const defaultBehavior = thenify(function(callback) {
137
  callback(null, 1, 2, 3);
138
});
139
defaultBehavior().then(result => console.log(result)); // [1, 2, 3]
140

141
// First argument only
142
const firstOnly = thenify(function(callback) {
143
  callback(null, 1, 2, 3);
144
}, { multiArgs: false });
145
firstOnly().then(result => console.log(result)); // 1
146

147
// Object mapping
148
const objectMapping = thenify(function(callback) {
149
  callback(null, 1, 2, 3);
150
}, { multiArgs: ['one', 'two', 'three'] });
151
objectMapping().then(result => console.log(result)); // { one: 1, two: 2, three: 3 }
152
```
153

154
## Key Features
155

156
### Function Name Preservation
157

158
Thenify preserves the original function name in the promisified version:
159

160
```javascript
161
function mySpecialFunction(callback) {
162
  callback(null, 'done');
163
}
164

165
const promisified = thenify(mySpecialFunction);
166
console.log(promisified.name); // 'mySpecialFunction'
167
```
168

169
### Error Handling
170

171
Callback errors are automatically converted to promise rejections:
172

173
```javascript
174
const errorFunction = thenify(function(callback) {
175
  callback(new Error('Something went wrong'));
176
});
177

178
errorFunction().catch(err => console.log(err.message)); // 'Something went wrong'
179
```
180

181
Thrown errors in the original function are also caught:
182

183
```javascript
184
const throwingFunction = thenify(function(callback) {
185
  throw new Error('Sync error');
186
});
187

188
throwingFunction().catch(err => console.log(err.message)); // 'Sync error'
189
```
190

191
### Performance Optimization
192

193
Thenify is designed to avoid function deoptimization and maintains optimal performance characteristics while providing the promisification functionality.
194

195
## Complete API Reference
196

197
```javascript { .api }
198
/**
199
 * Options object for thenify functions
200
 * @typedef {Object} ThenifyOptions
201
 * @property {boolean} [withCallback] - Enable backward compatibility with callback style
202
 * @property {boolean|string[]} [multiArgs] - Control behavior for multiple callback arguments:
203
 *   - true: converts to array (default)
204
 *   - false: use only first argument  
205
 *   - Array: convert to object with provided keys
206
 */
207

208
/**
209
 * Main thenify function - converts callback-based functions to promise-based
210
 * @param {Function} fn - The callback-based function to promisify
211
 * @param {ThenifyOptions} [options] - Configuration options
212
 * @returns {Function} Promisified function that returns a Promise
213
 */
214
function thenify(fn, options);
215

216
/**
217
 * Backward compatible version - supports both callback and promise styles
218
 * @param {Function} fn - The callback-based function to promisify
219
 * @param {ThenifyOptions} [options] - Configuration options
220
 * @returns {Function} Function that supports both promise and callback styles
221
 */
222
thenify.withCallback(fn, options);
223
```