pure-md5 0.2.0 → 0.2.2

package/STREAM_API.md

@@ -1,582 +0,0 @@
-# Streaming API Documentation
-
-## Overview
-
-The `pure-md5` library provides comprehensive streaming support for hashing large files and data streams. This includes both Node.js Streams and WHATWG Streams (for browser environments).
-
-## Node.js Streams API
-
-### MD5Stream Class
-
-A Node.js Transform stream for computing MD5 hashes while processing data.
-
-#### Constructor
-
-```typescript
-new MD5Stream(options?: MD5StreamOptions)
-```
-
-**Parameters:**
-
-- `options` (optional): Stream options
-  - `add32` (optional): Custom add32 function for testing/compatibility
-
-**Example:**
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-import fs from 'fs';
-
-const stream = new MD5Stream();
-stream.on('md5', (result) => {
-  console.log('MD5:', result.digest);
-  console.log('Bytes:', result.bytesProcessed);
-});
-
-fs.createReadStream('file.txt').pipe(stream);
-```
-
-#### Events
-
-**`md5` Event**
-
-Emitted when MD5 computation is complete.
-
-```typescript
-stream.on('md5', (result: MD5Result) => {
-  console.log('MD5:', result.digest);      // 32-character hex string
-  console.log('Bytes:', result.bytesProcessed); // Total bytes processed
-});
-```
-
-#### Methods
-
-**`getCurrentState(): { state: number[]; bytesProcessed: number }`**
-
-Get current internal MD5 state (for debugging/testing).
-
-```typescript
-const stream = new MD5Stream();
-stream.write('test');
-const state = stream.getCurrentState();
-console.log('State:', state.state); // [1732584193, -271733879, ...]
-console.log('Bytes:', state.bytesProcessed); // 4
-```
-
-**`getBytesProcessed(): number`**
-
-Get the total number of bytes processed so far.
-
-```typescript
-const stream = new MD5Stream();
-stream.write('hello');
-console.log(stream.getBytesProcessed()); // 5
-```
-
-**`reset(): void`**
-
-Reset the internal MD5 state. Allows reusing the stream instance.
-
-```typescript
-const stream = new MD5Stream();
-
-// First computation
-stream.write('first');
-stream.end();
-
-// Reset and start new computation
-stream.reset();
-stream.write('second');
-stream.end();
-```
-
-#### Static Methods
-
-**`fromStream(source: Readable, options?: MD5StreamOptions): { stream: MD5Stream; result: Promise<MD5Result> }`**
-
-Create an MD5Stream from an existing readable stream.
-
-```typescript
-import { Readable } from 'stream';
-
-const source = Readable.from(['hello', ' ', 'world']);
-const { stream, result } = MD5Stream.fromStream(source);
-
-result.then(r => {
-  console.log('MD5:', r.digest);
-  console.log('Bytes:', r.bytesProcessed);
-});
-```
-
-### Factory Functions
-
-**`createMD5Stream(options?: MD5StreamOptions): MD5Stream`**
-
-Create a new MD5Stream instance.
-
-```typescript
-import { createMD5Stream } from 'pure-md5';
-
-const stream = createMD5Stream();
-// Use stream...
-```
-
-### Helper Functions
-
-**`pipeThroughMD5(source: Readable, options?: MD5StreamOptions): Promise<MD5Result>`**
-
-Pipe a readable stream through an MD5 computation and return the result.
-
-```typescript
-import { Readable, Transform } from 'stream';
-import { pipeThroughMD5 } from 'pure-md5';
-
-const source = Readable.from(['hello', ' ', 'world']);
-const result = await pipeThroughMD5(source);
-
-console.log('MD5:', result.digest);
-```
-
-**`fromStream(source: Readable, options?: MD5StreamOptions): { stream: MD5Stream; result: Promise<MD5Result> }`**
-
-Create an MD5Stream and pipe a source through it.
-
-```typescript
-import { fromStream } from 'pure-md5';
-import fs from 'fs';
-
-const { stream, result } = fromStream(fs.createReadStream('file.txt'));
-
-result.then(r => console.log('MD5:', r.digest));
-```
-
-### Result Type
-
-```typescript
-interface MD5Result {
-  digest: string;       // MD5 hash as hex string (32 characters)
-  bytesProcessed: number; // Total bytes processed
-}
-```
-
-## File System Utilities
-
-### hashFile
-
-Async file hashing with full result.
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-const result = await hashFile('path/to/file.txt');
-console.log('MD5:', result.digest);
-console.log('Bytes:', result.bytesProcessed);
-```
-
-**Options:**
-
-```typescript
-interface HashFileOptions {
-  add32?: (x: number, y: number) => number; // Custom add32 function
-}
-```
-
-### hashFileSync
-
-Synchronous file hashing (for small files).
-
-```typescript
-import { hashFileSync } from 'pure-md5';
-
-const digest = hashFileSync('path/to/file.txt');
-console.log('MD5:', digest);
-```
-
-### hashFileDigest
-
-Get only the digest string (no bytes processed info).
-
-```typescript
-import { hashFileDigest } from 'pure-md5';
-
-const digest = await hashFileDigest('path/to/file.txt');
-console.log('MD5:', digest);
-```
-
-### verifyFile
-
-Verify file integrity against a known hash.
-
-```typescript
-import { verifyFile } from 'pure-md5';
-
-const isVerified = await verifyFile(
-  'path/to/file.txt',
-  '5d41402abc4b2a76b9719d911017c592'
-);
-
-if (isVerified) {
-  console.log('File verified successfully!');
-} else {
-  console.log('File verification failed!');
-}
-```
-
-## WHATWG Streams API (Browser)
-
-### MD5ReadableStream
-
-A wrapper for computing MD5 while reading from a ReadableStream.
-
-#### Constructor
-
-```typescript
-new MD5ReadableStream(source: ReadableStream, options?: MD5ReadableStreamOptions)
-```
-
-**Example:**
-
-```typescript
-import { MD5ReadableStream } from 'pure-md5';
-
-const source = new ReadableStream({
-  start(controller) {
-    controller.enqueue(new TextEncoder().encode('Hello World'));
-    controller.close();
-  }
-});
-
-const stream = new MD5ReadableStream(source);
-const result = await stream.getResult();
-console.log('MD5:', result.digest);
-```
-
-#### Methods
-
-**`getReader(): ReadableStreamDefaultReader<Uint8Array>`**
-
-Get a reader for the stream.
-
-**`getResult(): Promise<MD5Result>`**
-
-Get the MD5 result.
-
-**`getCurrentState(): { state: number[]; bytesProcessed: number }`**
-
-Get current internal state.
-
-**`getBytesProcessed(): number`**
-
-Get bytes processed so far.
-
-#### Static Methods
-
-**`hash(source: ReadableStream, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a stream directly.
-
-```typescript
-const result = await MD5ReadableStream.hash(source);
-```
-
-**`hashFile(file: File, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a File object.
-
-```typescript
-const input = document.querySelector('input[type="file"]');
-const file = input.files[0];
-const result = await MD5ReadableStream.hashFile(file);
-```
-
-**`hashBlob(blob: Blob, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a Blob object.
-
-```typescript
-const canvas = document.querySelector('canvas');
-canvas.toBlob(async (blob) => {
-  const result = await MD5ReadableStream.hashBlob(blob!);
-  console.log('MD5:', result.digest);
-});
-```
-
-### Factory Functions
-
-**`createMD5ReadableStream(source: ReadableStream, options?: MD5ReadableStreamOptions): MD5ReadableStream`**
-
-Create a new MD5ReadableStream instance.
-
-### Standalone Functions
-
-**`hashReadableStream(stream: ReadableStream, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a ReadableStream.
-
-**`hashFile(file: File, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a File object.
-
-**`hashBlob(blob: Blob, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Hash a Blob object.
-
-**`consumeWithMD5(source: ReadableStream, options?: MD5ReadableStreamOptions): Promise<MD5Result>`**
-
-Consume a stream while computing MD5.
-
-## Usage Examples
-
-### Example 1: Hash a Large File
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-import fs from 'fs';
-
-const stream = new MD5Stream();
-let bytesProcessed = 0;
-
-stream.on('md5', (result) => {
-  console.log('MD5:', result.digest);
-  console.log('Total bytes:', result.bytesProcessed);
-});
-
-stream.on('data', (chunk) => {
-  bytesProcessed += chunk.length;
-  const progress = (bytesProcessed / fileSize * 100).toFixed(1);
-  console.log(`Progress: ${progress}%`);
-});
-
-fs.createReadStream('large-file.bin').pipe(stream);
-```
-
-### Example 2: Browser File Upload with Progress
-
-```typescript
-import { MD5ReadableStream } from 'pure-md5';
-
-async function uploadWithHash(file: File): Promise<void> {
-  const fileStream = file.stream();
-  const md5Stream = new MD5ReadableStream(fileStream);
-  
-  const reader = md5Stream.getReader();
-  let bytesProcessed = 0;
-  
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    
-    bytesProcessed += value.length;
-    const progress = (bytesProcessed / file.size * 100).toFixed(1);
-    console.log(`Upload progress: ${progress}%`);
-  }
-  
-  const result = await md5Stream.getResult();
-  console.log('Upload complete. MD5:', result.digest);
-  
-  // Upload file with hash...
-}
-```
-
-### Example 3: Verify Downloaded File
-
-```typescript
-import { verifyFile } from 'pure-md5';
-
-async function verifyDownload(url: string, expectedHash: string): Promise<boolean> {
-  const response = await fetch(url);
-  const blob = await response.blob();
-  
-  // Create a File from Blob
-  const file = new File([blob], 'downloaded-file.bin', { type: blob.type });
-  
-  const isVerified = await verifyFile(file, expectedHash);
-  return isVerified;
-}
-```
-
-### Example 4: Hash Multiple Files Concurrently
-
-```typescript
-import { hashFile } from 'pure-md5';
-import fs from 'fs';
-
-async function hashFilesConcurrently(files: string[]): Promise<Map<string, string>> {
-  const results = new Map<string, string>();
-  
-  const promises = files.map(async (file) => {
-    const result = await hashFile(file);
-    return [file, result.digest] as const;
-  });
-  
-  const resolved = await Promise.all(promises);
-  resolved.forEach(([file, digest]) => results.set(file, digest));
-  
-  return results;
-}
-
-// Usage
-const fileHashes = await hashFilesConcurrently(['file1.txt', 'file2.txt', 'file3.txt']);
-fileHashes.forEach((hash, file) => console.log(`${file}: ${hash}`));
-```
-
-### Example 5: Streaming Data with Progress
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-async function streamWithProgress(source: NodeJS.ReadableStream): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const stream = new MD5Stream();
-    const totalSize = 1000000; // Known total size
-    let processed = 0;
-    
-    stream.on('md5', (result) => {
-      console.log('Complete! MD5:', result.digest);
-      resolve(result.digest);
-    });
-    
-    stream.on('data', (chunk) => {
-      processed += chunk.length;
-      const progress = ((processed / totalSize) * 100).toFixed(1);
-      console.log(`Processing: ${progress}%`);
-    });
-    
-    source.pipe(stream);
-  });
-}
-```
-
-## Error Handling
-
-### Node.js Streams
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-const stream = new MD5Stream();
-
-stream.on('error', (error) => {
-  console.error('Stream error:', error.message);
-});
-
-stream.on('md5', (result) => {
-  console.log('Success:', result.digest);
-});
-
-// Error will be caught by 'error' handler
-fs.createReadStream('nonexistent.txt').pipe(stream);
-```
-
-### WHATWG Streams
-
-```typescript
-import { MD5ReadableStream } from 'pure-md5';
-
-try {
-  const stream = new MD5ReadableStream(source);
-  const result = await stream.getResult();
-  console.log('Success:', result.digest);
-} catch (error) {
-  console.error('Stream error:', error.message);
-}
-```
-
-## Performance Tips
-
-1. **Use 64KB chunks** for optimal performance with Node.js streams
-2. **Reuse stream instances** with `reset()` when processing multiple files
-3. **For browser**, use `hashBlob()` or `hashFile()` directly for File/Blob objects
-4. **Monitor memory usage** with very large files (use streaming, not full load)
-5. **Consider parallel processing** for multiple independent files
-
-## Migration Guide
-
-### From crypto.createHash()
-
-**Before:**
-```typescript
-import crypto from 'crypto';
-
-const hash = crypto.createHash('md5').update(data).digest('hex');
-```
-
-**After:**
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-// For strings
-const stream = new MD5Stream();
-let digest = '';
-stream.on('md5', (result) => digest = result.digest);
-stream.end(data);
-
-// Or use fromStream
-const { result } = fromStream(Readable.from([data]));
-const digest = await result;
-```
-
-### From browser-based hashing
-
-**Before:**
-```typescript
-// Manual implementation
-const buffer = await file.arrayBuffer();
-const hashBuffer = await crypto.subtle.digest('MD5', buffer);
-// ... convert to hex
-```
-
-**After:**
-```typescript
-import { hashFile } from 'pure-md5';
-
-const result = await hashFile(file);
-const digest = result.digest;
-```
-
-## Browser Compatibility
-
-WHATWG Streams API requires modern browsers:
-- Chrome 52+
-- Firefox 57+
-- Safari 12.1+
-- Edge 79+
-
-For older browsers, consider using a WHATWG Streams polyfill.
-
-## FAQ
-
-**Q: Which API should I use for Node.js?**
-A: Use `MD5Stream` or the file utilities (`hashFile`, `hashFileSync`).
-
-**Q: Which API should I use in the browser?**
-A: Use `MD5ReadableStream` or the standalone functions (`hashFile`, `hashBlob`).
-
-**Q: How do I track progress?**
-A: Listen to 'data' events in Node.js or use the reader in WHATWG streams.
-
-**Q: Can I hash data that doesn't fit in memory?**
-A: Yes! Use streaming APIs to process data in chunks.
-
-**Q: Is the stream API thread-safe?**
-A: Yes, each stream instance maintains its own state.
-
-**Q: What's the difference between `fromStream` and `pipeThroughMD5`?**
-A: `fromStream` returns both stream and result for more control, while `pipeThroughMD5` is a convenience function that handles piping automatically.
-
-## Performance Benchmarks
-
-See `STREAM_OPTIMIZATION_REPORT.md` for detailed performance metrics.
-
-| File Size | MD5Stream (ms) | Native (ms) | Ratio |
-|-----------|----------------|-------------|-------|
-| 1 KB      | 0.15           | 0.08        | 1.88x |
-| 1 MB      | 5.23           | 4.12        | 1.27x |
-| 10 MB     | 48.67          | 38.45       | 1.27x |
-| 100 MB    | 482.34         | 389.21      | 1.24x |
-
-## See Also
-
-- [README.md](README.md) - Basic MD5 usage
-- [STREAM_OPTIMIZATION_REPORT.md](STREAM_OPTIMIZATION_REPORT.md) - Performance details
-- [WHATWG_STREAMS.md](WHATWG_STREAMS.md) - Browser streaming guide