eslint-plugin-promise

What is eslint-plugin-promise?

The eslint-plugin-promise package is an ESLint plugin that enforces best practices and common idioms for dealing with promises in JavaScript. It provides a set of rules that catch common mistakes and enforce conventions when working with promises.

What are eslint-plugin-promise's main functionalities?

Avoiding creation of new promises outside of utility libraries

This rule ensures that the executor function of a new Promise has the parameters named 'resolve' and 'reject'.

/* eslint promise/param-names: 'error' */
new Promise((resolve, reject) => { /* executor function */ });

Ensuring that each time a then() is applied to a promise, a catch() is applied as well

This rule enforces the use of catch() on unhandled promises.

/* eslint promise/catch-or-return: 'error' */
promise.then(function(data) {
  // handle data
}).catch(function(error) {
  // handle error
});

Enforcing the return of a promise in certain contexts

This rule ensures that promise chains always return a value, preventing silent failures and unhandled rejections.

/* eslint promise/always-return: 'error' */
function foo() {
  return doSomething().then(function() {
    // do something else
    return 'result';
  });
}

Other packages similar to eslint-plugin-promise

eslint-plugin-async-await

This plugin provides ESLint rules for async/await syntax, which is related to promises. It helps to enforce best practices and catch common mistakes when using async/await, but it does not focus on promises directly.

eslint-plugin-standard

Part of the 'eslint-plugin-standard' plugin includes rules that are applicable to promises, as it adheres to the JavaScript Standard Style. However, it covers a broader range of JavaScript features and is not solely focused on promises.

README

eslint-plugin-promise

Enforce best practices for JavaScript promises.

• Installation
• Usage
• Rules
• Maintainers
• License

Installation

You'll first need to install ESLint:

npm install 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.

Usage

Add promise to the plugins section of your .eslintrc.json 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-new-statics": "error",
    "promise/no-return-in-finally": "warn",
    "promise/valid-params": "warn",
    "promise/no-multiple-resolved": "error"
  }
}

or start with the recommended rule set:

• eslint.config.js:

  import pluginPromise from 'eslint-plugin-promise'
  export default [
    // ...
    pluginPromise.configs['flat/recommended'],
  ]
  

• .eslintrc.*:

  {
    "extends": ["plugin:promise/recommended"]
  }
  

Rules

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
🚫 Configurations disabled in.
✅ Set in the flat/recommended configuration.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.

Name	Description	💼	⚠️	🚫	🔧
always-return	Require returning inside each then() to create readable and reusable Promise chains.	✅
avoid-new	Disallow creating new promises outside of utility libs (use util.promisify instead).			✅
catch-or-return	Enforce the use of catch() on un-returned promises.	✅
no-callback-in-promise	Disallow calling cb() inside of a then() (use util.callbackify instead).		✅
no-multiple-resolved	Disallow creating new promises with paths that resolve multiple times.
no-native	Require creating a Promise constructor before using it in an ES5 environment.			✅
no-nesting	Disallow nested then() or catch() statements.		✅
no-new-statics	Disallow calling new on a Promise static method.	✅			🔧
no-promise-in-callback	Disallow using promises inside of callbacks.		✅
no-return-in-finally	Disallow return statements in finally().		✅
no-return-wrap	Disallow wrapping values in Promise.resolve or Promise.reject when not needed.	✅
param-names	Enforce consistent param names and ordering when creating new promises.	✅
prefer-await-to-callbacks	Prefer async/await to the callback pattern.
prefer-await-to-then	Prefer await to then()/catch()/finally() for reading Promise values.
prefer-catch	Prefer catch to then(a, b)/then(null, b) for handling errors.				🔧
spec-only	Disallow use of non-standard Promise static methods.
valid-params	Enforces the proper number of arguments are passed to Promise functions.		✅

Maintainers

• Jamund Ferguson - @xjamundx
• Macklin Underdown - @macklinu
• Aadit M Shah - @aaditmshah

License

• (c) MMXV jden mailto:[e-mail] - ISC license.
• (c) 2016 Jamund Ferguson mailto:[e-mail] - ISC license.

Changelog

7.2.1 (2024-11-26)

🩹 Fixes

• no-callback-in-promise: false triggering of callback (#574) (8324564)

🧹 Chores

• deps-dev: update husky to v9.1.7 (#573) (24fd90a)
• deps: bump cross-spawn from 7.0.3 to 7.0.6 (#568) (f33f82e)