eslint/docs/rules/prefer-destructuring.md

   1 # Prefer destructuring from arrays and objects (prefer-destructuring)
   2
   3 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.
   4
   5 ## Rule Details
   6
   7 ### Options
   8
   9 This rule takes two sets of configuration objects. The first object parameter determines what types of destructuring the rule applies to.
  10
  11 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.
  12
  13 Alternatively, you can use separate configurations for different assignment types. It accepts 2 other keys instead of `array` and `object`.
  14
  15 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`.
  16
  17 The rule has a second object with a single key, `enforceForRenamedProperties`, which determines whether the `object` destructuring applies to renamed variables.
  18
  19 **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:
  20
  21 - Accessing an object property whose key is an integer will fall under the category `array` destructuring.
  22 - Accessing an array element through a computed index will fall under the category `object` destructuring.
  23
  24 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.
  25
  26 Examples of **incorrect** code for this rule:
  27
  28 ```javascript
  29 // With `array` enabled
  30 var foo = array[0];
  31
  32 // With `object` enabled
  33 var foo = object.foo;
  34 var foo = object['foo'];
  35 ```
  36
  37 Examples of **correct** code for this rule:
  38
  39 ```javascript
  40 // With `array` enabled
  41 var [ foo ] = array;
  42 var foo = array[someIndex];
  43
  44 // With `object` enabled
  45 var { foo } = object;
  46
  47 var foo = object.bar;
  48
  49 let foo;
  50 ({ foo } = object);
  51 ```
  52
  53 Examples of **incorrect** code when `enforceForRenamedProperties` is enabled:
  54
  55 ```javascript
  56 var foo = object.bar;
  57 ```
  58
  59 Examples of **correct** code when `enforceForRenamedProperties` is enabled:
  60
  61 ```javascript
  62 var { bar: foo } = object;
  63 ```
  64
  65 Examples of additional **correct** code when `enforceForRenamedProperties` is enabled:
  66
  67 ```javascript
  68 class C {
  69     #x;
  70     foo() {
  71         const bar = this.#x; // private identifiers are not allowed in destructuring
  72     }
  73 }
  74 ```
  75
  76 An example configuration, with the defaults `array` and `object` filled in, looks like this:
  77
  78 ```json
  79 {
  80   "rules": {
  81     "prefer-destructuring": ["error", {
  82       "array": true,
  83       "object": true
  84     }, {
  85       "enforceForRenamedProperties": false
  86     }]
  87   }
  88 }
  89 ```
  90
  91 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.
  92
  93 For example, the following configuration enforces only object destructuring, but not array destructuring:
  94
  95 ```json
  96 {
  97   "rules": {
  98     "prefer-destructuring": ["error", {"object": true, "array": false}]
  99   }
 100 }
 101 ```
 102
 103 An example configuration, with the defaults `VariableDeclarator` and `AssignmentExpression` filled in, looks like this:
 104
 105 ```json
 106 {
 107   "rules": {
 108     "prefer-destructuring": ["error", {
 109       "VariableDeclarator": {
 110         "array": false,
 111         "object": true
 112       },
 113       "AssignmentExpression": {
 114         "array": true,
 115         "object": true
 116       }
 117     }, {
 118       "enforceForRenamedProperties": false
 119     }]
 120   }
 121 }
 122 ```
 123
 124 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.
 125
 126 For example, the following configuration enforces object destructuring in variable declarations and enforces array destructuring in assignment expressions.
 127
 128 ```json
 129 {
 130   "rules": {
 131     "prefer-destructuring": ["error", {
 132       "VariableDeclarator": {
 133         "array": false,
 134         "object": true
 135       },
 136       "AssignmentExpression": {
 137         "array": true,
 138         "object": false
 139       }
 140     }, {
 141       "enforceForRenamedProperties": false
 142     }]
 143   }
 144 }
 145
 146 ```
 147
 148 Examples of **correct** code when object destructuring in `VariableDeclarator` is enforced:
 149
 150 ```javascript
 151 /* eslint prefer-destructuring: ["error", {VariableDeclarator: {object: true}}] */
 152 var {bar: foo} = object;
 153 ```
 154
 155 Examples of **correct** code when array destructuring in `AssignmentExpression` is enforced:
 156
 157 ```javascript
 158 /* eslint prefer-destructuring: ["error", {AssignmentExpression: {array: true}}] */
 159 [bar] = array;
 160 ```
 161
 162 ## When Not To Use It
 163
 164 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.
 165
 166 Additionally, if you intend to access large array indices directly, like:
 167
 168 ```javascript
 169 var foo = array[100];
 170 ```
 171
 172 Then the `array` part of this rule is not recommended, as destructuring does not match this use case very well.
 173
 174 Or for non-iterable 'array-like' objects:
 175
 176 ```javascript
 177 var $ = require('jquery');
 178 var foo = $('body')[0];
 179 var [bar] = $('body'); // fails with a TypeError
 180 ```
 181
 182 ## Further Reading
 183
 184 If you want to learn more about destructuring, check out the links below:
 185
 186 - [Destructuring Assignment (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)
 187 - [Destructuring and parameter handling in ECMAScript 6 (2ality blog)](http://2ality.com/2015/01/es6-destructuring.html)