[6a3a178] | 1 | # pify [![Build Status](https://travis-ci.org/sindresorhus/pify.svg?branch=master)](https://travis-ci.org/sindresorhus/pify)
|
---|
| 2 |
|
---|
| 3 | > Promisify a callback-style function
|
---|
| 4 |
|
---|
| 5 |
|
---|
| 6 | ## Install
|
---|
| 7 |
|
---|
| 8 | ```
|
---|
| 9 | $ npm install --save pify
|
---|
| 10 | ```
|
---|
| 11 |
|
---|
| 12 |
|
---|
| 13 | ## Usage
|
---|
| 14 |
|
---|
| 15 | ```js
|
---|
| 16 | const fs = require('fs');
|
---|
| 17 | const pify = require('pify');
|
---|
| 18 |
|
---|
| 19 | // promisify a single function
|
---|
| 20 |
|
---|
| 21 | pify(fs.readFile)('package.json', 'utf8').then(data => {
|
---|
| 22 | console.log(JSON.parse(data).name);
|
---|
| 23 | //=> 'pify'
|
---|
| 24 | });
|
---|
| 25 |
|
---|
| 26 | // or promisify all methods in a module
|
---|
| 27 |
|
---|
| 28 | pify(fs).readFile('package.json', 'utf8').then(data => {
|
---|
| 29 | console.log(JSON.parse(data).name);
|
---|
| 30 | //=> 'pify'
|
---|
| 31 | });
|
---|
| 32 | ```
|
---|
| 33 |
|
---|
| 34 |
|
---|
| 35 | ## API
|
---|
| 36 |
|
---|
| 37 | ### pify(input, [promiseModule], [options])
|
---|
| 38 |
|
---|
| 39 | Returns a promise wrapped version of the supplied function or module.
|
---|
| 40 |
|
---|
| 41 | #### input
|
---|
| 42 |
|
---|
| 43 | Type: `function`, `object`
|
---|
| 44 |
|
---|
| 45 | Callback-style function or module whose methods you want to promisify.
|
---|
| 46 |
|
---|
| 47 | #### promiseModule
|
---|
| 48 |
|
---|
| 49 | Type: `function`
|
---|
| 50 |
|
---|
| 51 | Custom promise module to use instead of the native one.
|
---|
| 52 |
|
---|
| 53 | Check out [`pinkie-promise`](https://github.com/floatdrop/pinkie-promise) if you need a tiny promise polyfill.
|
---|
| 54 |
|
---|
| 55 | #### options
|
---|
| 56 |
|
---|
| 57 | ##### multiArgs
|
---|
| 58 |
|
---|
| 59 | Type: `boolean`
|
---|
| 60 | Default: `false`
|
---|
| 61 |
|
---|
| 62 | By default, the promisified function will only return the second argument from the callback, which works fine for most APIs. This option can be useful for modules like `request` that return multiple arguments. Turning this on will make it return an array of all arguments from the callback, excluding the error argument, instead of just the second argument.
|
---|
| 63 |
|
---|
| 64 | ```js
|
---|
| 65 | const request = require('request');
|
---|
| 66 | const pify = require('pify');
|
---|
| 67 |
|
---|
| 68 | pify(request, {multiArgs: true})('https://sindresorhus.com').then(result => {
|
---|
| 69 | const [httpResponse, body] = result;
|
---|
| 70 | });
|
---|
| 71 | ```
|
---|
| 72 |
|
---|
| 73 | ##### include
|
---|
| 74 |
|
---|
| 75 | Type: `array` of (`string`|`regex`)
|
---|
| 76 |
|
---|
| 77 | Methods in a module to promisify. Remaining methods will be left untouched.
|
---|
| 78 |
|
---|
| 79 | ##### exclude
|
---|
| 80 |
|
---|
| 81 | Type: `array` of (`string`|`regex`)
|
---|
| 82 | Default: `[/.+Sync$/]`
|
---|
| 83 |
|
---|
| 84 | Methods in a module **not** to promisify. Methods with names ending with `'Sync'` are excluded by default.
|
---|
| 85 |
|
---|
| 86 | ##### excludeMain
|
---|
| 87 |
|
---|
| 88 | Type: `boolean`
|
---|
| 89 | Default: `false`
|
---|
| 90 |
|
---|
| 91 | By default, if given module is a function itself, this function will be promisified. Turn this option on if you want to promisify only methods of the module.
|
---|
| 92 |
|
---|
| 93 | ```js
|
---|
| 94 | const pify = require('pify');
|
---|
| 95 |
|
---|
| 96 | function fn() {
|
---|
| 97 | return true;
|
---|
| 98 | }
|
---|
| 99 |
|
---|
| 100 | fn.method = (data, callback) => {
|
---|
| 101 | setImmediate(() => {
|
---|
| 102 | callback(data, null);
|
---|
| 103 | });
|
---|
| 104 | };
|
---|
| 105 |
|
---|
| 106 | // promisify methods but not fn()
|
---|
| 107 | const promiseFn = pify(fn, {excludeMain: true});
|
---|
| 108 |
|
---|
| 109 | if (promiseFn()) {
|
---|
| 110 | promiseFn.method('hi').then(data => {
|
---|
| 111 | console.log(data);
|
---|
| 112 | });
|
---|
| 113 | }
|
---|
| 114 | ```
|
---|
| 115 |
|
---|
| 116 |
|
---|
| 117 | ## License
|
---|
| 118 |
|
---|
| 119 | MIT © [Sindre Sorhus](http://sindresorhus.com)
|
---|