ESLint Plugin for Promises

Common errors

• Error: Failed to load plugin 'promise' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-promise'

  cause The eslint-plugin-promise package was not installed or not installed correctly in the project.
  fix Run `npm install eslint-plugin-promise --save-dev` or `yarn add eslint-plugin-promise --dev`.

• ESLint couldn't find the plugin "promise". (While processing 'eslint.config.js')

  cause In ESLint's flat configuration, plugins must be explicitly imported and then mapped in the `plugins` object within your configuration.
  fix Ensure `import pluginPromise from 'eslint-plugin-promise';` is at the top of `eslint.config.js`, and the plugin is mapped in `plugins: { promise: pluginPromise }`.

• Definition for rule 'promise/always-return' was not found.

  cause The plugin is loaded, but ESLint cannot find the specified rule. This often happens if the plugin is not correctly associated with its rules.
  fix Verify that `plugins: { promise: pluginPromise }` is correctly defined in your flat config, or that `"plugins": ["promise"]` is in your `.eslintrc.*` and that the rule name is correctly prefixed (`promise/`).

Warnings

• breaking Version 7.0.0 updated Node.js and ESLint peer dependency versions to align with ESLint v9, which means Node.js versions prior to 18.18.0 and ESLint versions older than 7.0.0 are no longer officially supported.
  Fix: Upgrade Node.js to `^18.18.0 || ^20.9.0 || >=21.1.0` and ESLint to `^7.0.0 || ^8.0.0 || ^9.0.0`. For ESLint v9, use the flat configuration (`eslint.config.js`).
• gotcha The `prefer-await-to-then` rule, when used with the `strict` option, will disallow `.then()` or `.catch()` following `await` expressions, which can be useful for enforcing full `async/await` syntax but might break existing codebases using mixed patterns.
  Fix: If enabling `strict` mode for `prefer-await-to-then`, refactor code to use `try/catch` blocks for error handling with `await` instead of `.catch()`. Otherwise, disable the `strict` option if mixed `async/await` and promise chaining is acceptable.
• gotcha The `no-callback-in-promise` rule can sometimes trigger false positives, especially in complex scenarios or when using specific patterns that mimic callbacks but are not true anti-patterns for promises.
  Fix: Review affected code; if the rule is incorrectly flagging legitimate code, consider using the `timeoutsErr` option (`no-callback-in-promise": ["error", { "timeoutsErr": true }]`) or disable the rule for specific lines/files with ESLint comments if a false positive cannot be re-architected.
• breaking With the introduction of ESLint's flat configuration system (ESLint v9+), the way plugins are configured has changed. The `extends` property with `plugin:promise/recommended` in `.eslintrc.*` is for legacy configurations.
  Fix: For ESLint v9 and `eslint.config.js`, explicitly import the plugin (`import pluginPromise from 'eslint-plugin-promise'`) and use `pluginPromise.configs['flat/recommended']` within your configuration array. Ensure you also map the plugin in the `plugins` object for rule definitions.

Install

• npm install eslint-plugin-promise npm
• yarn add eslint-plugin-promise yarn
• pnpm add eslint-plugin-promise pnpm

Imports

• ESLint Flat Config

  import pluginPromise from 'eslint-plugin-promise';

  For use in `eslint.config.js` with ESLint's new flat configuration system (ESLint v9+).
• Legacy .eslintrc Configuration
  wrong:

  import { rules } from 'eslint-plugin-promise'

  correct:

  { "plugins": ["promise"] }

  In legacy `.eslintrc.*` files, plugins are referenced by their short name in the `plugins` array. The plugin is loaded by ESLint itself; direct JavaScript imports are not used for configuration.
• Recommended Ruleset (Legacy)

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

  Applies the plugin's recommended set of rules for common best practices in `.eslintrc.*`.
• Recommended Ruleset (Flat Config)

  pluginPromise.configs['flat/recommended']

  Utilizes the plugin's recommended flat configuration object, typically spread into the `export default []` array in `eslint.config.js`.

Quickstart

Demonstrates setting up `eslint-plugin-promise` in an `eslint.config.js` (flat config) file, including importing the plugin, applying its recommended rules, and illustrating some problematic promise patterns the plugin targets.

import pluginPromise from 'eslint-plugin-promise';
import globals from 'globals';

export default [
  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: {
        ...globals.node,
        ...globals.browser
      }
    },
    plugins: {
      promise: pluginPromise
    },
    rules: {
      ...pluginPromise.configs['flat/recommended'].rules,
      // Override or add specific rules
      'promise/always-return': 'error',
      'promise/no-nesting': 'warn',
      'promise/prefer-await-to-then': 'error'
    }
  }
];

// Example file: src/async.js
// async function fetchData() {
//   return fetch('/api/data')
//     .then(response => response.json())
//     .catch(error => console.error('Fetch error:', error));
// }
//
// const badPromise = new Promise(resolve => {
//   resolve('first');
//   resolve('second'); // Will be flagged by no-multiple-resolved
// });
//
// function processData(data, cb) {
//   Promise.resolve(data).then(() => {
//     cb(null, data); // Will be flagged by no-callback-in-promise
//   });
// }
//
// fetchData();