@daghis/teamcity-mcp 0.9.1 → 0.9.2

package/src/utils/async/index.ts

@@ -1,578 +0,0 @@
-/**
- * Async Utilities for TeamCity MCP Server
- *
- * This module provides standardized async patterns and utilities
- * to ensure consistent error handling, retry logic, and performance
- * monitoring across the application.
- */
-import { getLogger } from '@/utils/logger';
-
-/**
- * Retry configuration options
- */
-export interface RetryOptions {
-  /**
-   * Maximum number of retry attempts
-   */
-  maxAttempts?: number;
-
-  /**
-   * Initial delay between retries in milliseconds
-   */
-  delay?: number;
-
-  /**
-   * Backoff multiplier for exponential backoff
-   */
-  backoff?: number;
-
-  /**
-   * Maximum delay between retries in milliseconds
-   */
-  maxDelay?: number;
-
-  /**
-   * Function to determine if error should trigger retry
-   */
-  shouldRetry?: (error: unknown, attempt: number) => boolean;
-
-  /**
-   * Callback for retry attempts
-   */
-  onRetry?: (error: unknown, attempt: number) => void;
-}
-
-/**
- * Timeout configuration
- */
-export interface TimeoutOptions {
-  /**
-   * Timeout duration in milliseconds
-   */
-  timeout: number;
-
-  /**
-   * Custom timeout error message
-   */
-  message?: string;
-}
-
-/**
- * Circuit breaker configuration
- */
-export interface CircuitBreakerOptions {
-  /**
-   * Number of failures before opening circuit
-   */
-  failureThreshold?: number;
-
-  /**
-   * Time in milliseconds before attempting to close circuit
-   */
-  resetTimeout?: number;
-
-  /**
-   * Monitor callback for circuit state changes
-   */
-  onStateChange?: (state: CircuitState, error?: unknown) => void;
-}
-
-/**
- * Circuit breaker states
- */
-export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
-
-/**
- * Result wrapper for operations that may fail
- */
-export type AsyncResult<T, E = Error> = { success: true; data: T } | { success: false; error: E };
-
-/**
- * Async handler wrapper that ensures errors are properly caught
- * and logged consistently across the application
- */
-export function asyncHandler<TArgs extends unknown[], TReturn>(
-  fn: (...args: TArgs) => Promise<TReturn>
-): (...args: TArgs) => Promise<TReturn> {
-  return async (...args: TArgs): Promise<TReturn> => {
-    try {
-      return await fn(...args);
-    } catch (error) {
-      // Re-throw the error after ensuring it's properly formatted
-      if (error instanceof Error) {
-        throw error;
-      }
-      throw new Error(`Async operation failed: ${String(error)}`);
-    }
-  };
-}
-
-/**
- * Safe async handler that returns Result type instead of throwing
- */
-export function safeAsyncHandler<TArgs extends unknown[], TReturn>(
-  fn: (...args: TArgs) => Promise<TReturn>
-): (...args: TArgs) => Promise<AsyncResult<TReturn>> {
-  return async (...args: TArgs): Promise<AsyncResult<TReturn>> => {
-    try {
-      const data = await fn(...args);
-      return { success: true, data };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
-    }
-  };
-}
-
-/**
- * Retry function with exponential backoff
- */
-export async function retry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
-  const {
-    maxAttempts = 3,
-    delay = 1000,
-    backoff = 2,
-    maxDelay = 10000,
-    shouldRetry = () => true,
-    onRetry,
-  } = options;
-
-  let lastError: unknown;
-  let currentDelay = delay;
-
-  /* eslint-disable no-await-in-loop */
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-
-      // Don't retry on last attempt or if shouldRetry returns false
-      if (attempt === maxAttempts || !shouldRetry(error, attempt)) {
-        throw error;
-      }
-
-      // Call retry callback if provided
-      if (onRetry) {
-        onRetry(error, attempt);
-      }
-
-      // Wait before retry
-      await sleep(Math.min(currentDelay, maxDelay));
-      currentDelay *= backoff;
-    }
-  }
-
-  throw lastError;
-}
-/* eslint-enable no-await-in-loop */
-
-/**
- * Add timeout to any promise
- */
-export function withTimeout<T>(promise: Promise<T>, options: TimeoutOptions): Promise<T> {
-  const { timeout, message = `Operation timed out after ${timeout}ms` } = options;
-
-  return Promise.race([
-    promise,
-    new Promise<never>((_, reject) => {
-      setTimeout(() => {
-        reject(new Error(message));
-      }, timeout);
-    }),
-  ]);
-}
-
-/**
- * Sleep utility
- */
-export function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Debounce function for limiting execution frequency
- */
-export function debounce<TArgs extends unknown[]>(
-  fn: (...args: TArgs) => void,
-  delay: number
-): (...args: TArgs) => void {
-  let timeoutId: NodeJS.Timeout | undefined;
-
-  return (...args: TArgs): void => {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-
-    timeoutId = setTimeout(() => fn(...args), delay);
-  };
-}
-
-/**
- * Async debounce for promise-returning functions
- */
-export function asyncDebounce<TArgs extends unknown[], TReturn>(
-  fn: (...args: TArgs) => Promise<TReturn>,
-  delay: number
-): (...args: TArgs) => Promise<TReturn> {
-  let timeoutId: NodeJS.Timeout | undefined;
-  let latestPromise: Promise<TReturn> | undefined;
-
-  return (...args: TArgs): Promise<TReturn> => {
-    return new Promise((resolve, reject) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-
-      timeoutId = setTimeout(async () => {
-        try {
-          const result = await fn(...args);
-          if (latestPromise === timeoutId) {
-            resolve(result);
-          }
-        } catch (error) {
-          if (latestPromise === timeoutId) {
-            reject(error);
-          }
-        }
-      }, delay);
-
-      latestPromise = Promise.resolve(timeoutId) as Promise<TReturn>;
-    });
-  };
-}
-
-/**
- * Throttle function for limiting execution rate
- */
-export function throttle<TArgs extends unknown[]>(
-  fn: (...args: TArgs) => void,
-  limit: number
-): (...args: TArgs) => void {
-  let inThrottle: boolean;
-
-  return (...args: TArgs): void => {
-    if (!inThrottle) {
-      fn(...args);
-      inThrottle = true;
-      setTimeout(() => {
-        inThrottle = false;
-      }, limit);
-    }
-  };
-}
-
-/**
- * Execute promises in parallel with concurrency limit
- */
-export async function parallelLimit<T>(
-  items: T[],
-  fn: (item: T, index: number) => Promise<void>,
-  limit: number
-): Promise<void> {
-  const semaphore = new Semaphore(limit);
-
-  const promises = items.map(async (item, index) => {
-    await semaphore.acquire();
-    try {
-      return await fn(item, index);
-    } finally {
-      semaphore.release();
-    }
-  });
-
-  await Promise.all(promises);
-}
-
-/**
- * Simple semaphore implementation for controlling concurrency
- */
-class Semaphore {
-  private permits: number;
-  private waitQueue: (() => void)[] = [];
-
-  constructor(permits: number) {
-    this.permits = permits;
-  }
-
-  async acquire(): Promise<void> {
-    if (this.permits > 0) {
-      this.permits--;
-      return Promise.resolve();
-    }
-
-    return new Promise<void>((resolve) => {
-      this.waitQueue.push(resolve);
-    });
-  }
-
-  release(): void {
-    this.permits++;
-    const next = this.waitQueue.shift();
-    if (next) {
-      this.permits--;
-      next();
-    }
-  }
-}
-
-/**
- * Circuit breaker implementation
- */
-export class CircuitBreaker<TArgs extends unknown[], TReturn> {
-  private state: CircuitState = 'CLOSED';
-  private failures = 0;
-  private lastFailureTime = 0;
-  private successCount = 0;
-
-  constructor(
-    private fn: (...args: TArgs) => Promise<TReturn>,
-    private options: CircuitBreakerOptions = {}
-  ) {}
-
-  async execute(...args: TArgs): Promise<TReturn> {
-    const { failureThreshold = 5, resetTimeout = 60000, onStateChange } = this.options;
-
-    // Check if circuit is open and should reset
-    if (this.state === 'OPEN') {
-      if (Date.now() - this.lastFailureTime >= resetTimeout) {
-        this.state = 'HALF_OPEN';
-        this.successCount = 0;
-        if (onStateChange) {
-          onStateChange(this.state);
-        }
-      } else {
-        throw new Error('Circuit breaker is OPEN');
-      }
-    }
-
-    try {
-      const result = await this.fn(...args);
-
-      // Reset on success
-      if (this.state === 'HALF_OPEN') {
-        this.successCount++;
-        if (this.successCount >= 3) {
-          // Require 3 successes to fully close
-          this.state = 'CLOSED';
-          this.failures = 0;
-          if (onStateChange) {
-            onStateChange(this.state);
-          }
-        }
-      } else if (this.state === 'CLOSED') {
-        this.failures = 0;
-      }
-
-      return result;
-    } catch (error) {
-      this.failures++;
-      this.lastFailureTime = Date.now();
-
-      if (this.failures >= failureThreshold) {
-        this.state = 'OPEN';
-        if (onStateChange) {
-          onStateChange(this.state, error);
-        }
-      } else if (this.state === 'HALF_OPEN') {
-        this.state = 'OPEN';
-        if (onStateChange) {
-          onStateChange(this.state, error);
-        }
-      }
-
-      throw error;
-    }
-  }
-
-  getState(): CircuitState {
-    return this.state;
-  }
-
-  getFailures(): number {
-    return this.failures;
-  }
-
-  reset(): void {
-    this.state = 'CLOSED';
-    this.failures = 0;
-    this.successCount = 0;
-    this.lastFailureTime = 0;
-  }
-}
-
-/**
- * Create a circuit breaker wrapper
- */
-export function circuitBreaker<TArgs extends unknown[], TReturn>(
-  fn: (...args: TArgs) => Promise<TReturn>,
-  options?: CircuitBreakerOptions
-): CircuitBreaker<TArgs, TReturn> {
-  return new CircuitBreaker(fn, options);
-}
-
-/**
- * Batch processing utility
- */
-export async function batchProcess<T, R>(
-  items: T[],
-  processor: (batch: T[]) => Promise<R[]>,
-  batchSize: number,
-  options: {
-    concurrency?: number;
-    onBatchComplete?: (batch: T[], results: R[]) => void;
-    onError?: (batch: T[], error: Error) => void;
-  } = {}
-): Promise<R[]> {
-  const { concurrency = 1, onBatchComplete, onError } = options;
-  const results: R[] = [];
-  const batches: T[][] = [];
-
-  // Split into batches
-  for (let i = 0; i < items.length; i += batchSize) {
-    batches.push(items.slice(i, i + batchSize));
-  }
-
-  // Process batches with concurrency control
-  await parallelLimit(
-    batches,
-    async (batch) => {
-      try {
-        const batchResults = await processor(batch);
-        results.push(...batchResults);
-
-        if (onBatchComplete) {
-          onBatchComplete(batch, batchResults);
-        }
-      } catch (error) {
-        if (onError && error instanceof Error) {
-          onError(batch, error);
-        }
-        throw error;
-      }
-    },
-    concurrency
-  );
-
-  return results;
-}
-
-/**
- * Measure execution time of async operations
- */
-export async function measureTime<T>(
-  operation: () => Promise<T>,
-  label?: string
-): Promise<{ result: T; duration: number }> {
-  const start = process.hrtime.bigint();
-
-  try {
-    const result = await operation();
-    const end = process.hrtime.bigint();
-    const duration = Number(end - start) / 1000000; // Convert to milliseconds
-
-    if (label) {
-      getLogger().debug(`${label} completed in ${duration.toFixed(2)}ms`);
-    }
-
-    return { result, duration };
-  } catch (error) {
-    const end = process.hrtime.bigint();
-    const duration = Number(end - start) / 1000000;
-
-    if (label) {
-      getLogger().debug(`${label} failed after ${duration.toFixed(2)}ms`);
-    }
-
-    throw error;
-  }
-}
-
-/**
- * Utility functions for common async patterns
- */
-export const asyncUtils = {
-  /**
-   * Convert callback-style function to Promise
-   */
-  promisify<TArgs extends unknown[], TReturn>(
-    fn: (...args: [...TArgs, (err: Error | null, result?: TReturn) => void]) => void
-  ): (...args: TArgs) => Promise<TReturn> {
-    return (...args: TArgs): Promise<TReturn> => {
-      return new Promise((resolve, reject) => {
-        fn(...args, (err, result) => {
-          if (err != null) reject(err);
-          else resolve(result as TReturn);
-        });
-      });
-    };
-  },
-
-  /**
-   * Race multiple promises with first success wins
-   */
-  raceToSuccess<T>(promises: Promise<T>[]): Promise<T> {
-    return new Promise((resolve, reject) => {
-      let rejectedCount = 0;
-      const errors: unknown[] = [];
-
-      promises.forEach((promise, index) => {
-        promise.then(resolve).catch((error) => {
-          errors[index] = error;
-          rejectedCount++;
-
-          if (rejectedCount === promises.length) {
-            reject(new Error(`All promises rejected: ${errors.join(', ')}`));
-          }
-        });
-      });
-    });
-  },
-
-  /**
-   * Create a cancellable promise
-   */
-  cancellable<T>(promise: Promise<T>): {
-    promise: Promise<T>;
-    cancel: () => void;
-  } {
-    let cancelled = false;
-
-    const cancellablePromise = new Promise<T>((resolve, reject) => {
-      promise
-        .then((result) => {
-          if (!cancelled) resolve(result);
-        })
-        .catch((error) => {
-          if (!cancelled) reject(error);
-        });
-    });
-
-    return {
-      promise: cancellablePromise,
-      cancel: () => {
-        cancelled = true;
-      },
-    };
-  },
-} as const;
-
-// Export all utilities as default
-export default {
-  asyncHandler,
-  safeAsyncHandler,
-  retry,
-  withTimeout,
-  sleep,
-  debounce,
-  asyncDebounce,
-  throttle,
-  parallelLimit,
-  circuitBreaker,
-  batchProcess,
-  measureTime,
-  asyncUtils,
-  CircuitBreaker,
-};