TypeScript Destructured Parameter

A destructured parameter in TypeScript is a function parameter that utilizes JavaScript’s destructuring assignment syntax to unpack object properties or array elements directly within the function signature, coupled with a TypeScript type annotation to enforce the shape of the unpacked data. In TypeScript, the destructuring pattern and the type annotation must be declared separately. The type annotation applies to the entire parameter object or array, not to the individual destructured variables.

Object Destructuring Syntax

The standard syntax requires defining the destructuring pattern first, followed by a colon, and then the type literal or interface.

function processUser({ name, age }: { name: string; age: number }): void {
    console.log(name, age);
}

Crucial Syntax Distinction: A common error is attempting to inline the type annotations directly within the destructuring pattern. In JavaScript, a colon inside a destructuring pattern indicates variable renaming, not type assignment.

// INCORRECT: This renames the property 'name' to a local variable called 'string'.
// It results in an implicit 'any' type error in strict mode.
function processUserIncorrect({ name: string, age: number }) { }

// CORRECT: Renaming a variable while providing the correct type annotation.
function processUserCorrect({ name: userName }: { name: string }): void {
    console.log(userName);
}

Using Type Aliases and Interfaces

To prevent function signatures from becoming overly verbose, the type annotation is typically extracted into a type alias or interface.

interface UserPayload {
    name: string;
    age: number;
    isActive?: boolean;
}

function processUserPayload({ name, age, isActive }: UserPayload): void {
    // ...
}

Default Values

Default values can be assigned at two distinct levels within a destructured parameter: at the property level and at the parameter level. 1. Property-level defaults: Assigned within the destructuring pattern. The type annotation must mark these properties as optional (?) if the caller is allowed to omit them.

function configure({ host = "localhost", port = 80 }: { host?: string; port?: number }): void {
    // ...
}

2. Parameter-level defaults: Assigned after the type annotation. This prevents a TypeError if the function is called with no arguments at all.

function configureWithFallback({ host = "localhost", port = 80 }: { host?: string; port?: number } = {}): void {
    // ...
}

configureWithFallback(); // Valid. Defaults to {} which then triggers property defaults.

Array Destructuring Syntax

Array destructured parameters follow the same principle but utilize tuple types for the annotation to ensure positional type safety.

function setCoordinates([x, y, z]: [number, number, number?]): void {
    // ...
}

Rest Elements in Destructured Parameters

The rest operator (...) can be used to gather remaining properties or elements. The type annotation must account for the types of these remaining properties.

interface Config {
    id: string;
    retries: number;
    timeout: number;
}

function initialize({ id, ...options }: Config): void {
    // 'id' is typed as string
    // 'options' is implicitly typed as { retries: number; timeout: number; }
}