0
# uint8arrays
1

2
uint8arrays is a comprehensive TypeScript utility library providing memory-efficient Uint8Array manipulation functions. It offers essential operations for byte array handling with automatic Node.js Buffer optimizations when available, while maintaining full compatibility across browsers and other JavaScript environments.
3

4
## Package Information
5

6
- **Package Name**: uint8arrays
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install uint8arrays`
10

11
## Core Imports
12

13
```typescript
14
import { compare, concat, equals, fromString, toString, xor } from "uint8arrays";
15
```
16

17
Submodule imports for tree-shaking:
18

19
```typescript
20
import { alloc, allocUnsafe } from "uint8arrays/alloc";
21
import { compare } from "uint8arrays/compare";
22
import { concat } from "uint8arrays/concat";
23
import { equals } from "uint8arrays/equals";
24
import { fromString } from "uint8arrays/from-string";
25
import { toString } from "uint8arrays/to-string";
26
import { xor } from "uint8arrays/xor";
27
import { xorCompare } from "uint8arrays/xor-compare";
28
```
29

30
CommonJS:
31

32
```javascript
33
const { compare, concat, equals, fromString, toString, xor } = require("uint8arrays");
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { concat, fromString, toString, equals } from "uint8arrays";
40
import { alloc } from "uint8arrays/alloc";
41

42
// Create and manipulate arrays
43
const buf1 = alloc(10); // Zero-initialized 10-byte array
44
const buf2 = fromString("hello", "utf8"); // Convert string to bytes
45
const buf3 = fromString("world", "utf8");
46

47
// Concatenate arrays
48
const combined = concat([buf2, new Uint8Array([32]), buf3]); // "hello world"
49

50
// Convert back to string
51
const text = toString(combined, "utf8"); // "hello world"
52

53
// Check equality
54
const areEqual = equals(buf2, fromString("hello", "utf8")); // true
55

56
// Encode to different formats
57
const hex = toString(buf2, "hex"); // "68656c6c6f"
58
const base64 = toString(buf2, "base64"); // "aGVsbG8"
59
```
60

61
## Architecture
62

63
uint8arrays is built around several key principles:
64

65
- **Memory Efficiency**: Uses native Uint8Array operations with Node.js Buffer optimizations when available
66
- **Platform Compatibility**: Automatically selects the best implementation for each environment
67
- **Tree Shaking**: Supports both main module and individual submodule imports
68
- **Encoding Support**: Comprehensive encoding support via multiformats integration
69
- **Type Safety**: Full TypeScript support with precise type definitions
70

71
## Capabilities
72

73
### Memory Allocation
74

75
Efficient Uint8Array creation with zero-initialized and unsafe allocation options. Automatically uses Node.js Buffer when available for better performance.
76

77
```typescript { .api }
78
function alloc(size?: number): Uint8Array;
79
function allocUnsafe(size?: number): Uint8Array;
80
```
81

82
[Memory Allocation](./memory-allocation.md)
83

84
### Array Operations
85

86
Core array manipulation functions including concatenation, comparison, and equality testing for Uint8Arrays.
87

88
```typescript { .api }
89
function concat(arrays: Uint8Array[], length?: number): Uint8Array;
90
function compare(a: Uint8Array, b: Uint8Array): number;
91
function equals(a: Uint8Array, b: Uint8Array): boolean;
92
```
93

94
[Array Operations](./array-operations.md)
95

96
### String Encoding
97

98
Comprehensive string encoding and decoding with support for UTF-8, hex, base64, and all multibase formats.
99

100
```typescript { .api }
101
function fromString(string: string, encoding?: SupportedEncodings): Uint8Array;
102
function toString(array: Uint8Array, encoding?: SupportedEncodings): string;
103

104
type SupportedEncodings = 'utf8' | 'utf-8' | 'hex' | 'latin1' | 'ascii' | 'binary' | keyof typeof bases;
105
```
106

107
[String Encoding](./string-encoding.md)
108

109
### XOR Operations
110

111
Bitwise XOR operations and distance comparison functions for cryptographic and DHT applications.
112

113
```typescript { .api }
114
function xor(a: Uint8Array, b: Uint8Array): Uint8Array;
115
function xorCompare(a: Uint8Array, b: Uint8Array): -1 | 0 | 1;
116
```
117

118
[XOR Operations](./xor-operations.md)
119

120
## Types
121

122
```typescript { .api }
123
type SupportedEncodings = 
124
  | 'utf8' 
125
  | 'utf-8' 
126
  | 'hex' 
127
  | 'latin1' 
128
  | 'ascii' 
129
  | 'binary' 
130
  | 'base2'
131
  | 'base8'
132
  | 'base10'
133
  | 'base16'
134
  | 'base16upper'
135
  | 'base32'
136
  | 'base32upper'
137
  | 'base32pad'
138
  | 'base32padupper'
139
  | 'base32hex'
140
  | 'base32hexupper'
141
  | 'base32hexpad'
142
  | 'base32hexpadupper'
143
  | 'base32z'
144
  | 'base36'
145
  | 'base36upper'
146
  | 'base58btc'
147
  | 'base58flickr'
148
  | 'base64'
149
  | 'base64pad'
150
  | 'base64url'
151
  | 'base64urlpad';
152
```