JavaScript TextDecoder y TextEncoder

Dominar las interfaces TextEncoder y TextDecoder en JavaScript es esencial para manejar datos de texto de manera eficiente, especialmente en aplicaciones que trabajan con datos binarios sin procesar y diversas codificaciones de caracteres. Esta guía explica qué hacen estas interfaces, cuándo realmente las necesitas y cómo usarlas correctamente, con ejemplos ejecutables y situaciones prácticas a tener en cuenta.

Qué cubre esta página

• Qué significa codificar y decodificar texto, y por qué no puedes simplemente tratar los bytes como caracteres.
• Codificar strings a bytes con TextEncoder (solo UTF-8).
• Decodificar bytes de vuelta a strings con TextDecoder, incluyendo codificaciones distintas de UTF-8.
• Streaming, manejo de errores (fatal) y un ejemplo del mundo real con fetch.

Introducción a la codificación y decodificación de texto

Un string de JavaScript es una secuencia de caracteres, pero la red, el sistema de archivos y la mayoría de las API binarias trabajan con bytes. La codificación de texto transforma caracteres en bytes siguiendo un esquema (como UTF-8); la decodificación de texto invierte ese proceso, convirtiendo bytes de vuelta en caracteres. El mismo string puede producir secuencias de bytes diferentes según la codificación, por eso un decodificador necesita saber con qué codificación se escribieron los bytes.

JavaScript proporciona dos interfaces integradas para esto: TextEncoder (string → bytes) y TextDecoder (bytes → string). Aparecen siempre que tocas datos binarios sin procesar: al leer un Blob, procesar un ArrayBuffer o hacer streaming de una respuesta desde la Fetch API.

Uso de TextEncoder en JavaScript

La interfaz TextEncoder en JavaScript convierte texto de un string a un flujo de bytes codificados. Soporta exclusivamente la codificación UTF-8 y no acepta parámetros de codificación en su constructor.

Ejemplo básico de codificación de texto

Para codificar un string usando TextEncoder, sigue este ejemplo sencillo:

Este script genera un Uint8Array que muestra la versión UTF-8 codificada de "Hello, world!". Cada número es un byte: 72 es H, 101 es e, y así sucesivamente. Este array es el dato binario que puede transmitirse a través de protocolos de red o almacenarse para uso posterior. Ten en cuenta que el constructor no recibe argumentos — TextEncoder siempre produce UTF-8.

Técnicas de codificación avanzadas

Manejo de caracteres no estándar

TextEncoder gestiona el rango Unicode completo sin problemas. Los caracteres multibyte (letras chinas, emoji, letras con acento) se expanden en varios bytes cada uno — una razón clave por la que la longitud en bytes de un string codificado suele ser mayor que su .length:

Esto muestra que TextEncoder convierte cualquier carácter representable en UTF-8, incluidos emoji y símbolos especiales, y que nunca debes asumir que un carácter equivale a un byte.

Uso de TextDecoder en JavaScript

Mientras que TextEncoder convierte strings a bytes, TextDecoder realiza la operación inversa, transformando datos de bytes codificados de vuelta en strings legibles. Soporta múltiples codificaciones pero toma UTF-8 como valor por defecto.

Ejemplo básico de decodificación de texto

Así es como puedes decodificar datos de bytes de vuelta a un string:

El argumento de decode() puede ser un Uint8Array, cualquier otro TypedArray, un ArrayBuffer o un DataView — cualquier cosa que envuelva bytes sin procesar.

Este código convierte un Uint8Array de vuelta al string "Hello, world!", ilustrando la funcionalidad básica de TextDecoder.

Decodificación con distintas codificaciones

Ejemplo con ISO-8859-1

A diferencia de TextEncoder, que solo soporta UTF-8, TextDecoder puede leer muchas codificaciones heredadas. Pasa la etiqueta de codificación (por ejemplo "iso-8859-1", "windows-1252" o "utf-16le") al constructor:

Esto genera "Hello, Monde!", mostrando cómo manejar flujos de bytes que no son UTF-8 — útil cuando se leen archivos producidos por sistemas más antiguos o herramientas que no son Unicode.

Buenas prácticas para la codificación y decodificación

Garantizar la integridad del texto

Al codificar y decodificar texto, asegúrate de que el texto se transfiera o almacene correcta y completamente. Verifica siempre que los datos de bytes codificados se conviertan de vuelta al texto original sin pérdidas.

Decodificación en streaming entre fragmentos

Un carácter multibyte puede dividirse entre dos fragmentos de datos que llegan por la red. Decodificar cada fragmento de forma independiente corrompería el carácter en el límite. La opción { stream: true } indica al decodificador que retenga cualquier secuencia incompleta al final y la anteponga al siguiente fragmento. Llama a decode() una vez al final sin argumento para vaciar el buffer:

Sin { stream: true }, esa secuencia de bytes dividida se decodificaría en caracteres de reemplazo (U+FFFD) y el 你 original se perdería.

Manejo de errores con fatal

Por defecto, TextDecoder reemplaza las secuencias de bytes inválidas con el carácter de reemplazo (U+FFFD, que aparece como �) en lugar de lanzar una excepción. Para imponer una validación estricta y lanzar un TypeError con entrada malformada, pasa { fatal: true }:

Usa fatal: true cuando debas rechazar datos corruptos; mantén el comportamiento por defecto (con pérdida) cuando mostrar parcialmente es mejor que un error fatal.

Ejemplo del mundo real: decodificar un flujo de respuesta Fetch

El uso práctico más común de TextDecoder es leer el cuerpo de una respuesta HTTP en streaming byte a byte. Combinado con la opción { stream: true }, reensambla el texto de forma segura incluso cuando los caracteres abarcan límites de fragmento. El fragmento de código siguiente simula un stream de dos fragmentos para que funcione en cualquier entorno:

En código real obtendrías esos fragmentos de response.body.getReader() tras una llamada a fetch, que es también como funciona el seguimiento del progreso de descarga.

Cuándo usar TextEncoder y TextDecoder

• Leer o escribir el contenido de un Blob o un File como bytes sin procesar.
• Trabajar directamente con un ArrayBuffer o array tipado.
• Procesar una respuesta de red en streaming fragmento a fragmento.
• Calcular longitudes en bytes (para cabeceras Content-Length) donde el recuento de caracteres no es suficiente.

Normalmente no los necesitas para JSON ordinario o texto obtenido con response.json() / response.text() — el navegador gestiona la decodificación en esos casos.

Conclusión

TextEncoder y TextDecoder son el puente entre los strings de JavaScript y los bytes sin procesar que usan las API binarias, la red y el sistema de archivos. Recuerda lo esencial: TextEncoder es solo UTF-8 y no acepta opciones; TextDecoder soporta muchas codificaciones y ofrece { stream: true } para datos fragmentados y { fatal: true } para validación estricta. Con estas herramientas en tu conjunto, puedes manejar texto correctamente en cualquier codificación y fuente de datos.

Práctica