0
# Base Encodings
1

2
Standard RFC 4648 compliant base encodings including base16 (hexadecimal), base32 variants, and base64 variants. All implementations are secure, audited, and use built-in browser APIs when available for optimal performance.
3

4
## Capabilities
5

6
### Base16 (Hexadecimal)
7

8
RFC 4648 base16 encoding using uppercase hexadecimal alphabet.
9

10
```typescript { .api }
11
/**
12
 * base16 encoding from RFC 4648
13
 * Uses uppercase hexadecimal (0-9, A-F)
14
 */
15
const base16: BytesCoder = {
16
  encode: (data: Uint8Array) => string;
17
  decode: (str: string) => Uint8Array;
18
};
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { base16 } from "@scure/base";
25

26
const data = new Uint8Array([0x12, 0xab, 0xff]);
27
const encoded = base16.encode(data);    // "12ABFF"
28
const decoded = base16.decode("12ABFF"); // Uint8Array([0x12, 0xab, 0xff])
29
```
30

31
### Base32 Standard
32

33
RFC 4648 base32 encoding with padding using standard alphabet.
34

35
```typescript { .api }
36
/**
37
 * base32 encoding from RFC 4648 with padding
38
 * Uses alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
39
 * Use base32nopad for unpadded version
40
 */
41
const base32: BytesCoder = {
42
  encode: (data: Uint8Array) => string;
43
  decode: (str: string) => Uint8Array;
44
};
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { base32 } from "@scure/base";
51

52
const data = new Uint8Array([0x12, 0xab]);
53
const encoded = base32.encode(data);    // "CKVQ===="
54
const decoded = base32.decode("CKVQ===="); // Uint8Array([0x12, 0xab])
55
```
56

57
### Base32 No Padding
58

59
RFC 4648 base32 encoding without padding.
60

61
```typescript { .api }
62
/**
63
 * base32 encoding from RFC 4648 without padding
64
 * Same alphabet as base32 but no padding characters
65
 */
66
const base32nopad: BytesCoder = {
67
  encode: (data: Uint8Array) => string;
68
  decode: (str: string) => Uint8Array;
69
};
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { base32nopad } from "@scure/base";
76

77
const data = new Uint8Array([0x12, 0xab]);
78
const encoded = base32nopad.encode(data);    // "CKVQ"
79
const decoded = base32nopad.decode("CKVQ");  // Uint8Array([0x12, 0xab])
80
```
81

82
### Base32 Hex
83

84
RFC 4648 base32hex encoding with padding using extended hex alphabet.
85

86
```typescript { .api }
87
/**
88
 * base32hex encoding from RFC 4648 with padding
89
 * Uses alphabet: 0123456789ABCDEFGHIJKLMNOPQRSTUV
90
 * Use base32hexnopad for unpadded version
91
 */
92
const base32hex: BytesCoder = {
93
  encode: (data: Uint8Array) => string;
94
  decode: (str: string) => Uint8Array;
95
};
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { base32hex } from "@scure/base";
102

103
const data = new Uint8Array([0x12, 0xab]);
104
const encoded = base32hex.encode(data);    // "2ALG===="
105
const decoded = base32hex.decode("2ALG===="); // Uint8Array([0x12, 0xab])
106
```
107

108
### Base32 Hex No Padding
109

110
RFC 4648 base32hex encoding without padding.
111

112
```typescript { .api }
113
/**
114
 * base32hex encoding from RFC 4648 without padding
115
 * Same extended hex alphabet as base32hex but no padding
116
 */
117
const base32hexnopad: BytesCoder = {
118
  encode: (data: Uint8Array) => string;
119
  decode: (str: string) => Uint8Array;
120
};
121
```
122

123
### Base32 Crockford
124

125
Doug Crockford's base32 variant with case-insensitive decoding and character normalization.
126

127
```typescript { .api }
128
/**
129
 * base32 encoding using Crockford's variant
130
 * Uses alphabet: 0123456789ABCDEFGHJKMNPQRSTVWXYZ
131
 * Normalizes O->0, I/L->1 during decoding for error resilience
132
 */
133
const base32crockford: BytesCoder = {
134
  encode: (data: Uint8Array) => string;
135
  decode: (str: string) => Uint8Array;
136
};
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
import { base32crockford } from "@scure/base";
143

144
const data = new Uint8Array([0x12, 0xab]);
145
const encoded = base32crockford.encode(data);  // "2ANG"
146
const decoded = base32crockford.decode("2ANG"); // Uint8Array([0x12, 0xab])
147

148
// Case insensitive and normalizes ambiguous characters
149
const normalized = base32crockford.decode("2ang"); // Same result
150
const withSubs = base32crockford.decode("2AI0");   // Treats I as 1, O as 0
151
```
152

153
### Base64 Standard
154

155
RFC 4648 base64 encoding with padding. Uses built-in browser APIs when available.
156

157
```typescript { .api }
158
/**
159
 * base64 encoding from RFC 4648 with padding
160
 * Uses alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
161
 * Falls back to built-in browser functions when available
162
 */
163
const base64: BytesCoder = {
164
  encode: (data: Uint8Array) => string;
165
  decode: (str: string) => Uint8Array;
166
};
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { base64 } from "@scure/base";
173

174
const data = new Uint8Array([0x12, 0xab]);
175
const encoded = base64.encode(data);   // "Eqs="
176
const decoded = base64.decode("Eqs="); // Uint8Array([0x12, 0xab])
177
```
178

179
### Base64 No Padding
180

181
RFC 4648 base64 encoding without padding.
182

183
```typescript { .api }
184
/**
185
 * base64 encoding from RFC 4648 without padding
186
 * Same alphabet as base64 but no padding characters
187
 */
188
const base64nopad: BytesCoder = {
189
  encode: (data: Uint8Array) => string;
190
  decode: (str: string) => Uint8Array;
191
};
192
```
193

194
### Base64 URL-Safe
195

196
RFC 4648 base64url encoding with padding using URL-safe alphabet.
197

198
```typescript { .api }
199
/**
200
 * base64url encoding from RFC 4648 with padding
201
 * Uses URL-safe alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
202
 * Falls back to built-in browser functions when available
203
 */
204
const base64url: BytesCoder = {
205
  encode: (data: Uint8Array) => string;
206
  decode: (str: string) => Uint8Array;
207
};
208
```
209

210
**Usage Examples:**
211

212
```typescript
213
import { base64url } from "@scure/base";
214

215
const data = new Uint8Array([0x12, 0xab]);
216
const encoded = base64url.encode(data);   // "Eqs="
217
const decoded = base64url.decode("Eqs="); // Uint8Array([0x12, 0xab])
218
```
219

220
### Base64 URL-Safe No Padding
221

222
RFC 4648 base64url encoding without padding.
223

224
```typescript { .api }
225
/**
226
 * base64url encoding from RFC 4648 without padding
227
 * Same URL-safe alphabet as base64url but no padding
228
 */
229
const base64urlnopad: BytesCoder = {
230
  encode: (data: Uint8Array) => string;
231
  decode: (str: string) => Uint8Array;
232
};
233
```
234

235
**Usage Examples:**
236

237
```typescript
238
import { base64urlnopad } from "@scure/base";
239

240
const data = new Uint8Array([0x12, 0xab]);
241
const encoded = base64urlnopad.encode(data);  // "Eqs"
242
const decoded = base64urlnopad.decode("Eqs"); // Uint8Array([0x12, 0xab])
243
```
244

245
### Hex Encoding
246

247
Lowercase hexadecimal encoding. Uses built-in browser APIs when available.
248

249
```typescript { .api }
250
/**
251
 * Hexadecimal encoding with lowercase output
252
 * Falls back to built-in browser functions when available
253
 * Accepts both uppercase and lowercase input during decoding
254
 */
255
const hex: BytesCoder = {
256
  encode: (data: Uint8Array) => string;  // Always lowercase output
257
  decode: (str: string) => Uint8Array;   // Accepts upper/lowercase input
258
};
259
```
260

261
**Usage Examples:**
262

263
```typescript
264
import { hex } from "@scure/base";
265

266
const data = new Uint8Array([0x01, 0x02, 0xff]);
267
const encoded = hex.encode(data);        // "0102ff" (lowercase)
268
const decoded = hex.decode("0102FF");    // Uint8Array([0x01, 0x02, 0xff]) - accepts uppercase
269
const decoded2 = hex.decode("0102ff");   // Same result - accepts lowercase
270
```
271

272
### UTF-8 Encoding
273

274
UTF-8 string to bytes conversion using built-in TextEncoder/TextDecoder.
275

276
```typescript { .api }
277
/**
278
 * UTF-8 string to bytes encoder using built-in TextEncoder/TextDecoder
279
 * encode: converts bytes to UTF-8 string
280
 * decode: converts UTF-8 string to bytes
281
 */
282
const utf8: BytesCoder = {
283
  encode: (data: Uint8Array) => string;  // bytes to UTF-8 string
284
  decode: (str: string) => Uint8Array;   // UTF-8 string to bytes
285
};
286
```
287

288
**Usage Examples:**
289

290
```typescript
291
import { utf8 } from "@scure/base";
292

293
const text = "Hello, 世界! 🚀";
294
const bytes = utf8.decode(text);    // Convert string to bytes
295
const restored = utf8.encode(bytes); // Convert bytes back to string
296
console.log(restored === text);     // true
297
```
298

299
## Error Handling
300

301
All encoders validate input and throw descriptive errors:
302

303
- Invalid characters for the encoding alphabet
304
- Incorrect padding for padded variants
305
- Invalid input types (non-Uint8Array for encode, non-string for decode)
306
- Invalid string length for fixed-length requirements
307

308
```typescript
309
import { base64, hex } from "@scure/base";
310

311
try {
312
  base64.decode("Invalid!Characters"); // Throws error
313
} catch (error) {
314
  console.log(error.message); // "invalid base64"
315
}
316

317
try {
318
  hex.decode("xyz"); // Throws error - invalid hex
319
} catch (error) {
320
  console.log(error.message); // Invalid hex characters
321
}
322
```