eslint/docs/src/rules/sort-keys.md

   1 ---
   2 title: sort-keys
   3 rule_type: suggestion
   4 related_rules:
   5 - sort-imports
   6 - sort-vars
   7 ---
   8
   9
  10 When declaring multiple properties, some developers prefer to sort property names alphabetically to more easily find and/or diff necessary properties at a later time. Others feel that it adds complexity and becomes burden to maintain.
  11
  12 ## Rule Details
  13
  14 This rule checks all property definitions of object expressions and verifies that all variables are sorted alphabetically.
  15
  16 Examples of **incorrect** code for this rule:
  17
  18 ::: incorrect
  19
  20 ```js
  21 /*eslint sort-keys: "error"*/
  22 /*eslint-env es6*/
  23
  24 let obj = {a: 1, c: 3, b: 2};
  25 let obj = {a: 1, "c": 3, b: 2};
  26
  27 // Case-sensitive by default.
  28 let obj = {a: 1, b: 2, C: 3};
  29
  30 // Non-natural order by default.
  31 let obj = {1: a, 2: c, 10: b};
  32
  33 // This rule checks computed properties which have a simple name as well.
  34 // Simple names are names which are expressed by an Identifier node or a Literal node.
  35 const S = Symbol("s")
  36 let obj = {a: 1, ["c"]: 3, b: 2};
  37 let obj = {a: 1, [S]: 3, b: 2};
  38 ```
  39
  40 :::
  41
  42 Examples of **correct** code for this rule:
  43
  44 ::: correct
  45
  46 ```js
  47 /*eslint sort-keys: "error"*/
  48 /*eslint-env es6*/
  49
  50 let obj = {a: 1, b: 2, c: 3};
  51 let obj = {a: 1, "b": 2, c: 3};
  52
  53 // Case-sensitive by default.
  54 let obj = {C: 3, a: 1, b: 2};
  55
  56 // Non-natural order by default.
  57 let obj = {1: a, 10: b, 2: c};
  58
  59 // This rule checks computed properties which have a simple name as well.
  60 let obj = {a: 1, ["b"]: 2, c: 3};
  61 let obj = {a: 1, [b]: 2, c: 3};
  62
  63 // This rule ignores computed properties which have a non-simple name.
  64 let obj = {a: 1, [c + d]: 3, b: 2};
  65 let obj = {a: 1, ["c" + "d"]: 3, b: 2};
  66 let obj = {a: 1, [`${c}`]: 3, b: 2};
  67 let obj = {a: 1, [tag`c`]: 3, b: 2};
  68
  69 // This rule does not report unsorted properties that are separated by a spread property.
  70 let obj = {b: 1, ...c, a: 2};
  71 ```
  72
  73 :::
  74
  75 ## Options
  76
  77 ```json
  78 {
  79     "sort-keys": ["error", "asc", {"caseSensitive": true, "natural": false, "minKeys": 2}]
  80 }
  81 ```
  82
  83 The 1st option is `"asc"` or `"desc"`.
  84
  85 * `"asc"` (default) - enforce properties to be in ascending order.
  86 * `"desc"` - enforce properties to be in descending order.
  87
  88 The 2nd option is an object which has 3 properties.
  89
  90 * `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`.
  91 * `minKeys` - Specifies the minimum number of keys that an object should have in order for the object's unsorted keys to produce an error. Default is `2`, which means by default all objects with unsorted keys will result in lint errors.
  92 * `natural` - if `true`, enforce properties to be in natural order. Default is `false`. Natural Order compares strings containing combination of letters and numbers in the way a human being would sort. It basically sorts numerically, instead of sorting alphabetically. So the number 10 comes after the number 3 in Natural Sorting.
  93 * `allowLineSeparatedGroups` - if `true`, the rule allows to group object keys through line breaks. In other words, a blank line after a property will reset the sorting of keys. Default is `false`.
  94
  95 Example for a list:
  96
  97 With `natural` as true, the ordering would be
  98 1
  99 3
 100 6
 101 8
 102 10
 103
 104 With `natural` as false, the ordering would be
 105 1
 106 10
 107 3
 108 6
 109 8
 110
 111 ### desc
 112
 113 Examples of **incorrect** code for the `"desc"` option:
 114
 115 ::: incorrect
 116
 117 ```js
 118 /*eslint sort-keys: ["error", "desc"]*/
 119 /*eslint-env es6*/
 120
 121 let obj = {b: 2, c: 3, a: 1};
 122 let obj = {"b": 2, c: 3, a: 1};
 123
 124 // Case-sensitive by default.
 125 let obj = {C: 1, b: 3, a: 2};
 126
 127 // Non-natural order by default.
 128 let obj = {10: b, 2: c, 1: a};
 129 ```
 130
 131 :::
 132
 133 Examples of **correct** code for the `"desc"` option:
 134
 135 ::: correct
 136
 137 ```js
 138 /*eslint sort-keys: ["error", "desc"]*/
 139 /*eslint-env es6*/
 140
 141 let obj = {c: 3, b: 2, a: 1};
 142 let obj = {c: 3, "b": 2, a: 1};
 143
 144 // Case-sensitive by default.
 145 let obj = {b: 3, a: 2, C: 1};
 146
 147 // Non-natural order by default.
 148 let obj = {2: c, 10: b, 1: a};
 149 ```
 150
 151 :::
 152
 153 ### insensitive
 154
 155 Examples of **incorrect** code for the `{caseSensitive: false}` option:
 156
 157 ::: incorrect
 158
 159 ```js
 160 /*eslint sort-keys: ["error", "asc", {caseSensitive: false}]*/
 161 /*eslint-env es6*/
 162
 163 let obj = {a: 1, c: 3, C: 4, b: 2};
 164 let obj = {a: 1, C: 3, c: 4, b: 2};
 165 ```
 166
 167 :::
 168
 169 Examples of **correct** code for the `{caseSensitive: false}` option:
 170
 171 ::: correct
 172
 173 ```js
 174 /*eslint sort-keys: ["error", "asc", {caseSensitive: false}]*/
 175 /*eslint-env es6*/
 176
 177 let obj = {a: 1, b: 2, c: 3, C: 4};
 178 let obj = {a: 1, b: 2, C: 3, c: 4};
 179 ```
 180
 181 :::
 182
 183 ### natural
 184
 185 Examples of **incorrect** code for the `{natural: true}` option:
 186
 187 ::: incorrect
 188
 189 ```js
 190 /*eslint sort-keys: ["error", "asc", {natural: true}]*/
 191 /*eslint-env es6*/
 192
 193 let obj = {1: a, 10: c, 2: b};
 194 ```
 195
 196 :::
 197
 198 Examples of **correct** code for the `{natural: true}` option:
 199
 200 ::: correct
 201
 202 ```js
 203 /*eslint sort-keys: ["error", "asc", {natural: true}]*/
 204 /*eslint-env es6*/
 205
 206 let obj = {1: a, 2: b, 10: c};
 207 ```
 208
 209 :::
 210
 211 ### minKeys
 212
 213 Examples of **incorrect** code for the `{minKeys: 4}` option:
 214
 215 ::: incorrect
 216
 217 ```js
 218 /*eslint sort-keys: ["error", "asc", {minKeys: 4}]*/
 219 /*eslint-env es6*/
 220
 221 // 4 keys
 222 let obj = {
 223     b: 2,
 224     a: 1, // not sorted correctly (should be 1st key)
 225     c: 3,
 226     d: 4,
 227 };
 228
 229 // 5 keys
 230 let obj = {
 231     2: 'a',
 232     1: 'b', // not sorted correctly (should be 1st key)
 233     3: 'c',
 234     4: 'd',
 235     5: 'e',
 236 };
 237 ```
 238
 239 :::
 240
 241 Examples of **correct** code for the `{minKeys: 4}` option:
 242
 243 ::: correct
 244
 245 ```js
 246 /*eslint sort-keys: ["error", "asc", {minKeys: 4}]*/
 247 /*eslint-env es6*/
 248
 249 // 3 keys
 250 let obj = {
 251     b: 2,
 252     a: 1,
 253     c: 3,
 254 };
 255
 256 // 2 keys
 257 let obj = {
 258     2: 'b',
 259     1: 'a',
 260 };
 261 ```
 262
 263 :::
 264
 265 ### allowLineSeparatedGroups
 266
 267 Examples of **incorrect** code for the `{allowLineSeparatedGroups: true}` option:
 268
 269 ::: incorrect
 270
 271 ```js
 272 /*eslint sort-keys: ["error", "asc", {allowLineSeparatedGroups: true}]*/
 273 /*eslint-env es6*/
 274
 275 let obj1 = {
 276     b: 1,
 277     c () {
 278
 279     },
 280     a: 3
 281 }
 282
 283 let obj2 = {
 284     b: 1,
 285     c: 2,
 286
 287     z () {
 288
 289     },
 290     y: 3
 291 }
 292
 293 let obj3 = {
 294     b: 1,
 295     c: 2,
 296
 297     z () {
 298
 299     },
 300     // comment
 301     y: 3,
 302 }
 303
 304 let obj4 = {
 305     b: 1
 306     // comment before comma
 307     , a: 2
 308 };
 309 ```
 310
 311 :::
 312
 313 Examples of **correct** code for the `{allowLineSeparatedGroups: true}` option:
 314
 315 ::: correct
 316
 317 ```js
 318 /*eslint sort-keys: ["error", "asc", {allowLineSeparatedGroups: true}]*/
 319 /*eslint-env es6*/
 320
 321 let obj = {
 322     e: 1,
 323     f: 2,
 324     g: 3,
 325
 326     a: 4,
 327     b: 5,
 328     c: 6
 329 }
 330
 331 let obj = {
 332     b: 1,
 333
 334     // comment
 335     a: 4,
 336     c: 5,
 337 }
 338
 339 let obj = {
 340     c: 1,
 341     d: 2,
 342
 343     b () {
 344
 345     },
 346     e: 3,
 347 }
 348
 349 let obj = {
 350     c: 1,
 351     d: 2,
 352     // comment
 353
 354     // comment
 355     b() {
 356
 357     },
 358     e: 4
 359 }
 360
 361 let obj = {
 362     b,
 363
 364     [foo + bar]: 1,
 365     a
 366 }
 367
 368 let obj = {
 369     b: 1
 370     // comment before comma
 371
 372     ,
 373     a: 2
 374 };
 375
 376 var obj = {
 377     b: 1,
 378
 379     a: 2,
 380     ...z,
 381     c: 3
 382 }
 383 ```
 384
 385 :::
 386
 387 ## When Not To Use It
 388
 389 If you don't want to notify about properties' order, then it's safe to disable this rule.
 390
 391 ## Compatibility
 392
 393 * **JSCS:** [validateOrderInObjectKeys](https://jscs-dev.github.io/rule/validateOrderInObjectKeys)