|
1 | | -# Prevent TypeScript-specific constructs from being erroneously flagged as unused (no-unused-vars) |
| 1 | +# Disallow unused variables (no-unused-vars) |
2 | 2 |
|
3 | | -It ensures that TypeScript-specific constructs, such as implemented interfaces, are not erroneously flagged as unused. |
| 3 | +Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers. |
4 | 4 |
|
5 | | -## Configuration |
| 5 | +## Rule Details |
| 6 | + |
| 7 | +This rule is aimed at eliminating unused variables, functions, and parameters of functions. |
| 8 | + |
| 9 | +A variable is considered to be used if any of the following are true: |
| 10 | + |
| 11 | +- It represents a function that is called (`doSomething()`) |
| 12 | +- It is read (`var y = x`) |
| 13 | +- It is passed into a function as an argument (`doSomething(x)`) |
| 14 | +- It is read inside of a function that is passed to another function (`doSomething(function() { foo(); })`) |
| 15 | + |
| 16 | +A variable is _not_ considered to be used if it is only ever assigned to (`var x = 5`) or declared. |
| 17 | + |
| 18 | +Examples of **incorrect** code for this rule: |
| 19 | + |
| 20 | +```js |
| 21 | +/*eslint no-unused-vars: "error"*/ |
| 22 | +/*global some_unused_var*/ |
| 23 | + |
| 24 | +// It checks variables you have defined as global |
| 25 | +some_unused_var = 42; |
| 26 | + |
| 27 | +var x; |
| 28 | + |
| 29 | +// Write-only variables are not considered as used. |
| 30 | +var y = 10; |
| 31 | +y = 5; |
| 32 | + |
| 33 | +// A read for a modification of itself is not considered as used. |
| 34 | +var z = 0; |
| 35 | +z = z + 1; |
| 36 | + |
| 37 | +// By default, unused arguments cause warnings. |
| 38 | +(function(foo) { |
| 39 | + return 5; |
| 40 | +})(); |
| 41 | + |
| 42 | +// Unused recursive functions also cause warnings. |
| 43 | +function fact(n) { |
| 44 | + if (n < 2) return 1; |
| 45 | + return n * fact(n - 1); |
| 46 | +} |
| 47 | + |
| 48 | +// When a function definition destructures an array, unused entries from the array also cause warnings. |
| 49 | +function getY([x, y]) { |
| 50 | + return y; |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Examples of **correct** code for this rule: |
| 55 | + |
| 56 | +```js |
| 57 | +/*eslint no-unused-vars: "error"*/ |
| 58 | + |
| 59 | +var x = 10; |
| 60 | +alert(x); |
| 61 | + |
| 62 | +// foo is considered used here |
| 63 | +myFunc( |
| 64 | + function foo() { |
| 65 | + // ... |
| 66 | + }.bind(this) |
| 67 | +); |
| 68 | + |
| 69 | +(function(foo) { |
| 70 | + return foo; |
| 71 | +})(); |
| 72 | + |
| 73 | +var myFunc; |
| 74 | +myFunc = setTimeout(function() { |
| 75 | + // myFunc is considered used |
| 76 | + myFunc(); |
| 77 | +}, 50); |
| 78 | + |
| 79 | +// Only the second argument from the descructured array is used. |
| 80 | +function getY([, y]) { |
| 81 | + return y; |
| 82 | +} |
| 83 | +``` |
6 | 84 |
|
7 | | -**_This rule only has an effect when the `no-unused-vars` core rule is enabled._** |
| 85 | +### exported |
8 | 86 |
|
9 | | -See [the core ESLint docs](https://eslint.org/docs/rules/no-unused-vars) for how to configure the base `no-unused-vars` rule. |
| 87 | +In environments outside of CommonJS or ECMAScript modules, you may use `var` to create a global variable that may be used by other scripts. You can use the `/* exported variableName */` comment block to indicate that this variable is being exported and therefore should not be considered unused. |
10 | 88 |
|
11 | | -```JSON |
| 89 | +Note that `/* exported */` has no effect for any of the following: |
| 90 | + |
| 91 | +- when the environment is `node` or `commonjs` |
| 92 | +- when `parserOptions.sourceType` is `module` |
| 93 | +- when `ecmaFeatures.globalReturn` is `true` |
| 94 | + |
| 95 | +The line comment `// exported variableName` will not work as `exported` is not line-specific. |
| 96 | + |
| 97 | +Examples of **correct** code for `/* exported variableName */` operation: |
| 98 | + |
| 99 | +```js |
| 100 | +/* exported global_var */ |
| 101 | + |
| 102 | +var global_var = 42; |
| 103 | +``` |
| 104 | + |
| 105 | +## Options |
| 106 | + |
| 107 | +This rule takes one argument which can be a string or an object. The string settings are the same as those of the `vars` property (explained below). |
| 108 | + |
| 109 | +By default this rule is enabled with `all` option for variables and `after-used` for arguments. |
| 110 | + |
| 111 | +```CJSON |
12 | 112 | { |
13 | 113 | "rules": { |
14 | | - "no-unused-vars": "error", |
15 | | - "typescript/no-unused-vars": "error" |
| 114 | + // note you must disable the base rule as it can report incorrect errors |
| 115 | + "no-unused-vars": "off", |
| 116 | + "typescript/no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }] |
16 | 117 | } |
17 | 118 | } |
18 | 119 | ``` |
19 | 120 |
|
20 | | -## Rule Details |
| 121 | +### vars |
| 122 | + |
| 123 | +The `vars` option has two settings: |
| 124 | + |
| 125 | +- `all` checks all variables for usage, including those in the global scope. This is the default setting. |
| 126 | +- `local` checks only that locally-declared variables are used but will allow global variables to be unused. |
| 127 | + |
| 128 | +#### vars: local |
| 129 | + |
| 130 | +Examples of **correct** code for the `{ "vars": "local" }` option: |
| 131 | + |
| 132 | +```js |
| 133 | +/*eslint no-unused-vars: ["error", { "vars": "local" }]*/ |
| 134 | +/*global some_unused_var */ |
| 135 | + |
| 136 | +some_unused_var = 42; |
| 137 | +``` |
| 138 | + |
| 139 | +### varsIgnorePattern |
| 140 | + |
| 141 | +The `varsIgnorePattern` option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain `ignored` or `Ignored`. |
| 142 | + |
| 143 | +Examples of **correct** code for the `{ "varsIgnorePattern": "[iI]gnored" }` option: |
| 144 | + |
| 145 | +```js |
| 146 | +/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/ |
| 147 | + |
| 148 | +var firstVarIgnored = 1; |
| 149 | +var secondVar = 2; |
| 150 | +console.log(secondVar); |
| 151 | +``` |
| 152 | + |
| 153 | +### args |
21 | 154 |
|
22 | | -The following patterns are considered warnings: |
| 155 | +The `args` option has three settings: |
23 | 156 |
|
24 | | -```ts |
25 | | -interface Foo {} |
| 157 | +- `after-used` - unused positional arguments that occur before the last used argument will not be checked, but all named arguments and all positional arguments after the last used argument will be checked. |
| 158 | +- `all` - all named arguments must be used. |
| 159 | +- `none` - do not check arguments. |
| 160 | + |
| 161 | +#### args: after-used |
| 162 | + |
| 163 | +Examples of **incorrect** code for the default `{ "args": "after-used" }` option: |
| 164 | + |
| 165 | +```js |
| 166 | +/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/ |
| 167 | + |
| 168 | +// 2 errors, for the parameters after the last used parameter (bar) |
| 169 | +// "baz" is defined but never used |
| 170 | +// "qux" is defined but never used |
| 171 | +(function(foo, bar, baz, qux) { |
| 172 | + return bar; |
| 173 | +})(); |
| 174 | +``` |
| 175 | + |
| 176 | +Examples of **correct** code for the default `{ "args": "after-used" }` option: |
| 177 | + |
| 178 | +```js |
| 179 | +/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/ |
| 180 | + |
| 181 | +(function(foo, bar, baz, qux) { |
| 182 | + return qux; |
| 183 | +})(); |
| 184 | +``` |
| 185 | + |
| 186 | +#### args: all |
| 187 | + |
| 188 | +Examples of **incorrect** code for the `{ "args": "all" }` option: |
| 189 | + |
| 190 | +```js |
| 191 | +/*eslint no-unused-vars: ["error", { "args": "all" }]*/ |
| 192 | + |
| 193 | +// 2 errors |
| 194 | +// "foo" is defined but never used |
| 195 | +// "baz" is defined but never used |
| 196 | +(function(foo, bar, baz) { |
| 197 | + return bar; |
| 198 | +})(); |
26 | 199 | ``` |
27 | 200 |
|
28 | | -The following patterns are not warnings: |
| 201 | +#### args: none |
29 | 202 |
|
30 | | -```ts |
31 | | -interface Foo {} |
| 203 | +Examples of **correct** code for the `{ "args": "none" }` option: |
32 | 204 |
|
33 | | -class Bar implements Foo {} |
| 205 | +```js |
| 206 | +/*eslint no-unused-vars: ["error", { "args": "none" }]*/ |
| 207 | + |
| 208 | +(function(foo, bar, baz) { |
| 209 | + return bar; |
| 210 | +})(); |
| 211 | +``` |
| 212 | + |
| 213 | +### ignoreRestSiblings |
| 214 | + |
| 215 | +The `ignoreRestSiblings` option is a boolean (default: `false`). Using a [Rest Property](https://github.com/tc39/proposal-object-rest-spread) it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored. |
| 216 | + |
| 217 | +Examples of **correct** code for the `{ "ignoreRestSiblings": true }` option: |
| 218 | + |
| 219 | +```js |
| 220 | +/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/ |
| 221 | +// 'type' is ignored because it has a rest property sibling. |
| 222 | +var { type, ...coords } = data; |
| 223 | +``` |
| 224 | + |
| 225 | +### argsIgnorePattern |
| 226 | + |
| 227 | +The `argsIgnorePattern` option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore. |
| 228 | + |
| 229 | +Examples of **correct** code for the `{ "argsIgnorePattern": "^_" }` option: |
| 230 | + |
| 231 | +```js |
| 232 | +/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/ |
| 233 | + |
| 234 | +function foo(x, _y) { |
| 235 | + return x + 1; |
| 236 | +} |
| 237 | +foo(); |
| 238 | +``` |
| 239 | + |
| 240 | +### caughtErrors |
| 241 | + |
| 242 | +The `caughtErrors` option is used for `catch` block arguments validation. |
| 243 | + |
| 244 | +It has two settings: |
| 245 | + |
| 246 | +- `none` - do not check error objects. This is the default setting. |
| 247 | +- `all` - all named arguments must be used. |
| 248 | + |
| 249 | +#### caughtErrors: none |
| 250 | + |
| 251 | +Not specifying this rule is equivalent of assigning it to `none`. |
| 252 | + |
| 253 | +Examples of **correct** code for the `{ "caughtErrors": "none" }` option: |
| 254 | + |
| 255 | +```js |
| 256 | +/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/ |
| 257 | + |
| 258 | +try { |
| 259 | + //... |
| 260 | +} catch (err) { |
| 261 | + console.error("errors"); |
| 262 | +} |
| 263 | +``` |
| 264 | + |
| 265 | +#### caughtErrors: all |
| 266 | + |
| 267 | +Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option: |
| 268 | + |
| 269 | +```js |
| 270 | +/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/ |
| 271 | + |
| 272 | +// 1 error |
| 273 | +// "err" is defined but never used |
| 274 | +try { |
| 275 | + //... |
| 276 | +} catch (err) { |
| 277 | + console.error("errors"); |
| 278 | +} |
| 279 | +``` |
| 280 | + |
| 281 | +### caughtErrorsIgnorePattern |
| 282 | + |
| 283 | +The `caughtErrorsIgnorePattern` option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'. |
| 284 | + |
| 285 | +Examples of **correct** code for the `{ "caughtErrorsIgnorePattern": "^ignore" }` option: |
| 286 | + |
| 287 | +```js |
| 288 | +/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/ |
| 289 | + |
| 290 | +try { |
| 291 | + //... |
| 292 | +} catch (ignoreErr) { |
| 293 | + console.error("errors"); |
| 294 | +} |
34 | 295 | ``` |
35 | 296 |
|
36 | 297 | ## When Not To Use It |
37 | 298 |
|
38 | | -If you are not using `no-unused-vars` then you will not need this rule. |
| 299 | +If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. |
| 300 | + |
| 301 | +<sup>Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/master/docs/rules/no-unused-vars.md)</sup> |
0 commit comments