Object Destructuring

Object destructuring is a syntactic expression in JavaScript that allows the extraction of properties from an object and their immediate assignment to distinct local variables. It utilizes an object literal-like syntax on the left-hand side of an assignment operation to map property keys to variable identifiers.

Basic Syntax

By default, the declared variable identifier must exactly match the property key of the source object.

const user = { id: 42, handle: 'dev_user' };

const { id, handle } = user;
// id === 42
// handle === 'dev_user'

Destructuring null or undefined

Attempting to destructure null or undefined throws a runtime TypeError. During destructuring, the JavaScript engine implicitly calls the internal ToObject() method on the right-hand side value, which fails for null and undefined.

const { id } = null; 
// TypeError: Cannot destructure property 'id' of 'null' as it is null.

const { name } = undefined; 
// TypeError: Cannot destructure property 'name' of 'undefined' as it is undefined.

Aliasing (Assigning to New Variable Names)

To assign an extracted property to a variable with a different name, use the sourceKey: targetVariable syntax.

const user = { id: 42 };

const { id: userId } = user;
// userId === 42
// 'id' is not defined as a variable

Computed Property Names

Object destructuring supports computed property names via bracket notation, allowing property extraction using dynamic keys evaluated at runtime. When using a computed property name, a target variable alias must be explicitly provided.

const dynamicKey = 'handle';
const user = { id: 42, handle: 'dev_user' };

const { [dynamicKey]: userHandle } = user;
// userHandle === 'dev_user'

Default Values

A variable can be assigned a default value, which will be used if the extracted property is strictly undefined (it will not trigger on null or falsy values).

const user = { id: 42, role: undefined };

const { role = 'guest', status = 'active' } = user;
// role === 'guest'
// status === 'active'

Aliasing with Default Values

Aliasing and default values can be combined. The syntax evaluates left-to-right: sourceKey: targetVariable = defaultValue.

const user = { id: 42 };

const { id: userId = 0, role: userRole = 'guest' } = user;
// userId === 42
// userRole === 'guest'

Nested Destructuring

Destructuring can traverse nested object structures. Only the innermost identifiers are declared as variables; the intermediate keys act solely as traversal paths.

const user = { 
  id: 42, 
  profile: { 
    email: '[e-mail]' 
  } 
};

const { profile: { email } } = user;
// email === '[e-mail]'
// 'profile' is not defined as a variable

Function Parameter Destructuring

Destructuring patterns can be applied directly within a function’s parameter list. This unpacks the properties of an object passed as an argument into local variables scoped to the function’s execution context.

const user = { id: 42, handle: 'dev_user' };

function getUserHandle({ handle }) {
  return handle;
}

getUserHandle(user); // Returns 'dev_user'

The Rest Property (...)

The rest syntax collects all remaining enumerable own properties that were not explicitly destructured into a new object. It must be the final element in the destructuring pattern.

const user = { id: 42, handle: 'dev_user', role: 'admin' };

const { id, ...metadata } = user;
// id === 42
// metadata === { handle: 'dev_user', role: 'admin' }

Assignment Without Declaration

Destructuring can be applied to previously declared variables. However, the entire assignment statement must be wrapped in parentheses. Without parentheses, the JavaScript engine parses the leading { as the start of a block statement rather than an object literal pattern, resulting in a syntax error.

let id, handle;
const user = { id: 42, handle: 'dev_user' };

({ id, handle } = user);

Master JavaScript with Deep Grasping Methodology!

Learn More