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. For example, if you use the npm package manager:

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(...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 a bug in typescript-eslint.

Configs

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

Rules

💼 Configurations enabled 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-object-braces	Requires object brace spacing to match the property count	✅	🔧
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-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-redundant-jsdoc-default	Disallows setting object properties to their JSDoc default values	✅		💭
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-is-array	Requires using the complete-common isArray helper instead of Array.isArray	✅	🔧
prefer-path-resolve	Disallows the path.join method with a parent directory segment	✅	🔧
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	✅		💭
prefer-unknown-type-annotations	Require variable type annotations over as unknown assertions	✅	🔧
require-ascii	Require code and comments to only contain ASCII characters	✅
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	✅		💭
sort-destructured-properties	Requires destructured object properties to match the declared type order	✅	🔧	💭
sort-objects	Requires object properties to match the declared type order or alphabetical order	✅	🔧	💭
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	✅
type-declaration-immutability	Enforces that interfaces are immutable	✅		💭

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 Visual Studio Code, 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.