byte-base64

byte-base64 is a minimal utility library that converts between base64-encoded strings and raw byte data in TypeScript and JavaScript. It handles three common representations - plain JS arrays of byte values, typed Uint8Array buffers, and JS strings - going beyond the browser’s native atob/btoa functions, which only support ASCII input.

The library exposes four small functions: bytesToBase64 and base64ToBytes for direct byte-array conversion, plus base64encode and base64decode for full string round-tripping via the standard TextEncoder/TextDecoder APIs (or a custom encoder/decoder). It ships as a zero-dependency, single-file implementation with UMD, ES6 module, and TypeScript typings builds, and the README explicitly signals that the project is no longer maintained, recommending base64-js as a successor.

What You Get

• Byte-array conversion - bytesToBase64 and base64ToBytes convert directly between base64 strings and Uint8Array/number-array byte buffers.
• String round-tripping - base64encode and base64decode wrap the byte functions with TextEncoder/TextDecoder for full JS string support beyond ASCII.
• Pluggable encoding - base64encode/base64decode accept a custom encoder/decoder object, so you aren’t limited to UTF-8.
• Multiple build targets - UMD (lib.js), ES6 module (lib.es6.js), and a TypeScript declaration file (lib.d.ts) are published for direct browser, bundler, or Node use.

Common Use Cases

• Encoding binary file contents (images, blobs) into a base64 string for embedding in JSON or a data URI.
• Decoding base64 payloads received from an API into raw bytes for further binary processing.
• Base64-encoding non-ASCII strings (emoji, non-Latin scripts) where atob/btoa fail outright.
• Round-tripping Uint8Array buffers produced by crypto or file APIs through base64 for storage or transmission.

Under The Hood

Architecture The entire implementation is one module (main/src/lib.ts) exporting four pure functions - bytesToBase64, base64ToBytes, base64encode, base64decode - built on two constant lookup tables (base64abc, base64codes); the byte-level conversion functions are pure and stateless, while the string-level encode/decode functions are thin wrappers that inject a default TextEncoder/TextDecoder (or an injected custom one) before delegating to the byte functions, giving a clean separation between byte-codec and string-codec concerns. The build pipeline compiles this single TypeScript source into three separate published targets (UMD, ES6 module, type declarations), while a completely separate test project consumes the built package via a file-path devDependency rather than importing the source directly, meaning any API change requires a rebuild before tests can see it.

Tech Stack The package is pure TypeScript (~3.5.3) compiled via Babel (7.9.x core/preset-env/cli), with zero runtime dependencies - it relies only on browser-native TextEncoder/TextDecoder. The separate test project uses Mocha, Chai, core-js as a polyfill, and Parcel-bundler to run browser-based test pages, with matching @types packages for typings. No CI configuration was found in the repository - this is a local-only dev toolchain with no automated build/test pipeline.

Code Quality Tests are thorough for the library’s size - four Mocha/Chai spec files covering empty arrays, single/double/triple-byte inputs, full base64-alphabet coverage with bit-level comments, and malformed-input error cases. Error handling is explicit: invalid input throws a descriptive Error rather than failing silently. Naming is clear and consistent, and TypeScript typings are used throughout and published as a declaration file, though inline documentation beyond the license header is minimal, and there is no linter, formatter, or CI enforcement.

API Design The public API is minimal and ergonomic - four named functions with no classes or required configuration, sensible defaults (TextEncoder/TextDecoder), and an optional parameter to swap in a custom encoder/decoder for edge cases. Errors are explicit rather than silent, and the surface area stays intentionally small versus alternatives like atob/btoa, which fail silently on non-ASCII input. Getting started requires a single import and function call. The main caveat for developer confidence is that the maintainer has explicitly archived the project in favor of base64-js.