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 An example configuration, with the defaults `array` and `object` filled in, looks like this:
  66
  67 ```json
  68 {
  69   "rules": {
  70     "prefer-destructuring": ["error", {
  71       "array": true,
  72       "object": true
  73     }, {
  74       "enforceForRenamedProperties": false
  75     }]
  76   }
  77 }
  78 ```
  79
  80 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.
  81
  82 For example, the following configuration enforces only object destructuring, but not array destructuring:
  83
  84 ```json
  85 {
  86   "rules": {
  87     "prefer-destructuring": ["error", {"object": true, "array": false}]
  88   }
  89 }
  90 ```
  91
  92 An example configuration, with the defaults `VariableDeclarator` and `AssignmentExpression` filled in, looks like this:
  93
  94 ```json
  95 {
  96   "rules": {
  97     "prefer-destructuring": ["error", {
  98       "VariableDeclarator": {
  99         "array": false,
 100         "object": true
 101       },
 102       "AssignmentExpression": {
 103         "array": true,
 104         "object": true
 105       }
 106     }, {
 107       "enforceForRenamedProperties": false
 108     }]
 109   }
 110 }
 111 ```
 112
 113 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.
 114
 115 For example, the following configuration enforces object destructuring in variable declarations and enforces array destructuring in assignment expressions.
 116
 117 ```json
 118 {
 119   "rules": {
 120     "prefer-destructuring": ["error", {
 121       "VariableDeclarator": {
 122         "array": false,
 123         "object": true
 124       },
 125       "AssignmentExpression": {
 126         "array": true,
 127         "object": false
 128       }
 129     }, {
 130       "enforceForRenamedProperties": false
 131     }]
 132   }
 133 }
 134
 135 ```
 136
 137 Examples of **correct** code when object destructuring in `VariableDeclarator` is enforced:
 138
 139 ```javascript
 140 /* eslint prefer-destructuring: ["error", {VariableDeclarator: {object: true}}] */
 141 var {bar: foo} = object;
 142 ```
 143
 144 Examples of **correct** code when array destructuring in `AssignmentExpression` is enforced:
 145
 146 ```javascript
 147 /* eslint prefer-destructuring: ["error", {AssignmentExpression: {array: true}}] */
 148 [bar] = array;
 149 ```
 150
 151 ## When Not To Use It
 152
 153 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.
 154
 155 Additionally, if you intend to access large array indices directly, like:
 156
 157 ```javascript
 158 var foo = array[100];
 159 ```
 160
 161 Then the `array` part of this rule is not recommended, as destructuring does not match this use case very well.
 162
 163 Or for non-iterable 'array-like' objects:
 164
 165 ```javascript
 166 var $ = require('jquery');
 167 var foo = $('body')[0];
 168 var [bar] = $('body'); // fails with a TypeError
 169 ```
 170
 171
 172 ## Further Reading
 173
 174 If you want to learn more about destructuring, check out the links below:
 175
 176 - [Destructuring Assignment (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)
 177 - [Destructuring and parameter handling in ECMAScript 6 (2ality blog)](http://2ality.com/2015/01/es6-destructuring.html)