Enforce best practices for JavaScript promises.
You'll first need to install ESLint:
$ npm i eslint --save-dev
Next, install eslint-plugin-promise
:
$ npm install eslint-plugin-promise --save-dev
Note: If you installed ESLint globally (using the -g
flag) then you must also install eslint-plugin-promise
globally.
Add promise
to the plugins section of your .eslintrc
configuration file. You can omit the eslint-plugin-
prefix:
{ "plugins": [ "promise" ] }
Then configure the rules you want to use under the rules section.
{ "rules": { "promise/always-return": "error", "promise/no-return-wrap": "error", "promise/param-names": "error", "promise/catch-or-return": "error", "promise/no-native": "off", "promise/no-nesting": "warn", "promise/no-promise-in-callback": "warn", "promise/no-callback-in-promise": "warn", "promise/avoid-new": "warn", "promise/no-return-in-finally": "warn" } }
or start with the recommended rule set
{ "extends": [ "plugin:promise/recommended" ] }
recommended | rule | description |
---|---|---|
:bangbang: | catch-or-return | Enforces the use of catch() on un-returned promises. |
:bangbang: | no-return-wrap | Avoid wrapping values in Promise.resolve or Promise.reject when not needed. |
:bangbang: | param-names | Enforce consistent param names when creating new promises. |
:bangbang: | always-return | Return inside each then() to create readable and reusable Promise chains. |
no-native | In an ES5 environment, make sure to create a Promise constructor before using. | |
:warning: | no-nesting | Avoid nested then() or catch() statements |
:warning: | no-promise-in-callback | Avoid using promises inside of callbacks |
:warning: | no-callback-in-promise | Avoid calling cb() inside of a then() (use nodeify instead) |
:warning: | avoid-new | Avoid creating new promises outside of utility libs (use pify instead) |
:warning: | no-return-in-finally | Disallow return statements in finally() |
:seven: | prefer-await-to-then | Prefer await to then() for reading Promise values |
:seven: | prefer-await-to-callbacks | Prefer async/await to the callback pattern |
Key
icon | description |
---|---|
:bangbang: | Reports as error in recommended configuration |
:warning: | Reports as warning in recommended configuration |
:seven: | ES2017 Async Await rules |
catch-or-return
Ensure that each time a then()
is applied to a promise, a catch()
is applied as well. Exceptions are made if you are returning that promise.
myPromise.then(doSomething).catch(errors); myPromise.then(doSomething).then(doSomethingElse).catch(errors); function doSomethingElse() { return myPromise.then(doSomething) }
myPromise.then(doSomething); myPromise.then(doSomething, catchErrors); // catch() may be a little better function doSomethingElse() { myPromise.then(doSomething) }
allowThen
You can pass an { allowThen: true }
as an option to this rule to allow for .then(null, fn)
to be used instead of catch()
at the end of the promise chain.
terminationMethod
You can pass a { terminationMethod: 'done' }
as an option to this rule to require done()
instead of catch()
at the end of the promise chain. This is useful for many non-standard Promise implementations.
You can also pass an array of methods such as { terminationMethod: ['catch', 'asCallback', 'finally'] }
.
This will allow any of
Promise.resolve(1).then(() => { throw new Error('oops') }).catch(logerror) Promise.resolve(1).then(() => { throw new Error('oops') }).asCallback(cb) Promise.resolve(1).then(() => { throw new Error('oops') }).finally(cleanUp)
always-return
Ensure that inside a then()
you make sure to return
a new promise or value. See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5) for more info on why that's a good idea.
We also allow someone to throw
inside a then()
which is essentially the same as return Promise.reject()
.
myPromise.then((val) => val * 2)); myPromise.then(function(val) { return val * 2; }); myPromise.then(doSomething); // could be either myPromise.then((b) => { if (b) { return "yes" } else { return "no" } });
myPromise.then(function(val) {}); myPromise.then(() => { doSomething(); }); myPromise.then((b) => { if (b) { return "yes" } else { forgotToReturn(); } });
param-names
Enforce standard parameter names for Promise constructors
new Promise(function (resolve) { ... }) new Promise(function (resolve, reject) { ... })
new Promise(function (reject, resolve) { ... }) // incorrect order new Promise(function (ok, fail) { ... }) // non-standard parameter names
Ensures that new Promise()
is instantiated with the parameter names resolve, reject
to avoid confusion with order such as reject, resolve
. The Promise constructor uses the RevealingConstructor pattern. Using the same parameter names as the language specification makes code more uniform and easier to understand.
no-native
Ensure that Promise
is included fresh in each file instead of relying on the existence of a native promise implementation. Helpful if you want to use bluebird
or if you don't intend to use an ES6 Promise shim.
var Promise = require("bluebird"); var x = Promise.resolve("good");
var x = Promise.resolve("bad");
no-return-wrap
Ensure that inside a then()
or a catch()
we always return
or throw
a raw value instead of wrapping in Promise.resolve
or Promise.reject
myPromise.then(function(val) { return val * 2; }); myPromise.then(function(val) { throw "bad thing"; });
myPromise.then(function(val) { return Promise.resolve(val * 2); }); myPromise.then(function(val) { return Promise.reject("bad thing"); })
allowReject
Pass { allowReject: true }
as an option to this rule to permit wrapping returned values with Promise.reject
, such as when you would use it as another way to reject the promise.
no-return-in-finally
Disallow return statements inside a callback passed to finally()
, since nothing would consume what's returned.
myPromise.finally(function(val) { console.log('value:', val); });
myPromise.finally(function(val) { return val; })