An ESLint plugin to disable mutation and promote functional programming in JavaScript and TypeScript.
👋 If you previously used the rules in tslint-immutable, this package is the eslint version of those rules. Please see the migration guide for how to migrate.
One aim of this project is to leverage the type system in TypeScript to enforce immutability at compile-time while still using regular objects and arrays. Additionally, this project will also aim to support disabling mutability for vanilla JavaScript where possible.
JavaScript is multi-paradigm, allowing both object-oriented and functional programming styles. In order to promote a functional style, the object oriented features of JavaScript need to be disabled.
In functional programming everything is an expression that produces a value. Javascript has a lot of syntax that is just statements that does not produce a value. That syntax has to be disabled to promote a functional style.
Functional programming style does not use run-time exceptions. Instead expressions produces values to indicate errors.
Javascript functions support syntax that is not compatible with curried functions. To enable currying this syntax has to be disabled.
# Install with npm
npm install eslint eslint-plugin-functional --save-dev
# Install with yarn
yarn add -D eslint eslint-plugin-functionalNote: If you installed ESLint globally (using the -g flag with npm or global with yarn) then you must also install eslint-plugin-functional globally.
To use this plugin with TypeScript, a TypeScript parser for eslint is needed. We recommend @typescript-eslint/parser.
# Install with npm
npm install eslint @typescript-eslint/parser eslint-plugin-functional --save-dev
# Install with yarn
yarn add -D eslint @typescript-eslint/parser eslint-plugin-functionalAdd functional to the plugins section of your .eslintrc configuration file. Then configure the rules you want to use under the rules section.
{
"plugins": ["functional"],
"rules": {
"functional/rule-name": "error"
}
}There are several rulesets provided by this plugin.
See below for what they are and what rules are including in each.
Enable rulesets via the "extends" property of your .eslintrc configuration file.
{
// ...
"extends": [
"plugin:functional/external-recommended",
"plugin:functional/recommended"
]
}Add @typescript-eslint/parser to the "parser" filed in your .eslintrc configuration file.
To use type information, you will need to specify a path to your tsconfig.json file in the "project" property of "parserOptions".
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "./tsconfig.json"
}
}See @typescript-eslint/parser's README.md for more information on the available parser options.
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "tsconfig.json"
},
"env": {
"es6": true
},
"plugins": [
"@typescript-eslint",
"functional"
],
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/eslint-recommended",
"plugin:@typescript-eslint/recommended",
"plugin:@typescript-eslint/recommended-requiring-type-checking",
"plugin:functional/external-recommended",
"plugin:functional/recommended"
]
}The following rulesets are made available by this plugin:
Presets:
- Recommended (plugin:functional/recommended)
- Lite (plugin:functional/lite)
Categorized:
- No Mutations (plugin:functional/no-mutations)
- No Object Orientation (plugin:functional/no-object-orientation)
- No Statements (plugin:functional/no-statements)
- No Exceptions (plugin:functional/no-exceptions)
- Currying (plugin:functional/currying)
Other:
- All (plugin:functional/all) - Enables all rules defined in this plugin.
- External Recommended (plugin:functional/external-recommended) - Configures recommended rules not defined by this plugin.
The below section gives details on which rules are enabled by each ruleset.
Key:
| Symbol | Meaning |
|---|---|
| 🙉 | Ruleset: Lite This ruleset is designed to enforce a somewhat functional programming code style. |
| 🙊 | Ruleset: Recommended This ruleset is designed to enforce a functional programming code style. |
| 🔧 | Fixable Problems found by this rule are potentially fixable with the --fix option. |
| 💭 | Only Avaliable for TypeScript The rule either requires Type Information or only works with TypeScript syntax. |
| 💙 | Works better with TypeScript Type Information will be used if available making the rule work in more cases. |
🙈 = no-mutations Ruleset.
| Name | Description | 🙈 | 🙉 | 🙊 | 🔧 | 💙 |
|---|---|---|---|---|---|---|
immutable-data |
Disallow mutating objects and arrays | ✔️ | ✔️ | ✔️ | 💙 | |
no-let |
Disallow mutable variables | ✔️ | ✔️ | ✔️ | ||
no-method-signature |
Enforce property signatures with readonly modifiers over method signatures | ✔️ | ✔️ | ✔️ | 💭 | |
prefer-readonly-type |
Use readonly types and readonly modifiers where possible | ✔️ | ✔️ | ✔️ | 🔧 | 💭 |
🙈 = no-object-orientation Ruleset.
| Name | Description | 🙈 | 🙉 | 🙊 | 🔧 | 💙 |
|---|---|---|---|---|---|---|
no-class |
Disallow classes | ✔️ | ✔️ | ✔️ | ||
no-mixed-type |
Restrict types so that only members of the same kind are allowed in them | ✔️ | ✔️ | ✔️ | 💭 | |
no-this-expression |
Disallow this access |
✔️ | ✔️ | ✔️ | ||
prefer-type-literal |
Use type literals over interfaces | ✔️ | ✔️ | ✔️ | 💭 |
🙈 = no-statements Ruleset.
| Name | Description | 🙈 | 🙉 | 🙊 | 🔧 | 💙 |
|---|---|---|---|---|---|---|
no-conditional-statement |
Disallow conditional statements (if and switch statements) | ✔️ | ✔️ | |||
no-expression-statement |
Disallow expressions to cause side-effects | ✔️ | ✔️ | |||
no-loop-statement |
Disallow imperative loops | ✔️ | ✔️ | ✔️ | ||
no-return-void |
Disallow functions that return nothing | ✔️ | ✔️ | ✔️ | 💭 |
🙈 = no-exceptions Ruleset.
| Name | Description | 🙈 | 🙉 | 🙊 | 🔧 | 💙 |
|---|---|---|---|---|---|---|
no-promise-reject |
Disallow rejecting Promises | |||||
no-throw-statement |
Disallow throwing exceptions | ✔️ | ✔️ | ✔️ | ||
no-try-statement |
Disallow try-catch[-finally] and try-finally patterns | ✔️ | ✔️ |
🙈 = currying Ruleset.
| Name | Description | 🙈 | 🙉 | 🙊 | 🔧 | 💙 |
|---|---|---|---|---|---|---|
functional-parameters |
Functions must have functional parameters | ✔️ | ✔️ | ✔️ |
In addition to the immutability rules above, there are a few standard rules that need to be enabled to achieve immutability.
These rules are all included in the external-recommended rulesets.
Without this rule, it is still possible to create var variables that are mutable.
Without this rule, function parameters are mutable.
This rule is helpful when converting from an imperative code style to a functional one.
For performance reasons, eslint-plugin-functional does not check implicit return types. So for example this function will return a mutable array but will not be detected:
function foo() {
return [1, 2, 3];
}To avoid this situation you can enable @typescript-eslint/explicit-function-return-type. Now the above function is forced to declare the return type and the mutability will be detected.
For new features file an issue. For bugs, file an issue and optionally file a PR with a failing test.
To execute the tests run yarn test.
To learn about eslint plugin development see the relevant section of the eslint docs. You can also checkout the typescript-eslint repo which has some more information specific to typescript.
In order to know which AST nodes are created for a snippet of TypeScript code you can use ast explorer with options JavaScript and @typescript-eslint/parser.
yarn version --patch
yarn version --minor
yarn version --major
This project started off as a port of tslint-immutable which was originally inspired by eslint-plugin-immutable.