eslint-plugin-boolean-trap

ESLint rules that catch the boolean trap: bare true / false arguments that make call sites unreadable.

el.addEventListener('click', onClick, true); // what does true mean here?
render(data, false, true); // and which one is which?

el.addEventListener('click', onClick, { capture: true }); // ✅ obvious
render(data, { animate: false, force: true }); // ✅ obvious
render(data, /* animate= */ false, /* force= */ true); // ✅ labeled

Works with ESLint 9 and 10 (flat config), JavaScript and TypeScript.

Install

npm install --save-dev eslint-plugin-boolean-trap

Usage

// eslint.config.js
import booleanTrap from 'eslint-plugin-boolean-trap';

export default [
  booleanTrap.configs.recommended,
];

Or pick rules yourself:

import booleanTrap from 'eslint-plugin-boolean-trap';

export default [
  {
    plugins: { 'boolean-trap': booleanTrap },
    rules: {
      'boolean-trap/no-boolean-literal-args': ['error', { ignoreFunctions: ['classList.toggle'] }],
      'boolean-trap/no-boolean-params': 'warn',
    },
  },
];

For TypeScript files, use typescript-eslint's parser as usual. no-boolean-params then also reads boolean type annotations.

Rules

Rule	Description	recommended	strict
no-boolean-literal-args	Disallow passing boolean literals as positional arguments	✅	✅
no-boolean-params	Disallow positional boolean parameters in function signatures	✅	✅

Configs

Config	What it does
recommended	Both rules as errors. Single-argument calls like setVisible(true) and single-parameter functions are allowed.
strict	Both rules as errors, and single-argument calls and single-parameter functions are reported too.

Tests and assertions

Assertion libraries often take booleans positionally (assert.equal(actual, true)). Ignore them by name, or relax the rule for test files:

export default [
  booleanTrap.configs.recommended,
  {
    files: ['**/*.test.*'],
    rules: {
      'boolean-trap/no-boolean-literal-args': ['error', { ignoreFunctions: ['assert.*', 't.*'] }],
    },
  },
];

Why

A positional boolean hides its meaning at every call site. To understand fetchUser(id, true, false) you have to open the function definition. Options objects, named constants or separate functions (insert / upsert instead of save(item, overwrite)) make the intent readable where the call happens.

License

MIT © acus9345