Skip to main content

eslint-plugin-complete

npm version

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 it 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
NameDescription🔧💭
complete/complete-sentences-jsdocRequires complete sentences for JSDoc comments
complete/complete-sentences-line-commentsRequires complete sentences for multi-line leading line comments
complete/consistent-enum-valuesRequires consistent enum values
complete/consistent-named-tuplesRequires that if one or more tuple elements are named, all of them are named
complete/eqeqeq-fixRequires the use of === and !== (and automatically fixes)🔧
complete/format-jsdoc-commentsDisallows /** comments longer than N characters and multi-line comments that can be merged together🔧
complete/format-line-commentsDisallows // comments longer than N characters and multi-line comments that can be merged together🔧
complete/jsdoc-code-block-languageRequires a language specification for every JSDoc code block
complete/newline-between-switch-caseRequires newlines between switch cases🔧
complete/no-confusing-set-methodsDisallows confusing methods for sets💭
complete/no-empty-jsdocDisallows empty JSDoc comments🔧
complete/no-empty-line-commentsDisallows empty line comments🔧
complete/no-explicit-array-loopsDisallows explicit iteration for arrays🔧💭
complete/no-explicit-map-set-loopsDisallows explicit iteration for maps and sets🔧💭
complete/no-for-inDisallows "for x in y" statements
complete/no-let-anyDisallows declaring variables with let that do not have a type💭
complete/no-mutable-returnDisallows returning mutable arrays, maps, and sets from functions💭
complete/no-number-enumsDisallows number enums
complete/no-object-anyDisallows declaring objects and arrays that do not have a type💭
complete/no-object-methods-with-map-setDisallows using object methods with maps and sets💭
complete/no-string-length-0Disallows checking for empty strings via the length method in favor of direct comparison to an empty string💭
complete/no-template-curly-in-string-fixDisallows template literal placeholder syntax in regular strings (and automatically fixes)🔧
complete/no-undefined-return-typeDisallows undefined return types on functions💭
complete/no-unnecessary-assignmentDisallows useless assignments💭
complete/no-unsafe-plusplusDisallow unsafe and confusing uses of the "++" and "--" operators💭
complete/no-useless-returnDisallow redundant return statements (with no auto-fixer)
complete/no-void-return-typeDisallows void return types on non-exported functions🔧
complete/prefer-constRequire const declarations for variables that are never reassigned after declared (with no auto-fixer)
complete/prefer-plusplusRequire "++" or "--" operators instead of assignment operators where applicable🔧
complete/prefer-postfix-plusplusRequire "i++" instead of "++i"💭
complete/prefer-readonly-parameter-typesRequire function parameters to be typed as readonly to prevent accidental mutation of inputs💭
complete/require-breakRequires that each case of a switch statement has a break statement
complete/require-capital-const-assertionsRequires a capital letter for named objects and arrays that have a const assertion🔧
complete/require-capital-read-onlyRequires maps/sets/arrays with a capital letter to be read-only💭
complete/require-unannotated-const-assertionsDisallows explicit type annotations for variables that have a const assertion
complete/require-variadic-function-argumentRequires that variadic functions must be supplied with at least one argument💭
complete/strict-array-methodsRequires boolean return types on array method functions💭
complete/strict-enumsDisallows the usage of unsafe enum patterns💭
complete/strict-undefined-functionsDisallows empty return statements in functions annotated as returning undefined💭
complete/strict-void-functionsDisallows 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.