Nivel inicial10 min de lectura · Publicado el

Destructuring o desestructuración en JavaScript

Asignación por destructuring en JavaScript: de la bolsa persona salen 'Ana' y 30 directos a nombre y edad. Cada valor, a su variablerubentejera.com personanombre'Ana'edad30const { nombre, edad } = persona;
Como vaciar la bolsa de la compra: la bolsa es el objeto persona y cada cosa va directa a su sitio. Con const { nombre, edad } = persona, 'Ana' acaba en nombre y 30 en edad, en una sola línea.

Piensa en vaciar la bolsa de la compra: en vez de decir «el primer objeto de la bolsa es la leche, el segundo es el pan», sacas cada cosa y la pones directamente en su sitio. El destructuring hace eso con los datos: los sacas del array u objeto y cada uno va a su variable.

Desestructuración de arrays: por posición

El ejemplo original de este artículo:

let [var1, var2] = [44, 42];
console.log("var1-->", var1);   // var1--> 44
console.log("var2-->", var2);   // var2--> 42

var1 recibe el primer valor y var2, el segundo. Más cosas que puedes hacer:

const [primero, , tercero] = ['a', 'b', 'c'];  // saltar uno: 'a', 'c'
const [cabeza, ...resto] = [1, 2, 3, 4];       // cabeza = 1, resto = [2, 3, 4]
const [x = 10, y = 20] = [5];                  // x = 5, y = 20 (valor por defecto)

Intercambiar dos variables

Sin destructuring necesitas una variable auxiliar, como cuando cambias el contenido de dos vasos y usas un tercero. Con destructuring se hace en una línea:

let a = 1, b = 2;
[a, b] = [b, a];
console.log(a, b);   // 2 1

A la derecha se crea un array nuevo con los valores de antes, [2, 1], y a la izquierda se reparte entre a y b.

Devolver varios valores de una función

Una función solo devuelve una cosa, pero puede ser un array. Con destructuring lo recoges con nombre:

function minMax(numeros) {
  return [Math.min(...numeros), Math.max(...numeros)];
}

const [min, max] = minMax([3, 9, 1]);
console.log(min, max);   // 1 9

Desestructuración de objetos: por nombre

En los objetos no importa el orden, sino el nombre de la propiedad:

const persona = { nombre: 'Ana', edad: 30, ciudad: 'Las Palmas' };

const { nombre, edad } = persona;                    // 'Ana', 30
const { ciudad: lugar, pais = 'España' } = persona;  // renombrar y valor por defecto
const { nombre: n, ...otros } = persona;             // otros = { edad: 30, ciudad: 'Las Palmas' }
Quieres… Array Objeto
Sacar valores [a, b] = arr { a, b } = obj
Valor por defecto [a = 1] = arr { a = 1 } = obj
Renombrar No aplica (eliges el nombre) { a: otroNombre } = obj
El resto [a, ...resto] = arr { a, ...resto } = obj

El valor por defecto solo cubre undefined

El valor por defecto se usa cuando la propiedad falta o vale undefined. Si vale null, se queda null:

const { a = 1, b = 2 } = { a: null, b: undefined };
console.log(a, b);   // null 2

Es como la nota «si no hay pan, compra»: si la bolsa del pan está, aunque vacía, nadie compra. Si el dato puede llegar como null y quieres sustituirlo, usa ?? después: const ciudad = datos.ciudad ?? 'Sin ciudad';.

Objetos dentro de objetos

Puedes bajar varios niveles de una vez:

const pedido = { id: 7, cliente: { nombre: 'Ana', direccion: { ciudad: 'Las Palmas' } } };

const { cliente: { direccion: { ciudad } } } = pedido;
console.log(ciudad);   // Las Palmas

Aquí solo se crea la variable ciudad: cliente y direccion son el camino, no variables. Úsalo con moderación: más de dos niveles se leen mal.

Donde más se usa

En los parámetros de una función, para recibir un objeto de opciones:

function saludar({ nombre, edad = 0 } = {}) {
  return `${nombre} tiene ${edad} años`;
}

saludar({ nombre: 'Ana', edad: 30 });   // 'Ana tiene 30 años'
saludar({ nombre: 'Luis' });            // 'Luis tiene 0 años'
saludar();                              // 'undefined tiene 0 años'

El = {} del final es el valor por defecto del parámetro entero: si llamas a saludar() sin nada, desestructura un objeto vacío en lugar de undefined. Sin él, esa llamada lanza un error (lo verás en el apartado siguiente).

Y al recorrer un objeto con Object.entries:

for (const [clave, valor] of Object.entries({ uno: 1, dos: 2 })) {
  console.log(clave, valor);   // uno 1, dos 2
}

Errores frecuentes

1. Desestructurar undefined o null. Es el más habitual: el dato que esperabas no ha llegado. Si quitas el = {} de saludar y la llamas sin argumentos:

function saludar({ nombre, edad = 0 }) {
  return `${nombre} tiene ${edad} años`;
}

saludar();
function saludar({ nombre, edad = 0 }) {
                   ^

TypeError: Cannot destructure property 'nombre' of 'undefined' as it is undefined.

Con una variable, el mensaje dice su nombre (of 'datos' as it is undefined.), y con null cambia el final: const { z } = null; lanza TypeError: Cannot destructure property 'z' of 'null' as it is null. La solución es dar un valor por defecto: = {} en un parámetro, o ?? {} al desestructurar una variable:

const datos = undefined;
const { z } = datos ?? {};
console.log(z);   // undefined, sin error

2. Desestructurar como array algo que no lo es. Con corchetes, JavaScript necesita algo que se pueda recorrer en orden (un array, un texto…). Un objeto no lo es:

const persona = { nombre: 'Ana', edad: 30 };
const [primero] = persona;
TypeError: persona is not iterable

Con undefined o null, el mensaje es undefined is not iterable o null is not iterable. Para objetos, usa llaves.

3. Bajar a un nivel que no existe. El valor por defecto no te protege si falta un objeto intermedio:

const { direccion: { ciudad } } = { nombre: 'Ana' };
TypeError: Cannot read properties of undefined (reading 'ciudad')

Da un valor por defecto al nivel intermedio:

const { direccion: { ciudad } = {} } = { nombre: 'Ana' };
console.log(ciudad);   // undefined, sin error

4. Asignar a variables que ya existen sin paréntesis. Si la línea empieza por una llave, JavaScript cree que abres un bloque de código:

let nombre;
{ nombre } = { nombre: 'Ana' };
SyntaxError: Unexpected token '='

Rodea toda la asignación con paréntesis: ({ nombre } = { nombre: 'Ana' });. Con arrays no pasa, porque un corchete no abre un bloque.

5. Poner el resto en medio. ...resto recoge «lo que sobra», así que solo puede ir al final:

const [...resto, ultimo] = [1, 2, 3];
SyntaxError: Rest element must be last element

Si necesitas el último elemento, usa arr.at(-1).

Compruébalo con un test

Si una función recibe un objeto de opciones, un test deja escrito qué pasa cuando falta algo. Con node:test, que viene con Node:

// destructuring.test.js
const test = require('node:test');
const assert = require('node:assert');

function saludar({ nombre, edad = 0 } = {}) {
  return `${nombre} tiene ${edad} años`;
}

test('usa el valor por defecto si falta la edad', () => {
  assert.strictEqual(saludar({ nombre: 'Luis' }), 'Luis tiene 0 años');
});

test('sin argumento no lanza TypeError', () => {
  assert.doesNotThrow(() => saludar());
});

test('desestructurar undefined lanza TypeError', () => {
  assert.throws(() => {
    const { nombre } = undefined;
  }, TypeError);
});
node --test
✔ usa el valor por defecto si falta la edad (0.697639ms)
✔ sin argumento no lanza TypeError (0.181285ms)
✔ desestructurar undefined lanza TypeError (0.3729ms)
ℹ tests 3

Quita el = {} de saludar y vuelve a ejecutarlo: el segundo test falla y te avisa antes de que el error llegue a producción.

Cuándo no usarlo

  • Cuando solo usas un valor una vez. persona.nombre se lee igual de bien que sacar nombre antes. El destructuring compensa cuando usas varios valores o los usas varias veces.
  • Cuando anidas demasiado. Tres niveles de llaves en una línea obligan a leerla dos veces. Desestructura por pasos o accede con ?. (pedido.cliente?.direccion?.ciudad), que además no falla si falta un nivel.
  • Para copiar un objeto «en profundidad». const { ...copia } = original solo copia el primer nivel: los objetos de dentro se siguen compartiendo. Lo tienes explicado en paso por referencia y paso por valor en JavaScript.

Ejercicio de cinco minutos

  1. Escribe una función crearUsuario({ nombre, rol = 'lector', activo = true } = {}) que devuelva un objeto con esos tres campos.
  2. Añade un test que la llame sin argumentos y compruebe que rol es 'lector', y otro que le pase { rol: null }. ¿Qué rol esperas? Ejecútalo y compruébalo.
  3. Intercambia dos variables con [a, b] = [b, a] y escribe un test que lo compruebe.

La página de MDN: qué encontrarás

El artículo original enlazaba a la referencia de MDN, la documentación de JavaScript de Mozilla. Es la página a la que acudir cuando necesites el detalle:

  • Pruébalo: un ejemplo editable para ver el resultado sin salir de la página.
  • Sintaxis y descripción: todas las formas válidas, también las menos habituales.
  • Ejemplos: separados en desestructuración de arreglos y de objetos.
  • Compatibilidad: la función es Baseline ampliamente disponible, es decir, funciona en todos los navegadores principales desde agosto de 2016. Hoy no necesitas ninguna precaución para usarla.

La versión en español está traducida por la comunidad. Si algo no cuadra, compárala con la versión en inglés, que es la original.

Para practicarlo, tienes la guía de katas de ES6. Y si quieres ver el destructuring junto al resto de la sintaxis moderna, mira la cheatsheet de JavaScript.

Fuentes

  • MDN, Asignación por desestructuración (la URL antigua del artículo, en /Referencia/Operadores/, redirige aquí): secciones, estado Baseline y aviso de traducción comunitaria. Última modificación de la página en español, comprobada el 7 de noviembre de 2026: 29 de mayo de 2026.
  • MDN, Destructuring, versión original en inglés: valores por defecto solo con undefined, paréntesis en la asignación sin declaración y el resto al final.

Ejecutado el 12 de noviembre de 2026 en Docker con las imágenes oficiales node:24 (Node 24.22.3) y node:26 (Node 26.13.1), con el mismo resultado en las dos: todos los ejemplos (los comentarios muestran la salida real), los cinco errores con su mensaje y el test con node --test.