README

always-promise

Promisify, basically, everything. Generator function, callback-style or synchronous function; sync function that returns child process, stream or observable; directly passed promise, stream or child process.

Install

npm i always-promise --save

API

For more use-cases see the tests or try examples

alwaysPromise

Promisify everything!

<val> {Function|GeneratorFunction|Stream|Promise} anything that merz accepts
Prome {Function} custom promise module, which will be used for promisify-ing
- you can also pass it through alwaysPromise.promise static property
- or through promisifiedFn.promise static property
return {Function} which returns promise

Example

const promisify = require('always-promise')

alwaysPromise.promise

Static property on which you can pass custom promise constructor.
Actually same as Prome argument.

Example

const fs = require('fs')

// `q` promise will be used if not native promise available
// but only in node <= 0.11.12
promisify.promise = require('q')
promisify(fs.readFile)('package.json', 'utf-8').then(data => {
  console.log(JSON.parse(data).name)
})

promisifiedFn.promise

You also can pass custom promise module through .promise static property of the returned promisified function.

Example

const fs = require('fs')
const readFile = promisify(fs.readFileSync)

// `q` promise will be used if not native promise available
// but only in node <= 0.11.12
readFile.promise = require('q')

readFile('package.json', 'utf-8').then(data => {
  console.log(JSON.parse(data).name)
})

Examples

Showing few examples how to can be used. See more in examples dir or tests

Generator function

Promisify-ing generator function, yielding readFile thunk

const fs = require('fs')

function readThunk (fp) {
  return function (done) {
    fs.readFile(fp, 'utf8', done)
  }
}

const readFile = promisify(function * (filepath) {
  var data = yield read(filepath)
  return JSON.parse(data)
})

readFile('package.json').then(function (json) {
  console.log(json.name) // => 'always-promise'
}, console.error)

JSON.stringify

Specific use-case which shows correct and working handling of optional arguments.

promisify(JSON.stringify)({foo: 'bar'})
.then(data => {
  console.log(data) //=> {"foo":"bar"}
}, console.error)

// result with identation
promisify(JSON.stringify)({foo: 'bar'}, null, 2).then(function (data) {
  console.log(data)
  // =>
  // {
  //   "foo": "bar"
  // }
}, console.error)

callback-style and sync functions

Again, showing correct handling of optinal arguments using native fs module.

const fs = require('fs')

// callback function
promisify(fs.stat)('package.json')
.then(res => {
  console.log(res.isFile()) //=> true
}, console.error)

// correct handling of optional arguments
promisify(fs.readFile)('package.json')
.then(buf => {
  console.log(Buffer.isBuffer(buf)) //=> true
}, console.error)

// read json file and parse it,
// because it will be utf8 string
promisify(fs.readFileSync)('package.json', 'utf-8')
.then(JSON.parse)
.then(data => {
  console.log(data.name) //=> 'always-callback'
}, console.error)

flatten multiple arguments by default

If you pass more than two arguments to the callback, they will be flattened by default.

promisify((one, two, three, cb) => {
  cb(null, one, two, 33)
})(11, 22)
.then(res => {
  console.log(Array.isArray(res)) //=> true
  console.log(res) //=> [11, 22, 33]
}, console.error)

always-done: Handles completion and errors of anything!
always-thunk: Create thunk from anything, works like thunkify. Transforms anything (callbacks, streams, promises, observables, child processes, sync and generator functions) to thunk.
native-or-another: Always will expose native Promise if available, otherwise Bluebird but only if you don't give another promise module like q or promise or what you want.
native-promise: Get native Promise or falsey value if not available.
merz: Wrapper to handle completion and errors of sync and async functions, promises, generators, streams, observables and child processes.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
But before doing anything, please read the CONTRIBUTING.md guidelines.