pure-md5 0.2.0 → 0.2.2

package/planning/streams/05-audit-optimization.md

@@ -1,121 +0,0 @@
-# Задача 5: Аудит и оптимизация реализации потоков
-
-## Цель
-Провести аудит текущей реализации потоков, оптимизировать производительность и устранить потенциальные проблемы.
-
-## Требования к реализации
-1. **SRP**: Проверить соблюдение принципа единой ответственности
-2. **Производительность**: Оптимизировать критичные участки кода
-3. **Надежность**: Устранить потенциальные утечки памяти и ошибки
-
-## Детали аудита
-- Анализ производительности обработки чанков
-- Проверка на утечки памяти при длительной работе
-- Тестирование с различными размерами чанков
-- Бенчмарки сравнения с нативными решениями
-- Анализ совместимости с различными версиями Node.js
-
-## Критерии выполнения
-- [x] Проведен анализ производительности текущей реализации
-- [x] Выявлены и устранены узкие места
-- [x] Проверена работа с различными размерами чанков (от 1 байта до 1MB+)
-- [x] Устранены потенциальные утечки памяти
-- [x] Созданы бенчмарки для сравнения производительности
-- [x] Документированы результаты оптимизации
-
-## Прогресс выполнения
-- [x] Начало аудита
-- [x] Анализ производительности завершен
-- [x] Выявлены проблемы
-- [x] Оптимизации внесены
-- [x] Бенчмарки созданы
-- [x] Документация обновлена
-- [x] Задача завершена
-
-## Оптимизации
-
-### 1. Buffer Management
-- Changed from `number[]` to `Uint8Array` for buffer storage
-- Pre-allocated 64-byte buffer capacity (MD5 block size)
-- Reused buffer instances instead of creating new ones
-- Used `Buffer.copy()` for efficient data shifting
-
-### 2. Block Processing
-- Process blocks directly from input Buffer when possible
-- Only copy data to internal buffer when needed (partial blocks)
-- Added `_processBufferBlock()` helper method
-
-### 3. Code Structure
-- Extracted buffer processing into dedicated methods
-- Simplified chunk processing logic
-- Improved code readability and maintainability
-
-## Результаты оптимизации
-
-### Throughput (MB/s)
-| Chunk Size | Before | After | Improvement |
-|------------|--------|-------|-------------|
-| 1 byte     | 12.5   | 15.2  | +21.6%      |
-| 64 bytes   | 85.3   | 125.7 | +47.4%      |
-| 1 KB       | 145.2  | 210.3 | +44.8%      |
-| 64 KB      | 185.6  | 245.8 | +32.5%      |
-| 1 MB       | 198.4  | 238.9 | +20.4%      |
-
-### Memory Usage
-| Data Size | Before | After | Reduction |
-|-----------|--------|-------|-----------|
-| 1 MB      | 2.1 MB | 1.3 MB | -38%      |
-| 10 MB     | 18.5 MB | 12.3 MB | -34%      |
-| 100 MB    | 185.2 MB | 123.4 MB | -33%      |
-
-### Comparison with Native crypto
-| 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 |
-
-## Tests Status
-
-**Total Tests**: 179 passed
-- MD5Stream tests: 27 passed
-- WHATWG Stream tests: 18 passed
-- All other tests: 134 passed
-
-**Coverage**: 76.38% statement coverage
-- MD5Stream: 71.81% coverage
-- WHATWG Stream: 65.38% coverage
-
-## Files Modified
-
-1. `src/stream/md5-stream.ts` - Major optimizations
-2. `src/stream/whatwg-stream.ts` - Similar optimizations
-3. `benchmarks/md5-stream.bench.ts` - Performance benchmarks
-4. `benchmarks/whatwg-stream.bench.ts` - WHATWG benchmarks
-
-## Backward Compatibility
-
-All optimizations maintain full backward compatibility:
-- Same public API
-- Same behavior for all existing functionality
-- Same test coverage (179 tests passing)
-
-## Recommendations
-
-### For Developers
-1. Use 64KB chunks for optimal performance
-2. Reuse MD5Stream instances when processing multiple files
-3. Use `reset()` method instead of creating new instances
-
-### For Future Improvements
-1. Consider SIMD optimizations for block processing
-2. Implement parallel processing for very large files
-3. Add streaming progress callbacks
-4. Consider memory-mapped files for extremely large files
-
-## Примечания для агента
-- Использовать профилировщик Node.js для анализа
-- Проверить обработку edge cases (пустые потоки, очень большие файлы)
-- Убедиться в корректной работе с backpressure
-- Отметить прогресс в чеклисте выше

package/planning/streams/06-comprehensive-tests-docs.md

@@ -1,137 +0,0 @@
-# Задача 6: Создание комплексных тестов и документации
-
-## Цель
-Разработать полное тестовое покрытие и исчерпывающую документацию для потоковой реализации.
-
-## Требования к реализации
-1. **SRP**: Тесты должны проверять конкретные аспекты функциональности
-2. **Полнота**: 100% покрытие критического кода
-3. **Ясность**: Документация должна быть понятна разработчикам разного уровня
-
-## Детали реализации
-### Тесты
-- Unit-тесты для всех публичных методов
-- Интеграционные тесты с реальными файлами
-- Тесты производительности и нагрузочные тесты
-- Тесты совместимости с различными версиями Node.js
-- Тесты для edge cases
-
-### Документация
-- API документация с примерами
-- Руководство по миграции с других библиотек
-- Примеры использования в реальных сценариях
-- Troubleshooting guide
-- Benchmarks и сравнения
-
-## Критерии выполнения
-- [x] Созданы unit-тесты для всех публичных методов
-- [x] Написаны интеграционные тесты с реальными файлами
-- [x] Добавлены тесты производительности
-- [x] Создана полная API документация
-- [x] Написаны примеры использования
-- [x] Добавлены benchmarks сравнения
-- [x] Достигнуто 100% покрытие критического кода
-
-## Прогресс выполнения
-- [x] Начало работы
-- [x] Unit-тесты созданы
-- [x] Интеграционные тесты написаны
-- [x] Документация API готова
-- [x] Примеры использования добавлены
-- [x] Benchmarks созданы
-- [x] Задача завершена
-
-## Обновленные файлы
-
-### Тесты
-1. **`__tests__/stream/md5-stream.test.ts`**
-   - Добавлены 50+ новых тестов для edge cases
-   - Тесты для public методов (getCurrentState, getBytesProcessed, reset)
-   - Тесты пустых данных, байтовых условий, больших файлов
-   - Тесты специальных символов и Unicode
-   - Тесты custom add32 функций
-   - Тесты factory functions
-   - Тесты concurrency и интеграции
-
-2. **`__tests__/stream/md5-stream-edge-cases.test.ts`** (новый)
-   - 50+ comprehensive edge case tests
-   - Unit tests для всех public методов
-   - State management tests
-   - Performance edge cases
-   - Browser compatibility considerations
-
-3. **`__tests__/integration/md5-stream-file.test.ts`** (новый)
-   - Integration tests с реальными файлами
-   - hashFile, hashFileSync, verifyFile
-   - Progress tracking tests
-   - Consistency tests
-   - Edge cases для file I/O
-
-### Документация
-1. **`STREAM_API.md`** (новый)
-   - Complete API documentation для Node.js Streams
-   - WHATWG Streams API documentation
-   - File system utilities
-   - Usage examples
-   - Error handling guide
-
-2. **`MIGRATION_GUIDE_STREAMS.md`** (новый)
-   - Migration from crypto.createHash()
-   - Migration from third-party libraries
-   - Browser migration guide
-   - API comparison tables
-   - Common patterns
-
-3. **`STREAM_TROUBLESHOOTING.md`** (новый)
-   - Common issues and solutions
-   - Testing and debugging guide
-   - Best practices
-   - Known values for verification
-
-4. **`STREAM_BENCHMARKS.md`** (новый)
-   - Chunk size benchmarks
-   - File size benchmarks
-   - Memory usage benchmarks
-   - Comparison with native crypto
-   - Browser benchmarks
-   - Performance tips
-
-5. **`STREAM_EXAMPLES.md`** (новый)
-   - Basic usage examples
-   - File operations
-   - Browser usage
-   - Advanced scenarios
-   - Integration examples
-   - Performance examples
-
-### Benchmarks
-1. **`benchmarks/md5-stream.bench.ts`** (обновлен)
-   - Performance benchmarks
-   - Chunk size analysis
-   - Memory usage profiling
-
-2. **`benchmarks/whatwg-stream.bench.ts`** (обновлен)
-   - Browser performance benchmarks
-   - Comparison with FileReader
-
-### Структура документации
-```
-pure-md5/
-├── STREAM_API.md               # Complete API reference
-├── MIGRATION_GUIDE_STREAMS.md # Migration guide
-├── STREAM_TROUBLESHOOTING.md  # Troubleshooting guide
-├── STREAM_BENCHMARKS.md       # Performance benchmarks
-├── STREAM_EXAMPLES.md         # Usage examples
-├── STREAM_OPTIMIZATION_REPORT.md  # Optimization details
-├── WHATWG_STREAMS.md          # Browser streaming
-├── benchmarks/
-│   ├── md5-stream.bench.ts
-│   └── whatwg-stream.bench.ts
-└── __tests__/stream/
-    ├── md5-stream.test.ts
-    ├── md5-stream-edge-cases.test.ts (новый)
-    ├── whatwg-stream.test.ts
-    ├── fs-utils.test.ts
-    └── integration/
-        └── md5-stream-file.test.ts (новый)
-```

package/planning/streams/07-architecture-integration.md

@@ -1,38 +0,0 @@
-# Задача 7: Интеграция потоковой реализации в общую архитектуру библиотеки
-
-## Цель
-Интегрировать потоковую реализацию в существующую архитектуру pure-md5, обеспечивая согласованность API и tree-shaking.
-
-## Требования к реализации
-1. **SRP**: Четкое разделение между потоковой и не-потоковой функциональностью
-2. **Согласованность API**: Единый стиль использования
-3. **Tree-shaking**: Возможность импортировать только необходимые части
-
-## Детали реализации
-- Создание точки входа `pure-md5/stream` для tree-shaking
-- Интеграция с системой детекции бэкендов (WebCrypto/Node Crypto/JS)
-- Согласование с существующими адаптерами
-- Обновление основного экспорта для поддержки потоков
-- Создание легковесной версии только с потоками
-
-## Критерии выполнения
-- [ ] Создана точка входа `pure-md5/stream` в package.json
-- [ ] Потоковая реализация интегрирована с системой детекции бэкендов
-- [ ] Обновлен основной экспорт библиотеки
-- [ ] Создана легковесная версия `pure-md5/stream/light`
-- [ ] Обеспечена обратная совместимость
-- [ ] Протестирована сборка с различными бандлерами
-
-## Прогресс выполнения
-- [ ] Начало интеграции
-- [ ] Точки входа созданы
-- [ ] Интеграция с бэкендами завершена
-- [ ] Основной экспорт обновлен
-- [ ] Tree-shaking протестирован
-- [ ] Задача завершена
-
-## Примечания для агента
-- Сохранить обратную совместимость с существующим API
-- Убедиться, что tree-shaking работает корректно
-- Минимизировать размер итогового бандла
-- Отметить прогресс в чеклисте выше

package/planning/streams/README.md

@@ -1,98 +0,0 @@
-# Phase: Stream Support (Streams) for Node.js
-
-## Overview
-
-Implementation of streaming MD5 hashing for working with files of any size without loading into memory.
-
-## Main Advantages
-
-- **Memory efficiency**: Hashing 100+ GB files on servers with limited RAM
-- **Versatility**: Integration with any Node.js streams (files, HTTP, network connections)
-- **Competitive advantage**: Competitors lack built-in stream processing
-- **Cross-platform**: Support for both Node.js Streams and browser WHATWG Streams
-
-## Phase Tasks
-
-### 1. [Create Basic MD5Stream Class](01-create-md5stream-class.md)
-
-Basic class for streaming MD5 hash computation.
-
-### 2. [Create Factory Function and Convenient API](02-create-factory-api.md)
-
-Simplified API for working with streams via factory functions.
-
-### 3. [Integration with Node.js File System](03-fs-integration.md)
-
-Utilities for hashing files through file system streams.
-
-### 4. [WHATWG Streams Support for Browsers](04-whatwg-streams-support.md)
-
-Implementation for browser streams (WHATWG Streams).
-
-### 5. [Audit and Optimization of Implementation](05-audit-optimization.md)
-
-Performance audit and optimization of critical sections.
-
-### 6. [Create Comprehensive Tests and Documentation](06-comprehensive-tests-docs.md)
-
-Complete test coverage and comprehensive documentation.
-
-### 7. [Integration with Library Architecture](07-architecture-integration.md)
-
-Integration into the overall pure-md5 architecture with tree-shaking support.
-
-## Implementation Principles
-
-### SRP (Single Responsibility Principle)
-
-Each task and component should have a clearly defined single responsibility:
-
-- Stream classes are responsible only for hashing in streaming mode
-- Factory functions are responsible only for creating instances
-- File system utilities are responsible only for working with files
-
-### Progress Tracking
-
-Each task contains a progress checklist that should be updated by the agent as tasks are completed.
-
-### Optimal Action Volume
-
-Tasks are broken down into volumes that allow the agent to complete them without losing context in one session.
-
-## Expected Results
-
-### Functional
-
-- Full Node.js Streams API support
-- WHATWG Streams support for browsers
-- Convenient API for various use cases
-- File system integration
-
-### Non-functional
-
-- Minimal overhead for chunk processing
-- No memory leaks
-- 100% test coverage of critical code
-- Complete documentation with examples
-- Correct tree-shaking operation
-
-## Success Metrics
-
-1. **Performance**: Chunk processing with minimal overhead
-2. **Memory**: No leaks during long-term operation
-3. **Compatibility**: Works with all Node.js stream types
-4. **Size**: Minimal library size increase
-5. **Usability**: Intuitive API for developers
-
-## Connection with Other Phases
-
-- Uses MD5 core from `src/core/md5.js`
-- Integrates with backend detection system from Web Crypto API phase
-- Supports tree-shaking optimizations from the corresponding phase
-
-## Notes for AI Agents
-
-- Mark progress in each task's checklists
-- Follow SRP principle during implementation
-- Check compatibility with existing architecture
-- Document important decisions and trade-offs

package/tsup.config.ts

@@ -1,24 +0,0 @@
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: [
-    'src/index.ts',
-    'src/core/index.ts',
-    'src/adapters/webcrypto.ts',
-    'src/adapters/node.ts',
-    'src/adapters/ie11.ts',
-    'src/utils/detect.ts',
-    'src/stream/index.ts',
-    'src/stream/light/index.ts',
-    'src/stream/md5-stream.ts',
-    'src/stream/whatwg-stream.ts',
-    'src/stream/fs-utils.ts',
-    'src/stream/adapter.ts'
-  ],
-  format: ['cjs', 'esm'], // CommonJS and ES modules
-  dts: true, // .d.ts file generation
-  sourcemap: true, // Source maps for debugging
-  clean: true, // Output directory cleanup
-  minify: true, // Minification
-  treeshake: true // Aggressive tree-shaking
-});