Referência do pacote npm
O base64hub é um módulo ES para Node.js 18 ou mais novo, com quatro funções, tipos TypeScript e o comando b64. Sem dependências.
Instalação
npm i base64hub # library
npm i -g base64hub # b64 command
O pacote é só ESM. Importe com import; a partir de CommonJS, use await import("base64hub"). As definições de tipos vêm junto.
import { encode, decode, validate, dataUri, Base64Error } from "base64hub";
encode(input, options?)
Codifica bytes, ou os bytes UTF-8 de uma string, e retorna uma string. input pode ser uma string, um Uint8Array (um Buffer do Node.js é um deles), um ArrayBuffer ou qualquer view de typed array.
| Opção | Tipo | Padrão | Efeito |
|---|---|---|---|
url | boolean | false | Alfabeto URL-safe (- e _). |
pad | boolean | true | Acrescenta o preenchimento =. |
wrap | number | 0 | Insere \n a cada N caracteres, nenhum no final; 76 é MIME. |
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
encode("foobar", { wrap: 4 }); // "Zm9v\nYmFy"
encode(new Uint8Array([0xfb, 0xff, 0xbf])); // "+/+/"
decode(text)
Decodifica Base64 para um Uint8Array. Espaços, tabulações e quebras de linha, um prefixo data:...;base64,, preenchimento ausente e os dois alfabetos são aceitos. Qualquer outra coisa lança um Base64Error, cujo position é o índice (a partir de 0) do caractere inválido na entrada já limpa.
decode("+/+/"); // Uint8Array(3) [ 251, 255, 191 ]
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
try {
decode("Zm9v!");
} catch (e) {
if (e instanceof Base64Error) console.log(e.message, e.position);
// invalid character '!' at position 4 4
}
Use new TextDecoder().decode(bytes) para obter texto e Buffer.from(bytes) quando outra API do Node.js pedir um Buffer.
validate(text)
Confere o texto sem lançar exceção. É válido exatamente quando o decode daria certo.
validate("SGVsbG8sIGh1YiE");
// { valid: true, variant: 'either', padded: false, bytes: 11 }
validate("Zm9v!");
// { valid: false, error: "invalid character '!' at position 4" }
| Campo | Significado |
|---|---|
valid | true ou false. |
variant | standard (apareceu + ou /), url (apareceu - ou _), mixed (os dois) ou either (nenhum). |
padded | O tamanho da entrada limpa, = incluído, é múltiplo de 4. |
bytes | Tamanho decodificado em bytes. |
error | Só com entrada inválida: o motivo, o mesmo texto que o decode lançaria. |
dataUri(input, mime?)
Monta uma string data:<mime>;base64,<payload>: alfabeto padrão, com preenchimento, nunca quebrada. Sem mime, o tipo é detectado: PNG, JPEG, GIF, WebP, PDF e SVG pela assinatura, text/plain;charset=utf-8 para texto UTF-8, e application/octet-stream nos outros casos.
dataUri("Hi"); // "data:text/plain;charset=utf-8;base64,SGk="
dataUri("a,b", "text/csv"); // "data:text/csv;base64,YSxi"
import { readFile } from "node:fs/promises";
dataUri(await readFile("logo.png")); // "data:image/png;base64,iVBORw0KGgo..."
O comando b64
npm i -g base64hub instala o b64, e npx base64hub "Hello, hub!" o executa uma vez sem instalar. As flags, mensagens e códigos de saída são os da referência da CLI. A versão do npm lê a entrada inteira para a memória antes de processá-la; para arquivos muito grandes, use a versão em Go.
Atualizado 22 de nov. de 2026