0
# String Encoding and Decoding
1

2
Core functionality for converting UTF-8 strings to/from Base64 with proper Unicode handling and support for both standard and URL-safe variants.
3

4
## Capabilities
5

6
### String to Base64 Encoding
7

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

10
```typescript { .api }
11
/**
12
 * Converts a UTF-8-encoded string to a Base64 string
13
 * @param src - The UTF-8 string to encode
14
 * @param urlsafe - If true, make the result URL-safe (RFC4648 §5)
15
 * @returns Base64 encoded string
16
 */
17
function encode(src: string, urlsafe?: boolean): string;
18

19
/**
20
 * Alias for encode function
21
 */
22
function toBase64(src: string, urlsafe?: boolean): string;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { encode, toBase64 } from "js-base64";
29

30
// Basic encoding
31
const basic = encode("Hello World!");
32
console.log(basic); // "SGVsbG8gV29ybGQh"
33

34
// UTF-8 encoding (handles Unicode properly)
35
const utf8 = encode("小飼弾");
36
console.log(utf8); // "5bCP6aO85by+"
37

38
// URL-safe encoding
39
const urlSafe = encode("小飼弾", true);
40
console.log(urlSafe); // "5bCP6aO85by-" (note the trailing -)
41

42
// Using alias
43
const alias = toBase64("Hello World!");
44
console.log(alias); // "SGVsbG8gV29ybGQh"
45
```
46

47
### URL-Safe Base64 Encoding
48

49
Convenience function for URL-safe Base64 encoding (RFC4648 §5).
50

51
```typescript { .api }
52
/**
53
 * Converts a UTF-8-encoded string to URL-safe Base64 RFC4648 §5
54
 * @param src - The UTF-8 string to encode
55
 * @returns URL-safe Base64 encoded string (uses - and _ instead of + and /)
56
 */
57
function encodeURI(src: string): string;
58

59
/**
60
 * Alias for encodeURI function
61
 */
62
function encodeURL(src: string): string;
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { encodeURI, encodeURL } from "js-base64";
69

70
const text = "Hello+World/Test=";
71

72
// URL-safe encoding
73
const urlSafe = encodeURI(text);
74
console.log(urlSafe); // "SGVsbG8rV29ybGQvVGVzdD0"
75

76
// Using alias
77
const alias = encodeURL(text);
78
console.log(alias); // "SGVsbG8rV29ybGQvVGVzdD0"
79

80
// Comparison with regular encoding
81
const regular = encode(text);
82
console.log(regular); // "SGVsbG8rV29ybGQvVGVzdD0=" (with padding)
83
const urlSafeExplicit = encode(text, true);
84
console.log(urlSafeExplicit); // "SGVsbG8rV29ybGQvVGVzdD0" (no padding)
85
```
86

87
### Base64 to String Decoding
88

89
Converts a Base64 string back to UTF-8, supporting both standard and URL-safe formats.
90

91
```typescript { .api }
92
/**
93
 * Converts a Base64 string to a UTF-8 string
94
 * @param src - Base64 string (both normal and URL-safe are supported)
95
 * @returns Decoded UTF-8 string
96
 */
97
function decode(src: string): string;
98

99
/**
100
 * Alias for decode function
101
 */
102
function fromBase64(src: string): string;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { decode, fromBase64 } from "js-base64";
109

110
// Basic decoding
111
const decoded = decode("SGVsbG8gV29ybGQh");
112
console.log(decoded); // "Hello World!"
113

114
// UTF-8 decoding
115
const utf8Decoded = decode("5bCP6aO85by+");
116
console.log(utf8Decoded); // "小飼弾"
117

118
// URL-safe decoding (automatically detected)
119
const urlSafeDecoded = decode("5bCP6aO85by-");
120
console.log(urlSafeDecoded); // "小飼弾"
121

122
// Works with or without padding
123
const withoutPadding = decode("SGVsbG8gV29ybGQ");
124
const withPadding = decode("SGVsbG8gV29ybGQ=");
125
console.log(withoutPadding); // "Hello World"
126
console.log(withPadding); // "Hello World"
127

128
// Using alias
129
const alias = fromBase64("SGVsbG8gV29ybGQh");
130
console.log(alias); // "Hello World!"
131

132
// Handles whitespace
133
const withSpaces = decode("SGVs bG8g V29y bGQh");
134
console.log(withSpaces); // "Hello World!"
135
```
136

137
## Key Features
138

139
- **UTF-8 Safe**: Properly handles Unicode characters, unlike native browser btoa/atob
140
- **Flexible Input**: Accepts both padded and non-padded Base64 strings
141
- **Format Detection**: Automatically handles both standard and URL-safe Base64 formats in decode
142
- **Whitespace Tolerant**: decode function ignores whitespace in input strings
143
- **Cross-platform**: Works consistently across browsers and Node.js environments