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

# Base64 Validation

> Validating base64 string formats

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

# Validation

Methods for validating base64 string formats before decoding.

## Standard Base64 Validation

### `Base64.isValid(str)`

Checks if string is valid standard base64 format. Validates alphabet, length, and padding requirements.

```typescript theme={null}
// Valid base64 strings
Base64.isValid("SGVsbG8=")           // true (proper padding)
Base64.isValid("SGVsbG8sIHdvcmxk")   // true (no padding needed)
Base64.isValid("")                   // true (empty string)
Base64.isValid("AAAA")               // true (minimal valid)

// Invalid base64 strings
Base64.isValid("SGVsbG8")            // false (wrong length without padding)
Base64.isValid("SGVs!G8=")           // false (invalid character !)
Base64.isValid("SGVsbG8=A")          // false (content after padding)
Base64.isValid("SGVsbG===")          // false (too many padding chars)
```

**Parameters:**

* `str: string` - String to validate

**Returns:** `boolean` - `true` if valid standard base64, `false` otherwise

**Validation rules:**

* **Alphabet:** Only `A-Z`, `a-z`, `0-9`, `+`, `/`
* **Length:** Must be multiple of 4 characters
* **Padding:** 0-2 `=` characters at end only
* **Empty:** Empty string is valid

**Example:**

```typescript theme={null}
// Validate before decoding
function safeDecodeBase64(input: string): Uint8Array | null {
  if (!Base64.isValid(input)) {
    console.warn("Invalid base64 format")
    return null
  }
  return Base64.decode(input)
}

// Usage with user input
const userInput = getUserInput()
if (Base64.isValid(userInput)) {
  const data = Base64.decode(userInput)
  processData(data)
} else {
  showError("Please enter valid base64")
}
```

Defined in: [primitives/Base64/BrandedBase64/isValid.js:7](https://github.com/evmts/voltaire/blob/main/src/primitives/Base64/BrandedBase64/isValid.js)

**Implementation:**

```typescript theme={null}
// Checks performed:
// 1. Empty string → valid
// 2. Regex: /^[A-Za-z0-9+/]*={0,2}$/
// 3. Length % 4 === 0
// 4. Try atob() to confirm decode works
```

## URL-Safe Base64 Validation

### `Base64.isValidUrlSafe(str)`

Checks if string is valid URL-safe base64 format. Validates URL-safe alphabet without padding requirements.

```typescript theme={null}
// Valid URL-safe base64
Base64.isValidUrlSafe("SGVsbG8")     // true (no padding)
Base64.isValidUrlSafe("AB-_CD")      // true (URL-safe chars)
Base64.isValidUrlSafe("")            // true (empty string)
Base64.isValidUrlSafe("abcdef123")   // true (alphanumeric)

// Invalid URL-safe base64
Base64.isValidUrlSafe("SGVs+G8/")    // false (standard chars +, /)
Base64.isValidUrlSafe("SGVsbG8=")    // false (has padding)
Base64.isValidUrlSafe("SGVs!G8")     // false (invalid character !)
Base64.isValidUrlSafe("SGVs G8")     // false (contains space)
```

**Parameters:**

* `str: string` - String to validate

**Returns:** `boolean` - `true` if valid URL-safe base64, `false` otherwise

**Validation rules:**

* **Alphabet:** Only `A-Z`, `a-z`, `0-9`, `-`, `_`
* **Length:** No length requirement (padding removed)
* **Padding:** No padding characters allowed
* **Empty:** Empty string is valid

**Example:**

```typescript theme={null}
// Validate URL parameter
const token = new URLSearchParams(window.location.search).get("token")
if (token && Base64.isValidUrlSafe(token)) {
  const decoded = Base64.decodeUrlSafe(token)
  authenticateWithToken(decoded)
} else {
  console.error("Invalid token format")
}

// Validate filename
function isValidBase64Filename(filename: string): boolean {
  const nameWithoutExt = filename.replace(/\.[^.]+$/, "")
  return Base64.isValidUrlSafe(nameWithoutExt)
}
```

Defined in: [primitives/Base64/BrandedBase64/isValidUrlSafe.js:7](https://github.com/evmts/voltaire/blob/main/src/primitives/Base64/BrandedBase64/isValidUrlSafe.js)

**Implementation:**

```typescript theme={null}
// Checks performed:
// 1. Empty string → valid
// 2. Regex: /^[A-Za-z0-9_-]*$/
```

## Usage Patterns

### Type-Safe Validation

```typescript theme={null}
// Type guard for validated base64
function isBase64String(value: unknown): value is string {
  return typeof value === "string" && Base64.isValid(value)
}

// Usage
function processBase64(input: unknown) {
  if (isBase64String(input)) {
    // TypeScript knows input is string here
    const decoded = Base64.decode(input)
    return decoded
  }
  throw new Error("Invalid base64 input")
}
```

### Format Detection

```typescript theme={null}
// Detect which base64 format is used
function detectBase64Format(str: string): "standard" | "url-safe" | "invalid" {
  if (Base64.isValid(str)) {
    return "standard"
  }
  if (Base64.isValidUrlSafe(str)) {
    return "url-safe"
  }
  return "invalid"
}

// Usage
const format = detectBase64Format(input)
switch (format) {
  case "standard":
    return Base64.decode(input)
  case "url-safe":
    return Base64.decodeUrlSafe(input)
  case "invalid":
    throw new Error("Invalid base64")
}
```

### Validation with Error Messages

```typescript theme={null}
// Detailed validation with error reporting
function validateBase64(str: string): { valid: boolean; error?: string } {
  if (str.length === 0) {
    return { valid: true }
  }

  // Check length for standard base64
  if (str.length % 4 !== 0) {
    return {
      valid: false,
      error: "Length must be multiple of 4 for standard base64"
    }
  }

  // Check characters
  const standardRegex = /^[A-Za-z0-9+/]*={0,2}$/
  if (!standardRegex.test(str)) {
    return {
      valid: false,
      error: "Contains invalid characters for standard base64"
    }
  }

  // Verify decode works
  try {
    atob(str)
    return { valid: true }
  } catch {
    return {
      valid: false,
      error: "Failed to decode - invalid base64 structure"
    }
  }
}
```

### Pre-decode Validation

```typescript theme={null}
// Always validate before decoding
function decodeBase64Safe(input: string): Uint8Array {
  // Validate format
  if (!Base64.isValid(input)) {
    throw new Error("Invalid base64 format")
  }

  // Decode (should not throw now)
  try {
    return Base64.decode(input)
  } catch (error) {
    // Should rarely reach here after validation
    throw new Error(`Unexpected decode error: ${error}`)
  }
}
```

### Batch Validation

```typescript theme={null}
// Validate multiple base64 strings
function validateBase64Batch(strings: string[]): {
  valid: string[]
  invalid: string[]
} {
  const valid: string[] = []
  const invalid: string[] = []

  for (const str of strings) {
    if (Base64.isValid(str)) {
      valid.push(str)
    } else {
      invalid.push(str)
    }
  }

  return { valid, invalid }
}

// Usage
const inputs = ["SGVsbG8=", "invalid!", "AAAA"]
const { valid, invalid } = validateBase64Batch(inputs)
console.log(`Valid: ${valid.length}, Invalid: ${invalid.length}`)
```

### Validation with Conversion

```typescript theme={null}
// Try URL-safe, convert to standard if needed
function normalizeBase64(input: string): string | null {
  // Already valid standard base64
  if (Base64.isValid(input)) {
    return input
  }

  // Try as URL-safe and convert
  if (Base64.isValidUrlSafe(input)) {
    // Convert URL-safe to standard
    let standard = input.replace(/-/g, "+").replace(/_/g, "/")

    // Add padding
    const pad = input.length % 4
    if (pad === 2) standard += "=="
    else if (pad === 3) standard += "="

    return standard
  }

  return null
}
```

## Validation Examples

### Valid Standard Base64

```typescript theme={null}
// All these pass Base64.isValid()
const examples = [
  "",                              // Empty
  "AAAA",                          // No padding
  "SGVsbG8=",                      // One = padding
  "SGVs",                          // No padding needed
  "YWJjZA==",                      // Two = padding
  "TWFu",                          // Minimal (3 bytes)
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/==", // All chars
]

examples.forEach(ex => {
  console.log(`"${ex}": ${Base64.isValid(ex)}`)
})
```

### Valid URL-Safe Base64

```typescript theme={null}
// All these pass Base64.isValidUrlSafe()
const examples = [
  "",                              // Empty
  "SGVsbG8",                       // No padding
  "AB-_CD",                        // URL-safe chars
  "abcdef123",                     // Alphanumeric
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_", // All chars
]

examples.forEach(ex => {
  console.log(`"${ex}": ${Base64.isValidUrlSafe(ex)}`)
})
```

### Invalid Examples

```typescript theme={null}
// All these fail both validators
const invalid = [
  "SGVsbG8",     // Wrong length without padding (standard)
  "SGVs!G8=",    // Invalid character !
  "SGVsbG8= ",   // Trailing space
  " SGVsbG8=",   // Leading space
  "SGVs G8=",    // Space in middle
  "SGVsbG===",   // Too many = characters
  "=SGVsbG8",    // Padding at start
  "SGVs=bG8=",   // Padding in middle
]

invalid.forEach(ex => {
  console.log(`"${ex}": standard=${Base64.isValid(ex)}, url-safe=${Base64.isValidUrlSafe(ex)}`)
})
```

## Validation Algorithm

Standard base64 validation:

1. Check empty string (valid)
2. Check regex: `/^[A-Za-z0-9+/]*={0,2}$/`
3. Check length: `length % 4 === 0`
4. Verify decode: `atob(str)` succeeds

URL-safe base64 validation:

1. Check empty string (valid)
2. Check regex: `/^[A-Za-z0-9_-]*$/`

## Performance

Validation is fast and should be done before decoding:

* `isValid()`: \~1μs per call (includes regex + atob)
* `isValidUrlSafe()`: \~0.5μs per call (regex only)

```typescript theme={null}
// Benchmark example
const iterations = 100000
const input = "SGVsbG8sIHdvcmxkIQ=="

console.time("validate")
for (let i = 0; i < iterations; i++) {
  Base64.isValid(input)
}
console.timeEnd("validate") // ~100ms for 100k iterations
```

## Related

* [Encoding](/primitives/base64/encoding) - Encoding to base64 format
* [Decoding](/primitives/base64/decoding) - Decoding base64 strings
* [Utilities](/primitives/base64/utilities) - Size calculations
* [BrandedBase64](/primitives/base64/branded-base64) - Tree-shakeable API