claude-flow 1.0.0

package/src/utils/helpers.ts

@@ -0,0 +1,476 @@
+/**
+ * Utility helper functions for Claude-Flow
+ */
+
+// Utility helper functions
+
+/**
+ * Generates a unique identifier
+ */
+export function generateId(prefix?: string): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substr(2, 9);
+  return prefix ? `${prefix}_${timestamp}_${random}` : `${timestamp}_${random}`;
+}
+
+/**
+ * Creates a timeout promise that rejects after the specified time
+ */
+export function timeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let completed = false;
+  
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      if (!completed) {
+        completed = true;
+        reject(new Error(message || 'Operation timed out'));
+      }
+    }, ms);
+  });
+
+  const wrappedPromise = promise.then((result) => {
+    completed = true;
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+    return result;
+  }, (error) => {
+    completed = true;
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+    throw error;
+  });
+
+  return Promise.race([
+    wrappedPromise,
+    timeoutPromise,
+  ]);
+}
+
+/**
+ * Delays execution for specified milliseconds
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retries a function with exponential backoff
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    factor?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+  } = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelay = 1000,
+    maxDelay = 30000,
+    factor = 2,
+    onRetry,
+  } = options;
+
+  let lastError: Error;
+  let delayMs = initialDelay;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt === maxAttempts) {
+        throw lastError;
+      }
+
+      if (onRetry) {
+        onRetry(attempt, lastError);
+      }
+
+      await delay(Math.min(delayMs, maxDelay));
+      delayMs *= factor;
+    }
+  }
+
+  throw lastError!;
+}
+
+/**
+ * Debounces a function
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  delayMs: number,
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  return (...args: Parameters<T>) => {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      fn(...args);
+      timeoutId = undefined;
+    }, delayMs);
+  };
+}
+
+/**
+ * Throttles a function
+ */
+export function throttle<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  limitMs: number,
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+  let lastArgs: Parameters<T> | null = null;
+
+  return (...args: Parameters<T>) => {
+    if (!inThrottle) {
+      fn(...args);
+      inThrottle = true;
+
+      setTimeout(() => {
+        inThrottle = false;
+        if (lastArgs !== null) {
+          fn(...lastArgs);
+          lastArgs = null;
+        }
+      }, limitMs);
+    } else {
+      lastArgs = args;
+    }
+  };
+}
+
+/**
+ * Deep clones an object
+ */
+export function deepClone<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  if (obj instanceof Array) {
+    return obj.map((item) => deepClone(item)) as T;
+  }
+
+  if (obj instanceof Map) {
+    const map = new Map();
+    obj.forEach((value, key) => {
+      map.set(key, deepClone(value));
+    });
+    return map as T;
+  }
+
+  if (obj instanceof Set) {
+    const set = new Set();
+    obj.forEach((value) => {
+      set.add(deepClone(value));
+    });
+    return set as T;
+  }
+
+  const cloned = {} as T;
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      cloned[key] = deepClone(obj[key]);
+    }
+  }
+
+  return cloned;
+}
+
+/**
+ * Merges multiple objects deeply
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: Partial<T>[]
+): T {
+  // Create a deep clone of the target to avoid mutation
+  const result = deepClone(target);
+  
+  if (!sources.length) return result;
+
+  const source = sources.shift();
+  if (!source) return result;
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key];
+      const resultValue = result[key];
+
+      if (isObject(resultValue) && isObject(sourceValue)) {
+        result[key] = deepMerge(
+          resultValue as Record<string, unknown>,
+          sourceValue as Record<string, unknown>,
+        ) as T[Extract<keyof T, string>];
+      } else {
+        result[key] = sourceValue as T[Extract<keyof T, string>];
+      }
+    }
+  }
+
+  return deepMerge(result, ...sources);
+}
+
+/**
+ * Checks if a value is a plain object
+ */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Creates a typed event emitter
+ */
+export class TypedEventEmitter<T extends Record<string, unknown>> {
+  private listeners = new Map<keyof T, Set<(data: unknown) => void>>();
+
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler as (data: unknown) => void);
+  }
+
+  off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.delete(handler as (data: unknown) => void);
+    }
+  }
+
+  emit<K extends keyof T>(event: K, data: T[K]): void {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => handler(data));
+    }
+  }
+
+  once<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
+    const onceHandler = (data: T[K]) => {
+      handler(data);
+      this.off(event, onceHandler);
+    };
+    this.on(event, onceHandler);
+  }
+
+  removeAllListeners(event?: keyof T): void {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+}
+
+/**
+ * Formats bytes to human-readable string
+ */
+export function formatBytes(bytes: number, decimals = 2): string {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+
+  // Handle negative numbers
+  const absBytes = Math.abs(bytes);
+  const i = Math.floor(Math.log(absBytes) / Math.log(k));
+
+  const value = parseFloat((absBytes / Math.pow(k, i)).toFixed(dm));
+  const sign = bytes < 0 ? '-' : '';
+  
+  return sign + value + ' ' + sizes[i];
+}
+
+/**
+ * Parses duration string to milliseconds
+ */
+export function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)(ms|s|m|h|d)$/);
+  if (!match) {
+    throw new Error(`Invalid duration format: ${duration}`);
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case 'ms':
+      return value;
+    case 's':
+      return value * 1000;
+    case 'm':
+      return value * 60 * 1000;
+    case 'h':
+      return value * 60 * 60 * 1000;
+    case 'd':
+      return value * 24 * 60 * 60 * 1000;
+    default:
+      throw new Error(`Unknown duration unit: ${unit}`);
+  }
+}
+
+/**
+ * Ensures a value is an array
+ */
+export function ensureArray<T>(value: T | T[]): T[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Groups an array by a key function
+ */
+export function groupBy<T, K extends string | number | symbol>(
+  items: T[],
+  keyFn: (item: T) => K,
+): Record<K, T[]> {
+  return items.reduce((groups, item) => {
+    const key = keyFn(item);
+    if (!groups[key]) {
+      groups[key] = [];
+    }
+    groups[key].push(item);
+    return groups;
+  }, {} as Record<K, T[]>);
+}
+
+/**
+ * Creates a promise that can be resolved/rejected externally
+ */
+export function createDeferred<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve: (value: T) => void;
+  let reject: (reason?: unknown) => void;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return { promise, resolve: resolve!, reject: reject! };
+}
+
+/**
+ * Safely parses JSON with error handling
+ */
+export function safeParseJSON<T>(json: string, fallback?: T): T | undefined {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+
+/**
+ * Circuit breaker state
+ */
+export interface CircuitBreakerState {
+  failureCount: number;
+  lastFailureTime: number;
+  state: 'closed' | 'open' | 'half-open';
+}
+
+/**
+ * Circuit breaker options
+ */
+export interface CircuitBreakerOptions {
+  threshold: number;
+  timeout: number;
+  resetTimeout: number;
+}
+
+/**
+ * Circuit breaker interface
+ */
+export interface CircuitBreaker {
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  getState(): CircuitBreakerState;
+  reset(): void;
+}
+
+/**
+ * Creates a circuit breaker
+ */
+export function circuitBreaker(
+  name: string,
+  options: CircuitBreakerOptions,
+): CircuitBreaker {
+  const state: CircuitBreakerState = {
+    failureCount: 0,
+    lastFailureTime: 0,
+    state: 'closed',
+  };
+
+  const isOpen = (): boolean => {
+    if (state.state === 'open') {
+      const now = Date.now();
+      if (now - state.lastFailureTime >= options.resetTimeout) {
+        state.state = 'half-open';
+        return false;
+      }
+      return true;
+    }
+    return false;
+  };
+
+  const recordSuccess = (): void => {
+    state.failureCount = 0;
+    state.state = 'closed';
+  };
+
+  const recordFailure = (): void => {
+    state.failureCount++;
+    state.lastFailureTime = Date.now();
+    
+    if (state.failureCount >= options.threshold) {
+      state.state = 'open';
+    }
+  };
+
+  return {
+    async execute<T>(fn: () => Promise<T>): Promise<T> {
+      if (isOpen()) {
+        throw new Error(`Circuit breaker ${name} is open`);
+      }
+
+      try {
+        const result = await timeout(fn(), options.timeout);
+        recordSuccess();
+        return result;
+      } catch (error) {
+        recordFailure();
+        throw error;
+      }
+    },
+
+    getState(): CircuitBreakerState {
+      return { ...state };
+    },
+
+    reset(): void {
+      state.failureCount = 0;
+      state.lastFailureTime = 0;
+      state.state = 'closed';
+    },
+  };
+}