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

# Usage Patterns

> Common patterns for Base64 encoding and decoding

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

# Usage Patterns

Practical patterns for Base64 encoding and decoding in Ethereum applications.

## Data Encoding

### Binary to Base64

```typescript theme={null}
import * as Base64 from 'tevm/Base64';

// Encode binary data
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
const encoded = Base64.encode(binaryData);
console.log(encoded);  // "AQIDBAU="

// Encode hex to Base64
import * as Hex from 'tevm/Hex';
const hexData = Hex("0x48656c6c6f");  // "Hello"
const base64 = Base64.encode(Hex.toBytes(hexData));
console.log(base64);  // "SGVsbG8="
```

### String to Base64

```typescript theme={null}
// Encode UTF-8 string
function encodeString(str: string): BrandedBase64 {
  const bytes = new TextEncoder().encode(str);
  return Base64.encode(bytes);
}

const encoded = encodeString("Hello, Ethereum!");
// "SGVsbG8sIEV0aGVyZXVtIQ=="
```

## Data Decoding

### Base64 to Binary

```typescript theme={null}
// Decode to bytes
const decoded = Base64.decode(encoded);
console.log(Array(decoded));  // [1, 2, 3, 4, 5]

// Decode to hex
const hex = Hex(decoded);
console.log(Hex.toHex(hex));  // "0x0102030405"
```

### Base64 to String

```typescript theme={null}
// Decode to UTF-8 string
function decodeString(base64: BrandedBase64): string {
  const bytes = Base64.decode(base64);
  return new TextDecoder().decode(bytes);
}

const text = decodeString(encoded);
console.log(text);  // "Hello, Ethereum!"
```

## Validation

### Input Validation

```typescript theme={null}
// Validate before decoding
function safeDecode(input: string): Uint8Array | null {
  if (!Base64.isValid(input)) {
    console.error("Invalid Base64 input");
    return null;
  }

  try {
    return Base64.decode(Base64(input));
  } catch (err) {
    console.error("Decoding failed:", err);
    return null;
  }
}
```

### Format Checking

```typescript theme={null}
// Check if string is valid Base64
function isBase64String(str: string): boolean {
  return Base64.isValid(str);
}

// Validate and normalize
function normalizeBase64(input: string): BrandedBase64 {
  // Remove whitespace
  const cleaned = input.replace(/\s/g, '');

  if (!Base64.isValid(cleaned)) {
    throw new Error("Invalid Base64 format");
  }

  return Base64(cleaned);
}
```

## API Integration

### JSON Payload Encoding

```typescript theme={null}
interface APIPayload {
  data: string;  // Base64 encoded
  signature: string;  // Base64 encoded
}

function createPayload(
  data: Uint8Array,
  signature: Uint8Array
): APIPayload {
  return {
    data: Base64.encode(data),
    signature: Base64.encode(signature)
  };
}

function parsePayload(payload: APIPayload): {
  data: Uint8Array;
  signature: Uint8Array;
} {
  return {
    data: Base64.decode(Base64(payload.data)),
    signature: Base64.decode(Base64(payload.signature))
  };
}
```

### URL-safe Encoding

```typescript theme={null}
// Convert standard Base64 to URL-safe
function toURLSafe(base64: BrandedBase64): string {
  return base64
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');  // Remove padding
}

// Convert URL-safe to standard Base64
function fromURLSafe(urlSafe: string): BrandedBase64 {
  let standard = urlSafe
    .replace(/-/g, '+')
    .replace(/_/g, '/');

  // Add padding
  const padding = (4 - (standard.length % 4)) % 4;
  standard += '='.repeat(padding);

  return Base64(standard);
}
```

## Storage Patterns

### Database Storage

```typescript theme={null}
// Store binary data as Base64 in database
async function storeBinaryData(
  db: Database,
  key: string,
  data: Uint8Array
): Promise<void> {
  const encoded = Base64.encode(data);
  await db.set(key, encoded);
}

async function loadBinaryData(
  db: Database,
  key: string
): Promise<Uint8Array | null> {
  const encoded = await db.get(key);
  if (!encoded) return null;

  return Base64.decode(Base64(encoded));
}
```

### Configuration Files

```typescript theme={null}
// Encode keys for JSON config
interface Config {
  privateKey: string;  // Base64
  salt: string;  // Base64
}

function saveConfig(
  privateKey: Uint8Array,
  salt: Uint8Array
): Config {
  return {
    privateKey: Base64.encode(privateKey),
    salt: Base64.encode(salt)
  };
}

function loadConfig(config: Config): {
  privateKey: Uint8Array;
  salt: Uint8Array;
} {
  return {
    privateKey: Base64.decode(Base64(config.privateKey)),
    salt: Base64.decode(Base64(config.salt))
  };
}
```

## Testing

### Test Fixtures

```typescript theme={null}
const TEST_VECTORS = [
  { input: "", expected: "" },
  { input: "f", expected: "Zg==" },
  { input: "fo", expected: "Zm8=" },
  { input: "foo", expected: "Zm9v" },
  { input: "foob", expected: "Zm9vYg==" },
  { input: "fooba", expected: "Zm9vYmE=" },
  { input: "foobar", expected: "Zm9vYmFy" }
];

// Test encoding
TEST_VECTORS.forEach(({ input, expected }) => {
  const bytes = new TextEncoder().encode(input);
  const encoded = Base64.encode(bytes);
  console.assert(encoded === expected, `Encoding failed for: ${input}`);
});
```

## Related

* [Encoding](/primitives/base64/encoding) - Encoding methods
* [Decoding](/primitives/base64/decoding) - Decoding methods
* [Validation](/primitives/base64/validation) - Format validation
* [Fundamentals](/primitives/base64/fundamentals) - Base64 basics