pure-md5 0.2.0 → 0.2.1

package/planning/04-adapter-backend/09-adapter-unified.md

@@ -1,255 +0,0 @@
-# Task 09: Creating Unified Adapter with Unified Interface
-
-## Goal
-
-Создать unified adapter, который объединяет все backend'ы и предоставляет единый API для пользователей.
-
-## Implementation
-
-### 1. Создать файл src/adapters/unified.ts
-
-```typescript
-import { PureJSBackend } from './pure-js.js';
-import { WebCryptoBackend } from './web-crypto.js';
-import { NodeCryptoBackend } from './node-crypto.js';
-import { IE11Backend } from './ie11.js';
-import { detector } from '../detection/backend-detector.js';
-
-export interface MD5AdapterOptions {
-  backend?: string;
-  fallback?: boolean;
-  reportFallback?: boolean;
-}
-
-export class MD5Adapter {
-  private backend: any | null = null;
-  private backendName: string | null = null;
-  private options: MD5AdapterOptions;
-  
-  constructor(options: MD5AdapterOptions = {}) {
-    this.options = {
-      fallback: true,
-      reportFallback: false,
-      ...options
-    };
-  }
-  
-  /**
-   * Hash string data with automatic backend selection or specified backend
-   */
-  async hash(data: string, options?: { backend?: string }): Promise<string> {
-    const backend = await this.getBackend(options?.backend);
-    return backend.hash(data);
-  }
-  
-  /**
-   * Hash binary data (ArrayBuffer, Uint8Array)
-   */
-  async hashBinary(data: ArrayBuffer | Uint8Array, options?: { backend?: string }): Promise<string> {
-    const backend = await this.getBackend(options?.backend);
-    return backend.hashBinary(data);
-  }
-  
-  /**
-   * Update hash with additional data (streaming)
-   */
-  async update(data: string | ArrayBuffer | Uint8Array, options?: { backend?: string }): Promise<void> {
-    const backend = await this.getBackend(options?.backend);
-    backend.update(data);
-  }
-  
-  /**
-   * Get final hash digest (for streaming)
-   */
-  async digest(encoding: 'hex' | 'buffer' = 'hex', options?: { backend?: string }): Promise<string | Uint8Array> {
-    const backend = await this.getBackend(options?.backend);
-    return backend.digest(encoding);
-  }
-  
-  /**
-   * Reset the hash state
-   */
-  async reset(options?: { backend?: string }): Promise<void> {
-    const backend = await this.getBackend(options?.backend);
-    backend.reset();
-  }
-  
-  /**
-   * Get backend name
-   */
-  async getBackendName(): Promise<string> {
-    if (!this.backendName) {
-      const result = await detector.detect();
-      this.backendName = result.backend;
-    }
-    return this.backendName;
-  }
-  
-  /**
-   * Check if specific backend is available
-   */
-  static async isAvailable(backend: string): Promise<boolean> {
-    const { checkBackendAvailability } = await import('./backend-availability.js');
-    const result = await checkBackendAvailability(backend);
-    return result.available;
-  }
-  
-  /**
-   * Get list of available backends
-   */
-  static async getAvailableBackends(): Promise<string[]> {
-    const { getAllAvailableBackends } = await import('./backend-availability.js');
-    return getAllAvailableBackends();
-  }
-  
-  /**
-   * Force specific backend for all operations
-   */
-  async useBackend(backendName: string): Promise<void> {
-    this.backend = await detector.createBackendByName(backendName);
-    this.backendName = backendName;
-  }
-  
-  /**
-   * Reset to automatic backend selection
-   */
-  async resetBackend(): Promise<void> {
-    this.backend = null;
-    this.backendName = null;
-  }
-  
-  /**
-   * Get backend instance (lazy initialization)
-   */
-  private async getBackend(overrideBackend?: string): Promise<any> {
-    if (overrideBackend) {
-      return await detector.createBackendByName(overrideBackend);
-    }
-    
-    if (this.backend) {
-      return this.backend;
-    }
-    
-    this.backend = await detector.createBackend();
-    this.backendName = await detector.getBackendName();
-    return this.backend;
-  }
-}
-
-export const md5 = new MD5Adapter();
-```
-
-### 2. Integration с основным API
-
-В `src/index.ts` обновить экспорт:
-
-```typescript
-export { md5 } from './adapters/unified.js';
-
-// Also keep original export
-export { default as pureMD5 } from './md51.js';
-
-// Export backend-related utilities
-export { detector } from './detection/backend-detector.js';
-export { BackendDetector } from './detection/backend-detector.js';
-```
-
-### 3. Упрощенный API для простых случаев
-
-Создать файл `src/index-simple.ts`:
-
-```typescript
-import { md5 } from './adapters/unified.js';
-
-/**
- * Simple MD5 hashing function
- * @param data - String to hash
- * @returns MD5 hash as hex string
- */
-export async function hash(data: string): Promise<string> {
-  return md5.hash(data);
-}
-
-/**
- * Hash with specific backend
- */
-export async function hashWithBackend(data: string, backend: string): Promise<string> {
-  return md5.hash(data, { backend });
-}
-```
-
-### 4. Tests
-
-Создать файл `__tests__/adapters/unified.test.ts`:
-
-```typescript
-describe('MD5Adapter', () => {
-  let adapter: MD5Adapter;
-  
-  beforeAll(() => {
-    adapter = new MD5Adapter();
-  });
-  
-  it('should hash string with automatic backend', async () => {
-    const result = await adapter.hash('hello');
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should hash with specific backend', async () => {
-    const result = await adapter.hash('hello', { backend: 'purejs' });
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should hash binary data', async () => {
-    const data = new Uint8Array([104, 101, 108, 108, 111]); // "hello"
-    const result = await adapter.hashBinary(data);
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should support streaming', async () => {
-    await adapter.update('he');
-    await adapter.update('l');
-    await adapter.update('lo');
-    const result = await adapter.digest('hex');
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should reset state', async () => {
-    await adapter.update('hello');
-    await adapter.reset();
-    await adapter.update('world');
-    const result = await adapter.digest('hex');
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should get backend name', async () => {
-    const name = await adapter.getBackendName();
-    expect(typeof name).toBe('string');
-  });
-  
-  it('should force specific backend', async () => {
-    await adapter.useBackend('purejs');
-    const backendName = await adapter.getBackendName();
-    expect(backendName).toBe('purejs');
-  });
-  
-  it('should get available backends', async () => {
-    const backends = await MD5Adapter.getAvailableBackends();
-    expect(Array.isArray(backends)).toBe(true);
-    expect(backends.length).toBeGreaterThan(0);
-  });
-});
-```
-
-### 5. Documentation
-
-Добавить JSDoc комментарии для всех публичных методов и классов.
-
-## Ожидаемый результат
-
-- ✅ Unified adapter реализован
-- ✅ Единый API для всех backend'ов
-- ✅ Support автоматического и принудительного выбора backend
-- ✅ Tests проходят успешно
-- ✅ Интегрирован в основной API
-- ✅ Documentation создана

package/planning/04-adapter-backend/10-fallback-mechanism.md

@@ -1,333 +0,0 @@
-# Task 10: Fallback Mechanisms Implementation with Priority Order
-
-## Goal
-
-Implement fallback механизм, который автоматически пробует альтернативные backend'ы при ошибке основного.
-
-## Implementation
-
-### 1. Создать файл src/adapters/fallback.ts
-
-```typescript
-import { PureJSBackend } from './pure-js.js';
-import { WebCryptoBackend } from './web-crypto.js';
-import { NodeCryptoBackend } from './node-crypto.js';
-import { IE11Backend } from './ie11.js';
-import { BackendDetector } from '../detection/backend-detector.js';
-
-export interface FallbackResult<T> {
-  success: boolean;
-  backend: string;
-  data: T;
-  errors?: { backend: string; error: Error }[];
-}
-
-export class FallbackManager {
-  private detector: BackendDetector;
-  private fallbackOrder: string[];
-  
-  constructor(fallbackOrder: string[] = ['nodecrypto', 'webcrypto', 'ie11', 'purejs']) {
-    this.detector = new BackendDetector();
-    this.fallbackOrder = fallbackOrder;
-  }
-  
-  /**
-   * Execute operation with fallback mechanism
-   */
-  async execute<T>(operation: (backend: any) => Promise<T>): Promise<FallbackResult<T>> {
-    const errors: { backend: string; error: Error }[] = [];
-    
-    for (const backendName of this.fallbackOrder) {
-      try {
-        const backend = await this.detector.createBackendByName(backendName);
-        const result = await operation(backend);
-        return {
-          success: true,
-          backend: backendName,
-          data: result
-        };
-      } catch (error) {
-        errors.push({ backend: backendName, error: error as Error });
-        
-        // Don't fallback if last backend failed
-        if (backendName === this.fallbackOrder[this.fallbackOrder.length - 1]) {
-          return {
-            success: false,
-            backend: backendName,
-            data: null as unknown as T,
-            errors
-          };
-        }
-      }
-    }
-    
-    return {
-      success: false,
-      backend: '',
-      data: null as unknown as T,
-      errors
-    };
-  }
-  
-  /**
-   * Hash with fallback mechanism
-   */
-  async hash(data: string): Promise<FallbackResult<string>> {
-    return this.execute(async (backend) => backend.hash(data));
-  }
-  
-  /**
-   * Hash binary data with fallback
-   */
-  async hashBinary(data: ArrayBuffer | Uint8Array): Promise<FallbackResult<string>> {
-    return this.execute(async (backend) => backend.hashBinary(data));
-  }
-  
-  /**
-   * Get the best available backend
-   */
-  async getBestBackend(): Promise<string> {
-    const available = await this.getAvailableBackends();
-    if (available.length === 0) {
-      return 'purejs'; // Fallback
-    }
-    return available[0]; // First is best
-  }
-  
-  /**
-   * Get available backends in priority order
-   */
-  async getAvailableBackends(): Promise<string[]> {
-    const available: string[] = [];
-    
-    for (const backendName of this.fallbackOrder) {
-      try {
-        const backend = await this.detector.createBackendByName(backendName);
-        available.push(backendName);
-      } catch {
-        // Backend not available
-      }
-    }
-    
-    return available;
-  }
-  
-  /**
-   * Get backend metrics for monitoring
-   */
-  getMetrics(): Record<string, { success: number; fail: number }> {
-    // Implementation for tracking usage
-    return {};
-  }
-}
-
-export const fallbackManager = new FallbackManager();
-```
-
-### 2. Integration с unified adapter
-
-Обновить `src/adapters/unified.ts`:
-
-```typescript
-import { FallbackManager, fallbackManager } from './fallback.js';
-
-export class MD5Adapter {
-  private fallbackManager: FallbackManager;
-  
-  constructor(options: MD5AdapterOptions = {}) {
-    this.fallbackManager = options.fallback !== false 
-      ? new FallbackManager() 
-      : null;
-  }
-  
-  async hash(data: string, options?: { backend?: string }): Promise<string> {
-    if (options?.backend) {
-      const backend = await this.getBackend(options.backend);
-      return backend.hash(data);
-    }
-    
-    // Use fallback if enabled
-    if (this.fallbackManager) {
-      const result = await this.fallbackManager.hash(data);
-      if (result.success) {
-        return result.data;
-      }
-      throw new Error(`MD5 hash failed: ${result.errors.map(e => e.error.message).join(', ')}`);
-    }
-    
-    const backend = await this.getBackend();
-    return backend.hash(data);
-  }
-  
-  // ... остальные методы с fallback
-}
-```
-
-### 3. Робастная функция хэширования
-
-Создать файл `src/adapters/robust.ts`:
-
-```typescript
-import { FallbackManager } from './fallback.js';
-
-export async function robustHash(
-  data: string,
-  options: { 
-    fallback?: boolean;
-    reportFallback?: boolean;
-    forceBackend?: string;
-  } = {}
-): Promise<string> {
-  const fallbackManager = new FallbackManager();
-  
-  if (options.forceBackend) {
-    // Use specific backend without fallback
-    const backend = await fallbackManager.detector.createBackendByName(options.forceBackend);
-    return backend.hash(data);
-  }
-  
-  if (options.fallback === false) {
-    // Use default backend without fallback
-    const backend = await fallbackManager.detector.createBackend();
-    return backend.hash(data);
-  }
-  
-  // Use fallback
-  const result = await fallbackManager.hash(data);
-  
-  if (result.success) {
-    if (options.reportFallback && result.backend !== 'nodecrypto' && result.backend !== 'webcrypto') {
-      console.info(`MD5 used fallback backend: ${result.backend}`);
-    }
-    return result.data;
-  }
-  
-  // All backends failed
-  const errorMessage = result.errors 
-    ? result.errors.map(e => `${e.backend}: ${e.error.message}`).join(', ')
-    : 'All backends failed';
-  
-  throw new Error(`MD5 hash failed after all attempts: ${errorMessage}`);
-}
-```
-
-### 4. Мониторинг fallback механизмов
-
-Создать файл `src/adapters/metrics.ts`:
-
-```typescript
-interface BackendMetrics {
-  success: number;
-  fail: number;
-}
-
-export class MetricsCollector {
-  private metrics: Record<string, BackendMetrics> = {
-    nodecrypto: { success: 0, fail: 0 },
-    webcrypto: { success: 0, fail: 0 },
-    ie11: { success: 0, fail: 0 },
-    purejs: { success: 0, fail: 0 }
-  };
-  
-  recordSuccess(backend: string): void {
-    if (this.metrics[backend]) {
-      this.metrics[backend].success++;
-    }
-  }
-  
-  recordFail(backend: string): void {
-    if (this.metrics[backend]) {
-      this.metrics[backend].fail++;
-    }
-  }
-  
-  getMetrics(): Record<string, BackendMetrics> {
-    return this.metrics;
-  }
-  
-  getSummary(): string {
-    const total = Object.values(this.metrics).reduce(
-      (sum, m) => sum + m.success + m.fail, 
-      0
-    );
-    
-    return `Total operations: ${total}\n` +
-      Object.entries(this.metrics)
-        .map(([backend, m]) => 
-          `${backend}: ${m.success} success, ${m.fail} fail`
-        )
-        .join('\n');
-  }
-  
-  reset(): void {
-    Object.keys(this.metrics).forEach(key => {
-      this.metrics[key] = { success: 0, fail: 0 };
-    });
-  }
-}
-
-export const metrics = new MetricsCollector();
-```
-
-### 5. Tests
-
-Создать файл `__tests__/adapters/fallback.test.ts`:
-
-```typescript
-describe('FallbackManager', () => {
-  let manager: FallbackManager;
-  
-  beforeAll(() => {
-    manager = new FallbackManager();
-  });
-  
-  it('should hash with fallback', async () => {
-    const result = await manager.hash('hello');
-    expect(result.success).toBe(true);
-    expect(result.data).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should get best backend', async () => {
-    const best = await manager.getBestBackend();
-    expect(typeof best).toBe('string');
-  });
-  
-  it('should get available backends', async () => {
-    const available = await manager.getAvailableBackends();
-    expect(Array.isArray(available)).toBe(true);
-    expect(available.length).toBeGreaterThan(0);
-  });
-  
-  it('should execute operation with fallback', async () => {
-    const result = await manager.execute(async (backend) => backend.hash('test'));
-    expect(result.success).toBe(true);
-  });
-  
-  describe('Robust hash', () => {
-    it('should hash with fallback', async () => {
-      const result = await robustHash('hello');
-      expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-    });
-    
-    it('should hash with force backend', async () => {
-      const result = await robustHash('hello', { forceBackend: 'purejs' });
-      expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-    });
-    
-    it('should throw on all backends failure', async () => {
-      // This test requires mocking all backends to fail
-      // In practice, this should never happen
-      await expect(robustHash('test')).resolves.toBeDefined();
-    });
-  });
-});
-```
-
-## Ожидаемый результат
-
-- ✅ Fallback mechanism реализован
-- ✅ Автоматический retry с другими backend'ами
-- ✅ Мониторинг и метрики
-- ✅ Робастная функция robustHash
-- ✅ Tests проходят успешно
-- ✅ Documentation создана