base-64

base-64 is a compact, dependency-free base64 encoder and decoder for JavaScript, published to npm as base-64. It implements the exact algorithm described in RFC 4648 and is designed to be a drop-in substitute for the browser’s native atob() and btoa() functions in environments where they aren’t available, such as older versions of Node.js, Narwhal, RingoJS, and Rhino.

The library exposes just two functions, encode and decode, operating on binary strings where each character represents a single byte from 0x00 to 0xFF. For encoding arbitrary Unicode text, the README recommends pairing it with a UTF-8 encoding step (such as the author’s companion utf8.js library) before calling base64.encode. Despite its age, the package remains widely used, seeing millions of weekly downloads on npm, thanks to its small footprint, zero dependencies, and strict spec compliance.

What You Get

• A single-purpose encode(input) function that mirrors native btoa() behavior for byte strings.
• A single-purpose decode(input) function that mirrors native atob() behavior, including matching error messages.
• Zero runtime dependencies and a tiny (~5KB unminified) source file with no build step required to consume it.
• Support across a wide range of JavaScript environments: Node.js, Narwhal, RingoJS, Rhino, AMD loaders, and all major browsers.

Common Use Cases

• Polyfilling atob()/btoa() in JavaScript engines that predate or omit those globals.
• Encoding binary payloads such as images, files, or tokens to safely embed in JSON, URLs, or text-based protocols.
• Decoding base64-encoded API responses or configuration values in server-side Node.js code.
• Pairing with a UTF-8 encoder to safely base64-encode arbitrary Unicode strings.

Under The Hood

Architecture base-64 ships as a single UMD-wrapped module (base64.js) generated at build time from a template source file (src/base64.js) via Grunt’s grunt-template task, which injects computed values, namely the whitespace-character regex and the package version, from scripts/export-data.js before publishing. At runtime the module detects its environment (CommonJS/Node exports/module, AMD via define, or a global root) and attaches the same {encode, decode, version} object accordingly, so there is no branching public API across environments, only the export mechanism differs. encode and decode are pure, side-effect-free functions operating over a fixed lookup TABLE string, with a single shared error() helper that throws a custom InvalidCharacterError to match Chromium’s native atob/btoa messages. There is no internal layering beyond this because the problem domain doesn’t call for one; the notable design choice is pushing environment detection to build/load time rather than scattering environment checks through the codec logic itself.

Tech Stack Written in plain ES5 JavaScript with no runtime dependencies. Development tooling is entirely Grunt-based: grunt with grunt-shell (for running istanbul coverage and uploading to coveralls) and grunt-template (for the src-to-base64.js build step described above), configured in Gruntfile.js. Tests run under mocha using Node’s built-in assert module, in a single tests/tests.js file of over a thousand lines. Code coverage is measured with istanbul and reported to Coveralls. regenerate is used only inside scripts/export-data.js to programmatically construct the whitespace-character regex consumed by the codec. Continuous integration runs on Travis CI against multiple Node.js versions, executing a combined build-and-test task followed by a coverage upload step.

Code Quality Testing is thorough for the codec’s surface area: the test suite covers RFC 4648 test vectors, full-byte-range round-tripping, all padding cases, and explicit InvalidCharacterError assertions for malformed input, but there are no TypeScript types, no linter configuration, and no linting step in continuous integration, so style consistency relies on an editorconfig file rather than enforced tooling. Error handling is deliberate rather than incidental: invalid input paths funnel through a single error() helper that throws a typed InvalidCharacterError, mirroring native browser behavior instead of returning null or silently swallowing the failure. Naming is consistent camelCase throughout the compact core file, and the code favors explicit bitwise operations with inline comments explaining each shift, which aids readability given the low-level nature of the algorithm.

API Design The public surface is deliberately minimal: two functions, encode and decode, plus a version string, mirroring the exact signatures of btoa()/atob() so it can be dropped in as a polyfill with essentially no API-learning cost for anyone who already knows the DOM globals. Error messages are copied verbatim from Chromium’s native implementation, an unusually careful developer-experience touch, since code that already handles InvalidCharacterError from the browser API needs no changes to also handle this library’s errors. Documentation in the README is example-driven and directly addresses the one real gotcha, that encoding Unicode requires a UTF-8 pre-encoding step, with a companion utf8.js library recommended. Nothing here is technically novel, it’s a standard base64 algorithm with no new capability over native APIs, but as a polyfill/utility its ergonomics are close to ideal for its narrow scope.