pure-md5 0.2.0 → 0.2.2

package/STREAM_EXAMPLES.md

@@ -1,669 +0,0 @@
-# MD5 Streaming API - Usage Examples
-
-This document provides practical examples for using the MD5 streaming API in various scenarios.
-
-## Table of Contents
-
-1. [Basic Usage](#basic-usage)
-2. [File Operations](#file-operations)
-3. [Browser Usage](#browser-usage)
-4. [Advanced Scenarios](#advanced-scenarios)
-5. [Integration Examples](#integration-examples)
-
----
-
-## Basic Usage
-
-### Hash a String
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-const stream = new MD5Stream();
-let digest = '';
-
-stream.on('md5', (result) => {
-  digest = result.digest;
-});
-
-stream.end('Hello, World!');
-console.log(digest); // 65a8e27d8879283831b664bd8b7f0ad4
-```
-
-### Hash a Buffer
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-const data = Buffer.from('Hello, World!', 'utf8');
-const stream = new MD5Stream();
-let digest = '';
-
-stream.on('md5', (result) => {
-  digest = result.digest;
-});
-
-stream.end(data);
-console.log(digest); // 65a8e27d8879283831b664bd8b7f0ad4
-```
-
-### Using fromStream (Promise-based)
-
-```typescript
-import { fromStream } from 'pure-md5';
-import { Readable } from 'stream';
-
-const source = Readable.from(['Hello', ' ', 'World!']);
-const { result } = fromStream(source);
-
-result.then(({ digest, bytesProcessed }) => {
-  console.log('MD5:', digest);
-  console.log('Bytes:', bytesProcessed);
-});
-```
-
-### Using pipeThroughMD5
-
-```typescript
-import { pipeThroughMD5 } from 'pure-md5';
-import { Readable } from 'stream';
-
-const source = Readable.from(['Hello', ' ', 'World!']);
-const { digest, bytesProcessed } = await pipeThroughMD5(source);
-
-console.log('MD5:', digest);
-console.log('Bytes:', bytesProcessed);
-```
-
----
-
-## File Operations
-
-### Hash a File
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-const result = await hashFile('path/to/file.txt');
-console.log('MD5:', result.digest);
-console.log('Bytes:', result.bytesProcessed);
-```
-
-### Hash Multiple Files
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-async function hashFiles(files: string[]): Promise<Map<string, string>> {
-  const results = new Map<string, string>();
-  
-  for (const file of files) {
-    const result = await hashFile(file);
-    results.set(file, result.digest);
-  }
-  
-  return results;
-}
-
-const fileHashes = await hashFiles(['file1.txt', 'file2.txt', 'file3.txt']);
-fileHashes.forEach((hash, file) => console.log(`${file}: ${hash}`));
-```
-
-### Hash Files Concurrently
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-async function hashFilesConcurrently(files: string[], maxConcurrent = 4): Promise<Map<string, string>> {
-  const results = new Map<string, string>();
-  const queue = [...files];
-  
-  async function processNext() {
-    if (queue.length === 0) return;
-    const file = queue.shift();
-    const result = await hashFile(file!);
-    results.set(file!, result.digest);
-    await processNext();
-  }
-  
-  const workers = Array.from({ length: Math.min(maxConcurrent, files.length) }, processNext);
-  await Promise.all(workers);
-  
-  return results;
-}
-```
-
-### Hash File with Progress
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-import fs from 'fs';
-
-async function hashFileWithProgress(filePath: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const fileSize = fs.statSync(filePath).size;
-    const stream = new MD5Stream();
-    let processed = 0;
-    
-    stream.on('md5', (result) => {
-      console.log('\nComplete!');
-      console.log('MD5:', result.digest);
-      resolve(result.digest);
-    });
-    
-    stream.on('data', (chunk) => {
-      processed += chunk.length;
-      const progress = ((processed / fileSize) * 100).toFixed(1);
-      process.stdout.write(`\rProgress: ${progress}%`);
-    });
-    
-    fs.createReadStream(filePath).pipe(stream);
-  });
-}
-
-await hashFileWithProgress('large-file.bin');
-```
-
-### Verify File Integrity
-
-```typescript
-import { verifyFile } from 'pure-md5';
-
-async function verifyDownload(filePath: string, expectedHash: string): Promise<void> {
-  const isVerified = await verifyFile(filePath, expectedHash);
-  
-  if (isVerified) {
-    console.log('✓ File verified successfully!');
-  } else {
-    console.log('✗ File verification failed!');
-    throw new Error('File integrity check failed');
-  }
-}
-
-await verifyDownload('downloaded-file.zip', '5d41402abc4b2a76b9719d911017c592');
-```
-
----
-
-## Browser Usage
-
-### Hash a File Upload
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-async function handleFileUpload(event: Event): Promise<void> {
-  const input = event.target as HTMLInputElement;
-  const file = input.files![0];
-  
-  const result = await hashFile(file);
-  console.log('File MD5:', result.digest);
-  
-  // Upload with hash...
-}
-
-document.querySelector('input[type="file"]').addEventListener('change', handleFileUpload);
-```
-
-### Hash Blob from Canvas
-
-```typescript
-import { hashBlob } from 'pure-md5';
-
-async function hashCanvas(canvas: HTMLCanvasElement): Promise<string> {
-  return new Promise((resolve, reject) => {
-    canvas.toBlob(async (blob) => {
-      if (!blob) {
-        reject(new Error('Failed to create blob'));
-        return;
-      }
-      
-      const result = await hashBlob(blob);
-      resolve(result.digest);
-    }, 'image/png');
-  });
-}
-
-const digest = await hashCanvas(document.querySelector('canvas'));
-console.log('Canvas MD5:', digest);
-```
-
-### Stream File with Progress
-
-```typescript
-import { MD5ReadableStream } from 'pure-md5';
-
-async function uploadWithHash(file: File, uploadUrl: string): Promise<void> {
-  const fileStream = file.stream();
-  const md5Stream = new MD5ReadableStream(fileStream);
-  
-  const reader = md5Stream.getReader();
-  let bytesProcessed = 0;
-  
-  // Consume stream and track progress
-  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);
-  
-  // Now upload with hash metadata
-  // await fetch(uploadUrl, { method: 'POST', body: file, headers: { 'X-MD5': result.digest } });
-}
-```
-
----
-
-## Advanced Scenarios
-
-### Custom add32 Function
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-// For testing - use a known add32 implementation
-const customAdd32 = (x: number, y: number): number => {
-  // Custom implementation for compatibility testing
-  const result = x + y;
-  return (result & 0xffffffff) >>> 0;
-};
-
-const stream = new MD5Stream({ add32: customAdd32 });
-let digest = '';
-
-stream.on('md5', (result) => {
-  digest = result.digest;
-});
-
-stream.end('test with custom add32');
-console.log(digest);
-```
-
-### Stream with Timeout
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-async function hashWithTimeout(source: NodeJS.ReadableStream, timeoutMs: number): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      reject(new Error('Hashing timeout'));
-    }, timeoutMs);
-    
-    const stream = new MD5Stream();
-    
-    stream.on('md5', (result) => {
-      clearTimeout(timeout);
-      resolve(result.digest);
-    });
-    
-    stream.on('error', (error) => {
-      clearTimeout(timeout);
-      reject(error);
-    });
-    
-    source.pipe(stream);
-  });
-}
-
-try {
-  const digest = await hashWithTimeout(fs.createReadStream('file.txt'), 5000);
-  console.log('MD5:', digest);
-} catch (error) {
-  console.error('Error:', error.message);
-}
-```
-
-### Multiple Hashes in Parallel
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-interface HashResult {
-  file: string;
-  digest: string;
-  size: number;
-}
-
-async function hashFilesParallel(files: string[]): Promise<HashResult[]> {
-  const promises = files.map(async (file) => {
-    const result = await hashFile(file);
-    const size = (await fs.promises.stat(file)).size;
-    return { file, digest: result.digest, size };
-  });
-  
-  return Promise.all(promises);
-}
-
-const results = await hashFilesParallel(['file1.txt', 'file2.txt', 'file3.txt']);
-results.forEach(r => console.log(`${r.file}: ${r.digest} (${r.size} bytes)`));
-```
-
-### Detect File Changes
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-interface FileHash {
-  path: string;
-  hash: string;
-  timestamp: number;
-}
-
-async function detectChanges(previous: Map<string, FileHash>, currentFiles: string[]): Promise<void> {
-  const changes: string[] = [];
-  
-  // Check existing files
-  for (const file of currentFiles) {
-    const currentHash = await hashFile(file);
-    const previousHash = previous.get(file);
-    
-    if (!previousHash || previousHash.hash !== currentHash.digest) {
-      changes.push(file);
-    }
-  }
-  
-  // Check for deleted files
-  for (const [file] of previous) {
-    if (!currentFiles.includes(file)) {
-      changes.push(file);
-    }
-  }
-  
-  if (changes.length > 0) {
-    console.log('Changed files:', changes);
-  }
-}
-```
-
----
-
-## Integration Examples
-
-### Express.js Middleware
-
-```typescript
-import { hashFile } from 'pure-md5';
-import express, { Request, Response, NextFunction } from 'express';
-
-interface RequestWithHash extends Request {
-  fileHash?: string;
-}
-
-const app = express();
-
-// Middleware to compute file hash
-app.use((req: RequestWithHash, res: Response, next: NextFunction) => {
-  if (req.body && req.body.file) {
-    hashFile(req.body.file.path)
-      .then(result => {
-        req.fileHash = result.digest;
-        next();
-      })
-      .catch(next);
-  } else {
-    next();
-  }
-});
-
-app.post('/upload', (req: RequestWithHash, res: Response) => {
-  res.json({
-    hash: req.fileHash,
-    message: 'File uploaded'
-  });
-});
-```
-
-### AWS Lambda Function
-
-```typescript
-import { hashFile } from 'pure-md5';
-import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
-
-const s3 = new S3Client({});
-
-export async function handler(event: any): Promise<any> {
-  const bucket = event.bucket;
-  const key = event.key;
-  
-  // Get object from S3
-  const command = new GetObjectCommand({ Bucket: bucket, Key: key });
-  const response = await s3.send(command);
-  
-  // Hash the content
-  const content = await response.Body!.transformToString();
-  const hash = await hashFile(content);
-  
-  return {
-    statusCode: 200,
-    body: JSON.stringify({
-      md5: hash.digest,
-      size: hash.bytesProcessed
-    })
-  };
-}
-```
-
-### GraphQL Resolver
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-const resolvers = {
-  Query: {
-    fileHash: async (_, { path }: { path: string }) => {
-      const result = await hashFile(path);
-      return {
-        digest: result.digest,
-        bytesProcessed: result.bytesProcessed,
-        path
-      };
-    }
-  }
-};
-```
-
-### CLI Tool
-
-```typescript
-#!/usr/bin/env node
-import { hashFile } from 'pure-md5';
-import fs from 'fs';
-
-async function main() {
-  const filePath = process.argv[2];
-  
-  if (!filePath) {
-    console.error('Usage: md5-hash <file>');
-    process.exit(1);
-  }
-  
-  try {
-    const result = await hashFile(filePath);
-    console.log(result.digest);
-  } catch (error) {
-    console.error('Error:', error.message);
-    process.exit(1);
-  }
-}
-
-main();
-```
-
-### React Component
-
-```typescript
-import { useState, useEffect } from 'react';
-import { hashFile } from 'pure-md5';
-
-function FileHasher() {
-  const [file, setFile] = useState<File | null>(null);
-  const [hash, setHash] = useState<string>('');
-  const [loading, setLoading] = useState(false);
-  
-  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    if (event.target.files && event.target.files[0]) {
-      setFile(event.target.files[0]);
-    }
-  };
-  
-  useEffect(() => {
-    if (file) {
-      setLoading(true);
-      hashFile(file)
-        .then(result => {
-          setHash(result.digest);
-          setLoading(false);
-        })
-        .catch(error => {
-          console.error(error);
-          setLoading(false);
-        });
-    }
-  }, [file]);
-  
-  return (
-    <div>
-      <input type="file" onChange={handleFileChange} />
-      {loading && <p>Computing hash...</p>}
-      {hash && <p>MD5: {hash}</p>}
-    </div>
-  );
-}
-```
-
-### Node.js CLI Tool with Progress
-
-```typescript
-#!/usr/bin/env node
-import { MD5Stream } from 'pure-md5';
-import fs from 'fs';
-import readline from 'readline';
-
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout
-});
-
-const filePath = process.argv[2];
-
-if (!filePath) {
-  console.error('Usage: md5-hash <file>');
-  process.exit(1);
-}
-
-const fileSize = fs.statSync(filePath).size;
-const stream = new MD5Stream();
-let processed = 0;
-
-const updateProgress = () => {
-  const progress = ((processed / fileSize) * 100).toFixed(1);
-  process.stdout.write(`\r${progress}% [${'#'.padEnd(50, ' ').substring(0, Math.floor(progress / 2))}]`);
-};
-
-stream.on('data', (chunk) => {
-  processed += chunk.length;
-  if (processed % (64 * 1024) === 0) { // Update every 64KB
-    updateProgress();
-  }
-});
-
-stream.on('md5', (result) => {
-  updateProgress();
-  console.log(`\n${result.digest}  ${filePath}`);
-  rl.close();
-});
-
-stream.on('error', (error) => {
-  console.error(`Error: ${error.message}`);
-  rl.close();
-  process.exit(1);
-});
-
-fs.createReadStream(filePath).pipe(stream);
-```
-
----
-
-## Performance Examples
-
-### Optimal File Hashing
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-import fs from 'fs';
-
-async function optimalHashFile(filePath: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const stream = new MD5Stream();
-    
-    stream.on('md5', (result) => {
-      resolve(result.digest);
-    });
-    
-    stream.on('error', reject);
-    
-    // Use piping for optimal performance
-    fs.createReadStream(filePath).pipe(stream);
-  });
-}
-```
-
-### Memory-Efficient Large File Processing
-
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-async function hashLargeFileEfficiently(source: NodeJS.ReadableStream): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const stream = new MD5Stream();
-    
-    stream.on('md5', (result) => {
-      resolve(result.digest);
-    });
-    
-    stream.on('error', reject);
-    
-    // Set optimal buffer size
-    source.setEncoding('binary');
-    source.pipe(stream);
-  });
-}
-```
-
-### Batch Processing
-
-```typescript
-import { hashFile } from 'pure-md5';
-
-async function batchHashFiles(
-  files: string[],
-  batchSize: number = 10
-): Promise<Map<string, string>> {
-  const results = new Map<string, string>();
-  
-  for (let i = 0; i < files.length; i += batchSize) {
-    const batch = files.slice(i, i + batchSize);
-    const batchResults = await Promise.all(batch.map(f => hashFile(f)));
-    
-    batch.forEach((file, index) => {
-      results.set(file, batchResults[index].digest);
-    });
-  }
-  
-  return results;
-}
-```
-
-## See Also
-
-- [STREAM_API.md](STREAM_API.md) - Complete API documentation
-- [MIGRATION_GUIDE_STREAMS.md](MIGRATION_GUIDE_STREAMS.md) - Migration examples
-- [STREAM_TROUBLESHOOTING.md](STREAM_TROUBLESHOOTING.md) - Common issues
-- [STREAM_BENCHMARKS.md](STREAM_BENCHMARKS.md) - Performance benchmarks