Try it Live

Run Base64 examples in the interactive playground

BrandedBase64

Tree-shakeable functional API for Base64 operations with optimal bundle size.

Overview

BrandedBase64 is the functional layer providing base64 encoding/decoding operations. It offers:

Tree-shakeable individual function exports
Data-first unopinionated methods
Bundle optimization through selective imports
Zero dependencies on Web APIs (btoa/atob)

Primary benefit: Import only the encoding/decoding variants you need, reducing bundle size when not using all features.

Available Functions

All Base64 functionality available as tree-shakeable functions:

Standard Encoding/Decoding

import {
  encode,
  decode,
  encodeString,
  decodeToString
} from 'tevm/BrandedBase64'

// Bytes ↔ Base64
const data = new Uint8Array([1, 2, 3])
const b64 = encode(data)
const original = decode(b64)

// String ↔ Base64
const str = "Hello, world!"
const encoded = encodeString(str)
const decoded = decodeToString(encoded)

See Encoding and Decoding for details.

URL-Safe Encoding/Decoding

import {
  encodeUrlSafe,
  decodeUrlSafe,
  encodeStringUrlSafe,
  decodeUrlSafeToString
} from 'tevm/BrandedBase64'

// Bytes ↔ URL-safe Base64
const data = new Uint8Array([255, 254, 253])
const urlSafe = encodeUrlSafe(data)
const original = decodeUrlSafe(urlSafe)

// String ↔ URL-safe Base64
const str = "user@example.com"
const encoded = encodeStringUrlSafe(str)
const decoded = decodeUrlSafeToString(encoded)

See Encoding and Decoding for details.

Validation

import {
  isValid,
  isValidUrlSafe
} from 'tevm/BrandedBase64'

const validStandard = isValid("SGVsbG8=")        // true
const validUrlSafe = isValidUrlSafe("SGVsbG8")   // true

See Validation for details.

Utilities

import {
  calcEncodedSize,
  calcDecodedSize
} from 'tevm/BrandedBase64'

const encodedSize = calcEncodedSize(1024)   // 1368 chars
const decodedSize = calcDecodedSize(1368)   // 1026 bytes max

See Utilities for details.

Data-First Pattern

All BrandedBase64 functions follow data-first pattern:

// Data as first parameter
encode(data)
decode(encoded)
encodeString(str)
isValid(str)
calcEncodedSize(length)

// vs Base64 namespace: same signatures
Base64.encode(data)
Base64.decode(encoded)

This enables functional composition:

import { encode, isValid, decode } from 'tevm/BrandedBase64'

// Function composition
const safeEncode = (data: Uint8Array) => encode(data)
const safeDecode = (str: string) => isValid(str) ? decode(str) : null

// Array methods
const dataArray = [
  new Uint8Array([1, 2, 3]),
  new Uint8Array([4, 5, 6]),
]
const encoded = dataArray.map(encode)
const decoded = encoded.map(decode)

// Partial application
const validator = (str: string) => isValid(str)
strings.filter(validator)

Tree-Shaking Benefits

Primary benefit: Selective inclusion of encoding variants

Example 1: Standard Only (Minimal)

import { encode, decode } from 'tevm/BrandedBase64'

const data = new Uint8Array([1, 2, 3])
const b64 = encode(data)
const original = decode(b64)

Bundle: Only standard base64 encoding/decoding. No URL-safe variants, no validation, no utilities.

Example 2: URL-Safe Only

import { encodeUrlSafe, decodeUrlSafe } from 'tevm/BrandedBase64'

const data = new Uint8Array([255, 254, 253])
const urlSafe = encodeUrlSafe(data)
const original = decodeUrlSafe(urlSafe)

Bundle: Only URL-safe encoding/decoding. No standard variants.

Example 3: With Validation

import { encode, decode, isValid } from 'tevm/BrandedBase64'

const data = new Uint8Array([1, 2, 3])
const b64 = encode(data)

if (isValid(b64)) {
  const original = decode(b64)
}

Bundle: Standard encoding/decoding + validation. No URL-safe variants, no utilities.

Example 4: Complete (All Features)

import { Base64 } from 'tevm'

// Using namespace includes all methods
const encoded = Base64.encode(data)
const urlSafe = Base64.encodeUrlSafe(data)
const valid = Base64.isValid(encoded)
const size = Base64.calcEncodedSize(data.length)

Bundle: All Base64 methods included.

Function Reference

Encoding Functions

Function	Input	Output	Notes
`encode`	`Uint8Array`	`Base64String`	Standard base64 with padding
`encodeString`	`string`	`Base64String`	UTF-8 string to standard base64
`encodeUrlSafe`	`Uint8Array`	`Base64UrlString`	URL-safe, no padding
`encodeStringUrlSafe`	`string`	`Base64UrlString`	UTF-8 string to URL-safe base64

Decoding Functions

Function	Input	Output	Notes
`decode`	`string`	`Uint8Array`	Standard base64 to bytes
`decodeToString`	`string`	`string`	Standard base64 to UTF-8 string
`decodeUrlSafe`	`string`	`Uint8Array`	URL-safe base64 to bytes
`decodeUrlSafeToString`	`string`	`string`	URL-safe base64 to UTF-8 string

Validation Functions

Function	Input	Output	Notes
`isValid`	`string`	`boolean`	Validate standard base64 format
`isValidUrlSafe`	`string`	`boolean`	Validate URL-safe base64 format

Utility Functions

Function	Input	Output	Notes
`calcEncodedSize`	`number`	`number`	Calculate encoded string length
`calcDecodedSize`	`number`	`number`	Calculate max decoded byte length

Usage Patterns

Minimal Bundle (Basic Encoding)

// Only import what you need
import { encode, decode } from 'tevm/BrandedBase64'

// Basic encode/decode
function serializeData(data: Uint8Array): string {
  return encode(data)
}

function deserializeData(str: string): Uint8Array {
  return decode(str)
}

Bundle size: ~200 bytes (encode + decode implementations)

With Validation

import { decode, isValid } from 'tevm/BrandedBase64'

function safeDecode(input: string): Uint8Array | null {
  if (!isValid(input)) {
    return null
  }
  try {
    return decode(input)
  } catch {
    return null
  }
}

Bundle size: ~400 bytes (decode + validation)

URL-Safe for Web APIs

import {
  encodeUrlSafe,
  decodeUrlSafe,
  isValidUrlSafe
} from 'tevm/BrandedBase64'

// Generate URL-safe tokens
function generateToken(data: Uint8Array): string {
  return encodeUrlSafe(data)
}

// Validate and decode tokens
function parseToken(token: string): Uint8Array | null {
  if (!isValidUrlSafe(token)) {
    return null
  }
  return decodeUrlSafe(token)
}

Bundle size: ~300 bytes (URL-safe variants only)

Size Pre-calculation

import {
  encode,
  decode,
  calcEncodedSize,
  calcDecodedSize
} from 'tevm/BrandedBase64'

function encodeWithAllocation(data: Uint8Array): string {
  const expectedSize = calcEncodedSize(data.length)
  console.log(`Will encode to ${expectedSize} characters`)
  return encode(data)
}

function decodeWithAllocation(encoded: string): Uint8Array {
  const maxSize = calcDecodedSize(encoded.length)
  console.log(`Will decode to max ${maxSize} bytes`)
  return decode(encoded)
}

Bundle size: ~400 bytes (encode/decode + size utilities)

When to Use BrandedBase64 vs Base64

Use BrandedBase64 When:

Bundle size critical (mobile, embedded)
Selective imports desired
Only using specific variants (standard OR URL-safe)
Functional style preferred
Composing functions heavily

Use Base64 Namespace When:

Using multiple variants
Ergonomics over bundle size
Simple namespace imports preferred
All features needed anyway

Interoperability

BrandedBase64 functions work with Base64 namespace:

import { Base64 } from 'tevm'
import { encode, decode } from 'tevm/BrandedBase64'

// Same implementations
const data = new Uint8Array([1, 2, 3])
const b64a = Base64.encode(data)
const b64b = encode(data)
console.log(b64a === b64b) // true

// Can mix and match
const encoded = encode(data)
const decoded = Base64.decode(encoded) // works

Types

/**
 * Standard base64-encoded string
 */
export type Base64String = string

/**
 * URL-safe base64-encoded string (no padding, - and _ instead of + and /)
 */
export type Base64UrlString = string

Source: types.ts

Implementation Details

All BrandedBase64 functions are implemented using Web APIs:

encode uses btoa() for encoding
decode uses atob() for decoding
URL-safe variants apply character substitutions
No external dependencies

// Example implementation (simplified)
export function encode(data: Uint8Array): string {
  let binary = ""
  for (let i = 0; i < data.length; i++) {
    binary += String.fromCharCode(data[i] ?? 0)
  }
  return btoa(binary)
}

export function encodeUrlSafe(data: Uint8Array): string {
  return encode(data)
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=/g, "")
}

Performance

BrandedBase64 functions have same performance as Base64 namespace (same implementations):

Encoding: O(n) where n is input byte length
Decoding: O(n) where n is input string length
Validation: O(n) with early exit on invalid chars
Size calculation: O(1) pure math

// Benchmark example
const data = new Uint8Array(1024)
const iterations = 100000

console.time("encode")
for (let i = 0; i < iterations; i++) {
  encode(data)
}
console.timeEnd("encode") // ~200-300ms for 100k iterations

Bundle Size Comparison

Approximate gzipped sizes:

Import Pattern	Size	Includes
`{ encode, decode }`	~200B	Standard encode/decode only
`{ encodeUrlSafe, decodeUrlSafe }`	~250B	URL-safe variants only
`{ encode, decode, isValid }`	~400B	Standard + validation
`{ encode, decode, calcEncodedSize }`	~250B	Standard + size calc
All functions	~800B	Complete Base64 implementation
`Base64` namespace	~800B	Same as all functions

Tree-shaking savings most significant when using only one variant.

Encoding - Encoding operations
Decoding - Decoding operations
Validation - Format validation
Utilities - Size calculations
Base64 - Main Base64 namespace documentation
Branded Types - Type branding pattern

Documentation Index

Try it Live

​BrandedBase64

​Overview

​Available Functions

​Standard Encoding/Decoding

​URL-Safe Encoding/Decoding

​Validation

​Utilities

​Data-First Pattern

​Tree-Shaking Benefits

​Example 1: Standard Only (Minimal)

​Example 2: URL-Safe Only

​Example 3: With Validation

​Example 4: Complete (All Features)

​Function Reference

​Encoding Functions

​Decoding Functions

​Validation Functions

​Utility Functions

​Usage Patterns

​Minimal Bundle (Basic Encoding)

​With Validation

​URL-Safe for Web APIs

​Size Pre-calculation

​When to Use BrandedBase64 vs Base64

​Use BrandedBase64 When:

​Use Base64 Namespace When:

​Interoperability

​Types

​Implementation Details

​Performance

​Bundle Size Comparison

​Related