Noções Básicas de Buffers

7 exemplos para você começar com Buffers - 5 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0 - Buffer é global; também disponível via node:buffer.
• Entenda quando usar Streams em vez de carregar arquivos inteiros.

Exemplos Básicos

1. Alocar um Buffer

Crie armazenamento binário de tamanho fixo com codificação conhecida antecipadamente.

import { Buffer } from 'node:buffer';
 
const buf = Buffer.alloc(8); // preenchido com zeros
buf.write('hello', 0, 'utf8');
console.log(buf.toString('utf8')); // hello com preenchimento nulo

• Buffer.alloc(n) preenche com zeros - seguro para criptografia e segredos.
• Buffer.allocUnsafe(n) é mais rápido, mas pode conter memória antiga - sobrescreva completamente antes de usar.
• Buffer.byteLength(str, 'utf8') dimensiona UTF-8 sem alocar.

Relacionado: Segurança de Buffer - preenchimento com zero e vazamentos

2. Criar a partir de uma String

Codifique texto em bytes com uma codificação explícita.

const text = 'Node.js 24';
const buf = Buffer.from(text, 'utf8');
console.log(buf.length, Buffer.byteLength(text, 'utf8'));

• A codificação padrão é utf8 - especifique explicitamente em código sensível à segurança.
• Sequências inválidas para a codificação geram TypeError em conversões estritas.
• buf.toString('hex') despeja bytes para depuração de protocolos.

Relacionado: Codificações de Texto - UTF-8 e entrada malformada

3. Fatiar Sem Copiar

slice retorna uma visualização que compartilha a mesma memória subjacente.

const original = Buffer.from('abcdef', 'utf8');
const slice = original.subarray(2, 5); // 'cde'
slice[0] = 67; // 0x43 'C'
console.log(original.toString()); // abCdef

• subarray é o alias moderno - mesmo comportamento que slice para Buffers.
• Mutar uma fatia afeta o pai - copie com Buffer.from(slice) quando o isolamento for necessário.
• Útil para analisar frames com prefixo de comprimento sem alocações.

4. Comparar e Concatenar

Igualdade binária e junção de blocos de leituras de rede.

const a = Buffer.from('abc');
const b = Buffer.from('abc');
console.log(a.equals(b)); // true
 
const combined = Buffer.concat([Buffer.from('hel'), Buffer.from('lo')]);

• equals é seguro em termos de tempo o suficiente para buffers de comprimento correspondente - use crypto.timingSafeEqual para segredos.
• Buffer.concat(list, totalLength) pré-dimensiona quando você sabe o comprimento final para evitar realocação.
• Evite concat massivo em loops - use uma lista e depois um concat ou um stream.

5. Ler Arquivo para Buffer (Arquivos Pequenos)

Adequado para configurações e chaves; use streams para ativos grandes.

import { readFile } from 'node:fs/promises';
 
const buf = await readFile('logo.png');
console.log(buf.length, buf[0], buf[1]); // bytes mágicos PNG

• O arquivo inteiro é carregado na memória - limite o tamanho do arquivo para uploads não confiáveis.
• buf.subarray(0, 8) inspeciona números mágicos para detecção de tipo.
• Para uploads de usuários, prefira streaming para armazenamento de objetos.

Relacionado: fs e fs/promises - E/S de arquivo assíncrona

Exemplos Intermediários

6. Interoperabilidade Uint8Array

APIs da Web e corpos fetch usam Uint8Array - Buffers são subclasses de Uint8Array.

const buf = Buffer.from([1, 2, 3]);
const view: Uint8Array = buf;
console.log(view instanceof Uint8Array); // true
 
const copy = Buffer.from(view); // copia quando o isolamento é necessário

• Visualizações ArrayBuffer de WASM ou Web Crypto interoperam via .buffer, .byteOffset, .byteLength.
• Tenha cuidado com visualizações de memória compartilhada - copie antes da passagem assíncrona se estiver mutando.
• Buffer.from(arrayBuffer, byteOffset, length) cria um Buffer com base em visualização.

7. Mensagem com Prefixo de Comprimento

Padrão comum de framing binário para protocolos TCP.

function encodeFrame(payload: Buffer): Buffer {
  const header = Buffer.alloc(4);
  header.writeUInt32BE(payload.length);
  return Buffer.concat([header, payload]);
}
 
function decodeFrame(data: Buffer): { frame: Buffer; rest: Buffer } {
  const len = data.readUInt32BE(0);
  return { frame: data.subarray(4, 4 + len), rest: data.subarray(4 + len) };
}

• Use a ordem de bytes de rede big-endian (BE) por convenção.
• O TCP pode entregar frames parciais - acumule em uma lista de Buffer até que esteja completo.
• Veja Protocolos Binários para parsers de produção.

Relacionado: Noções Básicas de Streams - tratamento de payloads grandes

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