xpm
Version:
The xPack project manager command line tool
298 lines (208 loc) • 8.24 kB
Markdown
[](https://www.npmjs.com/package/@ilg/es6-promisifier)
[](https://github.com/xpack/es6-promisifier-js/blob/xpack/LICENSE)
[](https://standardjs.com/)
[](https://travis-ci.org/xpack/es6-promisifier-js)
[](https://ci.appveyor.com/project/ilg-ul/es6-promisifier-js)
## 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](https://nodejs.org) (>7.x), since the ECMAScript 6
class syntax is used.
## Easy install
The module is available as
[`@ilg/es6-promisifier`](https://www.npmjs.com/package/@ilg/es6-promisifier)
from the public repository, use `npm` to install it inside the module
where it is needed:
```bash
$ 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`](https://github.com/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.
```javascript
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
```console
$ git clone https://github.com/xpack/es6-promisifier-js.git es6-promisifier-js.git
$ cd es6-promisifier-js.git
$ npm install
```
```console
$ sudo npm link
$ ls -l /usr/local/lib/node_modules/@ilg
```
or without sudo, on Windows or if installed in home folder:
```console
$ 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:
```console
$ npm link @ilg/es6-promisifier
```
### Tests
The tests use the [`node-tap`](http://www.node-tap.org) 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`:
```console
$ cd es6-promisifier-js.git
$ npm install
$ npm run test
```
A typical test result looks like:
```console
$ 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`:
```console
$ 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`:
```console
$ 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](https://travis-ci.org/xpack/es6-promisifier-js) and [AppVeyor](https://ci.appveyor.com/project/ilg-ul/es6-promisifier-js).
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](https://standardjs.com/),
automatically checked at each commit via Travis CI.
Known and accepted exceptions:
- none.
To manually fix compliance with the style guide (where possible):
```console
$ 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](http://usejsdoc.org) tags.
To enforce checking at file level, add the following comments right after
the `use strict`:
```js
'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](http://eslint.org).
### 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](https://opensource.org/licenses/MIT), with all rights reserved to
[Liviu Ionescu](https://github.com/ilg-ul).