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.

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 { defineConfig } from "eslint/config";

export default defineConfig(
  {
    plugins: {
      complete: ESLintPluginComplete,
    },
  },

  ...ESLintPluginComplete.configs.recommended,
);

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

// @ts-check

import ESLintPluginComplete from "eslint-plugin-complete";
import { defineConfig } from "eslint/config";

export default defineConfig({
  plugins: {
    complete: ESLintPluginComplete,
  },

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

Note that if you get type errors, you have have to use a @ts-expect-error directive, due to bugs in the upstream package.

Configs

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

Rules

💼 Configurations enabled in.
🚫 Configurations disabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
💭 Requires type information.

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