Serialización con JSON.stringify()
Aprende a convertir objetos JavaScript a strings JSON para almacenamiento y transmisión de datos, incluyendo formateo y filtrado avanzado.
TL;DR - Resumen rápido
- JSON.stringify() convierte objetos JavaScript a strings JSON válidos
- El segundo parámetro 'replacer' permite filtrar o transformar propiedades
- El tercer parámetro 'space' controla el formateo y sangría del resultado
- Propiedades como undefined, funciones y Symbol se omiten en la serialización
- Los objetos Date se convierten a strings ISO 8601 automáticamente
Introducción a JSON.stringify()
JSON.stringify() es el método fundamental en JavaScript para serializar objetos JavaScript a strings JSON. Esta conversión es esencial para almacenar datos en localStorage, enviar información a servidores, o guardar configuraciones en archivos. El método transforma estructuras de datos complejas en un formato de texto universalmente comprensible.
La serialización es el proceso de convertir un objeto en memoria a un formato que puede ser almacenado o transmitido. JSON (JavaScript Object Notation) se ha convertido en el estándar de facto para este propósito, con casos de uso que incluyen:
- <strong>Almacenamiento local</strong>: Guardar datos en localStorage o sessionStorage del navegador
- <strong>APIs REST</strong>: Enviar y recibir datos entre cliente y servidor vía HTTP
- <strong>Archivos de configuración</strong>: Almacenar settings de aplicaciones en formato legible
- <strong>Logs y debugging</strong>: Registrar el estado de objetos para análisis posterior
¿Por qué JSON y no otro formato?
JSON es ligero, legible por humanos y no requiere parsers complejos. A diferencia de XML, JSON es más conciso y tiene una estructura que se mapea naturalmente a objetos JavaScript. Esto lo hace ideal para APIs web y almacenamiento local.
Sintaxis Básica
La forma más simple de usar JSON.stringify() es pasando únicamente el objeto que deseas serializar. Esto producirá una representación JSON compacta sin espacios ni saltos de línea, ideal para transmisión de datos donde el tamaño importa.
El ejemplo muestra cómo JSON.stringify() convierte un objeto JavaScript anidado en un string JSON válido. Observa que las comillas dobles son obligatorias en JSON, a diferencia de JavaScript donde puedes usar comillas simples o dobles. El resultado es un string que puede ser transmitido por HTTP, guardado en localStorage, o almacenado en una base de datos como texto.
Parámetro space: Formateo Legible
El tercer parámetro opcional de JSON.stringify() permite controlar el formateo del resultado. Puedes especificar un número de espacios para indentación o un string que se usará como prefijo en cada nivel de anidación. Esto es especialmente útil para debugging y archivos de configuración que deben ser legibles por humanos.
El parámetro space acepta un número (máximo 10 espacios) o un string. Cuando es un número, indica cuántos espacios usar para indentación. Cuando es un string, ese string se usa como prefijo. En el ejemplo, usamos 2 espacios para crear un formato legible, mientras que con '\t' usamos tabuladores. El valor 0 produce el mismo resultado que no especificar el parámetro: un JSON compacto sin formateo.
Parámetro replacer: Filtrado y Transformación
El segundo parámetro de JSON.stringify() es una función o array que controla qué propiedades se incluyen en la serialización. Cuando es un array, solo las propiedades listadas se incluirán en el resultado. Cuando es una función, se llama para cada propiedad, permitiendo filtrar, transformar o modificar valores dinámicamente.
Cuando usas un array como replacer, solo las propiedades enumeradas en el array se incluirán en el JSON resultante. El orden de las propiedades en el array determina el orden en que aparecen en el resultado, lo cual es útil para consistencia en APIs o archivos de configuración. En el ejemplo, filtramos para incluir solo 'nombre', 'email' y 'rol', excluyendo 'password' y 'id' que contienen información sensible.
Mejor práctica: Filtrado de datos sensibles
Usa el parámetro replacer para excluir automáticamente propiedades sensibles como passwords, tokens, o información personal al serializar objetos. Esto previene fugas accidentales de información cuando se envían datos a logs o APIs de terceros.
Replacer como Función
Cuando el replacer es una función, recibe dos argumentos: la clave y el valor de cada propiedad. La función puede retornar el valor modificado, undefined para omitir la propiedad, o cualquier otro valor JSON válido. Esto permite transformaciones más complejas que un simple array de propiedades.
La función replacer se llama recursivamente para cada propiedad, incluyendo propiedades anidadas. En el ejemplo, filtramos propiedades que empiezan con '_' (convención para propiedades privadas), convertimos fechas a timestamps, y omitimos valores undefined. Este patrón es útil para serializar objetos de manera consistente mientras excluyes datos internos o temporales.
Casos Especiales y Limitaciones
JSON.stringify() tiene comportamientos específicos con ciertos tipos de datos que es importante conocer. Algunos valores se transforman automáticamente, otros se omiten, y algunos causan errores. Entender estos casos edge es crucial para evitar bugs inesperados en producción.
Los siguientes tipos de datos tienen un comportamiento especial durante la serialización:
- <strong>Omitidos</strong>: undefined, functions y Symbols se excluyen completamente del resultado
- <strong>Convertidos a null</strong>: NaN, Infinity y -Infinity se serializan como null
- <strong>Transformados</strong>: Date se convierte a string ISO 8601, BigInt debe manejarse con replacer
- <strong>Vacíos</strong>: RegExp, Error, Map y Set se convierten a objetos vacíos {}
El ejemplo demuestra estos comportamientos en la práctica. Los valores null, true, false y números se convierten directamente sin transformación. Los objetos Date se transforman a strings ISO 8601. Los objetos con referencias circulares causan TypeError, requiriendo manejo especial con try-catch o un replacer personalizado.
Advertencia: Referencias circulares
Intentar serializar objetos con referencias circulares (objeto A referencia a B, y B referencia a A) causa un TypeError: "Converting circular structure to JSON". Para manejar estos casos, necesitas implementar un replacer personalizado que detecte y rompa las referencias circulares.
Método toJSON()
Los objetos pueden definir un método toJSON() para controlar su propia serialización. Este método es llamado automáticamente por JSON.stringify() y debe retornar un valor JSON válido. Es útil para transformar objetos complejos en representaciones más simples o para excluir propiedades internas.
El método toJSON() tiene prioridad sobre el comportamiento predeterminado de serialización. En el ejemplo, el objeto Usuario define toJSON() para excluir la propiedad password y transformar el objeto Date a un timestamp. Este enfoque es más limpio que usar un replacer externo, ya que la lógica de serialización está encapsulada dentro del propio objeto.
Resumen: JSON.stringify()
Conceptos principales:
- •JSON.stringify() serializa objetos JavaScript a strings JSON
- •El parámetro replacer filtra o transforma propiedades
- •El parámetro space controla el formateo y sangría
- •undefined, functions y Symbols se omiten en la serialización
- •Los objetos Date se convierten a strings ISO 8601
Mejores prácticas:
- •Usa replacer para excluir datos sensibles como passwords
- •Implementa toJSON() en objetos para control de serialización
- •Usa space=2 para archivos de configuración legibles
- •Valida objetos antes de serializar para evitar circulares
- •Maneja TypeError para referencias circulares en producción