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

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