DEPRECATED!
This package was moved to the @xpack
scope.
To install it use @xpack/es6-promisifier
.
There are no plans for further releases of this package in the @ilg
scope.
An ES6 promisifier wrapper
A module providing a class with a static function to wrap standard Node.js callback functions into ES6 promises.
Prerequisites
A recent Node.js (>7.x), since the ECMAScript 6 class syntax is used.
Easy install
The module is available as
@ilg/es6-promisifier
from the public repository, use npm
to install it inside the module
where it is needed:
$ npm install @ilg/es6-promisifier --save
The module does not provide any executables, and generally there are few reasons to install it globally.
The development repository is available from the GitHub
xpack/es6-promisifier-js
project.
User info
The module can be included in any applications and the Promisifier
class can be used to access the promisify()
functions.
const Promisifier = require('@ilg/es6-promisifier').Promisifier
// Promisify functions from the Node.js callbacks library.
// The new functions have similar names, but suffixed with `Promise`,
// or below a `promises` object.
Promisifier.promisifyInPlace(fs, 'open')
// New use case:
// const fsPromises = fs.promises_
// await fsPromises.open()
// Old use case:
// await fs.openPromise()
// Note: using `promises_` is a workaround to avoid the `fs.promises`
// warning.
// Promisify a single function from a third party simple module.
const mkdirpPromise = Promisifier.promisify(require('mkdirp'))
Developer info
Git repo
$ git clone https://github.com/xpack/es6-promisifier-js.git es6-promisifier-js.git
$ cd es6-promisifier-js.git
$ npm install
$ sudo npm link
$ ls -l /usr/local/lib/node_modules/@ilg
or without sudo, on Windows or if installed in home folder:
$ npm link
A link to the development folder should be present in the global
node_modules
folder.
In projects that use this module under development, link back from the global location:
$ npm link @ilg/es6-promisifier
Tests
The tests use the node-tap
framework
(A Test-Anything-Protocol library for Node.js, written by Isaac Schlueter).
As for any npm
package, the standard way to run the project tests
is via npm test
:
$ cd es6-promisifier-js.git
$ npm install
$ npm run test
A typical test result looks like:
$ npm run test
> @ilg/es6-promisifier@0.1.2 test /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/es6-promisifier-js.git
> standard && npm run test-tap -s
test/tap/promisify.js ............................... 32/32
total ............................................... 32/32
32 passing (669.026ms)
ok
To run a specific test with more verbose output, use npm run tap
:
$ npm run tap test/tap/promisify.js -s
test/tap/promisify.js
original success
✓ null error
✓ returned value
original error
✓ have error
✓ error message match
✓ no returned value
promisify success
✓ returned value
promisify error
✓ exception message
promisify success await
✓ returned value
promisify error await
✓ exception message
promisify multi success
✓ result is array
✓ first value
✓ second value
promisify multi error
✓ exception message
promisify multi success await
✓ result is array
✓ first value
✓ second value
promisify multi error await
✓ exception message
promisify single success
✓ result is not array
✓ value
promisify single error
✓ exception message
promisify single success await
✓ result is not array
✓ value
promisify single error await
✓ exception message
promisify already success await
✓ returned value
promisify already error await
✓ exception message
promisify thisArg success await
✓ returned value
✓ context value
promisify thisArg error await
✓ exception message
constructor
✓ assert
promisify in place
✓ promise not there
✓ promise now available
✓ promise still there
32 passing (617.365ms)
Coverage tests
Coverage tests are a good indication on how much of the source files is exercised by the tests. Ideally all source files should be covered 100%, for all 4 criteria (statements, branches, functions, lines).
To run the coverage tests, use npm run test-coverage
:
$ npm run test-coverage
> @ilg/es6-promisifier@0.1.2 test-coverage /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/es6-promisifier-js.git
> tap --coverage --reporter=classic --timeout 600 --no-color "test/tap/*.js"
test/tap/promisify.js ............................... 32/32
total ............................................... 32/32
32 passing (829.493ms)
ok
----------------------------|----------|----------|----------|----------|----------------|
File | % Stmts | % Branch | % Funcs | % Lines |Uncovered Lines |
----------------------------|----------|----------|----------|----------|----------------|
All files | 100 | 100 | 100 | 100 | |
es6-promisifier-js.git | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
es6-promisifier-js.git/lib | 100 | 100 | 100 | 100 | |
promisifier.js | 100 | 100 | 100 | 100 | |
----------------------------|----------|----------|----------|----------|----------------|
Continuous Integration (CI)
The continuous integration tests are performed via Travis CI and AppVeyor.
To speed up things, the node_modules
folder is cached between builds.
Standard compliance
The module uses ECMAScript 6 class definitions.
As style, it uses the JavaScript Standard Style, automatically checked at each commit via Travis CI.
Known and accepted exceptions:
- none.
To manually fix compliance with the style guide (where possible):
$ npm run fix
> @ilg/es6-promisifier@0.1.12 fix /Users/ilg/My Files/MacBookPro Projects/xPack/npm-modules/es6-promisifier-js.git
> standard --fix
Documentation metadata
The documentation metadata follows the JSdoc tags.
To enforce checking at file level, add the following comments right after
the use strict
:
'use strict'
/* eslint valid-jsdoc: "error" */
/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
Note: be sure C style comments are used, C++ styles are not parsed by ESLint.
How to publish
- commit all changes
-
npm run test
(fix
included) - update
CHANGELOG.md
; commit with a message like CHANGELOG: prepare v0.1.2 npm version patch
- push all changes to GitHub; this should trigger CI
- wait for CI tests to complete
npm publish
License
The original content is released under the MIT License, with all rights reserved to Liviu Ionescu.