eslint/docs/src/rules/prefer-destructuring.md

   1 ---
   2 title: prefer-destructuring
   3 layout: doc
   4 rule_type: suggestion
   5 further_reading:
   6 - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
   7 - https://2ality.com/2015/01/es6-destructuring.html
   8 ---
   9
  10
  11
  12 With JavaScript ES6, a new syntax was added for creating variables from an array index or object property, called [destructuring](#further-reading).  This rule enforces usage of destructuring instead of accessing a property through a member expression.
  13
  14 ## Rule Details
  15
  16 ### Options
  17
  18 This rule takes two sets of configuration objects. The first object parameter determines what types of destructuring the rule applies to.
  19
  20 The two properties, `array` and `object`, can be used to turn on or off the destructuring requirement for each of those types independently. By default, both are true.
  21
  22 Alternatively, you can use separate configurations for different assignment types. It accepts 2 other keys instead of `array` and `object`.
  23
  24 One key is `VariableDeclarator` and the other is `AssignmentExpression`, which can be used to control the destructuring requirement for each of those types independently. Each property accepts an object that accepts two properties, `array` and `object`, which can be used to control the destructuring requirement for each of `array` and `object` independently for variable declarations and assignment expressions.  By default, `array` and `object` are set to true for both `VariableDeclarator` and `AssignmentExpression`.
  25
  26 The rule has a second object with a single key, `enforceForRenamedProperties`, which determines whether the `object` destructuring applies to renamed variables.
  27
  28 **Note**: It is not possible to determine if a variable will be referring to an object or an array at runtime. This rule therefore guesses the assignment type by checking whether the key being accessed is an integer. This can lead to the following possibly confusing situations:
  29
  30 * Accessing an object property whose key is an integer will fall under the category `array` destructuring.
  31 * Accessing an array element through a computed index will fall under the category `object` destructuring.
  32
  33 The `--fix` option on the command line fixes only problems reported in variable declarations, and among them only those that fall under the category `object` destructuring. Furthermore, the name of the declared variable has to be the same as the name used for non-computed member access in the initializer. For example, `var foo = object.foo` can be automatically fixed by this rule. Problems that involve computed member access (e.g., `var foo = object[foo]`) or renamed properties (e.g., `var foo = object.bar`) are not automatically fixed.
  34
  35 Examples of **incorrect** code for this rule:
  36
  37 ::: incorrect
  38
  39 ```javascript
  40 // With `array` enabled
  41 var foo = array[0];
  42
  43 // With `object` enabled
  44 var foo = object.foo;
  45 var foo = object['foo'];
  46 ```
  47
  48 :::
  49
  50 Examples of **correct** code for this rule:
  51
  52 ::: correct
  53
  54 ```javascript
  55 // With `array` enabled
  56 var [ foo ] = array;
  57 var foo = array[someIndex];
  58
  59 // With `object` enabled
  60 var { foo } = object;
  61
  62 var foo = object.bar;
  63
  64 let foo;
  65 ({ foo } = object);
  66 ```
  67
  68 :::
  69
  70 Examples of **incorrect** code when `enforceForRenamedProperties` is enabled:
  71
  72 ::: incorrect
  73
  74 ```javascript
  75 var foo = object.bar;
  76 ```
  77
  78 :::
  79
  80 Examples of **correct** code when `enforceForRenamedProperties` is enabled:
  81
  82 ::: correct
  83
  84 ```javascript
  85 var { bar: foo } = object;
  86 ```
  87
  88 :::
  89
  90 Examples of additional **correct** code when `enforceForRenamedProperties` is enabled:
  91
  92 ::: correct
  93
  94 ```javascript
  95 class C {
  96     #x;
  97     foo() {
  98         const bar = this.#x; // private identifiers are not allowed in destructuring
  99     }
 100 }
 101 ```
 102
 103 :::
 104
 105 An example configuration, with the defaults `array` and `object` filled in, looks like this:
 106
 107 ```json
 108 {
 109   "rules": {
 110     "prefer-destructuring": ["error", {
 111       "array": true,
 112       "object": true
 113     }, {
 114       "enforceForRenamedProperties": false
 115     }]
 116   }
 117 }
 118 ```
 119
 120 The two properties, `array` and `object`, which can be used to turn on or off the destructuring requirement for each of those types independently. By default, both are true.
 121
 122 For example, the following configuration enforces only object destructuring, but not array destructuring:
 123
 124 ```json
 125 {
 126   "rules": {
 127     "prefer-destructuring": ["error", {"object": true, "array": false}]
 128   }
 129 }
 130 ```
 131
 132 An example configuration, with the defaults `VariableDeclarator` and `AssignmentExpression` filled in, looks like this:
 133
 134 ```json
 135 {
 136   "rules": {
 137     "prefer-destructuring": ["error", {
 138       "VariableDeclarator": {
 139         "array": false,
 140         "object": true
 141       },
 142       "AssignmentExpression": {
 143         "array": true,
 144         "object": true
 145       }
 146     }, {
 147       "enforceForRenamedProperties": false
 148     }]
 149   }
 150 }
 151 ```
 152
 153 The two properties, `VariableDeclarator` and `AssignmentExpression`, which can be used to turn on or off the destructuring requirement for `array` and `object`. By default, all values are true.
 154
 155 For example, the following configuration enforces object destructuring in variable declarations and enforces array destructuring in assignment expressions.
 156
 157 ```json
 158 {
 159   "rules": {
 160     "prefer-destructuring": ["error", {
 161       "VariableDeclarator": {
 162         "array": false,
 163         "object": true
 164       },
 165       "AssignmentExpression": {
 166         "array": true,
 167         "object": false
 168       }
 169     }, {
 170       "enforceForRenamedProperties": false
 171     }]
 172   }
 173 }
 174
 175 ```
 176
 177 Examples of **correct** code when object destructuring in `VariableDeclarator` is enforced:
 178
 179 ::: correct
 180
 181 ```javascript
 182 /* eslint prefer-destructuring: ["error", {VariableDeclarator: {object: true}}] */
 183 var {bar: foo} = object;
 184 ```
 185
 186 :::
 187
 188 Examples of **correct** code when array destructuring in `AssignmentExpression` is enforced:
 189
 190 ::: correct
 191
 192 ```javascript
 193 /* eslint prefer-destructuring: ["error", {AssignmentExpression: {array: true}}] */
 194 [bar] = array;
 195 ```
 196
 197 :::
 198
 199 ## When Not To Use It
 200
 201 If you want to be able to access array indices or object properties directly, you can either configure the rule to your tastes or disable the rule entirely.
 202
 203 Additionally, if you intend to access large array indices directly, like:
 204
 205 ```javascript
 206 var foo = array[100];
 207 ```
 208
 209 Then the `array` part of this rule is not recommended, as destructuring does not match this use case very well.
 210
 211 Or for non-iterable 'array-like' objects:
 212
 213 ```javascript
 214 var $ = require('jquery');
 215 var foo = $('body')[0];
 216 var [bar] = $('body'); // fails with a TypeError
 217 ```