pure-md5 0.2.0 → 0.2.2

package/planning/04-adapter-backend/06-backend-ie11.md

@@ -1,158 +0,0 @@
-# Task 06: Support for Internet Explorer 11 (msCrypto)
-
-## Goal
-
-Создать адаптер для использования устаревшего `window.msCrypto` в Internet Explorer 11.
-
-## Важные замечания
-
-- IE11 поддерживает только подмножество Web Crypto API
-- Некоторые алгоритмы могут отличаться
-- Проверить совместимость с MD5
-
-## Implementation
-
-### 1. Создать файл src/adapters/ie11.ts
-
-```typescript
-export class IE11Backend implements MD5Backend {
-  static name = 'ie11';
-  static version = '1.0.0';
-  
-  private crypto: Crypto;
-  private algorithm: string = 'MD5';
-  
-  constructor() {
-    if (!this.isAvailable()) {
-      throw new Error('IE11 Crypto is not available');
-    }
-    this.crypto = (window as any).msCrypto;
-  }
-  
-  async hash(data: string): Promise<string> {
-    const encoder = new TextEncoder();
-    const buffer = encoder.encode(data);
-    const hashBuffer = await this.crypto.subtle.digest(this.algorithm, buffer);
-    return this.bufferToHex(hashBuffer);
-  }
-  
-  async hashBinary(data: ArrayBuffer | Uint8Array): Promise<string> {
-    const buffer = data instanceof Uint8Array 
-      ? data.buffer 
-      : data;
-    const hashBuffer = await this.crypto.subtle.digest(this.algorithm, buffer);
-    return this.bufferToHex(hashBuffer);
-  }
-  
-  static async isAvailable(): Promise<boolean> {
-    if (typeof window === 'undefined') {
-      return false;
-    }
-    
-    const msCrypto = (window as any).msCrypto;
-    if (!msCrypto) {
-      return false;
-    }
-    
-    if (!msCrypto.subtle) {
-      return false;
-    }
-    
-    try {
-      // Checking поддержки MD5
-      const testBuffer = new Uint8Array([1, 2, 3, 4]);
-      await msCrypto.subtle.digest('MD5', testBuffer);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  
-  private bufferToHex(buffer: ArrayBuffer): string {
-    const bytes = new Uint8Array(buffer);
-    return Array.from(bytes)
-      .map(b => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-}
-```
-
-### 2. Tests
-
-Создать файл `__tests__/adapters/ie11.test.ts`:
-
-```typescript
-describe('IE11Backend', () => {
-  let backend: IE11Backend;
-  
-  beforeAll(async () => {
-    if (!await IE11Backend.isAvailable()) {
-      console.log('IE11 Crypto not available, skipping tests');
-      return;
-    }
-    backend = new IE11Backend();
-  });
-  
-  it('should hash string correctly', async () => {
-    const result = await backend.hash('hello');
-    expect(result).toBe('5d41402abc4b2a76b9719d911017c592');
-  });
-  
-  it('should hash empty string', async () => {
-    const result = await backend.hash('');
-    expect(result).toBe('d41d8cd98f00b204e9800998ecf8427e');
-  });
-  
-  it('should be available in IE11', async () => {
-    const available = await IE11Backend.isAvailable();
-    // В реальных тестах этот тест будет пропущен в modern browsers
-    if (available) {
-      expect(true).toBe(true);
-    }
-  });
-});
-```
-
-### 3. Integration
-
-В `src/adapters/index.ts`:
-
-```typescript
-export { IE11Backend } from './ie11.js';
-```
-
-### 4. Conditional exports
-
-В `package.json`:
-
-```json
-{
-  "exports": {
-    "./adapters/ie11": {
-      "types": "./dist/adapters/ie11.d.ts",
-      "import": "./dist/adapters/ie11.js"
-    }
-  }
-}
-```
-
-### 5. Обработка ошибок
-
-В IE11 могут возникнуть ошибки, поэтому обернуть в try-catch:
-
-```typescript
-try {
-  const backend = new IE11Backend();
-  const result = await backend.hash('data');
-} catch (error) {
-  console.warn('IE11 backend failed:', error);
-  // Fallback to pure JS
-}
-```
-
-## Ожидаемый результат
-
-- ✅ IE11Backend реализован
-- ✅ Tests проходят успешно (если IE11 доступен)
-- ✅ Интегрирован в общую систему адаптеров
-- ✅ Обработка ошибок при отсутствии поддержки

package/planning/04-adapter-backend/07-detection-environment.md

@@ -1,232 +0,0 @@
-# Task 07: Environment Detection and Available Backends Implementation
-
-## Goal
-
-Создать систему обнаружения окружения (браузер, Node.js) и проверки доступности backend'ов.
-
-## Implementation
-
-### 1. Создать файл src/detection/environment.ts
-
-```typescript
-export enum RuntimeEnvironment {
-  BROWSER = 'browser',
-  NODE = 'node',
-  WEBWORKER = 'webworker',
-  UNKNOWN = 'unknown'
-}
-
-export function detectEnvironment(): RuntimeEnvironment {
-  // Check Node.js environment
-  if (typeof process !== 'undefined' && process.versions && process.versions.node) {
-    return RuntimeEnvironment.NODE;
-  }
-  
-  // Check web worker
-  if (typeof importScripts !== 'undefined') {
-    return RuntimeEnvironment.WEBWORKER;
-  }
-  
-  // Check browser
-  if (typeof window !== 'undefined' && window.document) {
-    return RuntimeEnvironment.BROWSER;
-  }
-  
-  return RuntimeEnvironment.UNKNOWN;
-}
-
-export function isNode(): boolean {
-  return typeof process !== 'undefined' && 
-         process.versions !== undefined && 
-         'node' in process.versions;
-}
-
-export function isBrowser(): boolean {
-  return typeof window !== 'undefined' && 
-         typeof document !== 'undefined';
-}
-
-export function isWebWorker(): boolean {
-  return typeof importScripts !== 'undefined';
-}
-```
-
-### 2. Checking конкретных backend'ов
-
-Создать файл `src/detection/backend-availability.ts`:
-
-```typescript
-import { PureJSBackend } from '../adapters/pure-js.js';
-import { WebCryptoBackend } from '../adapters/web-crypto.js';
-import { NodeCryptoBackend } from '../adapters/node-crypto.js';
-import { IE11Backend } from '../adapters/ie11.js';
-
-export interface BackendAvailability {
-  backend: string;
-  available: boolean;
-  reason?: string;
-}
-
-export async function checkBackendAvailability(backend: string): Promise<BackendAvailability> {
-  switch (backend) {
-    case 'webcrypto':
-      const webCryptoAvailable = await WebCryptoBackend.isAvailable();
-      return {
-        backend: 'webcrypto',
-        available: webCryptoAvailable,
-        reason: webCryptoAvailable ? undefined : 'Web Crypto API not available'
-      };
-    
-    case 'nodecrypto':
-      const nodeCryptoAvailable = NodeCryptoBackend.isAvailable();
-      return {
-        backend: 'nodecrypto',
-        available: nodeCryptoAvailable,
-        reason: nodeCryptoAvailable ? undefined : 'Node.js crypto not available'
-      };
-    
-    case 'ie11':
-      const ie11Available = await IE11Backend.isAvailable();
-      return {
-        backend: 'ie11',
-        available: ie11Available,
-        reason: ie11Available ? undefined : 'IE11 msCrypto not available'
-      };
-    
-    case 'purejs':
-      return {
-        backend: 'purejs',
-        available: PureJSBackend.isAvailable(),
-        reason: 'Always available'
-      };
-    
-    default:
-      return {
-        backend,
-        available: false,
-        reason: 'Unknown backend'
-      };
-  }
-}
-
-export async function getAllAvailableBackends(): Promise<string[]> {
-  const backends = ['webcrypto', 'nodecrypto', 'ie11', 'purejs'];
-  const available: string[] = [];
-  
-  for (const backend of backends) {
-    const { available: isAvailable } = await checkBackendAvailability(backend);
-    if (isAvailable) {
-      available.push(backend);
-    }
-  }
-  
-  return available;
-}
-```
-
-### 3. Rating backend'ов по приоритету
-
-Создать файл `src/detection/backend-ranking.ts`:
-
-```typescript
-export interface BackendPriority {
-  name: string;
-  priority: number;
-  description: string;
-}
-
-export const BACKEND_PRIORITY: BackendPriority[] = [
-  {
-    name: 'nodecrypto',
-    priority: 1,
-    description: 'Node.js native crypto (fastest)'
-  },
-  {
-    name: 'webcrypto',
-    priority: 2,
-    description: 'Web Crypto API (fast, hardware accelerated)'
-  },
-  {
-    name: 'ie11',
-    priority: 3,
-    description: 'IE11 msCrypto (legacy)'
-  },
-  {
-    name: 'purejs',
-    priority: 4,
-    description: 'Pure JavaScript (always available, slower)'
-  }
-];
-
-export function getBestAvailableBackend(availableBackends: string[]): string {
-  const sortedPriority = [...BACKEND_PRIORITY].sort((a, b) => a.priority - b.priority);
-  
-  for (const { name } of sortedPriority) {
-    if (availableBackends.includes(name)) {
-      return name;
-    }
-  }
-  
-  return 'purejs'; // Fallback
-}
-```
-
-### 4. Integration с фабрикой адаптеров
-
-В `src/detection/index.ts`:
-
-```typescript
-export { detectEnvironment, isNode, isBrowser, isWebWorker, RuntimeEnvironment } from './environment.js';
-export { checkBackendAvailability, getAllAvailableBackends } from './backend-availability.js';
-export { BACKEND_PRIORITY, getBestAvailableBackend } from './backend-ranking.js';
-```
-
-### 5. Tests
-
-Создать файл `__tests__/detection/environment.test.ts`:
-
-```typescript
-describe('Environment Detection', () => {
-  it('should detect Node.js environment', () => {
-    const env = detectEnvironment();
-    expect(env).toBeDefined();
-  });
-  
-  it('should detect browser environment', () => {
-    const isBrowser = detectEnvironment() === RuntimeEnvironment.BROWSER;
-    // May be true or false depending on test environment
-    expect(typeof isBrowser).toBe('boolean');
-  });
-});
-
-describe('Backend Availability', () => {
-  it('should check pure JS availability', async () => {
-    const result = await checkBackendAvailability('purejs');
-    expect(result.available).toBe(true);
-  });
-  
-  it('should check web crypto availability', async () => {
-    const result = await checkBackendAvailability('webcrypto');
-    expect(typeof result.available).toBe('boolean');
-  });
-  
-  it('should get all available backends', async () => {
-    const backends = await getAllAvailableBackends();
-    expect(Array.isArray(backends)).toBe(true);
-    expect(backends.length).toBeGreaterThan(0);
-  });
-  
-  it('should get best available backend', async () => {
-    const available = await getAllAvailableBackends();
-    const best = getBestAvailableBackend(available);
-    expect(typeof best).toBe('string');
-  });
-});
-```
-
-## Ожидаемый результат
-
-- ✅ System обнаружения окружения реализована
-- ✅ Checking доступности backend'ов работает корректно
-- ✅ Rating backend'ов по приоритету настроен
-- ✅ Tests проходят успешно

package/planning/04-adapter-backend/08-detection-backend.md

@@ -1,210 +0,0 @@
-# Task 08: Optimal Backend Detection System Implementation
-
-## Goal
-
-Создать систему интеллектуального выбора оптимального backend'а на основе окружения и приоритетов.
-
-## Implementation
-
-### 1. Создать файл src/detection/backend-detector.ts
-
-```typescript
-import { detectEnvironment, RuntimeEnvironment } from './environment.js';
-import { checkBackendAvailability, getAllAvailableBackends } from './backend-availability.js';
-import { BACKEND_PRIORITY, getBestAvailableBackend } from './backend-ranking.js';
-import { PureJSBackend } from '../adapters/pure-js.js';
-import { WebCryptoBackend } from '../adapters/web-crypto.js';
-import { NodeCryptoBackend } from '../adapters/node-crypto.js';
-import { IE11Backend } from '../adapters/ie11.js';
-
-export interface DetectionResult {
-  backend: string;
-  environment: RuntimeEnvironment;
-  availableBackends: string[];
-  selectedBy: string;
-}
-
-export class BackendDetector {
-  private static instance: BackendDetector;
-  
-  private constructor() {}
-  
-  static getInstance(): BackendDetector {
-    if (!BackendDetector.instance) {
-      BackendDetector.instance = new BackendDetector();
-    }
-    return BackendDetector.instance;
-  }
-  
-  async detect(): Promise<DetectionResult> {
-    const environment = detectEnvironment();
-    const availableBackends = await getAllAvailableBackends();
-    const selectedBackend = getBestAvailableBackend(availableBackends);
-    
-    // Determine why this backend was selected
-    let selectedBy = 'priority';
-    if (availableBackends.length === 1) {
-      selectedBy = 'only_available';
-    } else if (selectedBackend === 'nodecrypto') {
-      selectedBy = 'fastest_available';
-    } else if (selectedBackend === 'webcrypto') {
-      selectedBy = 'fastest_available';
-    }
-    
-    return {
-      backend: selectedBackend,
-      environment,
-      availableBackends,
-      selectedBy
-    };
-  }
-  
-  async createBackend(detectedBackend?: string): Promise<any> {
-    const { backend } = detectedBackend 
-      ? { backend: detectedBackend }
-      : await this.detect();
-    
-    switch (backend) {
-      case 'nodecrypto':
-        return new NodeCryptoBackend();
-      case 'webcrypto':
-        return new WebCryptoBackend();
-      case 'ie11':
-        return new IE11Backend();
-      case 'purejs':
-      default:
-        return new PureJSBackend();
-    }
-  }
-  
-  async createBackendByName(name: string): Promise<any> {
-    switch (name) {
-      case 'nodecrypto':
-        return new NodeCryptoBackend();
-      case 'webcrypto':
-        return new WebCryptoBackend();
-      case 'ie11':
-        return new IE11Backend();
-      case 'purejs':
-      default:
-        return new PureJSBackend();
-    }
-  }
-}
-
-export const detector = BackendDetector.getInstance();
-```
-
-### 2. Упрощенная функция для быстрого использования
-
-Создать файл `src/detection/index.ts`:
-
-```typescript
-export { detectEnvironment, isNode, isBrowser, isWebWorker, RuntimeEnvironment } from './environment.js';
-export { checkBackendAvailability, getAllAvailableBackends } from './backend-availability.js';
-export { BACKEND_PRIORITY, getBestAvailableBackend } from './backend-ranking.js';
-export { BackendDetector, detector } from './backend-detector.js';
-
-// Quick access functions
-export async function detectBackend(detectedBackend?: string): Promise<any> {
-  return detector.createBackend(detectedBackend);
-}
-
-export async function getAvailableBackends(): Promise<string[]> {
-  return getAllAvailableBackends();
-}
-
-export function getBackendPriority(): string[] {
-  return BACKEND_PRIORITY.map(b => b.name);
-}
-```
-
-### 3. Integration с основным API
-
-В `src/index.ts`:
-
-```typescript
-import { detector } from './detection/backend-detector.js';
-
-export async function md5(data: string, options?: { backend?: string }): Promise<string> {
-  const backend = options?.backend 
-    ? await detector.createBackendByName(options.backend)
-    : await detector.createBackend();
-  
-  return backend.hash(data);
-}
-
-// Export backend factory
-export { detector as backendDetector } from './detection/backend-detector.js';
-```
-
-### 4. Tests
-
-Создать файл `__tests__/detection/backend-detector.test.ts`:
-
-```typescript
-describe('BackendDetector', () => {
-  let detector: BackendDetector;
-  
-  beforeAll(() => {
-    detector = BackendDetector.getInstance();
-  });
-  
-  it('should detect backend', async () => {
-    const result = await detector.detect();
-    expect(result).toBeDefined();
-    expect(result.backend).toBeDefined();
-    expect(result.environment).toBeDefined();
-    expect(result.availableBackends).toBeInstanceOf(Array);
-  });
-  
-  it('should create backend by name', async () => {
-    const backend = await detector.createBackendByName('purejs');
-    expect(backend).toBeDefined();
-    expect(typeof backend.hash).toBe('function');
-  });
-  
-  it('should create default backend', async () => {
-    const backend = await detector.createBackend();
-    expect(backend).toBeDefined();
-    expect(typeof backend.hash).toBe('function');
-  });
-  
-  it('should cache singleton instance', () => {
-    const instance1 = BackendDetector.getInstance();
-    const instance2 = BackendDetector.getInstance();
-    expect(instance1).toBe(instance2);
-  });
-  
-  it('should handle backend name override', async () => {
-    const backend = await detector.createBackendByName('purejs');
-    const result = backend.hash('test');
-    expect(result).toBeDefined();
-  });
-});
-```
-
-### 5. Documentation API
-
-Добавить JSDoc комментарии:
-
-```typescript
-/**
- * Detects the optimal backend for MD5 computation
- * @returns Promise<DetectionResult> Object containing detected backend info
- * 
- * @example
- * const result = await detector.detect();
- * console.log(result.backend); // 'nodecrypto'
- * console.log(result.environment); // 'node'
- * console.log(result.availableBackends); // ['nodecrypto', 'purejs']
- */
-```
-
-## Ожидаемый результат
-
-- ✅ BackendDetector реализован
-- ✅ Intelligent выбор backend'а работает
-- ✅ Tests проходят успешно
-- ✅ Интегрирован в основной API
-- ✅ Documentation создана