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

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