pure-md5 0.2.0 → 0.2.2

package/CONTRIBUTING.md

@@ -1,203 +0,0 @@
-# Contributing to pure-md5
-
-Thank you for your interest in contributing to pure-md5! 🎉
-
-## Table of Contents
-
-- [Code of Conduct](#code-of-conduct)
-- [How Can I Contribute?](#how-can-i-contribute)
-- [Development Setup](#development-setup)
-- [Running Tests](#running-tests)
-- [Creating Changesets](#creating-changesets)
-- [Pull Request Process](#pull-request-process)
-- [Coding Standards](#coding-standards)
-
-## Code of Conduct
-
-This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, please include as many details as possible:
-
-- A clear, descriptive title
-- Steps to reproduce the issue
-- Expected behavior
-- Actual behavior
-- Environment details (OS, Node.js version, package version)
-- Code example that reproduces the issue
-
-### Suggesting Features
-
-Feature requests are welcome! Please provide:
-
-- A clear description of the feature
-- The problem it solves
-- Any alternative solutions you've considered
-- Examples of how the feature would be used
-
-### Pull Requests
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Run tests (`npm test`)
-5. Create a changeset (`npx changeset`)
-6. Push your branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
-
-## Development Setup
-
-### Prerequisites
-
-- Node.js >= 16
-- npm >= 8
-
-### Installation
-
-```bash
-# Fork the repository first
-git clone https://github.com/eustatos/pure-md5.git
-cd pure-md5
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run tests
-npm test
-```
-
-### Available Scripts
-
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Build the project |
-| `npm run build:watch` | Build in watch mode |
-| `npm run build:prod` | Build with minification |
-| `npm run dev` | Run in dev mode |
-| `npm test` | Run all tests |
-| `npm run coverage` | Generate coverage report |
-| `npx changeset` | Create a changeset |
-
-## Running Tests
-
-### All Tests
-
-```bash
-npm test
-```
-
-### Specific Test File
-
-```bash
-npm test __tests__/index.test.ts
-```
-
-### With Coverage
-
-```bash
-npm run coverage
-```
-
-### Watch Mode
-
-```bash
-npm test -- --watch
-```
-
-## Creating Changesets
-
-Changesets are used to manage versioning and changelog generation.
-
-### Creating a Changeset
-
-```bash
-npx changeset
-```
-
-This will prompt you to:
-
-1. Select the version bump type:
-   - `major` - Breaking changes
-   - `minor` - New features
-   - `patch` - Bug fixes
-
-2. Write a description of your changes
-
-### Example
-
-```
-? Which packages would you like to include in this changeset? pure-md5
-? Which type of change is this?
-  patch     Patch release (bug fixes)
-  minor     Minor release (new features)
-  major     Major release (breaking changes)
-```
-
-## Pull Request Process
-
-1. **Update Documentation**: Update README.md or other docs if needed
-2. **Run Tests**: Ensure all tests pass
-3. **Code Review**: Wait for review from maintainers
-4. **Address Feedback**: Make requested changes
-5. **Merge**: Maintainers will merge when approved
-
-### PR Title Format
-
-Use conventional commit format:
-
-```
-type: description
-```
-
-Types:
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation changes
-- `style`: Code style changes
-- `refactor`: Code refactoring
-- `perf`: Performance improvements
-- `test`: Adding tests
-- `chore`: Maintenance tasks
-
-Examples:
-```
-feat: add streaming API for large files
-fix: handle edge case in MD5 calculation
-docs: update installation instructions
-refactor: optimize performance
-```
-
-## Coding Standards
-
-### JavaScript/TypeScript
-
-- Use ES6+ features
-- Follow Airbnb JavaScript Style Guide
-- Use TypeScript for new code
-- Add JSDoc comments for public APIs
-
-### Commit Messages
-
-- Use conventional commits
-- Use present tense
-- Be descriptive but concise
-
-### File Structure
-
-- Place tests in `__tests__/` directory
-- Name test files `<module>.test.ts`
-- Keep files focused on single responsibility
-
-## Questions?
-
-Feel free to open an issue or ask in the pull request if you have questions!
-
-## Acknowledgments
-
-Thank you for contributing to pure-md5! 🙏

package/MIGRATION_GUIDE_STREAMS.md

@@ -1,374 +0,0 @@
-# Migration Guide: Node.js Streams to pure-md5
-
-This guide helps you migrate from native Node.js crypto or other MD5 libraries to the pure-md5 streaming API.
-
-## From crypto.createHash()
-
-### Basic String Hashing
-
-**Before:**
-```typescript
-import crypto from 'crypto';
-
-const data = 'Hello, World!';
-const hash = crypto.createHash('md5').update(data).digest('hex');
-console.log(hash); // 65a8e27d8879283831b664bd8b7f0ad4
-```
-
-**After:**
-```typescript
-import { MD5Stream, fromStream } from 'pure-md5';
-import { Readable } from 'stream';
-
-// Method 1: Using fromStream
-const { result } = fromStream(Readable.from([data]));
-console.log(result.digest); // 65a8e27d8879283831b664bd8b7f0ad4
-
-// Method 2: Using MD5Stream with manual piping
-const stream = new MD5Stream();
-let digest = '';
-stream.on('md5', (r) => digest = r.digest);
-stream.end(data);
-
-// Method 3: Using pipeThroughMD5
-const result = await pipeThroughMD5(Readable.from([data]));
-console.log(result.digest);
-```
-
-### File Hashing
-
-**Before:**
-```typescript
-import crypto from 'crypto';
-import fs from 'fs';
-
-const hash = crypto.createHash('md5');
-const stream = fs.createReadStream('file.txt');
-
-stream.on('data', (chunk) => {
-  hash.update(chunk);
-});
-
-stream.on('end', () => {
-  console.log(hash.digest('hex'));
-});
-```
-
-**After:**
-```typescript
-import { MD5Stream, hashFile } from 'pure-md5';
-import fs from 'fs';
-
-// Method 1: Using MD5Stream
-const stream = new MD5Stream();
-stream.on('md5', (result) => {
-  console.log(result.digest);
-});
-fs.createReadStream('file.txt').pipe(stream);
-
-// Method 2: Using hashFile (simpler)
-const result = await hashFile('file.txt');
-console.log(result.digest);
-
-// Method 3: Using pipeThroughMD5
-const source = fs.createReadStream('file.txt');
-const result = await pipeThroughMD5(source);
-console.log(result.digest);
-```
-
-## From crypto.createHash() with Progress
-
-**Before:**
-```typescript
-import crypto from 'crypto';
-import fs from 'fs';
-
-const hash = crypto.createHash('md5');
-const stream = fs.createReadStream('large-file.bin');
-let total = 0;
-const fileSize = fs.statSync('large-file.bin').size;
-
-stream.on('data', (chunk) => {
-  hash.update(chunk);
-  total += chunk.length;
-  const progress = ((total / fileSize) * 100).toFixed(1);
-  console.log(`Progress: ${progress}%`);
-});
-
-stream.on('end', () => {
-  console.log('MD5:', hash.digest('hex'));
-});
-```
-
-**After:**
-```typescript
-import { MD5Stream, createProgressTracker } from 'pure-md5';
-import fs from 'fs';
-
-const fileSize = fs.statSync('large-file.bin').size;
-const progress = createProgressTracker(fileSize, (percent) => {
-  console.log(`Progress: ${percent.toFixed(1)}%`);
-});
-
-const stream = new MD5Stream();
-stream.on('md5', (result) => {
-  console.log('MD5:', result.digest);
-  console.log('Bytes:', result.bytesProcessed);
-});
-
-// Note: Current version doesn't have built-in progress
-// You can still track progress manually:
-let processed = 0;
-stream.on('data', (chunk) => {
-  processed += chunk.length;
-  const percent = ((processed / fileSize) * 100).toFixed(1);
-  console.log(`Progress: ${percent}%`);
-});
-
-fs.createReadStream('large-file.bin').pipe(stream);
-```
-
-## From Third-Party MD5 Libraries
-
-### From js-md5
-
-**Before:**
-```javascript
-import md5 from 'js-md5';
-
-// String
-console.log(md5('Hello'));
-
-// ArrayBuffer
-const arrayBuffer = new TextEncoder().encode('Hello').buffer;
-console.log(md5(arrayBuffer));
-
-// Uint8Array
-const uint8Array = new TextEncoder().encode('Hello');
-console.log(md5(uint8Array));
-```
-
-**After:**
-```typescript
-import { MD5Stream } from 'pure-md5';
-
-// String
-const stream1 = new MD5Stream();
-let result1 = '';
-stream1.on('md5', (r) => result1 = r.digest);
-stream1.end('Hello');
-
-// ArrayBuffer
-const stream2 = new MD5Stream();
-let result2 = '';
-stream2.on('md5', (r) => result2 = r.digest);
-const buffer = new TextEncoder().encode('Hello').buffer;
-stream2.end(new Uint8Array(buffer));
-
-// Uint8Array
-const stream3 = new MD5Stream();
-let result3 = '';
-stream3.on('md5', (r) => result3 = r.digest);
-const uint8Array = new TextEncoder().encode('Hello');
-stream3.end(uint8Array);
-```
-
-### From blueimp-md5
-
-**Before:**
-```javascript
-import md5 from 'blueimp-md5';
-
-// String
-md5('Hello'); // "8b1a9953c4611296a827abf8c47804d7"
-
-// File (browser)
-const file = document.querySelector('input').files[0];
-const reader = new FileReader();
-reader.onload = function() {
-  const hash = md5(reader.result);
-  console.log(hash);
-};
-reader.readAsBinaryString(file);
-```
-
-**After:**
-```typescript
-import { MD5Stream, hashFile, hashBlob } from 'pure-md5';
-
-// String
-const stream = new MD5Stream();
-let result = '';
-stream.on('md5', (r) => result = r.digest);
-stream.end('Hello');
-
-// File (browser)
-const file = document.querySelector('input').files[0];
-const result = await hashFile(file);
-console.log(result.digest);
-
-// Blob (browser)
-const blob = new Blob(['Hello']);
-const result = await hashBlob(blob);
-console.log(result.digest);
-```
-
-## Browser Migration
-
-### From Manual MD5 Implementation
-
-**Before:**
-```javascript
-async function md5Browser(data) {
-  const buffer = await data.arrayBuffer();
-  const hashBuffer = await crypto.subtle.digest('MD5', buffer);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-  return hashHex;
-}
-```
-
-**After:**
-```typescript
-import { hashFile, hashBlob, MD5ReadableStream } from 'pure-md5';
-
-// For File
-const file = document.querySelector('input').files[0];
-const result = await hashFile(file);
-
-// For Blob
-const blob = new Blob([data]);
-const result = await hashBlob(blob);
-
-// For custom ReadableStream
-const source = new ReadableStream({ ... });
-const result = await MD5ReadableStream.hash(source);
-```
-
-## API Comparison
-
-### crypto.createHash() Style
-
-| crypto | pure-md5 |
-|--------|----------|
-| `update(chunk)` | `stream.write(chunk)` |
-| `digest('hex')` | Listen to `md5` event |
-| No built-in streaming | Built-in Transform stream |
-| No progress tracking | Manual progress via 'data' event |
-
-### File Operations
-
-| crypto | pure-md5 |
-|--------|----------|
-| Manual file stream | `hashFile('path')` |
-| Manual hash computation | `hashFileSync('path')` |
-| Manual verification | `verifyFile('path', hash)` |
-
-## Migration Checklist
-
-- [ ] Identify all uses of `crypto.createHash('md5')`
-- [ ] Replace with `MD5Stream` or `fromStream` for streaming
-- [ ] Use `hashFile` for simple file hashing
-- [ ] Update event handlers from 'end' to 'md5'
-- [ ] Replace 'data' handler usage with MD5 event
-- [ ] Update type imports
-- [ ] Test with various input sizes
-- [ ] Verify hash outputs match expected values
-
-## Common Patterns
-
-### Pattern 1: Simple File Hash
-
-```typescript
-// All of these are equivalent:
-const result1 = await hashFile('file.txt');
-const result2 = await pipeThroughMD5(fs.createReadStream('file.txt'));
-const { result } = fromStream(fs.createReadStream('file.txt'));
-```
-
-### Pattern 2: Memory-Efficient Large File Hash
-
-```typescript
-const stream = new MD5Stream();
-stream.on('md5', (result) => {
-  console.log('Hash:', result.digest);
-  console.log('Size:', result.bytesProcessed);
-});
-fs.createReadStream('large-file.bin').pipe(stream);
-```
-
-### Pattern 3: Concurrent File Hashing
-
-```typescript
-const files = ['file1.txt', 'file2.txt', 'file3.txt'];
-const results = await Promise.all(files.map(f => hashFile(f)));
-```
-
-## Troubleshooting
-
-### Issue: "digest is not a function"
-
-**Cause:** Using crypto API incorrectly
-
-**Solution:**
-```typescript
-// Wrong
-const stream = crypto.createHash('md5');
-stream.end(data);
-console.log(stream.digest); // Error: digest is not a function
-
-// Right
-const stream = crypto.createHash('md5');
-stream.end(data);
-console.log(stream.digest('hex')); // Pass 'hex' argument
-```
-
-### Issue: Hash values don't match
-
-**Cause:** Different encoding or data format
-
-**Solution:**
-```typescript
-// Ensure consistent encoding
-const data = 'Hello';
-const stream = new MD5Stream();
-let result = '';
-stream.on('md5', (r) => result = r.digest);
-stream.end(data); // This matches crypto.createHash('md5').update(data, 'utf8')
-
-// For binary data, use Buffer
-const binaryData = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
-stream.end(binaryData);
-```
-
-### Issue: Stream not emitting 'md5' event
-
-**Cause:** Not ending the stream
-
-**Solution:**
-```typescript
-const stream = new MD5Stream();
-stream.on('md5', (result) => console.log(result.digest));
-stream.write('Hello');
-stream.end(); // Must call end() to trigger 'md5' event
-```
-
-## Performance Notes
-
-The pure-md5 streaming implementation is designed for:
-
-- **Memory efficiency:** Processes data in chunks, doesn't load entire file
-- **Compatibility:** Works in both Node.js and browser environments
-- **Flexibility:** Multiple API styles for different use cases
-
-For maximum performance with large files:
-
-1. Use 64KB chunk sizes when manually writing
-2. Reuse stream instances with `reset()`
-3. Avoid unnecessary data copies
-
-## See Also
-
-- [STREAM_API.md](STREAM_API.md) - Complete API documentation
-- [README.md](README.md) - Basic usage examples
-- [WHATWG_STREAMS.md](WHATWG_STREAMS.md) - Browser streaming guide