0
# Binary Data Operations
1

2
Convert between Uint8Array and Base64 strings for handling binary data like images, files, and byte arrays with cross-platform compatibility.
3

4
## Capabilities
5

6
### Uint8Array to Base64
7

8
Converts a Uint8Array to a Base64 string with optional URL-safe encoding.
9

10
```typescript { .api }
11
/**
12
 * Converts a Uint8Array to a Base64 string
13
 * @param u8a - The Uint8Array to convert
14
 * @param urlsafe - If true, make the result URL-safe (uses - and _ instead of + and /)
15
 * @returns Base64 encoded string
16
 */
17
function fromUint8Array(u8a: Uint8Array, urlsafe?: boolean): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { fromUint8Array } from "js-base64";
24

25
// Basic conversion
26
const bytes = new Uint8Array([100, 97, 110, 107, 111, 103, 97, 105]);
27
const encoded = fromUint8Array(bytes);
28
console.log(encoded); // "ZGFua29nYWk="
29

30
// URL-safe conversion
31
const urlSafe = fromUint8Array(bytes, true);
32
console.log(urlSafe); // "ZGFua29nYWk" (no padding)
33

34
// Converting image data or file bytes
35
const imageBytes = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]); // PNG header
36
const imageB64 = fromUint8Array(imageBytes);
37
console.log(imageB64); // "iVBORw0KGgo="
38

39
// Working with typed arrays from File API or ArrayBuffer
40
const buffer = new ArrayBuffer(8);
41
const view = new Uint8Array(buffer);
42
view.set([72, 101, 108, 108, 111, 33, 33, 33]); // "Hello!!!"
43
const result = fromUint8Array(view);
44
console.log(result); // "SGVsbG8hISE="
45
```
46

47
### Base64 to Uint8Array
48

49
Converts a Base64 string to a Uint8Array for binary data processing.
50

51
```typescript { .api }
52
/**
53
 * Converts a Base64 string to a Uint8Array
54
 * @param a - Base64 string (both normal and URL-safe are supported)
55
 * @returns Uint8Array containing the decoded binary data
56
 */
57
function toUint8Array(a: string): Uint8Array;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { toUint8Array } from "js-base64";
64

65
// Basic conversion
66
const decoded = toUint8Array("ZGFua29nYWk=");
67
console.log(decoded); // Uint8Array(8) [100, 97, 110, 107, 111, 103, 97, 105]
68

69
// Convert to regular array if needed
70
const asArray = Array.from(decoded);
71
console.log(asArray); // [100, 97, 110, 107, 111, 103, 97, 105]
72

73
// Working with image data
74
const pngHeader = toUint8Array("iVBORw0KGgo=");
75
console.log(pngHeader); // Uint8Array [137, 80, 78, 71, 13, 10, 26, 10]
76

77
// URL-safe format (automatically detected)
78
const urlSafeDecoded = toUint8Array("ZGFua29nYWk");
79
console.log(urlSafeDecoded); // Same result as above
80

81
// Creating blobs from Base64 data
82
const b64Data = "SGVsbG8gV29ybGQh"; // "Hello World!"
83
const bytes = toUint8Array(b64Data);
84
const blob = new Blob([bytes], { type: 'text/plain' });
85

86
// Working with fetch responses
87
async function processB64Image(base64String) {
88
  const imageBytes = toUint8Array(base64String);
89
  const blob = new Blob([imageBytes], { type: 'image/png' });
90
  const url = URL.createObjectURL(blob);
91
  return url;
92
}
93
```
94

95
## Integration Examples
96

97
### Round-trip Conversion
98

99
```typescript
100
import { fromUint8Array, toUint8Array } from "js-base64";
101

102
// Original data
103
const original = new Uint8Array([1, 2, 3, 4, 5, 255, 128, 0]);
104

105
// Convert to Base64 and back
106
const encoded = fromUint8Array(original);
107
const decoded = toUint8Array(encoded);
108

109
// Verify integrity
110
console.log(original.every((byte, i) => byte === decoded[i])); // true
111
```
112

113
### File Processing
114

115
```typescript
116
import { fromUint8Array, toUint8Array } from "js-base64";
117

118
// Reading a file as Base64
119
async function fileToBase64(file: File): Promise<string> {
120
  const arrayBuffer = await file.arrayBuffer();
121
  const uint8Array = new Uint8Array(arrayBuffer);
122
  return fromUint8Array(uint8Array);
123
}
124

125
// Converting Base64 back to file
126
function base64ToFile(base64: string, filename: string, mimeType: string): File {
127
  const uint8Array = toUint8Array(base64);
128
  return new File([uint8Array], filename, { type: mimeType });
129
}
130
```
131

132
### Working with ArrayBuffer
133

134
```typescript
135
import { fromUint8Array, toUint8Array } from "js-base64";
136

137
// ArrayBuffer to Base64
138
function arrayBufferToBase64(buffer: ArrayBuffer): string {
139
  const uint8Array = new Uint8Array(buffer);
140
  return fromUint8Array(uint8Array);
141
}
142

143
// Base64 to ArrayBuffer
144
function base64ToArrayBuffer(base64: string): ArrayBuffer {
145
  const uint8Array = toUint8Array(base64);
146
  return uint8Array.buffer.slice(uint8Array.byteOffset, uint8Array.byteOffset + uint8Array.byteLength);
147
}
148
```
149

150
## Key Features
151

152
- **Cross-platform Compatibility**: Uses Buffer in Node.js and polyfills in browsers for optimal performance
153
- **Format Flexibility**: Automatically handles both standard and URL-safe Base64 formats
154
- **Memory Efficient**: Direct conversion without intermediate string representations when possible  
155
- **Binary Safe**: Preserves all byte values including null bytes and high values (128-255)
156
- **Type Safety**: Full TypeScript support with proper Uint8Array typing