Base64 Encoder / Decoder

A high-performance, TypeScript-ready Base64 and Base64URL encoding/decoding library for Node.js with comprehensive validation and error handling.

Features

• ✅ Fast & Lightweight - Optimized algorithms with minimal validation overhead
• ✅ Full Base64 & Base64URL Support - Complete RFC 4648 compliance
• ✅ TypeScript Ready - Full type definitions included
• ✅ Input Validation - Format validation with clear error messages
• ✅ Unicode Safe - Proper handling of international characters
• ✅ Binary Data Support - Direct Uint8Array conversion
• ✅ Zero Dependencies - Pure JavaScript implementation
• ✅ Comprehensive Tests - 14 test suites with edge case coverage

Installation

npm install @popovmp/base64

API Reference

String ↔ Base64URL

stringToBase64Url(str: string): string

Converts a string to a Base64URL string (URL-safe, no padding).

import { stringToBase64Url } from "@popovmp/base64";
const base64Url = stringToBase64Url("foo"); //=> "Zm9v"
const unicode = stringToBase64Url("Hello 世界"); //=> "SGVsbG8g5LiW55WM"

base64UrlToString(strB64Url: string): string

Converts a Base64URL string back to the original string.

import { base64UrlToString } from "@popovmp/base64";
const text = base64UrlToString("Zm9v"); //=> "foo"
const unicode = base64UrlToString("SGVsbG8g5LiW55WM"); //=> "Hello 世界"

String ↔ Base64

stringToBase64(str: string): string

Converts a string to a standard Base64 string (with padding).

import { stringToBase64 } from "@popovmp/base64";
const base64 = stringToBase64("foo"); //=> "Zm9v"
const withPadding = stringToBase64("f"); //=> "Zg=="

base64ToString(strB64: string): string

Converts a Base64 string back to the original string.

import { base64ToString } from "@popovmp/base64";
const text = base64ToString("Zm9v"); //=> "foo"
const withPadding = base64ToString("Zg=="); //=> "f"

Binary Data Support

bytesToBase64(input: Uint8Array): string

Converts a Uint8Array to a Base64 string.

import { bytesToBase64 } from "@popovmp/base64";
const bytes = new Uint8Array([102, 111, 111]); // "foo"
const base64 = bytesToBase64(bytes); //=> "Zm9v"

base64ToBytes(strB64: string): Uint8Array

Converts a Base64 string to a Uint8Array.

import { base64ToBytes } from "@popovmp/base64";
const bytes = base64ToBytes("Zm9v"); //=> Uint8Array [102, 111, 111]

Format Conversion

base64ToBase64Url(strB64: string): string

Converts a Base64 string to Base64URL format (removes padding, replaces +/- with -/_).

import { base64ToBase64Url } from "@popovmp/base64";
const base64Url = base64ToBase64Url("foo++/=="); //=> "foo--_"

base64UrlToBase64(strB64Url: string): string

Converts a Base64URL string to standard Base64 format (adds padding, replaces -/_ with +/-).

import { base64UrlToBase64 } from "@popovmp/base64";
const base64 = base64UrlToBase64("foo--_"); //=> "foo++/=="

Validation Functions

isValidBase64(str: string): boolean

Validates if a string is properly formatted Base64.

import { isValidBase64 } from "@popovmp/base64";
console.log(isValidBase64("Zm9v")); //=> true
console.log(isValidBase64("Zm9vYg==")); //=> true
console.log(isValidBase64("invalid@")); //=> false

isValidBase64Url(str: string): boolean

Validates if a string is properly formatted Base64URL.

import { isValidBase64Url } from "@popovmp/base64";
console.log(isValidBase64Url("Zm9v")); //=> true
console.log(isValidBase64Url("foo--_")); //=> true
console.log(isValidBase64Url("has+slash")); //=> false

Error Handling

The library throws descriptive errors for invalid input:

import { base64ToString, base64UrlToString } from "@popovmp/base64";

try {
  base64ToString("invalid@base64");
} catch (error) {
  console.log(error.message); //=> "Invalid base64 string"
}

try {
  base64UrlToString("invalid+base64url");
} catch (error) {
  console.log(error.message); //=> "Invalid base64url string"
}

Performance

This library uses minimal validation for optimal performance:

• Format validation catches encoding/decoding errors
• No type checking overhead in hot paths
• Native JavaScript errors for type mismatches
• Optimized algorithms for binary operations

Unicode Support

Full Unicode support with proper UTF-8 encoding:

import { stringToBase64, base64ToString } from "@popovmp/base64";

const unicode = "🎉 Hello 世界! αβγ مرحبا こんにちは";
const encoded = stringToBase64(unicode);
const decoded = base64ToString(encoded);
console.log(decoded === unicode); //=> true

TypeScript

Full TypeScript support with comprehensive type definitions:

import { stringToBase64, base64ToBytes, isValidBase64 } from "@popovmp/base64";

const result: string = stringToBase64("hello");
const bytes: Uint8Array = base64ToBytes("aGVsbG8=");
const isValid: boolean = isValidBase64("Zm9v");

License

MIT