eslint-plugin-isaacscript

eslint-plugin-isaacscript

eslint-plugin-isaacscript is a collection of miscellaneous ESLint rules that can help make your JavaScript/TypeScript code more safe or more strict.

This plugin is named after (and used in) the IsaacScript framework. But you don't have to know anything about IsaacScript to use it - you can use these rules with any JavaScript/TypeScript project.

Alternatively, if you want to get off the ground and running with ESLint + TypeScript in a new project, then you should check out the isaacscript-lint meta-package.

This project is written in TypeScript.

Install / Usage

• npm install --save-dev eslint eslint-plugin-isaacscript
• Add "plugin:isaacscript/recommended" to the extends section of your .eslintrc.cjs file. (This will automatically add the plugin and add all of the recommended rules.)
  • Alternatively, if you want to only enable some specific rules, then add "isaacscript" to the plugins section of your .eslintrc.cjs file, and then add the specific rules that you want in the rules section.

Configs

• recommended - Enables just the recommended rules. (Some rules are not recommended since they are intended for very specific environments.)

Rules

Each rule has emojis denoting:

• :white_check_mark: - if it belongs to the recommended configuration
• :wrench: - if some problems reported by the rule are automatically fixable by the --fix command line option
• :thought_balloon: - if it requires type information

Name	Description	:white_check_mark:	:wrench:	:thought_balloon:
isaacscript/complete-sentences-jsdoc	Requires complete sentences for JSDoc comments	:white_check_mark:
isaacscript/complete-sentences-line-comments	Requires complete sentences for multi-line leading line comments	:white_check_mark:
isaacscript/consistent-enum-values	Requires consistent enum values	:white_check_mark:
isaacscript/enum-member-number-separation	Disallows numbers next to letters in enum members
isaacscript/eqeqeq-fix	Requires the use of === and !== (and automatically fixes)	:white_check_mark:	:wrench:
isaacscript/format-jsdoc-comments	Disallows /** comments longer than N characters and multi-line comments that can be merged together	:white_check_mark:	:wrench:
isaacscript/format-line-comments	Disallows // comments longer than N characters and multi-line comments that can be merged together	:white_check_mark:	:wrench:
isaacscript/jsdoc-code-block-language	Requires a language specification for every JSDoc code block	:white_check_mark:
isaacscript/newline-between-switch-case	Requires newlines between switch cases	:white_check_mark:	:wrench:
isaacscript/no-confusing-set-methods	Disallows confusing methods for sets	:white_check_mark:		:thought_balloon:
isaacscript/no-empty-jsdoc	Disallows empty JSDoc comments	:white_check_mark:	:wrench:
isaacscript/no-empty-line-comments	Disallows empty line comments	:white_check_mark:	:wrench:
isaacscript/no-explicit-array-loops	Disallows explicit iteration for arrays	:white_check_mark:	:wrench:	:thought_balloon:
isaacscript/no-explicit-map-set-loops	Disallows explicit iteration for maps and sets	:white_check_mark:	:wrench:	:thought_balloon:
isaacscript/no-for-in	Disallows "for x in y" statements	:white_check_mark:
isaacscript/no-invalid-default-map	Disallows invalid constructors for the DefaultMap class			:thought_balloon:
isaacscript/no-let-any	Disallows declaring variables with let that do not have a type	:white_check_mark:		:thought_balloon:
isaacscript/no-mutable-return	Disallows returning mutable arrays, maps, and sets from functions	:white_check_mark:		:thought_balloon:
isaacscript/no-number-enums	Disallows number enums	:white_check_mark:
isaacscript/no-object-any	Disallows declaring objects and arrays that do not have a type	:white_check_mark:		:thought_balloon:
isaacscript/no-object-methods-with-map-set	Disallows using object methods with maps and sets	:white_check_mark:		:thought_balloon:
isaacscript/no-string-length-0	Disallows checking for empty strings via the length method in favor of direct comparison to an empty string	:white_check_mark:		:thought_balloon:
isaacscript/no-template-curly-in-string-fix	Disallows template literal placeholder syntax in regular strings (and automatically fixes)	:white_check_mark:	:wrench:
isaacscript/no-throw	Disallows the usage of "throw"			:thought_balloon:
isaacscript/no-undefined-return-type	Disallows undefined return types on functions	:white_check_mark:		:thought_balloon:
isaacscript/no-unsafe-plusplus	Disallow unsafe and confusing uses of the "++" and "--" operators	:white_check_mark:		:thought_balloon:
isaacscript/no-void-return-type	Disallows void return types on non-exported functions	:white_check_mark:	:wrench:
isaacscript/prefer-plusplus	Require "++" or "--" operators instead of assignment operators where applicable	:white_check_mark:	:wrench:
isaacscript/prefer-postfix-plusplus	Require "i++" instead of "++i"	:white_check_mark:		:thought_balloon:
isaacscript/prefer-readonly-parameter-types	Require function parameters to be typed as readonly to prevent accidental mutation of inputs	:white_check_mark:		:thought_balloon:
isaacscript/require-break	Requires that each case of a switch statement has a break statement	:white_check_mark:
isaacscript/require-capital-const-assertions	Requires a capital letter for named objects and arrays that have a const assertion	:white_check_mark:	:wrench:
isaacscript/require-capital-read-only	Requires maps/sets/arrays with a capital letter to be read-only	:white_check_mark:		:thought_balloon:
isaacscript/require-unannotated-const-assertions	Disallows explicit type annotations for variables that have a const assertion	:white_check_mark:
isaacscript/require-v-registration	Require variables named "v" to be registered with the save data manager			:thought_balloon:
isaacscript/require-variadic-function-argument	Requires that variadic functions must be supplied with at least one argument	:white_check_mark:		:thought_balloon:
isaacscript/strict-array-methods	Requires boolean return types on array method functions	:white_check_mark:		:thought_balloon:
isaacscript/strict-enums	Disallows the usage of unsafe enum patterns	:white_check_mark:		:thought_balloon:
isaacscript/strict-undefined-functions	Disallows empty return statements in functions annotated as returning undefined	:white_check_mark:		:thought_balloon:
isaacscript/strict-void-functions	Disallows non-empty return statements in functions annotated as returning void	:white_check_mark:

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 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]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "explicit"
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "editor.tabSize": 2
  },
  "[typescript]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "explicit"
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "editor.tabSize": 2
  }
}

Comment Formatting

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

Contributing

Thanks for helping out with this open-source project!

If you are adding a new rule, start by using the create-rule script to automate a few things:

npm run create-rule foo "This is a description of the foo rule."
git status # Show what the script did.

Additionally, You can contact me on Discord if you are doing a PR and have questions.