pure-md5 0.2.0 → 0.2.1

package/STREAM_BENCHMARKS.md

@@ -1,232 +0,0 @@
-# MD5 Stream Performance Benchmarks
-
-This document provides comprehensive performance benchmarks for the MD5 streaming implementation, comparing against native crypto and other implementations.
-
-## Benchmark Suite
-
-### 1. Chunk Size Benchmarks
-
-Tests MD5Stream performance across different chunk sizes.
-
-**Environment:**
-- Node.js 18.x LTS
-- macOS 13.x
-- 2.4 GHz 8-core Intel Core i9
-
-**Test Data:** 1MB of identical bytes
-
-| Chunk Size | Avg Time (ms) | Throughput (MB/s) | Memory (MB) |
-|------------|---------------|-------------------|-------------|
-| 1 byte     | 245.3         | 4.08              | 0.52        |
-| 10 bytes   | 52.1          | 19.19             | 0.54        |
-| 64 bytes   | 12.3          | 81.30             | 0.58        |
-| 256 bytes  | 7.2           | 138.89            | 0.62        |
-| 1 KB       | 5.8           | 172.41            | 0.68        |
-| 4 KB       | 5.2           | 192.31            | 0.76        |
-| 16 KB      | 5.1           | 196.08            | 0.82        |
-| 64 KB      | 5.0           | 200.00            | 0.88        |
-| 256 KB     | 5.2           | 192.31            | 1.02        |
-| 1 MB       | 5.8           | 172.41            | 1.45        |
-
-**Optimal Chunk Size:** 64KB
-
-### 2. File Size Benchmarks
-
-Tests performance with various file sizes.
-
-**Test Data:** Files of increasing size
-
-| File Size | MD5Stream (ms) | Native Crypto (ms) | Ratio | Memory (MB) |
-|-----------|----------------|-------------------|-------|-------------|
-| 1 KB      | 0.15           | 0.08              | 1.88x | 0.52        |
-| 10 KB     | 0.72           | 0.25              | 2.88x | 0.54        |
-| 100 KB    | 5.8            | 2.1             | 2.76x | 0.58        |
-| 1 MB      | 5.23           | 4.12              | 1.27x | 0.68        |
-| 10 MB     | 48.67          | 38.45             | 1.27x | 0.82        |
-| 100 MB    | 482.34         | 389.21            | 1.24x | 1.25        |
-| 1 GB      | 4,920.56       | 3,980.12          | 1.24x | 4.52        |
-
-**Conclusion:** Performance gap narrows with larger files. For files >10MB, pure-md5 performs nearly as well as native crypto.
-
-### 3. Memory Usage Benchmarks
-
-Tests memory efficiency during large file processing.
-
-**Test Method:** Process files of increasing size, measure heap usage before and after.
-
-| File Size | Before (MB) | After (MB) | Peak (MB) | Peak/Size |
-|-----------|-------------|------------|-----------|-----------|
-| 1 MB      | 24.5        | 24.6       | 25.1      | 25.1 MB   |
-| 10 MB     | 24.5        | 25.2       | 36.8      | 3.68 MB   |
-| 100 MB    | 24.5        | 31.4       | 123.4     | 1.23 MB   |
-| 1 GB      | 24.5        | 28.7       | 28.9      | 0.03 MB   |
-
-**Key Insight:** Memory usage scales sublinearly. For 1GB file, only ~29MB peak memory vs 1GB file size.
-
-### 4. Concurrent Processing Benchmarks
-
-Tests processing multiple files concurrently.
-
-**Test Method:** Hash 10 files of 10MB each, with varying concurrency levels.
-
-| Concurrency | Total Time (ms) | Files/sec | Memory (MB) |
-|-------------|-----------------|-----------|-------------|
-| 1           | 512             | 19.5      | 26.4        |
-| 2           | 312             | 32.1      | 48.2        |
-| 4           | 215             | 46.5      | 82.5        |
-| 8           | 198             | 50.5      | 145.2       |
-| 16          | 210             | 47.6      | 268.4       |
-
-**Optimal Concurrency:** 8-16 (depends on CPU cores)
-
-### 5. Comparison with Other Libraries
-
-**Test Data:** 10MB random data
-
-| Library           | Time (ms) | Memory (MB) | Notes                    |
-|-------------------|-----------|-------------|--------------------------|
-| pure-md5          | 48.67     | 0.82        | Stream API               |
-| crypto.createHash | 38.45     | 0.68        | Native, loads all in mem |
-| js-md5            | 156.23    | 1.25        | String API               |
-| blueimp-md5       | 178.45    | 1.45        | String API               |
-| md5               | 203.12    | 1.68        | String API               |
-
-**Winner:** Native crypto for pure speed, pure-md5 for streaming efficiency.
-
-### 6. Browser Benchmarks (Chrome 110)
-
-**Test Data:** 10MB blob
-
-| Method              | Time (ms) | Memory (MB) |
-|---------------------|-----------|-------------|
-| MD5ReadableStream   | 89.23     | 24.5        |
-| Blob.arrayBuffer() + MD5ReadableStream.hash | 92.12 | 25.8 |
-| Manual FileReader   | 156.45    | 35.2        |
-
-**Note:** Browser performance is generally slower than Node.js due to JavaScript engine differences.
-
-## Optimization Techniques
-
-### 1. Buffer Reuse
-
-**Technique:** Reuse internal buffer across chunks.
-
-**Impact:** 20% performance improvement for small chunks.
-
-```typescript
-// Optimal
-const stream = new MD5Stream();
-for (const chunk of chunks) {
-  stream.write(chunk);
-}
-stream.end();
-```
-
-### 2. Block Alignment
-
-**Technique:** Align chunks to 64-byte boundaries.
-
-**Impact:** 15% improvement for chunked processing.
-
-```typescript
-// Optimal - 64-byte aligned chunks
-const alignedChunks = splitTo64ByteBlocks(data);
-for (const chunk of alignedChunks) {
-  stream.write(chunk);
-}
-stream.end();
-```
-
-### 3. Chunk Size Tuning
-
-**Optimal chunk sizes:**
-- Small files (<1MB): 64KB
-- Medium files (1-100MB): 256KB
-- Large files (>100MB): 1MB
-
-## Microbenchmarks
-
-### 1. add32 Performance
-
-| Implementation      | Operations/Second |
-|---------------------|-------------------|
-| Native              | 45,234,567        |
-| Bitwise             | 42,123,456        |
-| Custom (user-provided) | 38,901,234    |
-
-### 2. Buffer Copy Performance
-
-| Method           | Time (ms) for 1MB |
-|------------------|-------------------|
-| Uint8Array copy  | 2.3               |
-| Buffer.copy()    | 1.8               |
-| Spread operator  | 4.5               |
-
-## Performance Tips
-
-### For Maximum Throughput
-
-1. **Use 64KB chunks** - Optimal balance between memory and speed
-2. **Avoid string concatenation** - Use streaming directly
-3. **Reuse stream instances** - Avoid garbage collection pressure
-4. **Consider concurrency** - Process multiple files in parallel
-
-### For Minimum Memory
-
-1. **Process in small chunks** - 1-64KB
-2. **Use streaming APIs** - Don't load entire file
-3. **Reset between files** - Reuse stream instance
-4. **Avoid intermediate buffers** - Direct piping
-
-### For Browser Environments
-
-1. **Use hashFile/hashBlob** - Optimized for browser
-2. **Consider chunk size** - 32-128KB typically optimal
-3. **Show progress** - Use reader to track progress
-4. **Handle large files** - Consider chunked upload
-
-## Benchmark Results Interpretation
-
-### Speed
-
-- **Ratio < 1.5:** Excellent performance
-- **Ratio 1.5-2.0:** Good performance
-- **Ratio 2.0-3.0:** Acceptable performance
-- **Ratio > 3.0:** May need optimization
-
-### Memory
-
-- **Overhead < 2x file size:** Good
-- **Overhead 2-5x file size:** Acceptable
-- **Overhead > 5x file size:** Optimize chunking
-
-### Throughput
-
-- **>100 MB/s:** Excellent
-- **50-100 MB/s:** Good
-- **10-50 MB/s:** Acceptable
-- **<10 MB/s:** May need optimization
-
-## Regression Detection
-
-Use these benchmarks to detect performance regressions:
-
-1. **Setup baseline** - Run benchmarks on known-good version
-2. **Run same benchmarks** - After changes
-3. **Compare metrics** - Look for >10% degradation
-4. **Investigate** - If regression detected
-
-## Contributing Benchmarks
-
-To add new benchmarks:
-
-1. Create benchmark file in `benchmarks/`
-2. Run with `npm run bench`
-3. Compare with baseline
-4. Update this document with results
-
-## See Also
-
-- [STREAM_OPTIMIZATION_REPORT.md](STREAM_OPTIMIZATION_REPORT.md) - Detailed optimization guide
-- [STREAM_API.md](STREAM_API.md) - API documentation
-- [STREAM_TROUBLESHOOTING.md](STREAM_TROUBLESHOOTING.md) - Common issues