0
# SparkMD5
1

2
SparkMD5 is a lightning-fast MD5 hashing library for JavaScript that provides both normal (one-shot) and incremental MD5 hashing capabilities. It offers significant performance improvements over other MD5 implementations with UTF-8 string conversion, overflow protection for large data sets, memory-efficient incremental hashing for files and large datasets, support for array buffers and typed arrays, and comprehensive APIs for both string and binary data processing.
3

4
## Package Information
5

6
- **Package Name**: spark-md5
7
- **Package Type**: npm  
8
- **Language**: JavaScript
9
- **Installation**: `npm install spark-md5`
10

11
## Core Imports
12

13
```javascript
14
const SparkMD5 = require("spark-md5");
15
```
16

17
For ES modules:
18

19
```javascript
20
import SparkMD5 from "spark-md5";
21
```
22

23
For AMD:
24

25
```javascript
26
define(["spark-md5"], function(SparkMD5) {
27
  // Use SparkMD5
28
});
29
```
30

31
Browser global:
32

33
```html
34
<script src="spark-md5.js"></script>
35
<script>
36
  // SparkMD5 is available as a global
37
  const hash = SparkMD5.hash("hello");
38
</script>
39
```
40

41
## Basic Usage
42

43
```javascript
44
const SparkMD5 = require("spark-md5");
45

46
// Direct hashing of strings
47
const hexHash = SparkMD5.hash("Hi there");        // hex hash
48
const rawHash = SparkMD5.hash("Hi there", true);  // raw binary string
49

50
// Incremental hashing for large data
51
const spark = new SparkMD5();
52
spark.append("Hi");
53
spark.append(" there");
54
const result = spark.end();                       // hex hash
55

56
// ArrayBuffer hashing for binary data
57
const buffer = new ArrayBuffer(16);
58
const hashFromBuffer = SparkMD5.ArrayBuffer.hash(buffer);
59

60
// Incremental ArrayBuffer hashing
61
const sparkAB = new SparkMD5.ArrayBuffer();
62
sparkAB.append(buffer);
63
const resultAB = sparkAB.end();
64
```
65

66
## Architecture
67

68
SparkMD5 provides two main classes for different data types:
69

70
- **SparkMD5**: Main class for string-based hashing with UTF-8 support
71
- **SparkMD5.ArrayBuffer**: Specialized class for binary data and ArrayBuffer hashing
72
- **Static Methods**: Direct hashing functions for one-shot operations
73
- **Incremental Processing**: Instance methods for memory-efficient processing of large data
74
- **State Management**: Get/set state functionality for pausable/resumable hashing
75

76
## Capabilities
77

78
### String Hashing
79

80
Direct MD5 hashing of strings with automatic UTF-8 conversion.
81

82
```javascript { .api }
83
/**
84
 * Performs MD5 hash on a string with UTF-8 conversion
85
 * @param {string} str - The string to hash
86
 * @param {boolean} [raw=false] - Optional, true for raw binary string, false for hex string
87
 * @returns {string} The computed MD5 hash
88
 */
89
SparkMD5.hash(str, raw);
90
```
91

92
### Binary String Hashing
93

94
Direct MD5 hashing of binary strings without UTF-8 conversion.
95

96
```javascript { .api }
97
/**
98
 * Performs MD5 hash on a binary string
99
 * @param {string} content - The binary string to hash
100
 * @param {boolean} [raw=false] - Optional, true for raw binary string, false for hex string  
101
 * @returns {string} The computed MD5 hash
102
 */
103
SparkMD5.hashBinary(content, raw);
104
```
105

106
### Incremental String Hashing
107

108
Create an incremental MD5 hasher for processing large strings in chunks.
109

110
```javascript { .api }
111
/**
112
 * Creates a new SparkMD5 instance for incremental hashing
113
 * @constructor
114
 */
115
function SparkMD5();
116

117
/**
118
 * Appends a string with UTF-8 conversion if necessary
119
 * @param str - The string to append
120
 * @returns The SparkMD5 instance for chaining
121
 */
122
SparkMD5.prototype.append(str);
123

124
/**
125
 * Appends a binary string without UTF-8 conversion
126
 * @param {string} contents - The binary string to append
127
 * @returns {SparkMD5} The SparkMD5 instance for chaining  
128
 */
129
SparkMD5.prototype.appendBinary(contents);
130

131
/**
132
 * Finishes the computation and returns the result
133
 * @param raw - Optional, true for raw binary string, false for hex string
134
 * @returns The computed MD5 hash
135
 */
136
SparkMD5.prototype.end(raw);
137

138
/**
139
 * Resets the internal state for reuse
140
 * @returns The SparkMD5 instance for chaining
141
 */
142
SparkMD5.prototype.reset();
143

144
/**
145
 * Gets the internal computation state for resuming later
146
 * @returns State object with buff, length, and hash properties
147
 */
148
SparkMD5.prototype.getState();
149

150
/**
151
 * Sets the internal computation state from a previous getState() call
152
 * @param state - State object from getState()
153
 * @returns The SparkMD5 instance for chaining
154
 */
155
SparkMD5.prototype.setState(state);
156

157
/**
158
 * Releases memory used by the incremental buffer
159
 * @returns void
160
 */
161
SparkMD5.prototype.destroy();
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
const SparkMD5 = require("spark-md5");
168

169
// Basic incremental hashing
170
const spark = new SparkMD5();
171
spark.append("Hello");
172
spark.append(" ");
173
spark.append("World");
174
const hash = spark.end(); // "65a8e27d8879283831b664bd8b7f0ad4"
175

176
// State management for resumable hashing
177
const spark1 = new SparkMD5();
178
spark1.append("Hello");
179
const state = spark1.getState(); // Save state
180

181
const spark2 = new SparkMD5();
182
spark2.setState(state);           // Resume from saved state
183
spark2.append(" World");
184
const hash2 = spark2.end();       // Same result as above
185

186
// Memory cleanup
187
spark1.destroy();
188
spark2.destroy();
189
```
190

191
### ArrayBuffer Hashing
192

193
Direct MD5 hashing of ArrayBuffer and typed array data.
194

195
```javascript { .api }
196
/**
197
 * Performs MD5 hash on an ArrayBuffer
198
 * @param arr - The ArrayBuffer to hash
199
 * @param raw - Optional, true for raw binary string, false for hex string
200
 * @returns The computed MD5 hash
201
 */
202
SparkMD5.ArrayBuffer.hash(arr, raw);
203
```
204

205
### Incremental ArrayBuffer Hashing
206

207
Create an incremental MD5 hasher for processing large binary data in chunks.
208

209
```javascript { .api }
210
/**
211
 * Creates a new SparkMD5.ArrayBuffer instance for incremental binary hashing
212
 * @constructor
213
 */
214
function SparkMD5.ArrayBuffer();
215

216
/**
217
 * Appends an ArrayBuffer to the hash computation
218
 * @param arr - The ArrayBuffer to append
219
 * @returns The SparkMD5.ArrayBuffer instance for chaining
220
 */
221
SparkMD5.ArrayBuffer.prototype.append(arr);
222

223
/**
224
 * Finishes the computation and returns the result
225
 * @param raw - Optional, true for raw binary string, false for hex string
226
 * @returns The computed MD5 hash
227
 */
228
SparkMD5.ArrayBuffer.prototype.end(raw);
229

230
/**
231
 * Resets the internal state for reuse
232
 * @returns The SparkMD5.ArrayBuffer instance for chaining
233
 */
234
SparkMD5.ArrayBuffer.prototype.reset();
235

236
/**
237
 * Gets the internal computation state for resuming later
238
 * @returns State object with buff, length, and hash properties
239
 */
240
SparkMD5.ArrayBuffer.prototype.getState();
241

242
/**
243
 * Sets the internal computation state from a previous getState() call
244
 * @param state - State object from getState()
245
 * @returns The SparkMD5.ArrayBuffer instance for chaining
246
 */
247
SparkMD5.ArrayBuffer.prototype.setState(state);
248

249
/**
250
 * Releases memory used by the incremental buffer
251
 * @returns void
252
 */
253
SparkMD5.ArrayBuffer.prototype.destroy();
254
```
255

256
**Usage Examples:**
257

258
```javascript
259
const SparkMD5 = require("spark-md5");
260

261
// Direct ArrayBuffer hashing
262
const buffer = new ArrayBuffer(16);
263
const view = new Uint8Array(buffer);
264
view.set([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
265
const hash = SparkMD5.ArrayBuffer.hash(buffer);
266

267
// Incremental file processing example
268
function hashFileInChunks(file) {
269
  return new Promise((resolve, reject) => {
270
    const chunkSize = 2097152; // 2MB chunks
271
    const chunks = Math.ceil(file.size / chunkSize);
272
    let currentChunk = 0;
273
    const spark = new SparkMD5.ArrayBuffer();
274
    const fileReader = new FileReader();
275

276
    fileReader.onload = function(e) {
277
      spark.append(e.target.result);
278
      currentChunk++;
279
      
280
      if (currentChunk < chunks) {
281
        loadNext();
282
      } else {
283
        const hash = spark.end();
284
        spark.destroy();
285
        resolve(hash);
286
      }
287
    };
288

289
    fileReader.onerror = function() {
290
      spark.destroy();
291
      reject(new Error("File reading failed"));
292
    };
293

294
    function loadNext() {
295
      const start = currentChunk * chunkSize;
296
      const end = Math.min(start + chunkSize, file.size);
297
      fileReader.readAsArrayBuffer(file.slice(start, end));
298
    }
299

300
    loadNext();
301
  });
302
}
303
```
304

305
## Types
306

307
```javascript { .api }
308
/**
309
 * State object returned by getState() methods
310
 */
311
interface State {
312
  buff: string;        // Internal buffer content
313
  length: number;      // Total length processed
314
  hash: number[];      // Internal hash state array
315
}
316

317
/**
318
 * SparkMD5 constructor function and static methods
319
 */
320
interface SparkMD5Static {
321
  new(): SparkMD5;
322
  hash(str: string, raw?: boolean): string;
323
  hashBinary(content: string, raw?: boolean): string;
324
  ArrayBuffer: SparkMD5ArrayBufferStatic;
325
}
326

327
/**
328
 * SparkMD5 instance methods
329
 */
330
interface SparkMD5 {
331
  append(str: string): SparkMD5;
332
  appendBinary(contents: string): SparkMD5;
333
  end(raw?: boolean): string;
334
  reset(): SparkMD5;
335
  getState(): State;
336
  setState(state: State): SparkMD5;
337
  destroy(): void;
338
}
339

340
/**
341
 * SparkMD5.ArrayBuffer constructor function and static methods
342
 */  
343
interface SparkMD5ArrayBufferStatic {
344
  new(): SparkMD5ArrayBuffer;
345
  hash(arr: ArrayBuffer, raw?: boolean): string;
346
}
347

348
/**
349
 * SparkMD5.ArrayBuffer instance methods
350
 */
351
interface SparkMD5ArrayBuffer {
352
  append(arr: ArrayBuffer): SparkMD5ArrayBuffer;
353
  end(raw?: boolean): string;
354
  reset(): SparkMD5ArrayBuffer;
355
  getState(): State;
356
  setState(state: State): SparkMD5ArrayBuffer;
357
  destroy(): void;
358
}
359
```