any-promise - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

package.json

 {
   "name": "any-promise",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Resolve any installed ES6 compatible promise",
-  "main": "any-promise.js",
-  "browser": "any-promise-shim.js",
+  "main": "index.js",
+  "browser": {
+    "./register.js": "./register-shim.js"
+  },
   "scripts": {
@@ -26,12 +28,12 @@ "test": "make test"
   "devDependencies": {
-    "promise": "~6.0.1",
-    "es6-promise": "~2.0.1",
-    "rsvp": "~3.0.16",
-    "bluebird": "~2.5.3",
-    "when": "~3.6.4",
-    "q": "~1.1.2",
-    "native-promise-only": "~0.7.6-a",
+    "promise": "~7.1.1",
+    "es6-promise": "~3.0.2",
+    "rsvp": "~3.1.0",
+    "bluebird": "~3.1.5",
+    "when": "~3.7.7",
+    "q": "~1.4.1",
+    "native-promise-only": "~0.8.1",
     "promises-aplus-tests": "~2.1.0",
-    "mocha": "~2.1.0"
+    "mocha": "~2.4.2"
   }
 }

README.md

@@ -5,19 +5,64 @@ ## Any Promise
 
-Let your library support any ES6 compatible Promise library or polyfill and leave the choice to the end user. The end user can install a polyfill or `npm install` their preference before using this library and the installed library will be automatically detected.
+Let your library support any ES 2015 (ES6) compatible `Promise` and leave the choice to application authors. The application can register its preferred `Promise` implementation and it will be exported when requiring `any-promise` from library code.
 
-Attempts to load libraries in the following order.  The first successful `require` will be exported.
+If no preference is registered, defaults to the global `Promise` for newer Node.js versions. The browser version will always export the global `Promise`, so polyfill as necessary.
 
-  - [es6-promise](https://github.com/jakearchibald/es6-promise)
-  - [promise](https://github.com/then/promise)
-  - [native-promise-only](https://github.com/getify/native-promise-only)
-  - [bluebird](https://github.com/petkaantonov/bluebird)
-  - [rsvp](https://github.com/tildeio/rsvp.js)
-  - [when](https://github.com/cujojs/when)
-  - [q](https://github.com/kriskowal/q)
+### Application Registration
 
-If no library is installed, attempts to export the global `Promise` (native or polyfill). The `browserify` version will always export the the global `Promise`, so polyfill as necessary.
+As an application author, you can optionally register a preferred `Promise` implementation on application startup (before any call to `require('any-promise')`:
 
-If you have multiple libraries installed (e.g. for testing), and would like to specify one you can use the `PROMISE_IMPL` env variable.
+```javascript
+require('any-promise/register')('bluebird')
+// -or- require('any-promise/register')('es6-promise')
+// -or- require('any-promise/register')('native-promise-only')
+// -or- require('any-promise/register')('rsvp')
+// -or- require('any-promise/register')('when')
+// -or- require('any-promise/register')('q')
+// -or- require('any-promise/register')('any other ES6 compatible library')
+```
 
+You must register your preference before any call to `require('any-promise')` (by you or required packages), and only one implementation can be registered. Typically, this registration would occur at the top of the application entry point.
+
+Registration is not required for Node.js version >= 0.12 as a native `Promise` implementation is included. If no preference is registered, the global `Promise` will be used.
+
+To ensure registration works correctly across all dependencies, it is necessary that only one `any-promise` package is installed in the dependency tree. To ensure this, you should use [`npm dedupe`](https://docs.npmjs.com/cli/dedupe) or manually remove any `any-promise` packages not at the top level of your application dependency tree.
+
+#### Example:
+
+Assuming `when` is the desired Promise implementation:
+
+```bash
+# Install preferred promise library
+$ npm install when
+# Install any-promise to allow registration
+$ npm install any-promise
+# Install any libraries you would like to use depending on any-promise
+$ npm install fs-promise
+# Remove potentially duplicated `any-promise` packages
+$ npm dedupe
+```
+Register your preference in the application entry point before any other `require` of packages that load `any-promise`:
+
 ```javascript
+// top of application index.js or other entry point
+require('any-promise/register')('when')
+```
+
+Now that the implementation is registered, you can use any package depending on `any-promise`:
+
+```javascript
+var fsp = require('fs-promise') // fs-promise will use `when` for promise implementations
+var Promise = require('any-promise')  // the registered `when.Promise`
+```
+
+It is safe to call `register` multiple times, but it must always be with the same implementation.
+
+Again, registration is not required. It should only be called by the application user if overriding the default implementation is desired.
+
+
+### Library Usage
+
+Libraries using `any-promise` should only use [documented](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) functions as there is no guarantee which implementation will be chosen by the end user.
+
+```javascript
 var Promise = require('any-promise');
@@ -39,1 +84,13 @@
 ```
+
+Libraries should never call `register`, only the application user should call if desired.
+
+If your library needs to branch code based on the registered implementation, you can retrieve it using `var impl = require('any-promise/implementation')`, where `impl` will be the package name (`"bluebird"`, `"when"`, etc.) if registered, `"global.Promise"` if using the global version on Node.js, or `"window.Promise"` if using the browser version. You should always include a default case, as there is no guarantee what package may be registered.
+
+### Support for old Node.js versions
+
+Node.js versions prior to `v0.12` may have contained buggy versions of the global `Promise`. For this reason, the global `Promise` is not loaded automatically for these old versions.  If using `any-promise` in Node.js versions versions `<= v0.12`, the user should register a desired implementation.
+
+If an implementation is not registered, `any-promise` will attempt to discover an installed `Promise` implementation.  If no implementation can be found, an error will be thrown on `require('any-promise')`.  While the auto-discovery usually avoids errors, it is non-deterministic. It is recommended that the user always register a preferred implementation for older Node.js versions.
+
+This auto-discovery is only available for Node.jS versions prior to `v0.12`. Any newer versions will always default to the global `Promise` implementation.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

11586

increased by182.72%

Number of package files

9

increased by28.57%

Lines of code

144

increased by336.36%

Number of lines in readme file

95

increased by150%

Number of low supply chain risk alerts

2

decreased by-33.33%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes