Codificações de Texto

Texto na rede são bytes - UTF-8 é o padrão para APIs do Node 24, e TextEncoder/TextDecoder fornecem conversão padrão da Web com tratamento explícito de erros para entrada malformada.

Receita

const encoder = new TextEncoder(); // sempre UTF-8
const decoder = new TextDecoder('utf-8', { fatal: true });
 
const bytes = encoder.encode('Hello 世界');
const text = decoder.decode(bytes);

const buf = Buffer.from('café', 'utf8');
console.log(buf.toString('utf8'));

Quando usar isso:

• Analisar nomes de arquivos de upload com caracteres não ASCII
• Converter bytes de resposta fetch para strings
• Validar CSV/XML declarados como UTF-8 de terceiros
• Interoperar com TextEncoder do navegador em código isomorfo

Exemplo de Trabalho

import { Buffer } from 'node:buffer';
 
function decodeUtf8Strict(bytes: Uint8Array): string {
  const decoder = new TextDecoder('utf-8', { fatal: true });
  try {
    return decoder.decode(bytes);
  } catch {
    throw new Error('Sequência UTF-8 inválida');
  }
}
 
function decodeUtf8Lossy(bytes: Uint8Array): string {
  return new TextDecoder('utf-8', { fatal: false }).decode(bytes);
}
 
const valid = Buffer.from('hello', 'utf8');
const invalid = Buffer.from([0xff, 0xfe, 0xfd]);
 
console.log(decodeUtf8Strict(valid));
console.log(decodeUtf8Lossy(invalid)); // caracteres de substituição

// O Content-Type HTTP deve especificar charset=utf-8
const encoder = new TextEncoder();
const body = encoder.encode(JSON.stringify({ greeting: '你好' }));

O que isso demonstra:

• fatal: true rejeita sequências inválidas - correto para parsers sensíveis à segurança
• fatal: false substitui U+FFFD - OK para exibição gerada pelo usuário com avisos
• TextEncoder suporta apenas UTF-8 por especificação - use iconv-lite para codificações legadas
• Buffer.toString('utf8') substitui bytes inválidos por padrão - similar ao decodificador não fatal

Mergulho Profundo

Como Funciona

• Strings JavaScript são UTF-16 internamente; UTF-8 é a codificação de intercâmbio para I/O.
• BOM - O BOM UTF-8 (EF BB BF) é opcional; remova ao analisar JSON que deve começar com {.
• Normalização - NFC vs NFD importa para comparação de strings (nomes de usuário, nomes de arquivos).
• Codificações de Buffer - hex, base64, base64url, latin1 para protocolos específicos - não para texto geral.

Seleção de Codificação

Notas de TypeScript

function assertUtf8Json(raw: Buffer): unknown {
  const text = new TextDecoder('utf-8', { fatal: true }).decode(raw);
  return JSON.parse(text);
}

Armadilhas

• Assumir que o modo de string binary preserva bytes - armadilha legada. Correção: use Buffer ou Uint8Array para binário.
• Codificação dupla de UTF-8 - codificar strings já válidas para "segurança". Correção: codifique uma vez no limite do sistema.
• Ignorar charset no Content-Type - padrão ISO-8859-1 em clientes antigos. Correção: force UTF-8 de ponta a ponta.
• Codificação de nome de arquivo em multipart - codificação percentual UTF-8 filename* do RFC 5987. Correção: use parsers de framework testados para i18n.
• Comparar Unicode não normalizado - nomes de usuário visualmente idênticos diferem no nível de byte. Correção: str.normalize('NFC') antes de comparar.

Alternativas

FAQs

Relacionado

• Noções Básicas de Buffers - alocação e fatias
• Protocolos Binários - payloads não textuais
• Segurança de Buffer - vazamentos em mensagens de erro
• Respostas HTTP em Streaming - cabeçalhos charset

Versões da Pilha: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.