Overview - Voltaire

Try it Live

Run Base64 examples in the interactive playground

New to Base64? Start with Fundamentals for guided examples and encoding patterns.

Type Definition

Namespace providing standard (RFC 4648) and URL-safe base64 encoding/decoding. Built on Web APIs (btoa/atob) for maximum performance and compatibility. Zero-overhead design with tree-shakeable function exports.

export type Base64String = string;
export type Base64UrlString = string;

Web API Integration

JavaScript builtins available on all Uint8Array instances:

setFromBase64() - Populate from base64 string
toBase64() - Encode to base64 string

MDN Reference

toBase64() and setFromBase64() are available as of 2025 (Node.js 22+, Chrome 131+). Use Tevm’s Base64.encode() for broader compatibility.

Quick Reference

Effect Schema

import { Base64Schema, Base64UrlSchema } from '@tevm/voltaire/Base64/effect'

const bytes = new TextEncoder().encode('Hello')
const b64 = Base64Schema.from(bytes)
b64.toString() // 'SGVsbG8='

const b64url = Base64UrlSchema.from(bytes)
b64url.toString() // 'SGVsbG8'

API Methods

Encoding

encode(data) - Encode bytes to standard base64
encodeString(str) - Encode UTF-8 string to base64
encodeUrlSafe(data) - Encode bytes to URL-safe base64
encodeStringUrlSafe(str) - Encode string to URL-safe base64
calcEncodedSize(length) - Calculate encoded size

Decoding

decode(encoded) - Decode standard base64 to bytes
decodeToString(encoded) - Decode base64 to UTF-8 string
decodeUrlSafe(encoded) - Decode URL-safe base64 to bytes
decodeUrlSafeToString(encoded) - Decode URL-safe base64 to string
calcDecodedSize(length) - Calculate decoded size

Validation

isValid(str) - Validate standard base64 format
isValidUrlSafe(str) - Validate URL-safe base64 format

BrandedBase64

Tree-shakeable functional API for minimal bundle size. View BrandedBase64 →

Types

Base64String
Base64UrlString

export type Base64String = string;

Base64-encoded string using standard alphabet: A-Z, a-z, 0-9, +, /. Includes padding with = characters.

export type Base64UrlString = string;

URL-safe base64-encoded string using alphabet: A-Z, a-z, 0-9, -, _. No padding characters.

Usage Patterns

Encoding Binary Data

const bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
const b64 = Base64.encode(bytes);
console.log(b64); // "SGVsbG8="

// Decode back to bytes
const decoded = Base64.decode(b64);
console.log(decoded); // Uint8Array([72, 101, 108, 108, 111])

Encoding Strings

// UTF-8 string encoding
const message = "Hello, 世界!";
const encoded = Base64.encodeString(message);
const decoded = Base64.decodeToString(encoded);
console.log(decoded === message); // true

URL-Safe Encoding

// For URLs, filenames, tokens
const data = new Uint8Array([255, 254, 253]);

// Standard encoding (with +, /, =)
const standard = Base64.encode(data);
// URL-safe encoding (with -, _, no padding)
const urlSafe = Base64.encodeUrlSafe(data);

// URL-safe can be used in query parameters
const url = `https://api.example.com?token=${urlSafe}`;

Safe Decoding with Validation

function safeDecodeBase64(input: string): Uint8Array | null {
  if (!Base64.isValid(input)) {
    return null;
  }
  try {
    return Base64.decode(input);
  } catch {
    return null;
  }
}

Pre-allocating Buffers

// Calculate buffer size before encoding
const dataSize = 1024;
const bufferSize = Base64.calcEncodedSize(dataSize);
console.log(bufferSize); // 1368 bytes needed

// Calculate decoded size
const encodedLength = 1368;
const decodedSize = Base64.calcDecodedSize(encodedLength);
console.log(decodedSize); // 1024 bytes maximum

Tree-Shaking

Import only what you need for optimal bundle size:

// Import specific functions (tree-shakeable)
import { encode, decode, isValid } from 'tevm/BrandedBase64';

const data = new Uint8Array([72, 101, 108, 108, 111]);
const encoded = encode(data);
const decoded = decode(encoded);
const valid = isValid(encoded);

// Only these 3 functions included in bundle

Core Documentation

Fundamentals - Learn encoding algorithm and patterns
Encoding - Encoding methods and variants
Decoding - Decoding methods and error handling
Validation - Format validation patterns

Hex - Hex string encoding and decoding
Keccak256 - Keccak256 hashing for data integrity
Uint - Unsigned integer utilities

Specification

RFC 4648 - Base64 encoding specification
- Section 4: Standard base64 encoding
- Section 5: URL-safe base64 encoding
MDN Web APIs - Browser base64 APIs

Try it Live

​Type Definition

​Web API Integration

​Quick Reference

​Effect Schema

​API Methods

​Encoding

​Decoding

​Validation

​BrandedBase64

​Types

​Usage Patterns

​Encoding Binary Data

​Encoding Strings

​URL-Safe Encoding

​Safe Decoding with Validation

​Pre-allocating Buffers

​Tree-Shaking

​Related

​Core Documentation

​Related Primitives

​Specification

Type Definition

Web API Integration

Quick Reference

Effect Schema

API Methods

Encoding

Decoding

Validation

BrandedBase64

Types

Usage Patterns

Encoding Binary Data

Encoding Strings

URL-Safe Encoding

Safe Decoding with Validation

Pre-allocating Buffers

Tree-Shaking

Related

Core Documentation

Related Primitives

Specification