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.
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.
Application Registration
As an application author, you can optionally register a preferred Promise
implementation on application startup (before any call to require('any-promise')
:
require('any-promise/register')('bluebird')
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
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:
$ npm install when
$ npm install any-promise
$ npm install mz
$ npm dedupe
Register your preference in the application entry point before any other require
of packages that load any-promise
:
require('any-promise/register')('when')
Now that the implementation is registered, you can use any package depending on any-promise
:
var fsp = require('fs-promise')
var Promise = require('any-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 functions as there is no guarantee which implementation will be chosen by the end user.
var Promise = require('any-promise');
return Promise
.all([xf, f, init, coll])
.then(fn);
return new Promise(function(resolve, reject){
try {
resolve(item);
} catch(e){
reject(e);
}
});
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.