eslint/docs/src/rules/object-property-newline.md

   1 ---
   2 title: object-property-newline
   3 rule_type: layout
   4 related_rules:
   5 - brace-style
   6 - comma-dangle
   7 - key-spacing
   8 - object-curly-spacing
   9 ---
  10
  11
  12
  13 This rule permits you to restrict the locations of property specifications in object literals. You may prohibit any part of any property specification from appearing on the same line as any part of any other property specification. You may make this prohibition absolute, or, by invoking an object option, you may allow an exception, permitting an object literal to have all parts of all of its property specifications on a single line.
  14
  15 ## Rule Details
  16
  17 ### Motivations
  18
  19 This rule makes it possible to ensure, as some style guides require, that property specifications appear on separate lines for better readability. For example, you can prohibit all of these:
  20
  21 ```js
  22 const newObject = {a: 1, b: [2, {a: 3, b: 4}]};
  23 const newObject = {
  24     a: 1, b: [2, {a: 3, b: 4}]
  25 };
  26 const newObject = {
  27     a: 1,
  28     b: [2, {a: 3, b: 4}]
  29 };
  30 const newObject = {
  31     a: 1,
  32     b: [
  33         2,
  34         {a: 3, b: 4}
  35     ]
  36 };
  37
  38 ```
  39
  40 Instead of those, you can comply with the rule by writing
  41
  42 ```js
  43 const newObject = {
  44     a: 1,
  45     b: [2, {
  46         a: 3,
  47         b: 4
  48     }]
  49 };
  50 ```
  51
  52 or
  53
  54 ```js
  55 const newObject = {
  56     a: 1,
  57     b: [
  58         2,
  59         {
  60             a: 3,
  61             b: 4
  62         }
  63     ]
  64 };
  65 ```
  66
  67 Another benefit of this rule is specificity of diffs when a property is changed:
  68
  69 ```diff
  70 // More specific
  71  var obj = {
  72      foo: "foo",
  73 -    bar: "bar",
  74 +    bar: "bazz",
  75      baz: "baz"
  76  };
  77 ```
  78
  79 ```diff
  80 // Less specific
  81 -var obj = { foo: "foo", bar: "bar", baz: "baz" };
  82 +var obj = { foo: "foo", bar: "bazz", baz: "baz" };
  83 ```
  84
  85 ### Optional Exception
  86
  87 The rule offers one object option, `allowAllPropertiesOnSameLine` (a deprecated synonym is `allowMultiplePropertiesPerLine`). If you set it to `true`, object literals such as the first two above, with all property specifications on the same line, will be permitted, but one like
  88
  89 ```js
  90 const newObject = {
  91     a: 'a.m.', b: 'p.m.',
  92     c: 'daylight saving time'
  93 };
  94
  95 ```
  96
  97 will be prohibited, because two properties, but not all properties, appear on the same line.
  98
  99 ### Notations
 100
 101 This rule applies equally to all property specifications, regardless of notation, including:
 102
 103 * `a: 1` (ES5)
 104 * `a` (ES2015 shorthand property)
 105 * ``[`prop${a}`]`` (ES2015 computed property name)
 106
 107 Thus, the rule (without the optional exception) prohibits both of these:
 108
 109 ```js
 110 const newObject = {
 111     a: 1, [
 112         process.argv[4]
 113     ]: '01'
 114 };
 115 const newObject = {
 116     a: 1, [process.argv[4]]: '01'
 117 };
 118 ```
 119
 120 (This behavior differs from that of the JSCS rule cited below, which does not treat the leading `[` of a computed property name as part of that property specification. The JSCS rule prohibits the second of these formats but permits the first.)
 121
 122 ### Multiline Properties
 123
 124 The rule prohibits the colocation on any line of at least 1 character of one property specification with at least 1 character of any other property specification. For example, the rule prohibits
 125
 126 ```js
 127 const newObject = {a: [
 128     'Officiële website van de Europese Unie',
 129     'Официален уебсайт на Европейския съюз'
 130 ], b: 2};
 131 ```
 132
 133 because 1 character of the specification of `a` (i.e. the trailing `]` of its value) is on the same line as the specification of `b`.
 134
 135 The optional exception does not excuse this case, because the entire collection of property specifications spans 4 lines, not 1.
 136
 137 ### Inter-property Delimiters
 138
 139 The comma and any whitespace that delimit property specifications are not considered parts of them. Therefore, the rule permits both of these formats:
 140
 141 ```js
 142 const newFunction = multiplier => ({
 143     a: 2 * multiplier,
 144     b: 4 * multiplier,
 145     c: 8 * multiplier
 146 });
 147 const newFunction = multiplier => ({
 148     a: 2 * multiplier
 149     , b: 4 * multiplier
 150     , c: 8 * multiplier
 151 });
 152 ```
 153
 154 (This behavior differs from that of the JSCS rule cited below, which permits the first but prohibits the second format.)
 155
 156 ### --fix
 157
 158 If this rule is invoked with the command-line `--fix` option, object literals that violate the rule are generally modified to comply with it. The modification in each case is to move a property specification to the next line whenever there is part or all of a previous property specification on the same line. For example,
 159
 160 ```js
 161 const newObject = {
 162     a: 'a.m.', b: 'p.m.',
 163     c: 'daylight saving time'
 164 };
 165 ```
 166
 167 is converted to
 168
 169 ```js
 170 const newObject = {
 171     a: 'a.m.',
 172 b: 'p.m.',
 173     c: 'daylight saving time'
 174 };
 175 ```
 176
 177 The modification does not depend on whether the object option is set to `true`. In other words, ESLint never collects all the property specifications onto a single line, even when the object option would permit that.
 178
 179 ESLint does not correct a violation of this rule if a comment immediately precedes the second or subsequent property specification on a line, since ESLint cannot determine which line to put the comment onto.
 180
 181 As illustrated above, the `--fix` option, applied to this rule, does not comply with other rules, such as `indent`, but, if those other rules are also in effect, the option applies them, too.
 182
 183 ## Examples
 184
 185 Examples of **incorrect** code for this rule, with no object option or with `allowAllPropertiesOnSameLine` set to `false`:
 186
 187 ::: incorrect
 188
 189 ```js
 190 /*eslint object-property-newline: "error"*/
 191
 192 const obj0 = { foo: "foo", bar: "bar", baz: "baz" };
 193
 194 const obj1 = {
 195     foo: "foo", bar: "bar", baz: "baz"
 196 };
 197
 198 const obj2 = {
 199     foo: "foo", bar: "bar",
 200     baz: "baz"
 201 };
 202
 203 const obj3 = {
 204     [process.argv[3] ? "foo" : "bar"]: 0, baz: [
 205         1,
 206         2,
 207         4,
 208         8
 209     ]
 210 };
 211
 212 const a = "antidisestablishmentarianistically";
 213 const b = "yugoslavyalılaştırabildiklerimizdenmişsiniz";
 214 const obj4 = {a, b};
 215
 216 const domain = process.argv[4];
 217 const obj5 = {
 218     foo: "foo", [
 219     domain.includes(":") ? "complexdomain" : "simpledomain"
 220 ]: true};
 221 ```
 222
 223 :::
 224
 225 Examples of **correct** code for this rule, with no object option or with `allowAllPropertiesOnSameLine` set to `false`:
 226
 227 ::: correct
 228
 229 ```js
 230 /*eslint object-property-newline: "error"*/
 231
 232 const obj1 = {
 233     foo: "foo",
 234     bar: "bar",
 235     baz: "baz"
 236 };
 237
 238 const obj2 = {
 239     foo: "foo"
 240     , bar: "bar"
 241     , baz: "baz"
 242 };
 243
 244 const user = process.argv[2];
 245 const obj3 = {
 246     user,
 247     [process.argv[3] ? "foo" : "bar"]: 0,
 248     baz: [
 249         1,
 250         2,
 251         4,
 252         8
 253     ]
 254 };
 255 ```
 256
 257 :::
 258
 259 Examples of additional **correct** code for this rule with the `{ "allowAllPropertiesOnSameLine": true }` option:
 260
 261 ::: correct
 262
 263 ```js
 264 /*eslint object-property-newline: ["error", { "allowAllPropertiesOnSameLine": true }]*/
 265
 266 const obj = { foo: "foo", bar: "bar", baz: "baz" };
 267
 268 const obj2 = {
 269     foo: "foo", bar: "bar", baz: "baz"
 270 };
 271 const user = process.argv[2];
 272 const obj3 = {
 273     user, [process.argv[3] ? "foo" : "bar"]: 0, baz: [1, 2, 4, 8]
 274 };
 275 ```
 276
 277 :::
 278
 279 ## When Not To Use It
 280
 281 You can turn this rule off if you want to decide, case-by-case, whether to place property specifications on separate lines.
 282
 283 ## Compatibility
 284
 285 * **JSCS**: This rule provides partial compatibility with [requireObjectKeysOnNewLine](https://jscs-dev.github.io/rule/requireObjectKeysOnNewLine).