0
# Prototype Extensions
1

2
Optional methods that can be added to String.prototype and Uint8Array.prototype for fluent method chaining and convenient Base64 operations directly on built-in types.
3

4
## Capabilities
5

6
### String Prototype Extensions  
7

8
Add Base64 encoding and decoding methods directly to String.prototype.
9

10
```typescript { .api }
11
/**
12
 * Extend String.prototype with Base64 methods
13
 * Adds: fromBase64, toBase64, toBase64URI, toBase64URL, toUint8Array
14
 */
15
function extendString(): void;
16
```
17

18
Once `extendString()` is called, these methods become available on all strings:
19

20
```typescript { .api }
21
interface String {
22
  /** Decode this Base64 string to UTF-8 */
23
  fromBase64(): string;
24
  /** Encode this string to Base64 */
25
  toBase64(urlsafe?: boolean): string;
26
  /** Encode this string to URL-safe Base64 */
27
  toBase64URI(): string;
28
  /** Alias for toBase64URI */
29
  toBase64URL(): string;
30
  /** Convert this Base64 string to Uint8Array */
31
  toUint8Array(): Uint8Array;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { extendString } from "js-base64";
39

40
// Enable string extensions
41
extendString();
42

43
// Now you can use Base64 methods on any string
44
const text = "Hello World!";
45
const encoded = text.toBase64();
46
console.log(encoded); // "SGVsbG8gV29ybGQh"
47

48
const decoded = encoded.fromBase64();
49
console.log(decoded); // "Hello World!"
50

51
// URL-safe encoding
52
const urlSafe = text.toBase64URI();
53
console.log(urlSafe); // "SGVsbG8gV29ybGQ" (no padding)
54

55
// Alternative URL-safe method
56
const urlSafe2 = text.toBase64URL();
57
console.log(urlSafe2); // Same as toBase64URI()
58

59
// UTF-8 support
60
const japanese = "小飼弾";
61
const japaneseEncoded = japanese.toBase64();
62
console.log(japaneseEncoded); // "5bCP6aO85by+"
63

64
const japaneseDecoded = japaneseEncoded.fromBase64();
65
console.log(japaneseDecoded); // "小飼弾"
66

67
// Convert Base64 string to binary data
68
const binaryData = encoded.toUint8Array();
69
console.log(binaryData); // Uint8Array representing "Hello World!"
70

71
// Method chaining
72
const result = "Test String"
73
  .toBase64()
74
  .fromBase64()
75
  .toBase64URI();
76
console.log(result); // "VGVzdCBTdHJpbmc"
77
```
78

79
### Uint8Array Prototype Extensions
80

81
Add Base64 encoding methods directly to Uint8Array.prototype.
82

83
```typescript { .api }
84
/**
85
 * Extend Uint8Array.prototype with Base64 methods
86
 * Adds: toBase64, toBase64URI, toBase64URL
87
 */
88
function extendUint8Array(): void;
89
```
90

91
Once `extendUint8Array()` is called, these methods become available on all Uint8Arrays:
92

93
```typescript { .api }
94
interface Uint8Array {
95
  /** Encode this Uint8Array to Base64 */
96
  toBase64(urlsafe?: boolean): string;
97
  /** Encode this Uint8Array to URL-safe Base64 */
98
  toBase64URI(): string;
99
  /** Alias for toBase64URI */
100
  toBase64URL(): string;
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { extendUint8Array } from "js-base64";
108

109
// Enable Uint8Array extensions
110
extendUint8Array();
111

112
// Create some binary data
113
const bytes = new Uint8Array([72, 101, 108, 108, 111, 33]); // "Hello!"
114

115
// Convert to Base64
116
const encoded = bytes.toBase64();
117
console.log(encoded); // "SGVsbG8h"
118

119
// URL-safe encoding
120
const urlSafe = bytes.toBase64URI();
121
console.log(urlSafe); // "SGVsbG8h" (no padding)
122

123
// Alternative URL-safe method
124
const urlSafe2 = bytes.toBase64URL();
125
console.log(urlSafe2); // Same as toBase64URI()
126

127
// Working with file data
128
async function processFile(file: File) {
129
  extendUint8Array();
130
  
131
  const arrayBuffer = await file.arrayBuffer();
132
  const uint8Array = new Uint8Array(arrayBuffer);
133
  
134
  // Now you can directly encode the file data
135
  const base64 = uint8Array.toBase64();
136
  return `data:${file.type};base64,${base64}`;
137
}
138

139
// Image processing example
140
const pngHeader = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
141
const headerB64 = pngHeader.toBase64();
142
console.log(headerB64); // "iVBORw0KGgo="
143
```
144

145
### Extend All Built-ins
146

147
Convenience function to extend both String and Uint8Array prototypes at once.
148

149
```typescript { .api }
150
/**
151
 * Extend both String.prototype and Uint8Array.prototype with Base64 methods
152
 * Equivalent to calling both extendString() and extendUint8Array()
153
 */
154
function extendBuiltins(): void;
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { extendBuiltins } from "js-base64";
161

162
// Enable all prototype extensions
163
extendBuiltins();
164

165
// Now both strings and Uint8Arrays have Base64 methods
166
const text = "Hello World!";
167
const encoded = text.toBase64(); // String method
168

169
const bytes = new Uint8Array([72, 101, 108, 108, 111]);
170
const binaryEncoded = bytes.toBase64(); // Uint8Array method
171

172
// Round-trip conversion
173
const original = "Test data";
174
const roundTrip = original
175
  .toBase64()           // String -> Base64
176
  .toUint8Array()       // Base64 -> Uint8Array
177
  .toBase64()           // Uint8Array -> Base64
178
  .fromBase64();        // Base64 -> String
179
console.log(roundTrip); // "Test data"
180
```
181

182
## Complete Extension API Reference
183

184
### String Methods Added
185

186
After calling `extendString()` or `extendBuiltins()`:
187

188
```typescript
189
"any string".fromBase64();        // Decode Base64 to UTF-8 string
190
"any string".toBase64();          // Encode to standard Base64
191
"any string".toBase64(true);      // Encode to URL-safe Base64 (no padding)
192
"any string".toBase64URI();       // Encode to URL-safe Base64
193
"any string".toBase64URL();       // Same as toBase64URI()
194
"base64string".toUint8Array();    // Convert Base64 string to Uint8Array
195
```
196

197
### Uint8Array Methods Added
198

199
After calling `extendUint8Array()` or `extendBuiltins()`:
200

201
```typescript
202
uint8Array.toBase64();            // Encode to standard Base64
203
uint8Array.toBase64(true);        // Encode to URL-safe Base64 (no padding)
204
uint8Array.toBase64URI();         // Encode to URL-safe Base64
205
uint8Array.toBase64URL();         // Same as toBase64URI()
206
```
207

208
## Important Considerations
209

210
### Global Scope Impact
211

212
```typescript
213
import { extendBuiltins } from "js-base64";
214

215
// This modifies global prototypes - affects ALL strings and Uint8Arrays
216
extendBuiltins();
217

218
// Every string now has these methods
219
console.log("test".toBase64); // [Function]
220

221
// This might conflict with other libraries or cause unexpected behavior
222
// Use with caution in shared codebases
223
```
224

225
### Best Practices
226

227
```typescript
228
import { extendBuiltins, encode, decode } from "js-base64";
229

230
// Option 1: Use extensions for convenience in applications
231
function initializeApp() {
232
  extendBuiltins();
233
  // Now use methods throughout the app
234
}
235

236
// Option 2: Use functional API for libraries
237
function myLibraryFunction(input: string) {
238
  // Don't modify global prototypes in library code
239
  return encode(input);
240
}
241

242
// Option 3: Conditional extension for compatibility
243
function safeExtendBuiltins() {
244
  if (typeof String.prototype.toBase64 === 'undefined') {
245
    extendBuiltins();
246
  }
247
}
248
```
249

250
### TypeScript Integration
251

252
```typescript
253
// If using TypeScript with extensions, you may need to declare the methods
254
declare global {
255
  interface String {
256
    fromBase64(): string;
257
    toBase64(urlsafe?: boolean): string;
258
    toBase64URI(): string;
259
    toBase64URL(): string;
260
    toUint8Array(): Uint8Array;
261
  }
262
  
263
  interface Uint8Array {
264
    toBase64(urlsafe?: boolean): string;
265
    toBase64URI(): string;
266
    toBase64URL(): string;
267
  }
268
}
269

270
// Or import the library's type extensions if provided
271
```
272

273
## Key Features
274

275
- **Fluent Interface**: Method chaining for complex operations
276
- **Consistent API**: Same options and behavior as functional equivalents
277
- **Non-enumerable**: Added methods don't appear in for-in loops or Object.keys()
278
- **Configurable**: Methods are configurable and writable (can be overridden)
279
- **Opt-in**: Prototype extensions are completely optional
280
- **Full Coverage**: All major Base64 operations available as methods