tessl/npm-js-base64

Yet another Base64 transcoder in pure-JS with comprehensive UTF-8 support and cross-platform compatibility

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Browser Compatibility Functions

Name: tessl/npm-js-base64
Author: tessl

Low-level functions that replicate browser btoa/atob behavior with cross-platform support and polyfills for environments lacking native implementations.

Capabilities

Base64 to Binary String (atob)

Browser-compatible atob function that decodes Base64 to binary string format.

/**
 * Does what window.atob of web browsers do - converts Base64 to binary string
 * @param asc - Base64-encoded string
 * @returns Binary string (each character represents a byte value 0-255)
 */
function atob(asc: string): string;

Usage Examples:

import { atob } from "js-base64";

// Basic usage - same as browser's window.atob
const binaryString = atob("SGVsbG8="); // "Hello" in Base64
console.log(binaryString); // Binary string representation

// Converting to byte values
const bytes = Array.from(binaryString).map(char => char.charCodeAt(0));
console.log(bytes); // [72, 101, 108, 108, 111] - ASCII values for "Hello"

// Working with binary data (like images)
const pngHeaderB64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";
const binaryData = atob(pngHeaderB64);
// binaryData contains the raw PNG bytes as a binary string

// Note: For UTF-8 text, use decode() instead of atob()
// atob("5bCP6aO85by+") will NOT correctly decode Japanese text

Binary String to Base64 (btoa)

Browser-compatible btoa function that encodes binary string to Base64.

/**
 * Does what window.btoa of web browsers do - converts binary string to Base64
 * @param bin - Binary string (each character must have charCode 0-255)
 * @returns Base64-encoded string
 */
function btoa(bin: string): string;

Usage Examples:

import { btoa } from "js-base64";

// Basic usage - same as browser's window.btoa
const encoded = btoa("Hello");
console.log(encoded); // "SGVsbG8="

// Creating binary string from byte array
const bytes = [72, 101, 108, 108, 111]; // ASCII for "Hello"
const binaryString = String.fromCharCode(...bytes);
const result = btoa(binaryString);
console.log(result); // "SGVsbG8="

// Working with image data or file bytes
const imageBytes = [137, 80, 78, 71, 13, 10, 26, 10]; // PNG header bytes
const imageBinaryString = String.fromCharCode(...imageBytes);
const imageB64 = btoa(imageBinaryString);
console.log(imageB64); // "iVBORw0KGgo="

// IMPORTANT: Only works with binary strings (characters 0-255)
// btoa("小飼弾") will throw TypeError - use encode() for UTF-8 text

Pure JavaScript Polyfills

Polyfill implementations that work in any JavaScript environment.

/**
 * Pure JavaScript polyfill version of atob
 * @param asc - Base64-encoded string
 * @returns Binary string
 * @throws TypeError if input is malformed Base64
 */
function atobPolyfill(asc: string): string;

/**
 * Pure JavaScript polyfill version of btoa  
 * @param bin - Binary string (each character must have charCode 0-255)
 * @returns Base64-encoded string
 * @throws TypeError if input contains invalid characters (charCode > 255)
 */
function btoaPolyfill(bin: string): string;

Usage Examples:

import { atobPolyfill, btoaPolyfill } from "js-base64";

// Use polyfills explicitly (useful for testing or consistent behavior)
const encoded = btoaPolyfill("Hello");
console.log(encoded); // "SGVsbG8="

const decoded = atobPolyfill(encoded);
console.log(decoded); // "Hello"

// Error handling
try {
  btoaPolyfill("Hello 🌍"); // Contains character > 255
} catch (error) {
  console.log(error.message); // "invalid character found"
}

try {
  atobPolyfill("invalid base64!!!"); 
} catch (error) {
  console.log(error.message); // "malformed base64."
}

Key Differences from UTF-8 Functions

When to Use atob/btoa vs decode/encode

import { atob, btoa, decode, encode } from "js-base64";

// For UTF-8 text - USE decode/encode
const utf8Text = "小飼弾";
const utf8Correct = encode(utf8Text); // ✅ Correct: "5bCP6aO85by+"
const utf8Decoded = decode(utf8Correct); // ✅ Correct: "小飼弾"

// DON'T use btoa/atob for UTF-8 text
// btoa(utf8Text) // ❌ Throws TypeError

// For binary data - USE atob/btoa or toUint8Array/fromUint8Array  
const binaryString = String.fromCharCode(72, 101, 108, 108, 111);
const binaryEncoded = btoa(binaryString); // ✅ Correct for binary data
const binaryDecoded = atob(binaryEncoded); // ✅ Correct for binary data

// For image/file data - prefer Uint8Array functions
const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const fromUint8 = fromUint8Array(bytes); // ✅ Preferred for binary data
const toUint8 = toUint8Array(fromUint8); // ✅ Preferred for binary data

Cross-Platform Behavior

The library automatically chooses the best implementation:

Browser with native btoa/atob: Uses native functions
Node.js with Buffer: Uses Buffer-based implementation
Other environments: Uses pure JavaScript polyfills

// The library handles environment detection automatically
import { atob, btoa } from "js-base64";

// These work the same everywhere:
const encoded = btoa("Hello");
const decoded = atob(encoded);

Error Handling

import { atob, btoa, atobPolyfill, btoaPolyfill } from "js-base64";

// btoa/btoaPolyfill errors
try {
  btoa("Text with emoji 🚀"); // Character code > 255
} catch (error) {
  console.log(error instanceof TypeError); // true
  console.log(error.message); // "invalid character found"
}

// atob/atobPolyfill errors  
try {
  atob("Not base64!!!"); // Invalid Base64
} catch (error) {
  console.log(error instanceof TypeError); // true
  console.log(error.message); // "malformed base64."
}