ubersearch 0.0.0-development

package/src/core/strategy/AllProvidersStrategy.ts

@@ -0,0 +1,245 @@
+/**
+ * AllProvidersStrategy - Queries all available providers and combines their results
+ *
+ * This strategy executes search queries against all configured providers,
+ * collecting results from all successful providers. Supports both sequential
+ * and parallel execution modes. Failed providers are logged but don't stop
+ * the overall search.
+ */
+
+import { createLogger } from "../logger";
+import type { SearchProvider } from "../provider";
+import type { EngineId, SearchResponse, SearchResultItem } from "../types";
+import { SearchError } from "../types";
+import type {
+  EngineAttempt,
+  ISearchStrategy,
+  AllSearchOptions,
+  StrategyContext,
+  StrategyResult,
+} from "./ISearchStrategy";
+
+const log = createLogger("AllProviders");
+
+/**
+ * Result from a single engine search attempt
+ */
+interface EngineSearchResult {
+  engineId: EngineId;
+  response?: SearchResponse;
+  error?: Error;
+}
+
+/**
+ * Strategy implementation that queries all providers and combines results
+ *
+ * Supports two execution modes:
+ * - Sequential (default): Providers are queried one at a time
+ * - Parallel: All providers are queried simultaneously using Promise.allSettled
+ */
+export class AllProvidersStrategy implements ISearchStrategy {
+  /**
+   * Execute search against all providers and combine results
+   *
+   * @param query - The search query string
+   * @param engineIds - Ordered list of engine IDs to search
+   * @param options - Search options (limit, includeRaw, parallel, etc.)
+   * @param context - Strategy context with registry and credits
+   * @returns Combined results from all successful providers with attempt metadata
+   */
+  async execute(
+    query: string,
+    engineIds: EngineId[],
+    options: AllSearchOptions,
+    context: StrategyContext,
+  ): Promise<StrategyResult> {
+    // Choose execution mode based on options
+    if (options.parallel) {
+      return this.executeParallel(query, engineIds, options, context);
+    }
+    return this.executeSequential(query, engineIds, options, context);
+  }
+
+  /**
+   * Execute searches sequentially (original behavior)
+   */
+  private async executeSequential(
+    query: string,
+    engineIds: EngineId[],
+    options: AllSearchOptions,
+    context: StrategyContext,
+  ): Promise<StrategyResult> {
+    const results: SearchResultItem[] = [];
+    const attempts: EngineAttempt[] = [];
+
+    // Query each engine sequentially
+    for (const engineId of engineIds) {
+      const provider = context.providerRegistry.get(engineId);
+      if (!provider) {
+        attempts.push({ engineId, success: false, reason: "no_provider" });
+        continue;
+      }
+
+      // Check credit availability
+      if (!context.creditManager.hasSufficientCredits(engineId)) {
+        attempts.push({ engineId, success: false, reason: "out_of_credit" });
+        continue;
+      }
+
+      try {
+        // Execute search
+        const response = await provider.search({
+          query,
+          limit: options.limit,
+          includeRaw: options.includeRaw,
+        });
+
+        // Deduct credits
+        if (!context.creditManager.charge(engineId)) {
+          // This shouldn't happen because we checked above, but handle gracefully
+          attempts.push({ engineId, success: false, reason: "out_of_credit" });
+          continue;
+        }
+
+        // Record success
+        attempts.push({ engineId, success: true });
+
+        // Add results, applying limit if specified
+        if (options.limit !== undefined) {
+          results.push(...response.items.slice(0, options.limit - results.length));
+        } else {
+          results.push(...response.items);
+        }
+      } catch (error) {
+        // Record failure
+        if (error instanceof SearchError) {
+          attempts.push({ engineId, success: false, reason: error.reason });
+        } else {
+          attempts.push({ engineId, success: false, reason: "unknown" });
+        }
+
+        // Log warning but continue with other providers
+        log.warn(
+          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    // Apply final limit if specified
+    if (options.limit !== undefined && results.length > options.limit) {
+      results.splice(options.limit);
+    }
+
+    return { results, attempts };
+  }
+
+  /**
+   * Execute searches in parallel using Promise.allSettled
+   *
+   * This provides faster execution when querying multiple providers,
+   * as all requests are made simultaneously.
+   */
+  private async executeParallel(
+    query: string,
+    engineIds: EngineId[],
+    options: AllSearchOptions,
+    context: StrategyContext,
+  ): Promise<StrategyResult> {
+    const results: SearchResultItem[] = [];
+    const attempts: EngineAttempt[] = [];
+
+    // Filter engines that are available and have credits
+    const eligibleEngines: { engineId: EngineId; provider: SearchProvider }[] = [];
+    const ineligibleAttempts: EngineAttempt[] = [];
+
+    for (const engineId of engineIds) {
+      const provider = context.providerRegistry.get(engineId);
+      if (!provider) {
+        ineligibleAttempts.push({ engineId, success: false, reason: "no_provider" });
+        continue;
+      }
+
+      if (!context.creditManager.hasSufficientCredits(engineId)) {
+        ineligibleAttempts.push({ engineId, success: false, reason: "out_of_credit" });
+        continue;
+      }
+
+      eligibleEngines.push({ engineId, provider });
+    }
+
+    // Execute all eligible searches in parallel
+    const searchPromises = eligibleEngines.map(
+      async ({ engineId, provider }): Promise<EngineSearchResult> => {
+        try {
+          const response = await provider.search({
+            query,
+            limit: options.limit,
+            includeRaw: options.includeRaw,
+          });
+          return { engineId, response };
+        } catch (error) {
+          return { engineId, error: error instanceof Error ? error : new Error(String(error)) };
+        }
+      },
+    );
+
+    // Wait for all searches to complete
+    const searchResults = await Promise.allSettled(searchPromises);
+
+    // Process results in original order (maintain engine priority)
+    for (let i = 0; i < searchResults.length; i++) {
+      const settledResult = searchResults[i];
+      const { engineId } = eligibleEngines[i];
+
+      if (settledResult.status === "rejected") {
+        // Promise itself was rejected (shouldn't happen with our try/catch, but handle it)
+        attempts.push({ engineId, success: false, reason: "unknown" });
+        log.warn(`Search failed for ${engineId}: Promise rejected`);
+        continue;
+      }
+
+      const { response, error } = settledResult.value;
+
+      if (error) {
+        // Search threw an error
+        if (error instanceof SearchError) {
+          attempts.push({ engineId, success: false, reason: error.reason });
+        } else {
+          attempts.push({ engineId, success: false, reason: "unknown" });
+        }
+        log.warn(`Search failed for ${engineId}: ${error.message}`);
+        continue;
+      }
+
+      if (response) {
+        // Deduct credits
+        if (!context.creditManager.charge(engineId)) {
+          attempts.push({ engineId, success: false, reason: "out_of_credit" });
+          continue;
+        }
+
+        // Record success
+        attempts.push({ engineId, success: true });
+
+        // Add results
+        results.push(...response.items);
+      }
+    }
+
+    // Add ineligible attempts at the end (maintaining order within their category)
+    attempts.push(...ineligibleAttempts);
+
+    // Sort attempts to match original engine order
+    const engineOrder = new Map(engineIds.map((id, idx) => [id, idx]));
+    attempts.sort(
+      (a, b) => (engineOrder.get(a.engineId) ?? 0) - (engineOrder.get(b.engineId) ?? 0),
+    );
+
+    // Apply final limit if specified
+    if (options.limit !== undefined && results.length > options.limit) {
+      results.splice(options.limit);
+    }
+
+    return { results, attempts };
+  }
+}

package/src/core/strategy/FirstSuccessStrategy.ts

@@ -0,0 +1,98 @@
+/**
+ * First Success Strategy - stops after first successful provider
+ *
+ * This strategy tries search providers in order and returns immediately
+ * with results from the first successful provider. It skips providers
+ * with insufficient credits and stops execution after the first success.
+ */
+
+import { createLogger } from "../logger";
+import type { EngineId } from "../types";
+import { SearchError } from "../types";
+import type {
+  EngineAttempt,
+  ISearchStrategy,
+  AllSearchOptions,
+  StrategyContext,
+  StrategyResult,
+} from "./ISearchStrategy";
+
+const log = createLogger("FirstSuccess");
+
+/**
+ * First Success Strategy implementation
+ *
+ * Tries engines in order until first success, then returns immediately.
+ * Records all attempts up to and including the first successful one.
+ * Skips providers with insufficient credits.
+ */
+export class FirstSuccessStrategy implements ISearchStrategy {
+  /**
+   * Execute search with first-success strategy
+   *
+   * @param query - The search query string
+   * @param engineIds - Ordered list of engine IDs to try
+   * @param options - Search options (limit, includeRaw, etc.)
+   * @param context - Strategy context with registry and credits
+   * @returns Promise resolving to strategy result with first successful results
+   */
+  async execute(
+    query: string,
+    engineIds: EngineId[],
+    options: AllSearchOptions,
+    context: StrategyContext,
+  ): Promise<StrategyResult> {
+    const attempts: EngineAttempt[] = [];
+
+    // Try each engine in order until one succeeds
+    for (const engineId of engineIds) {
+      const provider = context.providerRegistry.get(engineId);
+      if (!provider) {
+        attempts.push({ engineId, success: false, reason: "no_provider" });
+        continue;
+      }
+
+      // Check credit availability
+      if (!context.creditManager.hasSufficientCredits(engineId)) {
+        attempts.push({ engineId, success: false, reason: "out_of_credit" });
+        continue;
+      }
+
+      try {
+        // Execute search
+        const response = await provider.search({
+          query,
+          limit: options.limit,
+          includeRaw: options.includeRaw,
+        });
+
+        // Deduct credits
+        if (!context.creditManager.charge(engineId)) {
+          attempts.push({ engineId, success: false, reason: "out_of_credit" });
+          continue;
+        }
+
+        // Record success
+        attempts.push({ engineId, success: true });
+
+        // Return immediately with results from this provider
+        return { results: response.items, attempts };
+      } catch (error) {
+        // Record failure and continue to next provider
+        if (error instanceof SearchError) {
+          attempts.push({ engineId, success: false, reason: error.reason });
+        } else {
+          attempts.push({ engineId, success: false, reason: "unknown" });
+        }
+
+        // Log warning and continue
+        log.warn(
+          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    // No provider succeeded
+    return { results: [], attempts };
+  }
+}

package/src/core/strategy/ISearchStrategy.ts

@@ -0,0 +1,94 @@
+/**
+ * Search Strategy Interface
+ *
+ * Defines the contract for all search strategies, enabling the Strategy pattern
+ * for different search execution approaches (all engines, first success, etc.)
+ */
+
+import type { CreditManager } from "../credits";
+import type { ProviderRegistry } from "../provider";
+import type { EngineId, SearchResultItem } from "../types";
+
+/**
+ * Context object providing dependencies to search strategies
+ */
+export interface StrategyContext {
+  /** Registry of available search providers */
+  providerRegistry: ProviderRegistry;
+
+  /** Credit manager for tracking usage across providers */
+  creditManager: CreditManager;
+}
+
+/**
+ * Options for configuring search strategy behavior
+ */
+export interface AllSearchOptions {
+  /** Override the default engine order */
+  engineOrderOverride?: EngineId[];
+
+  /** Maximum results per provider */
+  limit?: number;
+
+  /** Include raw provider responses */
+  includeRaw?: boolean;
+
+  /** Search strategy */
+  strategy?: "all" | "first-success";
+
+  /**
+   * Execute searches in parallel (only applies to 'all' strategy)
+   * When true, all providers are queried simultaneously using Promise.allSettled
+   * When false (default), providers are queried sequentially
+   */
+  parallel?: boolean;
+}
+
+/**
+ * Metadata about a single engine attempt
+ */
+export interface EngineAttempt {
+  /** Engine ID that was attempted */
+  engineId: EngineId;
+
+  /** Whether the attempt succeeded */
+  success: boolean;
+
+  /** Reason for failure (if success=false) */
+  reason?: string;
+}
+
+/**
+ * Result from executing a search strategy
+ */
+export interface StrategyResult {
+  /** Combined results from all successful providers */
+  results: SearchResultItem[];
+
+  /** Metadata about which engines were tried and their outcomes */
+  attempts: EngineAttempt[];
+}
+
+/**
+ * Interface for implementing different search execution strategies
+ *
+ * This enables the Strategy pattern, allowing different approaches to
+ * coordinate multiple search providers while maintaining a consistent interface.
+ */
+export interface ISearchStrategy {
+  /**
+   * Execute the search strategy with the given parameters
+   *
+   * @param query - The search query string
+   * @param engineIds - Ordered list of engine IDs to attempt
+   * @param options - Strategy configuration options
+   * @param context - Dependencies and services needed for execution
+   * @returns Promise resolving to strategy execution results
+   */
+  execute(
+    query: string,
+    engineIds: EngineId[],
+    options: AllSearchOptions,
+    context: StrategyContext,
+  ): Promise<StrategyResult>;
+}

package/src/core/strategy/StrategyFactory.ts

@@ -0,0 +1,204 @@
+import { AllProvidersStrategy } from "./AllProvidersStrategy";
+import { FirstSuccessStrategy } from "./FirstSuccessStrategy";
+import type { ISearchStrategy } from "./ISearchStrategy";
+
+/**
+ * Configuration options for search strategies
+ * @interface StrategyOptions
+ */
+export interface StrategyOptions {
+  /**
+   * Timeout in milliseconds for individual provider requests
+   * @default 30000
+   */
+  timeout?: number;
+
+  /**
+   * Maximum number of concurrent requests
+   * @default 5
+   */
+  maxConcurrent?: number;
+
+  /**
+   * Retry configuration
+   */
+  retry?: {
+    /**
+     * Number of retry attempts
+     * @default 2
+     */
+    attempts?: number;
+    /**
+     * Delay between retries in milliseconds
+     * @default 1000
+     */
+    delay?: number;
+  };
+
+  /**
+   * Additional strategy-specific options
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Maps strategy names to their implementing classes
+ * @interface StrategyMap
+ */
+interface StrategyMap {
+  [strategyName: string]: new (options?: StrategyOptions) => ISearchStrategy;
+}
+
+/**
+ * Factory for creating search strategy instances.
+ * Implements the Factory pattern to enable Open/Closed Principle -
+ * new strategies can be added without modifying existing code.
+ *
+ * @class StrategyFactory
+ * @example
+ * ```typescript
+ * // Create an all-providers strategy
+ * const allStrategy = StrategyFactory.createStrategy('all', {
+ *   timeout: 30000,
+ *   maxConcurrent: 3
+ * });
+ *
+ * // Create a first-success strategy
+ * const firstSuccessStrategy = StrategyFactory.createStrategy('first-success', {
+ *   timeout: 15000
+ * });
+ *
+ * // Register a custom strategy
+ * StrategyFactory.registerStrategy('custom', CustomStrategy);
+ * ```
+ */
+let strategies: StrategyMap = {
+  all: AllProvidersStrategy,
+  "first-success": FirstSuccessStrategy,
+};
+
+/**
+ * Creates a search strategy instance based on the provided name and options.
+ *
+ * @param {string} strategyName - The name of the strategy to create
+ * @param {StrategyOptions} [options] - Optional configuration for the strategy
+ * @returns {ISearchStrategy} An instance of the requested strategy
+ * @throws {Error} If the strategy name is not recognized
+ *
+ * @example
+ * ```typescript
+ * const strategy = StrategyFactory.createStrategy('all', {
+ *   timeout: 20000,
+ *   maxConcurrent: 5,
+ *   retry: { attempts: 3, delay: 500 }
+ * });
+ * ```
+ */
+function createStrategy(strategyName: string, options?: StrategyOptions): ISearchStrategy {
+  const StrategyClass = strategies[strategyName];
+
+  if (!StrategyClass) {
+    const availableStrategies = Object.keys(strategies).join(", ");
+    throw new Error(
+      `Unknown strategy: "${strategyName}". Available strategies: [${availableStrategies}]`,
+    );
+  }
+
+  return new StrategyClass(options);
+}
+
+/**
+ * Registers a new strategy in the factory.
+ * Enables the Open/Closed Principle by allowing new strategies to be added
+ * without modifying the factory code itself.
+ *
+ * @param {string} name - The name to register the strategy under
+ * @param strategyClass - The strategy class constructor
+ * @throws {Error} If a strategy with the same name already exists
+ *
+ * @example
+ * ```typescript
+ * class WeightedStrategy implements ISearchStrategy {
+ *   constructor(private options?: StrategyOptions) {}
+ *
+ *   async search(
+ *     query: string,
+ *     providers: ISearchProvider[],
+ *     options?: SearchOptions
+ *   ): Promise<SearchResult[]> {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * StrategyFactory.registerStrategy('weighted', WeightedStrategy);
+ * ```
+ */
+function registerStrategy(
+  name: string,
+  strategyClass: new (options?: StrategyOptions) => ISearchStrategy,
+): void {
+  if (strategies[name]) {
+    throw new Error(`Strategy "${name}" is already registered`);
+  }
+
+  strategies[name] = strategyClass;
+}
+
+/**
+ * Gets a list of all available strategy names.
+ *
+ * @returns {string[]} Array of available strategy names
+ *
+ * @example
+ * ```typescript
+ * const availableStrategies = StrategyFactory.getAvailableStrategies();
+ * console.log(availableStrategies); // ['all', 'first-success', 'custom']
+ * ```
+ */
+function getAvailableStrategies(): string[] {
+  return Object.keys(strategies);
+}
+
+/**
+ * Checks if a strategy is registered.
+ *
+ * @param {string} strategyName - The name of the strategy to check
+ * @returns {boolean} True if the strategy is registered, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (StrategyFactory.hasStrategy('all')) {
+ *   console.log('All providers strategy is available');
+ * }
+ * ```
+ */
+function hasStrategy(strategyName: string): boolean {
+  return strategyName in strategies;
+}
+
+/**
+ * Resets the factory to its default state.
+ * This is primarily useful for testing to ensure test isolation.
+ *
+ * @example
+ * ```typescript
+ * // In test setup/teardown
+ * afterEach(() => {
+ *   StrategyFactory.reset();
+ * });
+ * ```
+ */
+function reset(): void {
+  strategies = {
+    all: AllProvidersStrategy,
+    "first-success": FirstSuccessStrategy,
+  };
+}
+
+export const StrategyFactory = {
+  createStrategy,
+  registerStrategy,
+  getAvailableStrategies,
+  hasStrategy,
+  reset,
+};

package/src/core/strategy/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Search strategy implementations and interfaces
+ */
+
+export * from "./AllProvidersStrategy";
+export * from "./FirstSuccessStrategy";
+export * from "./ISearchStrategy";
+export * from "./StrategyFactory";
+export * from "./types";

package/src/core/strategy/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Strategy interface and types for search execution patterns
+ */
+
+import type { CreditManager } from "../credits";
+import type { ProviderRegistry } from "../provider";
+import type { EngineId, SearchQuery, SearchResultItem } from "../types";
+
+/**
+ * Context passed to search strategies containing dependencies
+ */
+export interface StrategyContext {
+  /** Provider registry for accessing search providers */
+  registry: ProviderRegistry;
+  /** Credit manager for checking and charging credits */
+  credits: CreditManager;
+}
+
+/**
+ * Result from a search strategy execution
+ */
+export interface StrategyResult {
+  /** Search results from successful providers */
+  results: SearchResultItem[];
+  /** Metadata about engine attempts */
+  attempts: EngineAttempt[];
+}
+
+/**
+ * Engine attempt metadata
+ */
+export interface EngineAttempt {
+  engineId: EngineId;
+  success: boolean;
+  reason?: string;
+}
+
+/**
+ * Interface for implementing different search execution strategies
+ */
+export interface ISearchStrategy {
+  /**
+   * Execute search using this strategy
+   * @param query - The search query
+   * @param engineIds - Ordered list of engine IDs to try
+   * @param options - Search options (limit, includeRaw, etc.)
+   * @param context - Strategy context with dependencies
+   * @returns Promise resolving to strategy result
+   */
+  execute(
+    query: string,
+    engineIds: EngineId[],
+    options: SearchQuery,
+    context: StrategyContext,
+  ): Promise<StrategyResult>;
+}