JSPM – @ilg/es6-promisifier@0.3.1

Package Exports

@ilg/es6-promisifier

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ilg/es6-promisifier) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

@ilg/es6-promisifier