@ilg/es6-promisifier

DEPRECATED: An ES6 promisifier wrapper

Usage no npm install needed!

<script type="module">
  import ilgEs6Promisifier from 'https://cdn.skypack.dev/@ilg/es6-promisifier';
</script>

README

npm (scoped) license Standard Travis AppVeyor

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.