0
# @parcel/hash
1

2
@parcel/hash is a high-performance hashing utility designed for the Parcel bundler ecosystem. It provides xxHash (XXH3) implementations through dual execution environments: a JavaScript version using xxhash-wasm for browser compatibility and a native Rust implementation using xxhash-rust with napi-rs bindings for Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: @parcel/hash
7
- **Package Type**: npm
8
- **Language**: JavaScript with Rust native bindings
9
- **Installation**: `npm install @parcel/hash`
10

11
## Core Imports
12

13
```javascript
14
const { hashString, hashBuffer, Hash, init } = require('@parcel/hash');
15
```
16

17
For ES modules:
18

19
```javascript
20
import { hashString, hashBuffer, Hash, init } from '@parcel/hash';
21
```
22

23
## Basic Usage
24

25
### Node.js Environment (Native Rust)
26

27
```javascript
28
const { hashString, hashBuffer, Hash } = require('@parcel/hash');
29

30
// Hash a string
31
const stringHash = hashString('hello world');
32
console.log(stringHash); // '0123456789abcdef' (16-char hex)
33

34
// Hash a buffer
35
const buffer = Buffer.from('hello world', 'utf8');
36
const bufferHash = hashBuffer(buffer);
37
console.log(bufferHash); // '0123456789abcdef' (16-char hex)
38

39
// Incremental hashing
40
const hash = new Hash();
41
hash.writeString('hello ');
42
hash.writeString('world');
43
const result = hash.finish();
44
console.log(result); // '0123456789abcdef' (16-char hex)
45
```
46

47
### Browser Environment (WebAssembly)
48

49
```javascript
50
import { hashString, hashBuffer, Hash, init } from '@parcel/hash';
51

52
// Initialize the WASM module first
53
await init;
54

55
// Hash a string
56
const stringHash = hashString('hello world');
57
console.log(stringHash); // '0123456789abcdef' (16-char hex)
58

59
// Hash a Uint8Array
60
const buffer = new TextEncoder().encode('hello world');
61
const bufferHash = hashBuffer(buffer);
62
console.log(bufferHash); // '0123456789abcdef' (16-char hex)
63

64
// Incremental hashing
65
const hash = new Hash();
66
hash.writeString('hello ');
67
hash.writeString('world');
68
const result = hash.finish();
69
console.log(result); // '0123456789abcdef' (16-char hex)
70
```
71

72
## Architecture
73

74
@parcel/hash implements a dual-target strategy:
75

76
- **Node.js**: Native Rust implementation via napi-rs bindings for maximum performance
77
- **Browser**: JavaScript implementation using xxhash-wasm for cross-platform compatibility
78
- **Algorithm**: xxHash3 (XXH3_64) for consistent, high-performance hashing
79
- **Output Format**: 64-bit hash values formatted as 16-character hexadecimal strings
80

81
## Capabilities
82

83
### String Hashing
84

85
Hash string inputs using the xxHash3 algorithm.
86

87
```javascript { .api }
88
/**
89
 * Hash a string using xxHash3 algorithm
90
 * @param s - The input string to hash
91
 * @returns 16-character hexadecimal hash string
92
 */
93
function hashString(s: string): string;
94
```
95

96
### Buffer Hashing
97

98
Hash binary data using the xxHash3 algorithm.
99

100
```javascript { .api }
101
/**
102
 * Hash a buffer using xxHash3 algorithm
103
 * @param b - The input buffer to hash (Buffer in Node.js, Uint8Array in browser)
104
 * @returns 16-character hexadecimal hash string
105
 */
106
function hashBuffer(b: Buffer | Uint8Array): string;
107
```
108

109
### Incremental Hashing
110

111
Build hashes incrementally from multiple inputs using the Hash class.
112

113
```javascript { .api }
114
/**
115
 * Hash class for incremental hashing operations
116
 */
117
class Hash {
118
  /**
119
   * Create a new Hash instance
120
   */
121
  constructor();
122

123
  /**
124
   * Add a string to the incremental hash
125
   * @param s - String to add to the hash
126
   */
127
  writeString(s: string): void;
128

129
  /**
130
   * Add a buffer to the incremental hash
131
   * @param b - Buffer to add to the hash (Buffer in Node.js, Uint8Array in browser)
132
   */
133
  writeBuffer(b: Buffer | Uint8Array): void;
134

135
  /**
136
   * Finalize the incremental hash and return the result
137
   * @returns 16-character hexadecimal hash string
138
   */
139
  finish(): string;
140
}
141
```
142

143
### Initialization (Browser Only)
144

145
WebAssembly module initialization for browser environments.
146

147
```javascript { .api }
148
/**
149
 * Promise that resolves when the WASM module is initialized (browser only)
150
 * Must be awaited before using other functions in browser environment
151
 */
152
const init: Promise<void>;
153
```
154

155
## Usage Examples
156

157
### Single-Shot Hashing
158

159
```javascript
160
const { hashString, hashBuffer } = require('@parcel/hash');
161

162
// Hash strings
163
const hash1 = hashString('user123');
164
const hash2 = hashString('file-content-data');
165

166
// Hash buffers
167
const jsonData = Buffer.from(JSON.stringify({id: 123, name: 'test'}));
168
const jsonHash = hashBuffer(jsonData);
169

170
const binaryData = new Uint8Array([0xFF, 0x00, 0xAB, 0xCD]);
171
const binaryHash = hashBuffer(binaryData);
172
```
173

174
### Incremental Hashing for Complex Data
175

176
```javascript
177
const { Hash } = require('@parcel/hash');
178

179
// Build hash from multiple components
180
const hash = new Hash();
181
hash.writeString('module:');
182
hash.writeString(moduleName);
183
hash.writeString(':version:');
184
hash.writeString(moduleVersion);
185
hash.writeBuffer(moduleContent);
186

187
const finalHash = hash.finish();
188
```
189

190
### Browser with Async Initialization
191

192
```javascript
193
import { init, hashString, Hash } from '@parcel/hash';
194

195
async function computeHashes() {
196
  // Wait for WASM initialization
197
  await init;
198
  
199
  // Now safe to use hashing functions
200
  const quickHash = hashString('fast-computation');
201
  
202
  const incrementalHash = new Hash();
203
  incrementalHash.writeString('browser-');
204
  incrementalHash.writeString('compatible');
205
  const result = incrementalHash.finish();
206
  
207
  return { quickHash, result };
208
}
209
```
210

211
## Performance Characteristics
212

213
- **Deterministic**: Same input always produces the same hash
214
- **Fast**: xxHash3 algorithm optimized for speed
215
- **Consistent**: Identical output across Node.js and browser environments
216
- **64-bit**: Full 64-bit hash space with minimal collision probability
217
- **Cross-platform**: Works identically in Node.js (native) and browsers (WASM)
218

219
## Error Handling
220

221
### Browser Environment
222

223
In browser environments, ensure the WASM module initializes successfully:
224

225
```javascript
226
import { init, hashString } from '@parcel/hash';
227

228
try {
229
  await init;
230
  const hash = hashString('data');
231
} catch (error) {
232
  console.error('Failed to initialize WASM module:', error);
233
  // Fallback to alternative hashing if needed
234
}
235
```
236

237
### Node.js Environment
238

239
Native bindings should load automatically. If native bindings fail to load, the package will fall back to the browser implementation:
240

241
```javascript
242
const { hashString } = require('@parcel/hash');
243

244
try {
245
  const hash = hashString('data');
246
} catch (error) {
247
  console.error('Hashing failed:', error);
248
}
249
```
250

251
## Common Use Cases
252

253
- **File Content Hashing**: Generate consistent hashes for file contents in build processes
254
- **Cache Keys**: Create reliable cache keys for bundling and asset management
255
- **Data Integrity**: Verify data consistency across transformations
256
- **Incremental Builds**: Hash multiple inputs to determine when rebuilds are needed