@umituz/web-ai-groq-provider 1.1.13 → 2.0.0

package/src/domains/groq/utils/cache-manager.util.ts

@@ -1,215 +0,0 @@
-/**
- * Cache Manager Utility
- * @description LRU cache for storing API responses
- */
-
-interface CacheEntry<T> {
-  value: T;
-  timestamp: number;
-  accessCount: number;
-  lastAccess: number;
-}
-
-interface CacheOptions {
-  /** Maximum number of entries in cache */
-  maxSize?: number;
-  /** Time-to-live for cache entries in milliseconds */
-  ttl?: number;
-  /** Custom key generator */
-  keyGenerator?: (input: unknown) => string;
-}
-
-class CacheManager {
-  private cache = new Map<string, CacheEntry<unknown>>();
-  private readonly maxSize: number;
-  private readonly ttl: number;
-
-  constructor(options: CacheOptions = {}) {
-    this.maxSize = options.maxSize || 100; // Default 100 entries
-    this.ttl = options.ttl || 300000; // 5 minutes default TTL
-  }
-
-  /**
-   * Get a value from cache
-   */
-  get<T>(key: string): T | null {
-    const entry = this.cache.get(key);
-
-    if (!entry) {
-      return null;
-    }
-
-    // Check if entry has expired
-    if (this.isExpired(entry)) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    // Update access statistics
-    entry.accessCount++;
-    entry.lastAccess = Date.now();
-
-    return entry.value as T;
-  }
-
-  /**
-   * Set a value in cache
-   */
-  set<T>(key: string, value: T): void {
-    // If cache is full, remove least recently used entry
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      this.evictLRU();
-    }
-
-    this.cache.set(key, {
-      value,
-      timestamp: Date.now(),
-      accessCount: 1,
-      lastAccess: Date.now(),
-    });
-  }
-
-  /**
-   * Check if key exists and is not expired
-   */
-  has(key: string): boolean {
-    const entry = this.cache.get(key);
-    return entry !== undefined && !this.isExpired(entry);
-  }
-
-  /**
-   * Delete a specific entry
-   */
-  delete(key: string): boolean {
-    return this.cache.delete(key);
-  }
-
-  /**
-   * Clear all cache entries
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Get cache statistics
-   */
-  getStats(): {
-    size: number;
-    maxSize: number;
-    hitRate: number;
-    entries: Array<{ key: string; accessCount: number; age: number }>;
-  } {
-    const now = Date.now();
-    const entries = Array.from(this.cache.entries()).map(([key, entry]) => ({
-      key,
-      accessCount: entry.accessCount,
-      age: now - entry.timestamp,
-    }));
-
-    // Calculate average hit rate
-    const totalAccessCount = entries.reduce(
-      (sum, e) => sum + e.accessCount,
-      0
-    );
-    const hitRate = this.cache.size > 0 ? totalAccessCount / this.cache.size : 0;
-
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hitRate,
-      entries,
-    };
-  }
-
-  /**
-   * Clean up expired entries
-   */
-  cleanup(): number {
-    let removed = 0;
-    for (const [key, entry] of this.cache.entries()) {
-      if (this.isExpired(entry)) {
-        this.cache.delete(key);
-        removed++;
-      }
-    }
-    return removed;
-  }
-
-  /**
-   * Check if an entry has expired
-   */
-  private isExpired(entry: CacheEntry<unknown>): boolean {
-    return Date.now() - entry.timestamp > this.ttl;
-  }
-
-  /**
-   * Evict least recently used entry
-   */
-  private evictLRU(): void {
-    let lruKey: string | null = null;
-    let lruTime = Infinity;
-
-    for (const [key, entry] of this.cache.entries()) {
-      if (entry.lastAccess < lruTime) {
-        lruTime = entry.lastAccess;
-        lruKey = key;
-      }
-    }
-
-    if (lruKey) {
-      this.cache.delete(lruKey);
-    }
-  }
-
-  /**
-   * Generate a cache key from parameters
-   */
-  generateKey(params: Record<string, unknown>): string {
-    // Sort keys to ensure consistent key generation
-    const sortedParams = Object.keys(params)
-      .sort()
-      .reduce((acc, key) => {
-        acc[key] = params[key];
-        return acc;
-      }, {} as Record<string, unknown>);
-
-    return JSON.stringify(sortedParams);
-  }
-
-  /**
-   * Preload cache with multiple entries
-   */
-  preload<T>(entries: Array<{ key: string; value: T }>): void {
-    for (const entry of entries) {
-      this.set(entry.key, entry.value);
-    }
-  }
-
-  /**
-   * Get or set pattern - return cached value or compute and cache it
-   */
-  async getOrSet<T>(
-    key: string,
-    computeFn: () => Promise<T>
-  ): Promise<T> {
-    const cached = this.get<T>(key);
-    if (cached !== null) {
-      return cached;
-    }
-
-    const value = await computeFn();
-    this.set(key, value);
-    return value;
-  }
-
-  /**
-   * Reset cache to initial state
-   */
-  reset(): void {
-    this.cache.clear();
-  }
-}
-
-export const cacheManager = new CacheManager();
-export { CacheManager };

package/src/domains/groq/utils/debounce.util.ts

@@ -1,268 +0,0 @@
-/**
- * Debounce and Throttle Utility
- * @description Rate limiting utilities for user input and API calls
- */
-
-interface DebounceOptions {
-  /** Delay in milliseconds */
-  delay?: number;
-  /** Execute on leading edge */
-  leading?: boolean;
-  /** Execute on trailing edge */
-  trailing?: boolean;
-}
-
-interface ThrottleOptions {
-  /** Interval in milliseconds */
-  interval?: number;
-  /** Execute on leading edge */
-  leading?: boolean;
-  /** Execute on trailing edge */
-  trailing?: boolean;
-}
-
-class DebounceManager {
-  private timers = new Map<string, NodeJS.Timeout>();
-  private lastArgs = new Map<string, unknown[]>();
-  private lastThis = new Map<string, unknown>();
-
-  /**
-   * Debounce a function
-   * Delays execution until after delay milliseconds have elapsed since last invocation
-   */
-  debounce<T extends (...args: unknown[]) => unknown>(
-    fn: T,
-    options: DebounceOptions = {}
-  ): T {
-    const delay = options.delay ?? 300;
-    const leading = options.leading ?? false;
-    const trailing = options.trailing ?? true;
-
-    let timer: NodeJS.Timeout | null = null;
-    let lastCallTime = 0;
-    let lastResult: unknown;
-
-    return ((...args: unknown[]) => {
-      const now = Date.now();
-      const shouldCallLeading = leading && !timer && now - lastCallTime > delay;
-
-      // Clear existing timer
-      if (timer) {
-        clearTimeout(timer);
-        timer = null;
-      }
-
-      // Call on leading edge
-      if (shouldCallLeading) {
-        lastCallTime = now;
-        lastResult = fn(...args);
-        return lastResult;
-      }
-
-      // Schedule trailing edge call
-      if (trailing) {
-        timer = setTimeout(() => {
-          timer = null;
-          lastCallTime = Date.now();
-          lastResult = fn(...args);
-        }, delay);
-      }
-
-      return lastResult;
-    }) as T;
-  }
-
-  /**
-   * Debounce with key (for multiple independent debounced functions)
-   */
-  debounceByKey<T extends (...args: unknown[]) => unknown>(
-    key: string,
-    fn: T,
-    delay: number = 300
-  ): T {
-    return ((...args: unknown[]) => {
-      // Store args and context for trailing call
-      this.lastArgs.set(key, args);
-
-      // Clear existing timer
-      const existingTimer = this.timers.get(key);
-      if (existingTimer) {
-        clearTimeout(existingTimer);
-      }
-
-      // Schedule new call
-      const timer = setTimeout(() => {
-        this.timers.delete(key);
-        const args = this.lastArgs.get(key);
-        this.lastArgs.delete(key);
-        if (args) {
-          fn(...args);
-        }
-      }, delay);
-
-      this.timers.set(key, timer);
-    }) as T;
-  }
-
-  /**
-   * Cancel a pending debounced call
-   */
-  cancelDebounce(key: string): void {
-    const timer = this.timers.get(key);
-    if (timer) {
-      clearTimeout(timer);
-      this.timers.delete(key);
-    }
-    this.lastArgs.delete(key);
-  }
-
-  /**
-   * Flush a pending debounced call immediately
-   */
-  flushDebounce<T extends (...args: unknown[]) => unknown>(
-    key: string,
-    fn: T
-  ): void {
-    this.cancelDebounce(key);
-    const args = this.lastArgs.get(key);
-    if (args) {
-      fn(...args);
-      this.lastArgs.delete(key);
-    }
-  }
-}
-
-class ThrottleManager {
-  private timers = new Map<string, NodeJS.Timeout>();
-  private lastArgs = new Map<string, unknown[]>();
-
-  /**
-   * Throttle a function
-   * Limits execution to once per interval
-   */
-  throttle<T extends (...args: unknown[]) => unknown>(
-    fn: T,
-    options: ThrottleOptions = {}
-  ): T {
-    const interval = options.interval ?? 1000;
-    const leading = options.leading ?? true;
-    const trailing = options.trailing ?? false;
-
-    let timer: NodeJS.Timeout | null = null;
-    let lastCallTime = 0;
-    let lastResult: unknown;
-    let pendingArgs: unknown[] | null = null;
-
-    return ((...args: unknown[]) => {
-      const now = Date.now();
-      const timeSinceLastCall = now - lastCallTime;
-      const shouldCall = timeSinceLastCall >= interval;
-
-      // Store args for potential trailing call
-      pendingArgs = args;
-
-      // Call on leading edge or if enough time has passed
-      if (shouldCall && (leading || !timer)) {
-        lastCallTime = now;
-        lastResult = fn(...args);
-        return lastResult;
-      }
-
-      // Schedule trailing edge call if needed
-      if (trailing && !timer) {
-        timer = setTimeout(() => {
-          timer = null;
-          lastCallTime = Date.now();
-          if (pendingArgs) {
-            lastResult = fn(...pendingArgs);
-            pendingArgs = null;
-          }
-        }, interval - timeSinceLastCall);
-      }
-
-      return lastResult;
-    }) as T;
-  }
-
-  /**
-   * Throttle by key (for multiple independent throttled functions)
-   */
-  throttleByKey<T extends (...args: unknown[]) => unknown>(
-    key: string,
-    fn: T,
-    interval: number = 1000
-  ): T {
-    return ((...args: unknown[]) => {
-      // Check if we're within throttle interval
-      const existingTimer = this.timers.get(key);
-      if (existingTimer) {
-        // Store args for potential trailing call
-        this.lastArgs.set(key, args);
-        return;
-      }
-
-      // Execute immediately
-      fn(...args);
-
-      // Set up throttle window
-      const timer = setTimeout(() => {
-        this.timers.delete(key);
-
-        // Check if there are pending args to execute
-        const pendingArgs = this.lastArgs.get(key);
-        if (pendingArgs) {
-          this.lastArgs.delete(key);
-          fn(...pendingArgs);
-
-          // Set up another throttle window
-          const nextTimer = setTimeout(() => {
-            this.timers.delete(key);
-          }, interval);
-
-          this.timers.set(key, nextTimer);
-        }
-      }, interval);
-
-      this.timers.set(key, timer);
-    }) as T;
-  }
-
-  /**
-   * Cancel a throttled function
-   */
-  cancelThrottle(key: string): void {
-    const timer = this.timers.get(key);
-    if (timer) {
-      clearTimeout(timer);
-      this.timers.delete(key);
-    }
-    this.lastArgs.delete(key);
-  }
-
-  /**
-   * Check if function is currently throttled
-   */
-  isThrottled(key: string): boolean {
-    return this.timers.has(key);
-  }
-}
-
-export const debounceManager = new DebounceManager();
-export const throttleManager = new ThrottleManager();
-
-/**
- * Convenience functions
- */
-export function debounce<T extends (...args: unknown[]) => unknown>(
-  fn: T,
-  delay?: number
-): T {
-  return debounceManager.debounce(fn, { delay });
-}
-
-export function throttle<T extends (...args: unknown[]) => unknown>(
-  fn: T,
-  interval?: number
-): T {
-  return throttleManager.throttle(fn, { interval });
-}

package/src/domains/groq/utils/error.util.ts

@@ -1,57 +0,0 @@
-/**
- * Error Utilities
- * @description Helper functions for error handling
- */
-
-// Error utilities - moved to error constants for better organization
-
-/**
- * Get user-friendly error message
- */
-export function getUserFriendlyError(error: Error): string {
-  const errorMessage = error.message.toLowerCase();
-
-  if (errorMessage.includes("api key") || errorMessage.includes("unauthorized")) {
-    return "Please check your Groq API key and try again.";
-  }
-
-  if (errorMessage.includes("rate limit")) {
-    return "You've reached the rate limit. Please wait a moment and try again.";
-  }
-
-  if (errorMessage.includes("network") || errorMessage.includes("fetch")) {
-    return "Network error. Please check your connection and try again.";
-  }
-
-  if (errorMessage.includes("abort")) {
-    return "Request was cancelled.";
-  }
-
-  return error.message || "An unexpected error occurred. Please try again.";
-}
-
-// isRetryableError and isAuthError are exported from ../constants/error.constants.ts
-// Re-export them here for backward compatibility
-export { isRetryableError, isAuthError } from "../constants/error.constants";
-
-/**
- * Format error for logging
- */
-export function formatErrorForLogging(error: unknown): {
-  message: string;
-  type: string;
-  stack?: string;
-} {
-  if (error instanceof Error) {
-    return {
-      message: error.message,
-      type: error.name,
-      stack: error.stack,
-    };
-  }
-
-  return {
-    message: String(error),
-    type: typeof error,
-  };
-}

package/src/domains/groq/utils/groq-error.util.ts

@@ -1,18 +0,0 @@
-/**
- * Groq Error Class
- * @description Custom error for Groq API operations
- */
-
-import { GroqErrorType } from "../constants/error.constants";
-
-export class GroqError extends Error {
-  constructor(
-    public readonly type: GroqErrorType,
-    message: string,
-    public readonly cause?: Error,
-    public readonly metadata?: { readonly status?: number; readonly url?: string }
-  ) {
-    super(message);
-    this.name = "GroqError";
-  }
-}

package/src/domains/groq/utils/index.ts

@@ -1,37 +0,0 @@
-/**
- * Infrastructure Utils Index
- * Subpath: @umituz/web-ai-groq-provider/utils
- */
-
-// Message utilities
-export {
-  createUserMessage,
-  createAssistantMessage,
-  createSystemMessage,
-  createTextMessage,
-  promptToMessages,
-  extractTextFromMessages,
-  formatMessagesForDisplay,
-} from "./message.util";
-
-// Error utilities
-export {
-  getUserFriendlyError,
-  isRetryableError,
-  isAuthError,
-  formatErrorForLogging,
-} from "./error.util";
-
-export { GroqError } from "./groq-error.util";
-
-// Performance utilities
-export { requestDeduplicator, RequestDeduplicator } from "./request-deduplicator.util";
-export { requestQueue, RequestQueue } from "./request-queue.util";
-export { cacheManager, CacheManager } from "./cache-manager.util";
-export { retryManager, RetryManager, withRetry } from "./retry.util";
-export {
-  debounceManager,
-  throttleManager,
-  debounce,
-  throttle,
-} from "./debounce.util";

package/src/domains/groq/utils/message.util.ts

@@ -1,57 +0,0 @@
-/**
- * Message Utilities
- * @description Helper functions for creating and working with messages
- */
-
-import type { GroqMessage, GroqMessageRole } from "../entities";
-
-/**
- * Create a user message
- */
-export function createUserMessage(content: string): GroqMessage {
-  return { role: "user", content };
-}
-
-/**
- * Create an assistant message
- */
-export function createAssistantMessage(content: string): GroqMessage {
-  return { role: "assistant", content };
-}
-
-/**
- * Create a system message
- */
-export function createSystemMessage(content: string): GroqMessage {
-  return { role: "system", content };
-}
-
-/**
- * Create a text message with specified role
- */
-export function createTextMessage(role: GroqMessageRole, content: string): GroqMessage {
-  return { role, content };
-}
-
-/**
- * Convert a simple prompt to message array
- */
-export function promptToMessages(prompt: string): GroqMessage[] {
-  return [{ role: "user", content: prompt }];
-}
-
-/**
- * Extract text content from messages
- */
-export function extractTextFromMessages(messages: GroqMessage[]): string {
-  return messages.map(m => m.content).join("\n\n");
-}
-
-/**
- * Format messages for display
- */
-export function formatMessagesForDisplay(messages: GroqMessage[]): string {
-  return messages
-    .map(m => `[${m.role.toUpperCase()}]: ${m.content}`)
-    .join("\n\n---\n\n");
-}