eslint-plugin-complete

Introduction

This is an ESLint plugin containing rules that can help make your TypeScript code more safe or more strict.

Install

Using complete-lint

This package is part of the complete-lint meta-linting package. If you want to enable a comprehensive ESLint config in your TypeScript project as quickly as possible, it is recommended that instead of consuming eslint-plugin-complete directly, you instead list complete-lint as a dependency, as that will install the plugin, the config, and other goodies. (However, complete-lint will not work with the pnpm package manager, since pnpm does not handle transitive dependencies properly.)

For installation instructions, see the complete-lint page.

Manually

If you do not want to use the complete-lint meta-package, then you can install this plugin manually:

npm install --save-dev eslint typescript eslint-plugin-complete

(eslint and typescript are peer-dependencies.)

Usage

If you are using eslint-config-complete, then this plugin is automatically enabled. Otherwise, you can manually enable this plugin and the recommended rules with the following "eslint.config.mjs" file:

// @ts-check

import ESLintPluginComplete from "eslint-plugin-complete";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    plugins: {
      complete: ESLintPluginComplete,
    },
  },

  ...ESLintPluginComplete.configs.recommended,
);

Alternative, you can omit the recommended config and just enable the specific rules that you need:

// @ts-check

import ESLintPluginComplete from "eslint-plugin-complete";
import tseslint from "typescript-eslint";

export default tseslint.config({
  plugins: {
    complete: ESLintPluginComplete,
  },

  rules: {
    "complete/no-let-any": "error",
  },
});

Configs

• recommended - Currently, every rule in this plugin is recommended.

Rules

Each rule has emojis denoting:

• ✅ - if it belongs to the recommended configuration
• 🔧 - if some problems reported by the rule are automatically fixable by the --fix command line option
• 💭 - if it requires type information

Name	Description	✅	🔧	💭
complete/complete-sentences-jsdoc	Requires complete sentences for JSDoc comments	✅
complete/complete-sentences-line-comments	Requires complete sentences for multi-line leading line comments	✅
complete/consistent-enum-values	Requires consistent enum values	✅
complete/consistent-named-tuples	Requires that if one or more tuple elements are named, all of them are named	✅
complete/eqeqeq-fix	Requires the use of === and !== (and automatically fixes)	✅	🔧
complete/format-jsdoc-comments	Disallows /** comments longer than N characters and multi-line comments that can be merged together	✅	🔧
complete/format-line-comments	Disallows // comments longer than N characters and multi-line comments that can be merged together	✅	🔧
complete/jsdoc-code-block-language	Requires a language specification for every JSDoc code block	✅
complete/newline-between-switch-case	Requires newlines between switch cases	✅	🔧
complete/no-confusing-set-methods	Disallows confusing methods for sets	✅		💭
complete/no-empty-jsdoc	Disallows empty JSDoc comments	✅	🔧
complete/no-empty-line-comments	Disallows empty line comments	✅	🔧
complete/no-explicit-array-loops	Disallows explicit iteration for arrays	✅	🔧	💭
complete/no-explicit-map-set-loops	Disallows explicit iteration for maps and sets	✅	🔧	💭
complete/no-for-in	Disallows "for x in y" statements	✅
complete/no-let-any	Disallows declaring variables with let that do not have a type	✅		💭
complete/no-mutable-return	Disallows returning mutable arrays, maps, and sets from functions	✅		💭
complete/no-number-enums	Disallows number enums	✅
complete/no-object-any	Disallows declaring objects and arrays that do not have a type	✅		💭
complete/no-object-methods-with-map-set	Disallows using object methods with maps and sets	✅		💭
complete/no-string-length-0	Disallows checking for empty strings via the length method in favor of direct comparison to an empty string	✅		💭
complete/no-template-curly-in-string-fix	Disallows template literal placeholder syntax in regular strings (and automatically fixes)	✅	🔧
complete/no-undefined-return-type	Disallows undefined return types on functions	✅		💭
complete/no-unnecessary-assignment	Disallows useless assignments	✅		💭
complete/no-unsafe-plusplus	Disallow unsafe and confusing uses of the "++" and "--" operators	✅		💭
complete/no-useless-return	Disallow redundant return statements (with no auto-fixer)	✅
complete/no-void-return-type	Disallows void return types on non-exported functions	✅	🔧
complete/prefer-const	Require const declarations for variables that are never reassigned after declared (with no auto-fixer)	✅
complete/prefer-plusplus	Require "++" or "--" operators instead of assignment operators where applicable	✅	🔧
complete/prefer-postfix-plusplus	Require "i++" instead of "++i"	✅		💭
complete/prefer-readonly-parameter-types	Require function parameters to be typed as readonly to prevent accidental mutation of inputs	✅		💭
complete/require-break	Requires that each case of a switch statement has a break statement	✅
complete/require-capital-const-assertions	Requires a capital letter for named objects and arrays that have a const assertion	✅	🔧
complete/require-capital-read-only	Requires maps/sets/arrays with a capital letter to be read-only	✅		💭
complete/require-unannotated-const-assertions	Disallows explicit type annotations for variables that have a const assertion	✅
complete/require-variadic-function-argument	Requires that variadic functions must be supplied with at least one argument	✅		💭
complete/strict-array-methods	Requires boolean return types on array method functions	✅		💭
complete/strict-enums	Disallows the usage of unsafe enum patterns	✅		💭
complete/strict-undefined-functions	Disallows empty return statements in functions annotated as returning undefined	✅		💭
complete/strict-void-functions	Disallows non-empty return statements in functions annotated as returning void	✅

Automatic Fixing

You probably already use Prettier, which is helpful to automatically format files. You probably even have your IDE set up to run Prettier every time your save a file. This kind of thing saves you a tremendous amount of time - you can type out a bunch of code completely unformatted, and then press Ctrl + s at the end to automatically fix everything. (Alternatively, you could press Ctrl + shift + f to format the file without saving it, but it's simpler to just use one hotkey for everything.)

In a similar way to Prettier, this ESLint plugin contains several rules that are designed to automatically apply whenever you save the file (like the complete/format-jsdoc-comments rule). These rules are "fixers", which are applied when ESLint is executed with the "--fix" flag. So, in the same way that you configure Prettier to run on save, you should also configure eslint --fix to run on save.

For example, if you use VSCode, and you have the Prettier and the ESLint extensions installed, you can add the following to your repository's .vscode/settings.json file:

{
  // Automatically run the formatter when certain files are saved.
  "[javascript][typescript][javascriptreact][typescriptreact]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "explicit",
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
  },
}

Comment Formatting

For a discussion around comments and the motivations for some of the comment rules in the plugin, see this page.