eslint/docs/rules/no-unused-expressions.md

   1 # Disallow Unused Expressions (no-unused-expressions)
   2
   3 An unused expression which has no effect on the state of the program indicates a logic error.
   4
   5 For example, `n + 1;` is not a syntax error, but it might be a typing mistake where a programmer meant an assignment statement `n += 1;` instead. Sometimes, such unused expressions may be eliminated by some build tools in production environment, which possibly breaks application logic.
   6
   7 ## Rule Details
   8
   9 This rule aims to eliminate unused expressions which have no effect on the state of the program.
  10
  11 This rule does not apply to function calls or constructor calls with the `new` operator, because they could have *side effects* on the state of the program.
  12
  13 ```js
  14 var i = 0;
  15 function increment() { i += 1; }
  16 increment(); // return value is unused, but i changed as a side effect
  17
  18 var nThings = 0;
  19 function Thing() { nThings += 1; }
  20 new Thing(); // constructed object is unused, but nThings changed as a side effect
  21 ```
  22
  23 This rule does not apply to directives (which are in the form of literal string expressions such as `"use strict";` at the beginning of a script, module, or function).
  24
  25 Sequence expressions (those using a comma, such as `a = 1, b = 2`) are always considered unused unless their return value is assigned or used in a condition evaluation, or a function call is made with the sequence expression value.
  26
  27 ## Options
  28
  29 This rule, in its default state, does not require any arguments. If you would like to enable one or more of the following you may pass an object with the options set as follows:
  30
  31 * `allowShortCircuit` set to `true` will allow you to use short circuit evaluations in your expressions (Default: `false`).
  32 * `allowTernary` set to `true` will enable you to use ternary operators in your expressions similarly to short circuit evaluations (Default: `false`).
  33 * `allowTaggedTemplates` set to `true` will enable you to use tagged template literals in your expressions (Default: `false`).
  34 * `enforceForJSX` set to `true` will flag unused JSX element expressions (Default: `false`).
  35
  36 These options allow unused expressions *only if all* of the code paths either directly change the state (for example, assignment statement) or could have *side effects* (for example, function call).
  37
  38 Examples of **incorrect** code for the default `{ "allowShortCircuit": false, "allowTernary": false }` options:
  39
  40 ```js
  41 /*eslint no-unused-expressions: "error"*/
  42
  43 0
  44
  45 if(0) 0
  46
  47 {0}
  48
  49 f(0), {}
  50
  51 a && b()
  52
  53 a, b()
  54
  55 c = a, b;
  56
  57 a() && function namedFunctionInExpressionContext () {f();}
  58
  59 (function anIncompleteIIFE () {});
  60
  61 injectGlobal`body{ color: red; }`
  62
  63 ```
  64
  65 Examples of **correct** code for the default `{ "allowShortCircuit": false, "allowTernary": false }` options:
  66
  67 ```js
  68 /*eslint no-unused-expressions: "error"*/
  69
  70 {} // In this context, this is a block statement, not an object literal
  71
  72 {myLabel: someVar} // In this context, this is a block statement with a label and expression, not an object literal
  73
  74 function namedFunctionDeclaration () {}
  75
  76 (function aGenuineIIFE () {}());
  77
  78 f()
  79
  80 a = 0
  81
  82 new C
  83
  84 delete a.b
  85
  86 void a
  87 ```
  88
  89 Note that one or more string expression statements (with or without semi-colons) will only be considered as unused if they are not in the beginning of a script, module, or function (alone and uninterrupted by other statements). Otherwise, they will be treated as part of a "directive prologue", a section potentially usable by JavaScript engines. This includes "strict mode" directives.
  90
  91 Examples of **correct** code for this rule in regard to directives:
  92
  93 ```js
  94 /*eslint no-unused-expressions: "error"*/
  95
  96 "use strict";
  97 "use asm"
  98 "use stricter";
  99 "use babel"
 100 "any other strings like this in the directive prologue";
 101 "this is still the directive prologue";
 102
 103 function foo() {
 104     "bar";
 105 }
 106
 107 class Foo {
 108     someMethod() {
 109         "use strict";
 110     }
 111 }
 112 ```
 113
 114 Examples of **incorrect** code for this rule in regard to directives:
 115
 116 ```js
 117 /*eslint no-unused-expressions: "error"*/
 118
 119 doSomething();
 120 "use strict"; // this isn't in a directive prologue, because there is a non-directive statement before it
 121
 122 function foo() {
 123     "bar" + 1;
 124 }
 125
 126 class Foo {
 127     static {
 128         "use strict"; // class static blocks do not have directive prologues
 129     }
 130 }
 131 ```
 132
 133 ### allowShortCircuit
 134
 135 Examples of **incorrect** code for the `{ "allowShortCircuit": true }` option:
 136
 137 ```js
 138 /*eslint no-unused-expressions: ["error", { "allowShortCircuit": true }]*/
 139
 140 a || b
 141 ```
 142
 143 Examples of **correct** code for the `{ "allowShortCircuit": true }` option:
 144
 145 ```js
 146 /*eslint no-unused-expressions: ["error", { "allowShortCircuit": true }]*/
 147
 148 a && b()
 149 a() || (b = c)
 150 ```
 151
 152 ### allowTernary
 153
 154 Examples of **incorrect** code for the `{ "allowTernary": true }` option:
 155
 156 ```js
 157 /*eslint no-unused-expressions: ["error", { "allowTernary": true }]*/
 158
 159 a ? b : 0
 160 a ? b : c()
 161 ```
 162
 163 Examples of **correct** code for the `{ "allowTernary": true }` option:
 164
 165 ```js
 166 /*eslint no-unused-expressions: ["error", { "allowTernary": true }]*/
 167
 168 a ? b() : c()
 169 a ? (b = c) : d()
 170 ```
 171
 172 ### allowShortCircuit and allowTernary
 173
 174 Examples of **correct** code for the `{ "allowShortCircuit": true, "allowTernary": true }` options:
 175
 176 ```js
 177 /*eslint no-unused-expressions: ["error", { "allowShortCircuit": true, "allowTernary": true }]*/
 178
 179 a ? b() || (c = d) : e()
 180 ```
 181
 182 ### allowTaggedTemplates
 183
 184 Examples of **incorrect** code for the `{ "allowTaggedTemplates": true }` option:
 185
 186 ```js
 187 /*eslint no-unused-expressions: ["error", { "allowTaggedTemplates": true }]*/
 188
 189 `some untagged template string`;
 190 ```
 191
 192 Examples of **correct** code for the `{ "allowTaggedTemplates": true }` option:
 193
 194 ```js
 195 /*eslint no-unused-expressions: ["error", { "allowTaggedTemplates": true }]*/
 196
 197 tag`some tagged template string`;
 198 ```
 199
 200 ### enforceForJSX
 201
 202 JSX is most-commonly used in the React ecosystem, where it is compiled to `React.createElement` expressions. Though free from side-effects, these calls are not automatically flagged by the `no-unused-expression` rule. If you're using React, or any other side-effect-free JSX pragma, this option can be enabled to flag these expressions.
 203
 204 Examples of **incorrect** code for the `{ "enforceForJSX": true }` option:
 205
 206 ```jsx
 207 /*eslint no-unused-expressions: ["error", { "enforceForJSX": true }]*/
 208
 209 <MyComponent />;
 210
 211 <></>;
 212 ```
 213
 214 Examples of **correct** code for the `{ "enforceForJSX": true }` option:
 215
 216 ```jsx
 217 /*eslint no-unused-expressions: ["error", { "enforceForJSX": true }]*/
 218
 219 var myComponentPartial = <MyComponent />;
 220
 221 var myFragment = <></>;
 222 ```