eslint/docs/rules/semi.md

   1 # require or disallow semicolons instead of ASI (semi)
   2
   3 JavaScript doesn't require semicolons at the end of each statement. In many cases, the JavaScript engine can determine that a semicolon should be in a certain spot and will automatically add it. This feature is known as **automatic semicolon insertion (ASI)** and is considered one of the more controversial features of JavaScript. For example, the following lines are both valid:
   4
   5 ```js
   6 var name = "ESLint"
   7 var website = "eslint.org";
   8 ```
   9
  10 On the first line, the JavaScript engine will automatically insert a semicolon, so this is not considered a syntax error. The JavaScript engine still knows how to interpret the line and knows that the line end indicates the end of the statement.
  11
  12 In the debate over ASI, there are generally two schools of thought. The first is that we should treat ASI as if it didn't exist and always include semicolons manually. The rationale is that it's easier to always include semicolons than to try to remember when they are or are not required, and thus decreases the possibility of introducing an error.
  13
  14 However, the ASI mechanism can sometimes be tricky to people who are using semicolons. For example, consider this code:
  15
  16 ```js
  17 return
  18 {
  19     name: "ESLint"
  20 };
  21 ```
  22
  23 This may look like a `return` statement that returns an object literal, however, the JavaScript engine will interpret this code as:
  24
  25 ```js
  26 return;
  27 {
  28     name: "ESLint";
  29 }
  30 ```
  31
  32 Effectively, a semicolon is inserted after the `return` statement, causing the code below it (a labeled literal inside a block) to be unreachable. This rule and the [no-unreachable](no-unreachable.md) rule will protect your code from such cases.
  33
  34 On the other side of the argument are those who say that since semicolons are inserted automatically, they are optional and do not need to be inserted manually. However, the ASI mechanism can also be tricky to people who don't use semicolons. For example, consider this code:
  35
  36 ```js
  37 var globalCounter = { }
  38
  39 (function () {
  40     var n = 0
  41     globalCounter.increment = function () {
  42         return ++n
  43     }
  44 })()
  45 ```
  46
  47 In this example, a semicolon will not be inserted after the first line, causing a run-time error (because an empty object is called as if it's a function). The [no-unexpected-multiline](no-unexpected-multiline.md) rule can protect your code from such cases.
  48
  49 Although ASI allows for more freedom over your coding style, it can also make your code behave in an unexpected way, whether you use semicolons or not. Therefore, it is best to know when ASI takes place and when it does not, and have ESLint protect your code from these potentially unexpected cases. In short, as once described by Isaac Schlueter, a `\n` character always ends a statement (just like a semicolon) unless one of the following is true:
  50
  51 1. The statement has an unclosed paren, array literal, or object literal or ends in some other way that is not a valid way to end a statement. (For instance, ending with `.` or `,`.)
  52 1. The line is `--` or `++` (in which case it will decrement/increment the next token.)
  53 1. It is a `for()`, `while()`, `do`, `if()`, or `else`, and there is no `{`
  54 1. The next line starts with `[`, `(`, `+`, `*`, `/`, `-`, `,`, `.`, or some other binary operator that can only be found between two tokens in a single expression.
  55
  56 ## Rule Details
  57
  58 This rule enforces consistent use of semicolons.
  59
  60 ## Options
  61
  62 This rule has two options, a string option and an object option.
  63
  64 String option:
  65
  66 * `"always"` (default) requires semicolons at the end of statements
  67 * `"never"` disallows semicolons as the end of statements (except to disambiguate statements beginning with `[`, `(`, `/`, `+`, or `-`)
  68
  69 Object option (when `"always"`):
  70
  71 * `"omitLastInOneLineBlock": true` ignores the last semicolon in a block in which its braces (and therefore the content of the block) are in the same line
  72
  73 Object option (when `"never"`):
  74
  75 * `"beforeStatementContinuationChars": "any"` (default) ignores semicolons (or lacking semicolon) at the end of statements if the next line starts with `[`, `(`, `/`, `+`, or `-`.
  76 * `"beforeStatementContinuationChars": "always"` requires semicolons at the end of statements if the next line starts with `[`, `(`, `/`, `+`, or `-`.
  77 * `"beforeStatementContinuationChars": "never"` disallows semicolons as the end of statements if it doesn't make ASI hazard even if the next line starts with `[`, `(`, `/`, `+`, or `-`.
  78
  79 ### always
  80
  81 Examples of **incorrect** code for this rule with the default `"always"` option:
  82
  83 ```js
  84 /*eslint semi: ["error", "always"]*/
  85
  86 var name = "ESLint"
  87
  88 object.method = function() {
  89     // ...
  90 }
  91 ```
  92
  93 Examples of **correct** code for this rule with the default `"always"` option:
  94
  95 ```js
  96 /*eslint semi: "error"*/
  97
  98 var name = "ESLint";
  99
 100 object.method = function() {
 101     // ...
 102 };
 103 ```
 104
 105 ### never
 106
 107 Examples of **incorrect** code for this rule with the `"never"` option:
 108
 109 ```js
 110 /*eslint semi: ["error", "never"]*/
 111
 112 var name = "ESLint";
 113
 114 object.method = function() {
 115     // ...
 116 };
 117 ```
 118
 119 Examples of **correct** code for this rule with the `"never"` option:
 120
 121 ```js
 122 /*eslint semi: ["error", "never"]*/
 123
 124 var name = "ESLint"
 125
 126 object.method = function() {
 127     // ...
 128 }
 129
 130 var name = "ESLint"
 131
 132 ;(function() {
 133     // ...
 134 })()
 135
 136 import a from "a"
 137 (function() {
 138     // ...
 139 })()
 140
 141 import b from "b"
 142 ;(function() {
 143     // ...
 144 })()
 145 ```
 146
 147 #### omitLastInOneLineBlock
 148
 149 Examples of additional **correct** code for this rule with the `"always", { "omitLastInOneLineBlock": true }` options:
 150
 151 ```js
 152 /*eslint semi: ["error", "always", { "omitLastInOneLineBlock": true}] */
 153
 154 if (foo) { bar() }
 155
 156 if (foo) { bar(); baz() }
 157 ```
 158
 159 #### beforeStatementContinuationChars
 160
 161 Examples of additional **incorrect** code for this rule with the `"never", { "beforeStatementContinuationChars": "always" }` options:
 162
 163 ```js
 164 /*eslint semi: ["error", "never", { "beforeStatementContinuationChars": "always"}] */
 165 import a from "a"
 166
 167 (function() {
 168     // ...
 169 })()
 170 ```
 171
 172 Examples of additional **incorrect** code for this rule with the `"never", { "beforeStatementContinuationChars": "never" }` options:
 173
 174 ```js
 175 /*eslint semi: ["error", "never", { "beforeStatementContinuationChars": "never"}] */
 176 import a from "a"
 177
 178 ;(function() {
 179     // ...
 180 })()
 181 ```
 182
 183 ## When Not To Use It
 184
 185 If you do not want to enforce semicolon usage (or omission) in any particular way, then you can turn this rule off.
 186
 187 ## Further Reading
 188
 189 * [An Open Letter to JavaScript Leaders Regarding Semicolons](http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding)
 190 * [JavaScript Semicolon Insertion](http://inimino.org/~inimino/blog/javascript_semicolons)
 191
 192 ## Related Rules
 193
 194 * [no-extra-semi](no-extra-semi.md)
 195 * [no-unexpected-multiline](no-unexpected-multiline.md)
 196 * [semi-spacing](semi-spacing.md)