0
# Validation and Utility Functions
1

2
Validate Base64 strings and access version information with comprehensive validation logic that handles multiple Base64 formats.
3

4
## Capabilities
5

6
### Base64 Validation
7

8
Validates whether a value is a properly formatted Base64 string.
9

10
```typescript { .api }
11
/**
12
 * Check if a value is a valid Base64 string
13
 * @param src - A value to check (typically string, but accepts any type)
14
 * @returns true if the value is a valid Base64 string, false otherwise
15
 */
16
function isValid(src: unknown): boolean;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { isValid } from "js-base64";
23

24
// Basic validation
25
console.log(isValid("SGVsbG8=")); // true - valid Base64
26
console.log(isValid("Hello")); // false - not Base64
27
console.log(isValid("")); // true - empty string is valid Base64 (represents empty data)
28

29
// Type checking
30
console.log(isValid(123)); // false - not a string
31
console.log(isValid(null)); // false - not a string
32
console.log(isValid(undefined)); // false - not a string
33

34
// Padding validation
35
console.log(isValid("SGVsbG8=")); // true - with proper padding
36
console.log(isValid("SGVsbG8")); // true - padding can be omitted
37
console.log(isValid("SGVsbG")); // true - partial padding omitted
38

39
// Format variations
40
console.log(isValid("SGVs bG8=")); // true - whitespace is allowed
41
console.log(isValid("SGVsbG8+")); // true - standard Base64 characters
42
console.log(isValid("SGVsbG8-")); // true - URL-safe Base64 characters
43

44
// Invalid formats
45
console.log(isValid("SGVs+-bG8=")); // false - can't mix standard and URL-safe
46
console.log(isValid("SGVs@bG8=")); // false - invalid character (@)
47
console.log(isValid("SGVs=====")); // false - too much padding
48

49
// Real-world usage
50
function processBase64Input(input: unknown): string | null {
51
  if (isValid(input)) {
52
    return decode(input as string);
53
  }
54
  return null;
55
}
56

57
// Form validation
58
function validateBase64Field(value: string): { isValid: boolean; error?: string } {
59
  if (!value.trim()) {
60
    return { isValid: true }; // Empty is valid
61
  }
62
  
63
  if (!isValid(value)) {
64
    return { 
65
      isValid: false, 
66
      error: "Please enter a valid Base64 string" 
67
    };
68
  }
69
  
70
  return { isValid: true };
71
}
72
```
73

74
### Version Information
75

76
Access the library version for compatibility checking and debugging.
77

78
```typescript { .api }
79
/**
80
 * Current version of the js-base64 library
81
 */
82
const version: string;
83

84
/**
85
 * @deprecated Use lowercase 'version' instead
86
 * Legacy uppercase version constant
87
 */
88
const VERSION: string;
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { version, VERSION } from "js-base64";
95

96
// Check current version
97
console.log(version); // "3.7.8"
98

99
// Version compatibility checking
100
function checkCompatibility() {
101
  const minVersion = "3.0.0";
102
  const currentVersion = version;
103
  
104
  // Simple version comparison (for more complex needs, use a semver library)
105
  const [major, minor] = currentVersion.split('.').map(Number);
106
  const [minMajor, minMinor] = minVersion.split('.').map(Number);
107
  
108
  if (major > minMajor || (major === minMajor && minor >= minMinor)) {
109
    console.log("Compatible version");
110
  } else {
111
    console.log("Version too old");
112
  }
113
}
114

115
// Debugging information
116
function getDebugInfo() {
117
  return {
118
    library: "js-base64",
119
    version: version,
120
    environment: typeof window !== 'undefined' ? 'browser' : 'node',
121
    hasBuffer: typeof Buffer !== 'undefined',
122
    hasTextEncoder: typeof TextEncoder !== 'undefined'
123
  };
124
}
125

126
// Legacy usage (deprecated)
127
console.log(VERSION); // "3.7.8" - same as version, but deprecated
128
```
129

130
## Validation Details
131

132
### What isValid() Checks
133

134
The `isValid` function performs comprehensive validation:
135

136
1. **Type Check**: Must be a string
137
2. **Character Set**: Only valid Base64 characters (A-Z, a-z, 0-9, +, /, =) or URL-safe characters (A-Z, a-z, 0-9, -, _, =)
138
3. **Format Consistency**: Cannot mix standard (+/) and URL-safe (-_) characters
139
4. **Padding Rules**: Proper padding with = characters, or no padding
140
5. **Whitespace Handling**: Ignores whitespace for validation
141

142
### Advanced Validation Examples
143

144
```typescript
145
import { isValid, decode } from "js-base64";
146

147
// Validation with error details (custom wrapper)
148
function validateBase64WithDetails(input: unknown): { 
149
  valid: boolean; 
150
  reason?: string; 
151
  data?: string 
152
} {
153
  if (typeof input !== 'string') {
154
    return { valid: false, reason: 'Input must be a string' };
155
  }
156
  
157
  if (!isValid(input)) {
158
    return { valid: false, reason: 'Invalid Base64 format' };
159
  }
160
  
161
  try {
162
    const decoded = decode(input);
163
    return { valid: true, data: decoded };
164
  } catch (error) {
165
    return { valid: false, reason: 'Base64 decoding failed' };
166
  }
167
}
168

169
// Usage in API validation
170
function apiEndpoint(request: { data: string }) {
171
  const validation = validateBase64WithDetails(request.data);
172
  
173
  if (!validation.valid) {
174
    throw new Error(`Invalid input: ${validation.reason}`);
175
  }
176
  
177
  // Process the valid Base64 data
178
  return { decoded: validation.data };
179
}
180
```
181

182
### Performance Considerations
183

184
```typescript
185
import { isValid } from "js-base64";
186

187
// For large amounts of data, validate before expensive operations
188
function processBase64Data(inputs: string[]) {
189
  // Pre-filter valid inputs
190
  const validInputs = inputs.filter(isValid);
191
  
192
  // Only decode valid inputs
193
  return validInputs.map(decode);
194
}
195

196
// Quick validation for user input
197
function onUserInput(value: string) {
198
  if (value.length > 1000000) {
199
    // Skip validation for very large strings to avoid UI blocking
200
    return false;
201
  }
202
  
203
  return isValid(value);
204
}
205
```
206

207
## Key Features
208

209
- **Type Safe**: Accepts any type but only validates strings
210
- **Format Flexible**: Handles both standard and URL-safe Base64
211
- **Whitespace Tolerant**: Ignores whitespace in validation
212
- **Padding Flexible**: Works with or without padding
213
- **Performance Optimized**: Fast validation without full decoding
214
- **Version Tracking**: Access to library version for compatibility checks