JavaScript TextDecoder e TextEncoder

Dominar as interfaces TextEncoder e TextDecoder em JavaScript é essencial para lidar com dados de texto de forma eficiente, especialmente em aplicações que trabalham com dados binários brutos e diversas codificações de caracteres. Este guia explica o que essas interfaces fazem, quando você realmente precisa delas e como usá-las corretamente, com exemplos executáveis e armadilhas práticas.

O que esta página aborda

• O que significam codificação e decodificação de texto, e por que não é possível tratar bytes como caracteres.
• Codificação de strings em bytes com TextEncoder (somente UTF-8).
• Decodificação de bytes de volta em strings com TextDecoder, incluindo codificações não-UTF-8.
• Streaming, tratamento de erros (fatal) e um exemplo prático com fetch.

Introdução à codificação e decodificação de texto

Uma string JavaScript é uma sequência de caracteres, mas a rede, o sistema de arquivos e a maioria das APIs binárias trabalham com bytes. A codificação de texto transforma caracteres em bytes seguindo um esquema (como UTF-8); a decodificação de texto faz o inverso, convertendo bytes de volta em caracteres. A mesma string pode produzir sequências de bytes diferentes dependendo da codificação, razão pela qual um decodificador precisa saber em qual codificação os bytes foram escritos.

JavaScript fornece duas interfaces integradas para isso: TextEncoder (string → bytes) e TextDecoder (bytes → string). Elas aparecem sempre que você lida com dados binários brutos — lendo um Blob, processando um ArrayBuffer, ou transmitindo uma resposta da Fetch API.

Usando TextEncoder em JavaScript

A interface TextEncoder em JavaScript converte texto de uma string em um fluxo de bytes codificado. Ela suporta exclusivamente a codificação UTF-8 e não aceita parâmetros de codificação em seu construtor.

Exemplo básico de codificação de texto

Para codificar uma string usando TextEncoder, siga este exemplo simples:

Este script gera um Uint8Array mostrando a versão codificada em UTF-8 de "Hello, world!". Cada número corresponde a um byte: 72 é H, 101 é e, e assim por diante. Este array é o dado binário que pode ser transmitido por protocolos de rede ou armazenado para uso posterior. Observe que o construtor não recebe argumentos — TextEncoder sempre produz apenas UTF-8.

Técnicas avançadas de codificação

Tratando caracteres não-padrão

TextEncoder lida com o intervalo Unicode completo de forma transparente. Caracteres de múltiplos bytes (letras chinesas, emojis, letras acentuadas) se expandem em vários bytes cada — um motivo importante pelo qual o tamanho em bytes de uma string codificada geralmente é maior que seu .length:

Isso demonstra que TextEncoder converte qualquer caractere representável em UTF-8, incluindo emojis e símbolos especiais, e que nunca se deve assumir que um caractere equivale a um byte.

Usando TextDecoder em JavaScript

Enquanto TextEncoder converte strings em bytes, TextDecoder realiza o processo inverso, transformando dados de bytes codificados de volta em strings legíveis. Ele suporta múltiplas codificações, mas usa UTF-8 como padrão.

Exemplo básico de decodificação de texto

Veja como decodificar dados de bytes de volta para uma string:

O argumento para decode() pode ser um Uint8Array, qualquer outro TypedArray, um ArrayBuffer, ou um DataView — qualquer coisa que envolva bytes brutos.

Este código converte um Uint8Array de volta para a string "Hello, world!", ilustrando a funcionalidade básica do TextDecoder.

Decodificação com diferentes codificações

Exemplo usando ISO-8859-1

Ao contrário do TextEncoder, que é somente UTF-8, o TextDecoder pode ler muitas codificações legadas. Passe o rótulo de codificação (por exemplo, "iso-8859-1", "windows-1252", ou "utf-16le") ao construtor:

Isso produz "Hello, Monde!", mostrando como lidar com fluxos de bytes não-UTF-8 — útil ao ler arquivos produzidos por sistemas mais antigos ou ferramentas não-Unicode.

Boas práticas de codificação e decodificação

Garantindo a integridade do texto

Ao codificar e decodificar texto, certifique-se de que o texto seja transferido ou armazenado de forma correta e completa. Sempre verifique se os dados de bytes codificados convertem de volta ao texto original sem perda.

Decodificação em streaming por partes

Um caractere de múltiplos bytes pode ser dividido entre dois fragmentos de dados que chegam pela rede. Decodificar cada fragmento de forma independente corromperia o caractere na fronteira. A opção { stream: true } instrui o decodificador a reter qualquer sequência incompleta no final e precedê-la ao próximo fragmento. Chame decode() uma vez no final sem argumento para liberar:

Sem { stream: true }, essa sequência de bytes dividida seria decodificada como caracteres de substituição (U+FFFD) e o 你 original seria perdido.

Tratamento de erros com fatal

Por padrão, TextDecoder substitui sequências de bytes inválidas pelo caractere de substituição (U+FFFD, exibido como �) em vez de lançar um erro. Para impor validação estrita e lançar um TypeError em caso de entrada malformada, passe { fatal: true }:

Use fatal: true quando for necessário rejeitar dados corrompidos; mantenha o comportamento padrão (com perda) quando uma exibição parcial for melhor do que uma falha total.

Exemplo prático: decodificando um fluxo de resposta Fetch

O uso prático mais comum de TextDecoder é ler o corpo de uma resposta HTTP transmitida em streaming byte a byte. Combinado com a opção { stream: true }, ele remonta o texto com segurança mesmo quando caracteres atravessam as fronteiras entre fragmentos. O trecho abaixo simula um fluxo de dois fragmentos para que funcione em qualquer lugar:

No código real, você obteria esses fragmentos de response.body.getReader() após uma chamada fetch, que é também como funciona o rastreamento de progresso de download.

Quando usar TextEncoder e TextDecoder

• Lendo ou gravando o conteúdo de um Blob ou File como bytes brutos.
• Trabalhando diretamente com um ArrayBuffer ou typed array.
• Processando uma resposta de rede transmitida em streaming fragmento por fragmento.
• Calculando tamanhos em bytes (para cabeçalhos Content-Length) onde a contagem de caracteres não é suficiente.

Normalmente você não precisa deles para JSON comum ou texto buscado com response.json() / response.text() — o navegador cuida da decodificação nesses casos.

Conclusão

TextEncoder e TextDecoder são a ponte entre as strings JavaScript e os bytes brutos usados por APIs binárias, pela rede e pelo sistema de arquivos. Lembre-se do essencial: TextEncoder é somente UTF-8 e não recebe opções; TextDecoder suporta muitas codificações e oferece { stream: true } para dados fragmentados e { fatal: true } para validação estrita. Com essas ferramentas em seu repertório, você pode lidar com texto corretamente em qualquer codificação e fonte de dados.

Prática