1 # Prefer destructuring from arrays and objects (prefer-destructuring)
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.
9 This rule takes two sets of configuration objects. The first object parameter determines what types of destructuring the rule applies to.
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.
13 Alternatively, you can use separate configurations for different assignment types. It accepts 2 other keys instead of `array` and `object`.
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`.
17 The rule has a second object with a single key, `enforceForRenamedProperties`, which determines whether the `object` destructuring applies to renamed variables.
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:
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.
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.
26 Examples of **incorrect** code for this rule:
29 // With `array` enabled
32 // With `object` enabled
34 var foo = object['foo'];
37 Examples of **correct** code for this rule:
40 // With `array` enabled
42 var foo = array[someIndex];
44 // With `object` enabled
53 Examples of **incorrect** code when `enforceForRenamedProperties` is enabled:
59 Examples of **correct** code when `enforceForRenamedProperties` is enabled:
62 var { bar: foo } = object;
65 Examples of additional **correct** code when `enforceForRenamedProperties` is enabled:
71 const bar = this.#x; // private identifiers are not allowed in destructuring
76 An example configuration, with the defaults `array` and `object` filled in, looks like this:
81 "prefer-destructuring": ["error", {
85 "enforceForRenamedProperties": false
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.
93 For example, the following configuration enforces only object destructuring, but not array destructuring:
98 "prefer-destructuring": ["error", {"object": true, "array": false}]
103 An example configuration, with the defaults `VariableDeclarator` and `AssignmentExpression` filled in, looks like this:
108 "prefer-destructuring": ["error", {
109 "VariableDeclarator": {
113 "AssignmentExpression": {
118 "enforceForRenamedProperties": false
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.
126 For example, the following configuration enforces object destructuring in variable declarations and enforces array destructuring in assignment expressions.
131 "prefer-destructuring": ["error", {
132 "VariableDeclarator": {
136 "AssignmentExpression": {
141 "enforceForRenamedProperties": false
148 Examples of **correct** code when object destructuring in `VariableDeclarator` is enforced:
151 /* eslint prefer-destructuring: ["error", {VariableDeclarator: {object: true}}] */
152 var {bar: foo} = object;
155 Examples of **correct** code when array destructuring in `AssignmentExpression` is enforced:
158 /* eslint prefer-destructuring: ["error", {AssignmentExpression: {array: true}}] */
162 ## When Not To Use It
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.
166 Additionally, if you intend to access large array indices directly, like:
169 var foo = array[100];
172 Then the `array` part of this rule is not recommended, as destructuring does not match this use case very well.
174 Or for non-iterable 'array-like' objects:
177 var $ = require('jquery');
178 var foo = $('body')[0];
179 var [bar] = $('body'); // fails with a TypeError
185 If you want to learn more about destructuring, check out the links below:
187 - [Destructuring Assignment (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)
188 - [Destructuring and parameter handling in ECMAScript 6 (2ality blog)](http://2ality.com/2015/01/es6-destructuring.html)