eslint/docs/rules/sort-keys.md

   1 # require object keys to be sorted (sort-keys)
   2
   3 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.
   4
   5 ## Rule Details
   6
   7 This rule checks all property definitions of object expressions and verifies that all variables are sorted alphabetically.
   8
   9 Examples of **incorrect** code for this rule:
  10
  11 ```js
  12 /*eslint sort-keys: "error"*/
  13 /*eslint-env es6*/
  14
  15 let obj = {a: 1, c: 3, b: 2};
  16 let obj = {a: 1, "c": 3, b: 2};
  17
  18 // Case-sensitive by default.
  19 let obj = {a: 1, b: 2, C: 3};
  20
  21 // Non-natural order by default.
  22 let obj = {1: a, 2: c, 10: b};
  23
  24 // This rule checks computed properties which have a simple name as well.
  25 // Simple names are names which are expressed by an Identifier node or a Literal node.
  26 const S = Symbol("s")
  27 let obj = {a: 1, ["c"]: 3, b: 2};
  28 let obj = {a: 1, [S]: 3, b: 2};
  29 ```
  30
  31 Examples of **correct** code for this rule:
  32
  33 ```js
  34 /*eslint sort-keys: "error"*/
  35 /*eslint-env es6*/
  36
  37 let obj = {a: 1, b: 2, c: 3};
  38 let obj = {a: 1, "b": 2, c: 3};
  39
  40 // Case-sensitive by default.
  41 let obj = {C: 3, a: 1, b: 2};
  42
  43 // Non-natural order by default.
  44 let obj = {1: a, 10: b, 2: c};
  45
  46 // This rule checks computed properties which have a simple name as well.
  47 let obj = {a: 1, ["b"]: 2, c: 3};
  48 let obj = {a: 1, [b]: 2, c: 3};
  49
  50 // This rule ignores computed properties which have a non-simple name.
  51 let obj = {a: 1, [c + d]: 3, b: 2};
  52 let obj = {a: 1, ["c" + "d"]: 3, b: 2};
  53 let obj = {a: 1, [`${c}`]: 3, b: 2};
  54 let obj = {a: 1, [tag`c`]: 3, b: 2};
  55
  56 // This rule does not report unsorted properties that are separated by a spread property.
  57 let obj = {b: 1, ...c, a: 2};
  58 ```
  59
  60 ## Options
  61
  62 ```json
  63 {
  64     "sort-keys": ["error", "asc", {"caseSensitive": true, "natural": false, "minKeys": 2}]
  65 }
  66 ```
  67
  68 The 1st option is `"asc"` or `"desc"`.
  69
  70 * `"asc"` (default) - enforce properties to be in ascending order.
  71 * `"desc"` - enforce properties to be in descending order.
  72
  73 The 2nd option is an object which has 3 properties.
  74
  75 * `caseSensitive` - if `true`, enforce properties to be in case-sensitive order. Default is `true`.
  76 * `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.
  77 * `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.
  78
  79 Example for a list:
  80
  81 With `natural` as true, the ordering would be
  82 1
  83 3
  84 6
  85 8
  86 10
  87
  88 With `natural` as false, the ordering would be
  89 1
  90 10
  91 3
  92 6
  93 8
  94
  95 ### desc
  96
  97 Examples of **incorrect** code for the `"desc"` option:
  98
  99 ```js
 100 /*eslint sort-keys: ["error", "desc"]*/
 101 /*eslint-env es6*/
 102
 103 let obj = {b: 2, c: 3, a: 1};
 104 let obj = {"b": 2, c: 3, a: 1};
 105
 106 // Case-sensitive by default.
 107 let obj = {C: 1, b: 3, a: 2};
 108
 109 // Non-natural order by default.
 110 let obj = {10: b, 2: c, 1: a};
 111 ```
 112
 113 Examples of **correct** code for the `"desc"` option:
 114
 115 ```js
 116 /*eslint sort-keys: ["error", "desc"]*/
 117 /*eslint-env es6*/
 118
 119 let obj = {c: 3, b: 2, a: 1};
 120 let obj = {c: 3, "b": 2, a: 1};
 121
 122 // Case-sensitive by default.
 123 let obj = {b: 3, a: 2, C: 1};
 124
 125 // Non-natural order by default.
 126 let obj = {2: c, 10: b, 1: a};
 127 ```
 128
 129 ### insensitive
 130
 131 Examples of **incorrect** code for the `{caseSensitive: false}` option:
 132
 133 ```js
 134 /*eslint sort-keys: ["error", "asc", {caseSensitive: false}]*/
 135 /*eslint-env es6*/
 136
 137 let obj = {a: 1, c: 3, C: 4, b: 2};
 138 let obj = {a: 1, C: 3, c: 4, b: 2};
 139 ```
 140
 141 Examples of **correct** code for the `{caseSensitive: false}` option:
 142
 143 ```js
 144 /*eslint sort-keys: ["error", "asc", {caseSensitive: false}]*/
 145 /*eslint-env es6*/
 146
 147 let obj = {a: 1, b: 2, c: 3, C: 4};
 148 let obj = {a: 1, b: 2, C: 3, c: 4};
 149 ```
 150
 151 ### natural
 152
 153 Examples of **incorrect** code for the `{natural: true}` option:
 154
 155 ```js
 156 /*eslint sort-keys: ["error", "asc", {natural: true}]*/
 157 /*eslint-env es6*/
 158
 159 let obj = {1: a, 10: c, 2: b};
 160 ```
 161
 162 Examples of **correct** code for the `{natural: true}` option:
 163
 164 ```js
 165 /*eslint sort-keys: ["error", "asc", {natural: true}]*/
 166 /*eslint-env es6*/
 167
 168 let obj = {1: a, 2: b, 10: c};
 169 ```
 170
 171 ### minKeys
 172
 173 Examples of **incorrect** code for the `{minKeys: 4}` option:
 174
 175 ```js
 176 /*eslint sort-keys: ["error", "asc", {minKeys: 4}]*/
 177 /*eslint-env es6*/
 178
 179 // 4 keys
 180 let obj = {
 181     b: 2,
 182     a: 1, // not sorted correctly (should be 1st key)
 183     c: 3,
 184     d: 4,
 185 };
 186
 187 // 5 keys
 188 let obj = {
 189     2: 'a',
 190     1: 'b', // not sorted correctly (should be 1st key)
 191     3: 'c',
 192     4: 'd',
 193     5: 'e',
 194 };
 195 ```
 196
 197 Examples of **correct** code for the `{minKeys: 4}` option:
 198
 199 ```js
 200 /*eslint sort-keys: ["error", "asc", {minKeys: 4}]*//
 201 /*eslint-env es6*/
 202
 203 // 3 keys
 204 let obj = {
 205     b: 2,
 206     a: 1,
 207     c: 3,
 208 };
 209
 210 // 2 keys
 211 let obj = {
 212     2: 'b',
 213     1: 'a',
 214 };
 215 ```
 216
 217 ## When Not To Use It
 218
 219 If you don't want to notify about properties' order, then it's safe to disable this rule.
 220
 221 ## Related Rules
 222
 223 * [sort-imports](sort-imports.md)
 224 * [sort-vars](sort-vars.md)
 225
 226 ## Compatibility
 227
 228 * **JSCS:** [validateOrderInObjectKeys](https://jscs-dev.github.io/rule/validateOrderInObjectKeys)