pure-md5 0.2.0 → 0.2.2

package/planning/prd.md

@@ -1,405 +0,0 @@
-## 1. Stream Support (Streams) for Node.js
-
-Stream processing allows hashing files of any size (videos, databases, logs) without loading the entire file into memory. This is critically important for server applications.
-
-### How it works
-
-In Node.js, streams read files in parts (chunks). Our task is to update the hash for each chunk and finalize it at the end.
-
-### Implementation
-
-```javascript
-const { createHash } = require('node:crypto');
-const { Readable } = require('node:stream');
-
-class MD5Stream extends Readable {
-  constructor(options = {}) {
-    super(options);
-    this.hash = createHash('md5');
-    this.bytesProcessed = 0;
-  }
-
-  // This method is called automatically when reading the stream
-  _transform(chunk, encoding, callback) {
-    this.hash.update(chunk);
-    this.bytesProcessed += chunk.length;
-    this.push(chunk); // Pass the chunk further down the stream
-    callback();
-  }
-
-  // Called at the end of the stream
-  _flush(callback) {
-    const digest = this.hash.digest('hex');
-    // Add metadata to the end of the stream or emit an event
-    this.emit('md5', { digest, bytes: this.bytesProcessed });
-    callback();
-  }
-}
-
-// Convenient API for users
-function createMD5Stream() {
-  return new MD5Stream();
-}
-
-// Usage example:
-const fs = require('node:fs');
-
-const readStream = fs.createReadStream('large-file.iso');
-const hasher = createMD5Stream();
-
-readStream.pipe(hasher).on('md5', (result) => {
-  console.log(`MD5: ${result.digest}`);
-  console.log(`Size: ${result.bytes} bytes`);
-});
-```
-
-### What this gives `pure-md5`
-
-- **Competitive advantage**: None of the competitors (`md5`, `crypto-js`) offer built-in stream processing.
-- **Memory efficiency**: Can hash 100 GB files on a server with 512 MB RAM.
-- **Versatility**: Suitable for integration with any Node.js streams (HTTP requests, file system, network streams).
-
-### Additionally: browser stream support
-
-For browsers, you can add support for `ReadableStream` (WHATWG Streams):
-
-```javascript
-// browser-stream.js
-async function hashFileThroughStream(file) {
-  const stream = file.stream();
-  const reader = stream.getReader();
-  const hash = await initializeMD5(); // your MD5 implementation
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    hash.update(value);
-  }
-
-  return hash.digest('hex');
-}
-```
-
-## 2. Web Crypto API Detection and Fallback Mechanisms
-
-Web Crypto API is a cryptographic interface built into browsers and Node.js. It works dozens of times faster than pure JavaScript implementation and uses hardware acceleration.
-
-### Smart Environment Detection
-
-We need to determine which runtime environment and what level of support is available:
-
-```javascript
-// crypto-detect.js
-export const CryptoBackend = {
-  WEB_CRYPTO: 'webcrypto', // Modern browsers, Node.js (with flags)
-  NODE_CRYPTO: 'nodecrypto', // Native Node.js crypto
-  IE11_MS_CRYPTO: 'ie11', // Internet Explorer 11 (window.msCrypto)
-  FALLBACK_JS: 'purejs' // Pure JS implementation (your current one)
-};
-
-export async function detectCryptoBackend() {
-  // 1. Check Node.js environment
-  if (typeof globalThis.crypto?.subtle?.digest === 'function') {
-    // Node.js 15+ with WebCrypto enabled
-    return CryptoBackend.WEB_CRYPTO;
-  }
-
-  if (typeof require === 'function') {
-    try {
-      const nodeCrypto = require('node:crypto');
-      if (nodeCrypto?.createHash) {
-        return CryptoBackend.NODE_CRYPTO;
-      }
-    } catch {
-      // node:crypto is not available
-    }
-  }
-
-  // 2. Check browser environment
-  if (typeof window !== 'undefined') {
-    // Modern browsers
-    if (window.crypto?.subtle?.digest) {
-      return CryptoBackend.WEB_CRYPTO;
-    }
-
-    // Internet Explorer 11 (uses msCrypto)
-    if (window.msCrypto?.subtle?.digest) {
-      return CryptoBackend.IE11_MS_CRYPTO;
-    }
-  }
-
-  // 3. Nothing found — use pure JS
-  return CryptoBackend.FALLBACK_JS;
-}
-```
-
-### Adapter for Different Backends
-
-We create a unified interface that hides implementation details:
-
-```javascript
-// md5-adapter.js
-import { CryptoBackend, detectCryptoBackend } from './crypto-detect.js';
-import { md5 as pureJSMD5 } from './pure-md5.js';
-
-class MD5Adapter {
-  constructor() {
-    this.backend = null;
-    this.initialized = false;
-  }
-
-  async initialize() {
-    if (this.initialized) return;
-    this.backend = await detectCryptoBackend();
-    this.initialized = true;
-  }
-
-  async hash(data) {
-    await this.initialize();
-
-    switch (this.backend) {
-      case CryptoBackend.WEB_CRYPTO:
-        return this.hashWithWebCrypto(data);
-      case CryptoBackend.NODE_CRYPTO:
-        return this.hashWithNodeCrypto(data);
-      case CryptoBackend.IE11_MS_CRYPTO:
-        return this.hashWithMsCrypto(data);
-      default:
-        return pureJSMD5(data);
-    }
-  }
-
-  async hashWithWebCrypto(data) {
-    const encoder = new TextEncoder();
-    const buffer = encoder.encode(data);
-    const hashBuffer = await crypto.subtle.digest('MD5', buffer);
-    return this.bufferToHex(hashBuffer);
-  }
-
-  async hashWithNodeCrypto(data) {
-    const crypto = require('node:crypto');
-    return crypto.createHash('md5').update(data).digest('hex');
-  }
-
-  // For IE11
-  async hashWithMsCrypto(data) {
-    const encoder = new TextEncoder();
-    const buffer = encoder.encode(data);
-    const hashBuffer = await window.msCrypto.subtle.digest('MD5', buffer);
-    return this.bufferToHex(hashBuffer);
-  }
-
-  bufferToHex(buffer) {
-    return Array.from(new Uint8Array(buffer))
-      .map((b) => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-}
-
-export const md5 = new MD5Adapter();
-```
-
-### Graceful Degradation
-
-It's important not just to fail with an error, but to try alternative paths:
-
-```javascript
-async function robustHash(input, options = {}) {
-  const errors = [];
-
-  // Try to use WebCrypto
-  if (!options.forcePureJS) {
-    try {
-      return await hashWithWebCrypto(input);
-    } catch (e) {
-      errors.push({ backend: 'webcrypto', error: e.message });
-      // Log for monitoring but continue
-      console.warn('WebCrypto failed, falling back:', e.message);
-    }
-  }
-
-  // Try Node.js crypto
-  try {
-    return await hashWithNodeCrypto(input);
-  } catch (e) {
-    errors.push({ backend: 'nodecrypto', error: e.message });
-  }
-
-  // Final fallback — pure JS implementation
-  try {
-    const result = pureJSMD5(input);
-
-    // If there were errors but we managed to work — inform
-    if (errors.length > 0 && options.reportFallback) {
-      console.info('MD5 used fallback. Previous errors:', errors);
-    }
-
-    return result;
-  } catch (e) {
-    // Complete failure
-    throw new Error(
-      `MD5 hash failed after all attempts: ${errors.map((e) => e.error).join(', ')}`
-    );
-  }
-}
-```
-
-### Fallback Usage Monitoring
-
-For production systems, it's important to track how often fallback mechanisms are triggered:
-
-```javascript
-const metrics = {
-  webcrypto: { success: 0, fail: 0 },
-  nodecrypto: { success: 0, fail: 0 },
-  purejs: { success: 0, fail: 0 }
-};
-
-// Wrapper with metrics
-async function monitoredHash(input) {
-  for (const backend of ['webcrypto', 'nodecrypto', 'purejs']) {
-    try {
-      const result = await hashWithBackend(backend, input);
-      metrics[backend].success++;
-      return result;
-    } catch (e) {
-      metrics[backend].fail++;
-      // continue to the next backend
-    }
-  }
-  throw new Error('All backends failed');
-}
-
-// Periodic report
-setInterval(() => {
-  console.log('MD5 Backend Metrics:', metrics);
-}, 60000); // Every minute
-```
-
-## 3. Size Optimization and Tree-Shaking Configuration
-
-Tree-shaking allows bundlers (webpack, Rollup, Vite) to remove unused code from the final bundle. Here's how to make `pure-md5` fully "shakable".
-
-### ESM Module Structure
-
-We switch to the modern ES module format:
-
-```javascript
-// package.json
-{
-  "name": "pure-md5",
-  "version": "2.0.0",
-  "type": "module",              // <-- Entire package as ESM
-  "sideEffects": false,          // <-- Critically important for tree-shaking!
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    },
-    "./stream": {
-      "import": "./dist/stream.js",
-      "require": "./dist/stream.cjs"
-    },
-    "./light": {
-      "import": "./dist/light.js"  // Only basic function, without adapters
-    },
-    "./package.json": "./package.json"
-  },
-  "module": "./dist/index.js",
-  "main": "./dist/index.cjs",
-  "types": "./dist/index.d.ts"
-}
-```
-
-### Modular Architecture
-
-We split the code into separate files so that only what's needed can be imported:
-
-```javascript
-// src/core/md5.js - pure algorithm implementation (no dependencies)
-export function md5Core(input) {
-  // Only the algorithm, without environment detection
-  // ~2KB gzipped
-}
-
-// src/adapters/webcrypto.js
-export async function md5WebCrypto(input) {
-  // Uses Web Crypto API
-  // ~0.5KB gzipped
-}
-
-// src/adapters/node.js
-export function md5Node(input) {
-  // Uses node:crypto
-  // ~0.5KB gzipped
-}
-
-// src/index.js - smart version with auto-detection
-import { md5Core } from './core/md5.js';
-import { detectBackend } from './utils/detect.js';
-
-export async function md5(input) {
-  const backend = await detectBackend();
-  return backend(input);
-}
-
-// src/light.js - only pure JS implementation, minimal code
-export { md5Core as md5 } from './core/md5.js';
-```
-
-### Optimization via "pure" Annotations
-
-We help the bundler understand that functions are pure and can be safely removed:
-
-```javascript
-// Add comments in the code for Terser/webpack
-const fastMD5 = /*#__PURE__*/ createMD5Function();
-
-// For complex computations that can be removed if the result is not used
-const precomputedTable = /*#__PURE__*/ (() => {
-  // Constant table for MD5
-  return [0x67452301, 0xefcdab89 /* ... */];
-})();
-```
-
-### Minimization via Conditional Exports
-
-We create "entry points" with different functionality:
-
-```javascript
-// Example usage in a user's project
-// 1. Maximum compatibility (auto-detection)
-import { md5 } from 'pure-md5';
-await md5('hello');
-
-// 2. Only stream processing (for Node.js)
-import { createMD5Stream } from 'pure-md5/stream';
-fs.createReadStream('big.iso').pipe(createMD5Stream());
-
-// 3. Ultra-light version (for microcontrollers/small scripts)
-import { md5 } from 'pure-md5/light'; // ~2KB!
-console.log(md5('hello'));
-
-// 4. Only WebCrypto (for modern browsers)
-import { md5 } from 'pure-md5/webcrypto'; // ~0.5KB!
-```
-
-### Size Comparison After Optimization
-
-| Version              | Size (gzipped) | What's Included               |
-| -------------------- | -------------- | ----------------------------- |
-| `pure-md5/light`     | **~2 KB**      | Only pure JS algorithm        |
-| `pure-md5/webcrypto` | **~0.5 KB**    | Only Web Crypto API wrapper   |
-| `pure-md5` (full)    | **~4 KB**      | Auto-detection + all adapters |
-| **Competitors**      |                |                               |
-| `md5`                | ~15 KB         | Only JS implementation        |
-| `crypto-js/md5`      | ~25 KB         | MD5 + additional code         |
-
-## Summary: What This Optimization Provides
-
-1. **Streams** — a unique feature that competitors don't have. Attracts server developers.
-2. **WebCrypto + fallback** — security and speed on modern platforms + guaranteed operation everywhere.
-3. **Tree-shaking** — ability to use `pure-md5` even in the smallest projects without fear of bloating the bundle.
-
-The package becomes not just "another MD5 library", but **a tool with clear positioning**: modern, lightweight, smart, and performant.

package/planning/streams/01-create-md5stream-class.md

@@ -1,69 +0,0 @@
-# Task 1: Creating the MD5Stream Base Class
-
-## Goal
-Create a base `MD5Stream` class extending `stream.Transform` for streaming MD5 hash computation.
-
-## Implementation Requirements
-1. **SRP**: The class should only be responsible for computing MD5 hash in streaming mode
-2. **Performance**: Minimal overhead when processing each chunk
-3. **Compatibility**: Works with any Node.js streams (Readable, Writable, Transform)
-
-## Implementation Details
-- Extends `stream.Transform`
-- Initializes MD5 hash in constructor
-- Updates hash in `_transform` method
-- Finalizes hash in `_flush` method
-- Emits 'md5' event with result (digest and bytesProcessed)
-
-## Acceptance Criteria
-- [x] Created `MD5Stream` class in `src/stream/md5-stream.ts`
-- [x] Class correctly extends `stream.Transform`
-- [x] Implemented `_transform` method for hash updates
-- [x] Implemented `_flush` method for hash finalization
-- [x] Added `'md5'` event with result (digest and bytesProcessed)
-- [x] Basic tests written for class functionality
-
-## Implementation Status
-- [x] Examined existing MD5 implementation structure
-- [x] Created stream directory structure
-- [x] Created MD5Stream class in src/stream/md5-stream.ts
-- [x] Exported MD5Stream from index.ts
-- [x] Added stream entry to tsup.config.ts
-- [x] Created tests for MD5Stream
-- [x] Verified implementation with tests
-- [x] Documentation updated
-
-## Implementation Summary
-- **Location**: `src/stream/md5-stream.ts`
-- **Exports**: `MD5Stream` and `createMD5Stream` (factory function)
-- **Features**:
-  - Efficient chunk processing with 64-byte block optimization
-  - Automatic padding and length handling
-  - Configurable add32 function for testing
-  - State management with `reset()` method
-  - State inspection via `getCurrentState()` and `getBytesProcessed()`
-
-## Test Results
-All 19 MD5Stream tests pass:
-- Empty string handling
-- Simple and longer strings
-- Chunked data processing
-- 64-byte block alignment
-- Special characters
-- Binary buffer input
-- Large file simulation
-- Factory function
-- Custom add32 function
-- Sequential processing
-- Single byte chunks
-- Hex digest validation
-- State reset functionality
-- Current state inspection
-- Empty chunks handling
-
-## Notes for Agent
-- Uses native MD5 implementation from `src/core/index.ts`
-- Minimal performance overhead
-- Compatible with all Node.js stream types
-- Stream is marked as completed in the planning document
-

package/planning/streams/02-create-factory-api.md

@@ -1,65 +0,0 @@
-# Задача 2: Создание фабричной функции и удобного API
-
-## Цель
-Создать удобный API для работы с MD5 потоками через фабричные функции и упрощенные методы.
-
-## Требования к реализации
-1. **SRP**: Функции должны предоставлять простой интерфейс без внутренней логики
-2. **Удобство использования**: API должен быть интуитивно понятен
-3. **Гибкость**: Поддержка различных сценариев использования
-
-## Детали реализации
-- Фабричная функция `createMD5Stream()` для создания экземпляров
-- Метод `pipeThroughMD5()` для удобной интеграции в цепочки pipe
-- Статический метод `MD5Stream.fromStream()` для создания из существующего потока
-- Экспорт всех необходимых компонентов
-
-## Критерии выполнения
-- [x] Создана фабричная функция `createMD5Stream()` в `src/stream/index.js`
-- [x] Реализован метод `pipeThroughMD5()` для обертки потоков
-- [x] Добавлен статический метод `MD5Stream.fromStream()`
-- [x] Экспортированы все публичные API в основном экспорте
-- [x] Написаны примеры использования в документации
-- [x] Добавлены тесты для фабричных функций
-
-## Прогресс выполнения
-- [x] Начало работы
-- [x] Фабричные функции созданы
-- [x] API документирован
-- [x] Тесты написаны
-- [x] Код проверен на соответствие SRP
-- [x] Задача завершена
-
-## Реализовано
-
-### Фабричные функции
-- ✅ `createMD5Stream()` - создание экземпляра MD5Stream
-- ✅ `fromStream()` - создание stream из существующего readable stream
-- ✅ `MD5Stream.fromStream()` - статический метод класса
-
-### Методы и утилиты
-- ✅ `pipeThroughMD5()` - удобная обертка для pipe
-- ✅ `hashFile()` - хэширование файла по пути
-- ✅ `hashFileDigest()` - хэширование с возвратом только digest
-- ✅ `hashFileStream()` - хэширование потока
-- ✅ `hashFileSync()` - синхронное хэширование
-- ✅ `verifyFile()` - проверка целостности файла
-- ✅ `createProgressTracker()` - отслеживание прогресса
-
-### Документация
-- ✅ Примеры использования в README.md
-- ✅ Комментарии JSDoc в коде
-- ✅ Примеры для всех функций
-
-### Тесты
-- ✅ Тесты `createMD5Stream()`
-- ✅ Тесты `pipeThroughMD5()`
-- ✅ Тесты `fromStream()`
-- ✅ Тесты `MD5Stream.fromStream()`
-- ✅ Тесты файловых утилит
-
-## Примечания для агента
-- API должен быть согласован с существующим интерфейсом библиотеки
-- Функции должны быть чистыми и не иметь побочных эффектов
-- Учесть различные сценарии использования (файлы, HTTP, пользовательские потоки)
-- Отметить прогресс в чеклисте выше

package/planning/streams/03-fs-integration.md

@@ -1,37 +0,0 @@
-# Задача 3: Интеграция с файловой системой Node.js
-
-## Цель
-Создать удобные утилиты для хэширования файлов через потоки файловой системы.
-
-## Требования к реализации
-1. **SRP**: Утилиты должны отвечать только за работу с файловой системой
-2. **Эффективность**: Минимальное использование памяти при работе с большими файлами
-3. **Обработка ошибок**: Корректная обработка ошибок файловой системы
-
-## Детали реализации
-- Функция `hashFile(filePath)` для хэширования файла по пути
-- Функция `hashFileStream(readStream)` для хэширования существующего потока
-- Поддержка прогресса хэширования (опционально)
-- Обработка ошибок чтения файлов
-
-## Критерии выполнения
-- [ ] Создана функция `hashFile()` в `src/stream/fs-utils.js`
-- [ ] Создана функция `hashFileStream()`
-- [ ] Реализована обработка ошибок файловой системы
-- [ ] Добавлена опциональная поддержка прогресса
-- [ ] Написаны тесты с реальными файлами
-- [ ] Добавлены примеры использования
-
-## Прогресс выполнения
-- [ ] Начало работы
-- [ ] Функции созданы
-- [ ] Обработка ошибок реализована
-- [ ] Тесты написаны
-- [ ] Код проверен на соответствие SRP
-- [ ] Задача завершена
-
-## Примечания для агента
-- Использовать `fs.createReadStream` для эффективного чтения
-- Учесть различные кодировки и типы файлов
-- Обеспечить корректное освобождение ресурсов
-- Отметить прогресс в чеклисте выше

package/planning/streams/04-whatwg-streams-support.md

@@ -1,37 +0,0 @@
-# Задача 4: Поддержка WHATWG Streams для браузеров
-
-## Цель
-Добавить поддержку браузерных потоков (WHATWG Streams) для использования в веб-приложениях.
-
-## Требования к реализации
-1. **SRP**: Отдельная реализация для браузерных потоков
-2. **Совместимость**: Работа с современными браузерами
-3. **Производительность**: Эффективная работа в браузерной среде
-
-## Детали реализации
-- Класс `MD5ReadableStream` для работы с WHATWG Streams
-- Функция `hashReadableStream()` для хэширования существующих потоков
-- Поддержка `ReadableStream`, `File`, `Blob` объектов
-- Адаптер для конвертации между Node.js и WHATWG потоками
-
-## Критерии выполнения
-- [ ] Создан класс `MD5ReadableStream` в `src/stream/whatwg-stream.js`
-- [ ] Реализована функция `hashReadableStream()`
-- [ ] Добавлена поддержка `File` и `Blob` объектов
-- [ ] Создан адаптер для конвертации потоков
-- [ ] Написаны тесты для браузерной среды
-- [ ] Добавлена документация по использованию
-
-## Прогресс выполнения
-- [ ] Начало работы
-- [ ] WHATWG Streams поддержка реализована
-- [ ] Адаптеры созданы
-- [ ] Тесты написаны
-- [ ] Код проверен на соответствие SRP
-- [ ] Задача завершена
-
-## Примечания для агента
-- Учесть различия между Node.js и WHATWG Streams API
-- Обеспечить кросс-браузерную совместимость
-- Минимизировать размер кода для браузерной сборки
-- Отметить прогресс в чеклисте выше