Что входит в пакет
base64hub – ES-модуль с четырьмя функциями и без зависимостей. Работает в Node.js 18 и новее.
| Функция | Возвращает |
|---|---|
encode(bytesOrString, { url, pad, wrap }) | текст Base64; строки сначала кодируются в UTF-8 |
decode(string) | Uint8Array; на некорректных данных выбрасывает исключение |
validate(string) | { valid, variant, padded, bytes } или { valid: false, error } |
dataUri(bytes, mime?) | data: URI; если MIME-тип не указан, он определяется автоматически |
npm i base64hub
import { encode, decode, validate, dataUri } from "base64hub";
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
validate("-_-_").variant; // "url"
dataUri(new TextEncoder().encode("Hi")); // "data:text/plain;charset=utf-8;base64,SGk="
decode принимает то, что люди вставляют на практике: переводы строк, пробелы, строки без дополнения =, префикс data:...;base64, и любой из двух алфавитов. Всё остальное он отвергает: случайный !, = в середине или длину, которой у Base64 быть не может.
Команда b64 из npm
Глобальная установка добавляет команду b64 – тот же инструмент, что и нативный CLI, с теми же флагами и кодами выхода:
$ npm i -g base64hub
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
Сборка из npm сначала читает все входные данные в память и только потом обрабатывает их. Для файлов в несколько гигабайт возьмите сборку на Go, она работает потоково. Все параметры перечислены в документации пакета npm.
base64hub, Buffer, btoa и atob
В Node.js Base64 уже встроен, и для доверенных данных этого достаточно. Разница проявляется на данных, которые вы получили со стороны. Эти строки выполнены в Node.js 24:
Buffer.from("Zm9v!YmFy", "base64").toString(); // "foobar", the "!" is skipped silently
btoa("Привет"); // throws InvalidCharacterError (Latin-1 only)
atob("-_-_"); // throws InvalidCharacterError (no URL-safe)
Buffer | btoa / atob | base64hub | |
|---|---|---|---|
| Текст Unicode | да | только Latin-1 | да, как UTF-8 |
| URL-safe алфавит | кодировка "base64url" | нет | { url: true }, при декодировании принимается |
| Недопустимые символы | молча пропускаются | ошибка | ошибка с позицией |
| Проверка | нет | нет | validate() |
data: URI | нет | нет | dataUri(), при декодировании префикс отбрасывается |
В новых средах выполнения появился и Uint8Array.prototype.toBase64(); где он работает, рассказывает это руководство. Другие примеры для Node.js без пакетов собраны в статье Base64 в Node.js.
Почему здесь важно отсутствие зависимостей
Через функции Base64 проходят токены, ключи и загружаемые файлы, и длинное дерево зависимостей там ни к чему. Пакет использует только встроенные модули Node.js, его ядро Base64 занимает около сотни строк, а тесты прогоняют общие тестовые векторы, которые проходят также CLI, пакет для Python и API.
Вопросы и ответы
Как установить утилиту Base64 для командной строки через npm?
npm i -g base64hub устанавливает команду b64 глобально. Чтобы один раз попробовать без установки, выполните npx base64hub "Hello, hub!".
Работает ли пакет base64hub с require()?
Это ES-модуль, поэтому подключайте его через import { encode } from "base64hub". В файле CommonJS используйте динамический await import("base64hub").
Зачем пакет, если в Node.js есть Buffer?
Buffer.from(text, "base64") пропускает непонятные ему символы, и повреждённые данные молча превращаются в неправильные байты. decode() из base64hub такие данные отвергает и сообщает позицию ошибки, а validate() ещё до декодирования скажет алфавит и размер.
Как закодировать файл в Base64 в Node.js с помощью base64hub?
Прочитайте байты и передайте их в функцию: encode(await readFile("logo.png")), где readFile взят из node:fs/promises. Чтобы получить готовую строку data:image/png;base64,…, вызовите dataUri() для тех же байтов.