> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Standard and URL-safe base64 encoding/decoding built on Web APIs

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/base64.ts">
  Run Base64 examples in the interactive playground
</Card>

<Tip>
  New to Base64? Start with [Fundamentals](/primitives/base64/fundamentals) for guided examples and encoding patterns.
</Tip>

## 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.

```typescript theme={null}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)

<Note>
  `toBase64()` and `setFromBase64()` are available as of 2025 (Node.js 22+, Chrome 131+). Use Tevm's `Base64.encode()` for broader compatibility.
</Note>

## Quick Reference

<Tabs />

### Effect Schema

```ts theme={null}
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)`](./encoding#encode) - Encode bytes to standard base64
* [`encodeString(str)`](./encoding#encodestring) - Encode UTF-8 string to base64
* [`encodeUrlSafe(data)`](./encoding#encodeurlsafe) - Encode bytes to URL-safe base64
* [`encodeStringUrlSafe(str)`](./encoding#encodestringurl) - Encode string to URL-safe base64
* [`calcEncodedSize(length)`](./utilities#calcencodedsize) - Calculate encoded size

### Decoding

* [`decode(encoded)`](./decoding#decode) - Decode standard base64 to bytes
* [`decodeToString(encoded)`](./decoding#decodetostring) - Decode base64 to UTF-8 string
* [`decodeUrlSafe(encoded)`](./decoding#decodeurlsafe) - Decode URL-safe base64 to bytes
* [`decodeUrlSafeToString(encoded)`](./decoding#decodeurlsafetostring) - Decode URL-safe base64 to string
* [`calcDecodedSize(length)`](./utilities#calcdecodedsize) - Calculate decoded size

### Validation

* [`isValid(str)`](./validation#isvalid) - Validate standard base64 format
* [`isValidUrlSafe(str)`](./validation#isvalidurlsafe) - Validate URL-safe base64 format

### BrandedBase64

Tree-shakeable functional API for minimal bundle size.

[View BrandedBase64 →](./branded-base64)

## Types

<Tabs>
  <Tab title="Base64String">
    ```typescript theme={null}
    export type Base64String = string;
    ```

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

  <Tab title="Base64UrlString">
    ```typescript theme={null}
    export type Base64UrlString = string;
    ```

    URL-safe base64-encoded string using alphabet: A-Z, a-z, 0-9, -, \_. No padding characters.
  </Tab>
</Tabs>

## Usage Patterns

### Encoding Binary Data

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

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

### Pre-allocating Buffers

```typescript theme={null}
// 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:

```typescript theme={null}
// 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
```

## Related

### Core Documentation

* [Fundamentals](/primitives/base64/fundamentals) - Learn encoding algorithm and patterns
* [Encoding](/primitives/base64/encoding) - Encoding methods and variants
* [Decoding](/primitives/base64/decoding) - Decoding methods and error handling
* [Validation](/primitives/base64/validation) - Format validation patterns

### Related Primitives

* [Hex](/primitives/hex) - Hex string encoding and decoding
* [Keccak256](/crypto/keccak256) - Keccak256 hashing for data integrity
* [Uint](/primitives/uint) - Unsigned integer utilities

## Specification

* [RFC 4648](https://tools.ietf.org/html/rfc4648) - Base64 encoding specification
  * Section 4: Standard base64 encoding
  * Section 5: URL-safe base64 encoding
* [MDN Web APIs](https://developer.mozilla.org/en-US/docs/Web/API/atob) - Browser base64 APIs