0
# js-base64
1

2
js-base64 is a comprehensive Base64 encoding and decoding library for JavaScript that works across all environments including browsers and Node.js. It provides UTF-8 safe encoding/decoding, URL-safe Base64 variants, binary data support through Uint8Array integration, and optional prototype extensions for convenient usage patterns.
3

4
## Package Information
5

6
- **Package Name**: js-base64
7
- **Package Type**: npm
8
- **Language**: TypeScript (compiled to JavaScript)
9
- **Installation**: `npm install js-base64`
10

11
## Core Imports
12

13
```typescript
14
import { Base64, encode, decode, fromUint8Array, toUint8Array } from "js-base64";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Base64, encode, decode, fromUint8Array, toUint8Array } = require("js-base64");
21
```
22

23
Using the namespace object:
24

25
```typescript
26
import { Base64 } from "js-base64";
27
// All functions available as Base64.encode(), Base64.decode(), etc.
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { encode, decode, fromUint8Array, toUint8Array } from "js-base64";
34

35
// Basic string encoding/decoding
36
const encoded = encode("Hello World!");
37
console.log(encoded); // "SGVsbG8gV29ybGQh"
38

39
const decoded = decode(encoded);
40
console.log(decoded); // "Hello World!"
41

42
// UTF-8 safe encoding
43
const utf8Text = "小飼弾"; // Japanese text
44
const utf8Encoded = encode(utf8Text);
45
console.log(utf8Encoded); // "5bCP6aO85by+"
46

47
const utf8Decoded = decode(utf8Encoded);
48
console.log(utf8Decoded); // "小飼弾"
49

50
// Binary data support
51
const uint8Array = new Uint8Array([100, 97, 110, 107, 111, 103, 97, 105]);
52
const binaryEncoded = fromUint8Array(uint8Array);
53
console.log(binaryEncoded); // "ZGFua29nYWk="
54

55
const binaryDecoded = toUint8Array(binaryEncoded);
56
console.log(binaryDecoded); // Uint8Array(8) [100, 97, 110, 107, 111, 103, 97, 105]
57
```
58

59
## Architecture
60

61
js-base64 is built around several key components:
62

63
- **Cross-platform Compatibility**: Automatically detects environment capabilities (Buffer, TextEncoder/TextDecoder) and uses native functions when available, falling back to pure JavaScript polyfills
64
- **Multiple Export Patterns**: Provides both individual function exports and a complete namespace object (Base64) for different usage preferences
65
- **UTF-8 Safety**: Handles Unicode characters properly, unlike native btoa/atob which only work with binary strings
66
- **URL-Safe Variants**: Supports RFC4648 §5 URL-safe Base64 encoding with `-` and `_` instead of `+` and `/`
67
- **Optional Extensions**: Prototype extensions can be added to String and Uint8Array for fluent method chaining
68

69
## Capabilities
70

71
### String Encoding and Decoding
72

73
Core functionality for converting UTF-8 strings to/from Base64, with support for both standard and URL-safe variants.
74

75
```typescript { .api }
76
function encode(src: string, urlsafe?: boolean): string;
77
function decode(src: string): string;
78
function encodeURI(src: string): string;
79
```
80

81
[String Operations](./string-operations.md)
82

83
### Binary Data Operations
84

85
Convert between Uint8Array and Base64 strings for handling binary data like images, files, and byte arrays.
86

87
```typescript { .api }
88
function fromUint8Array(u8a: Uint8Array, urlsafe?: boolean): string;
89
function toUint8Array(a: string): Uint8Array;
90
```
91

92
[Binary Data](./binary-data.md)
93

94
### Browser Compatibility Functions
95

96
Low-level functions that replicate browser btoa/atob behavior with cross-platform support and polyfills.
97

98
```typescript { .api }
99
function atob(asc: string): string;
100
function btoa(bin: string): string;
101
function atobPolyfill(asc: string): string;
102
function btoaPolyfill(bin: string): string;
103
```
104

105
[Browser Compatibility](./browser-compatibility.md)
106

107
### Validation and Utility Functions
108

109
Validate Base64 strings and access version information.
110

111
```typescript { .api }
112
function isValid(src: unknown): boolean;
113
const version: string;
114
const VERSION: string; // @deprecated
115
```
116

117
[Validation and Utilities](./validation-utilities.md)
118

119
### Prototype Extensions
120

121
Optional methods that can be added to String.prototype and Uint8Array.prototype for fluent method chaining.
122

123
```typescript { .api }
124
function extendString(): void;
125
function extendUint8Array(): void;
126
function extendBuiltins(): void;
127
```
128

129
[Prototype Extensions](./prototype-extensions.md)
130

131
## Types
132

133
```typescript { .api }
134
// All functions are also available in the Base64 namespace object
135
interface Base64Namespace {
136
  version: string;
137
  VERSION: string; // @deprecated
138
  encode(src: string, urlsafe?: boolean): string;
139
  toBase64(src: string, urlsafe?: boolean): string; // alias for encode
140
  encodeURI(src: string): string;
141
  encodeURL(src: string): string; // alias for encodeURI
142
  decode(src: string): string;
143
  fromBase64(src: string): string; // alias for decode
144
  fromUint8Array(u8a: Uint8Array, urlsafe?: boolean): string;
145
  toUint8Array(a: string): Uint8Array;
146
  atob(asc: string): string;
147
  btoa(bin: string): string;
148
  atobPolyfill(asc: string): string;
149
  btoaPolyfill(bin: string): string;
150
  isValid(src: unknown): boolean;
151
  utob(u: string): string; // @deprecated
152
  btou(b: string): string; // @deprecated
153
  extendString(): void;
154
  extendUint8Array(): void;
155
  extendBuiltins(): void;
156
}
157

158
declare const Base64: Base64Namespace;
159
```