any-promise - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0

package.json

 {
   "name": "any-promise",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Resolve any installed ES6 compatible promise",
   "main": "index.js",
+  "typings": "index.d.ts",
   "browser": {
@@ -10,3 +11,3 @@ "./register.js": "./register-shim.js"
   "scripts": {
-    "test": "mocha test/index.js"
+    "test": "ava"
   },
@@ -29,14 +30,18 @@ "repository": {
   "devDependencies": {
+    "ava": "^0.14.0",
     "bluebird": "^3.0.0",
     "es6-promise": "^3.0.0",
+    "is-promise": "^2.0.0",
+    "lie": "^3.0.0",
     "mocha": "^2.0.0",
     "native-promise-only": "^0.8.0",
-    "phantomjs-prebuilt": "^2.1.7",
+    "phantomjs-prebuilt": "^2.0.0",
+    "pinkie": "^2.0.0",
     "promise": "^7.0.0",
-    "promises-aplus-tests": "^2.0.0",
     "q": "^1.0.0",
     "rsvp": "^3.0.0",
+    "vow": "^0.4.0",
     "when": "^3.0.0",
-    "zuul": "^3.10.1"
+    "zuul": "^3.0.0"
   }
 }

README.md

@@ -5,30 +5,61 @@ ## Any Promise
 
-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.
+Let your library support any ES 2015 (ES6) compatible `Promise` and leave the choice to application authors. The application can *optionally* register its preferred `Promise` implementation and it will be exported when requiring `any-promise` from library code.
 
 If no preference is registered, defaults to the global `Promise` for newer Node.js versions. The browser version defaults to the window `Promise`, so polyfill or register as necessary.
 
-### Library Usage
+### Usage with global Promise:
 
-To use any `Promise` constructor, simply require it:
+Assuming the global `Promise` is the desired implementation:
 
+```bash
+# Install any libraries depending on any-promise
+$ npm install mz
+```
+
+The installed libraries will use global Promise by default.
+
+```js
+// in library
+var Promise = require('any-promise')  // the global Promise
+
+function promiseReturningFunction(){
+    return new Promise(function(resolve, reject){...})
+}
+```
+
+### Usage with registration:
+
+Assuming `bluebird` is the desired Promise implementation:
+
+```bash
+# Install preferred promise library
+$ npm install bluebird
+# Install any-promise to allow registration
+$ npm install any-promise
+# Install any libraries you would like to use depending on any-promise
+$ npm install mz
+```
+
+Register your preference in the application entry point before any other `require` of packages that load `any-promise`:
+
 ```javascript
-var Promise = require('any-promise');
+// top of application index.js or other entry point
+require('any-promise/register/bluebird')
 
-return Promise
-  .all([xf, f, init, coll])
-  .then(fn);
+// -or- Equivalent to above, but allows customization of Promise library
+require('any-promise/register')('bluebird', {Promise: require('bluebird')})
+```
 
+Now that the implementation is registered, you can use any package depending on `any-promise`:
 
-return new Promise(function(resolve, reject){
-  try {
-    resolve(item);
-  } catch(e){
-    reject(e);
-  }
-});
 
+```javascript
+var fsp = require('mz/fs') // mz/fs will use registered bluebird promises
+var Promise = require('any-promise')  // the registered bluebird promise 
 ```
 
-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 application author.  Libraries should never call `register`, only the application user should call if desired.
+It is safe to call `register` multiple times, but it must always be with the same implementation.
 
+Again, registration is *optional*. It should only be called by the application user if overriding the global `Promise` implementation is desired.
+
 ### Optional Application Registration
@@ -38,14 +69,35 @@
 
+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 shortcuts
+
+If you are using a known `Promise` implementation, you can register your preference with a shortcut:
+
+
+```js
+require('any-promise/register/bluebird')
+// -or-
+import 'any-promise/register/q';
+```
+
+Shortcut registration is the preferred registration method as it works in the browser and Node.js. It is also convenient for using with `import` and many test runners, that offer a `--require` flag:
+
+```
+$ ava --require=any-promise/register/bluebird test.js
+```
+
+Current known implementations include `bluebird`, `q`, `when`, `rsvp`, `es6-promise`, `promise`, `native-promise-only`, `pinkie`, `vow` and `lie`. If you are not using a known implementation, you can use another registration method described below.
+
+
+#### Basic Registration
+
+As an alternative to registration shortcuts, you can call the `register` function with the preferred `Promise` implementation. The benefit of this approach is that a `Promise` library can be required by name without being a known implementation.  This approach does NOT work in the browser. To use `any-promise` in the browser use either registration shortcuts or specify the `Promise` constructor using advanced registration (see below).
+
 ```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')
+require('any-promise/register')('when')
+// -or- require('any-promise/register')('any other ES6 compatible library (known or otherwise)')
 ```
-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.
+This registration method will try to detect the `Promise` constructor from requiring the specified implementation.  If you would like to specify your own constructor, see advanced registration.
 
@@ -70,37 +122,28 @@
 
-#### Example:
+### Library Usage
 
-Assuming `when` is the desired Promise implementation:
+To use any `Promise` constructor, simply require it:
 
-```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 mz
-```
-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')
+var Promise = require('any-promise');
 
-// -or- Equivalent to above in Node.js, but browser version needs polyfill or explicit registration
-require('any-promise/register')('when', {Promise: require('when').Promise})
-```
+return Promise
+  .all([xf, f, init, coll])
+  .then(fn);
 
-Now that the implementation is registered, you can use any package depending on `any-promise`:
 
+return new Promise(function(resolve, reject){
+  try {
+    resolve(item);
+  } catch(e){
+    reject(e);
+  }
+});
 
-```javascript
-var fsp = require('mz/fs') // mz/fs will use registered `when` promises
-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.
+Except noted below, 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 application author.  Libraries should never call `register`, only the application user should call if desired.
 
-Again, registration is not required. It should only be called by the application user if overriding the default implementation is desired.
 
-### Advanced Library Usage
+#### Advanced Library Usage
 
@@ -117,1 +160,6 @@ 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.
 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.
+
+### Related
+
+- [any-observable](https://github.com/sindresorhus/any-observable) - `any-promise` for Observables.
+

register-shim.js

@@ -12,3 +12,3 @@ "use strict";
     throw new Error("any-promise browser requires a polyfill or explicit registration"+
-      " e.g: require('any-promise/register')('bluebird', {Promise: require('bluebird')})")
+      " e.g: require('any-promise/register/bluebird')")
   }
@@ -15,0 +15,0 @@ return {

register.js

@@ -40,3 +40,3 @@ "use strict"
       ' require("any-promise/register") with your preferred'+
-      ' implementation, e.g. require("any-promise/register")("bluebird")'+
+      ' implementation, e.g. require("any-promise/register/bluebird")'+
       ' on application load prior to any require("any-promise").')
@@ -84,3 +84,6 @@ }
       "when",
-      "q"]
+      "q",
+      "pinkie",
+      "lie",
+      "vow"]
   var i = 0, len = libs.length
@@ -87,0 +90,0 @@ for(; i < len; i++){

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

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

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

Improved metrics

Total package byte prevSize

22195

increased by61.83%

Number of package files

34

increased by240%

Lines of code

297

increased by69.71%

Number of lines in readme file

162

increased by42.11%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

15

increased by36.36%

No dependency changes