TypeScript Object Destructuring

Object destructuring is a syntax expression that extracts properties from an object and binds them to distinct local variables. In TypeScript, this mechanism is augmented with static type checking, allowing developers to enforce shape and type constraints on the extracted variables.

Basic Syntax

The destructuring assignment uses object literal syntax on the left-hand side of an assignment operation. (Note: Code examples are wrapped in block scopes { ... } to isolate variable declarations and prevent redeclaration errors in shared environments.)

{
  const user = { id: 1, name: "Alice" };
  const { id, name } = user;
}

Type Annotations

To apply TypeScript types to destructured variables, the type annotation must follow the entire destructuring pattern.

{
  const user = { id: 1, name: "Alice" };

  // Inline type annotation
  const { id, name }: { id: number; name: string } = user;
}

{
  // Using an interface or type alias
  interface User {
    id: number;
    name: string;
  }
  
  const user: User = { id: 1, name: "Alice" };
  const { id, name }: User = user;
}

Crucial Syntax Distinction: A common error in TypeScript is attempting to inline types directly within the destructuring pattern. In JavaScript destructuring, a colon : denotes property aliasing, not a type declaration.

{
  const user = { id: 1 };

  // ❌ INCORRECT: This renames 'id' to a local variable named 'number'
  // const { id: number } = user; 

  // ✅ CORRECT: This types the destructured object
  const { id }: { id: number } = user; 
}

Property Aliasing (Renaming)

You can bind an extracted property to a variable with a different name using the propertyName: localVariableName syntax.

{
  const user = { id: 1, name: "Alice" };
  const { id: userId, name: userName } = user;
}

Combined with type annotations, the syntax separates the aliasing (inside the braces) from the typing (after the braces):

{
  const user = { id: 1, name: "Alice" };
  const { id: userId, name: userName }: { id: number; name: string } = user;
}

Default Values

Default values can be assigned using the = operator. The default value is applied only if the extracted property is strictly undefined. To satisfy TypeScript’s strict type checking, the source object must be typed with the optional property.

{
  const partialUser: { id: number; name: string; role?: string } = { 
    id: 1, 
    name: "Alice" 
  };

  const { role = "guest" }: { role?: string } = partialUser;
}

Aliasing and default values can be combined. The alias precedes the default value assignment:

{
  const partialUser: { id: number; role?: string } = { id: 1 };
  const { role: userRole = "guest" }: { role?: string } = partialUser;
}

Assignment to Existing Variables

When destructuring into variables that have already been declared (without const, let, or var), the entire assignment statement must be wrapped in parentheses. Without parentheses, the JavaScript engine parses the opening brace { as the start of a block statement rather than an object literal, resulting in a syntax error.

{
  let id: number;
  let name: string;
  const user = { id: 1, name: "Alice" };

  // Parentheses are strictly required
  ({ id, name } = user);
}

Nested Destructuring

Destructuring can traverse nested object graphs to extract deeply nested properties.

{
  const config = { db: { host: "localhost", port: 5432 } };

  const { 
    db: { host, port } 
  }: { 
    db: { host: string; port: number } 
  } = config;
}

Rest Properties

The rest operator (...) collects all remaining enumerable own properties that were not explicitly destructured into a new object. A strict syntax rule dictates that the rest property must always be the very last element in the destructuring pattern.

{
  const user = { id: 1, name: "Alice", role: "admin", active: true };
  
  // '...metadata' must be the final element in the pattern
  const { id, name, ...metadata } = user;
  
  // 'id' and 'name' are extracted individually
  // 'metadata' is inferred as { role: string; active: boolean }
}

Function Parameter Destructuring

Destructuring is frequently applied directly within function signatures. The type annotation is applied to the parameter object as a whole.

{
  interface Payload {
    target: string;
    force?: boolean;
  }

  function execute({ target, force = false }: Payload): void {
    console.log(target, force);
  }
}