ubersearch 0.0.0-development

package/src/core/container.ts

@@ -0,0 +1,268 @@
+/**
+ * Dependency Injection Container
+ *
+ * Central service locator that manages service registration and resolution.
+ * Implements factory pattern with singleton and transient lifetimes.
+ *
+ * @module core/container
+ */
+
+/**
+ * Service identifier - can be string or Symbol for unique identification
+ */
+export type ServiceIdentifier<_T = unknown> = string | symbol;
+
+/**
+ * Container binding configuration
+ */
+export interface ContainerBinding<T> {
+  /** Factory function that creates service instance */
+  factory: (container: Container) => T;
+  /** Whether service should be singleton (cached) */
+  singleton: boolean;
+  /** Cached instance for singleton services */
+  cached?: T;
+}
+
+/**
+ * Dependency Injection Container
+ *
+ * Manages service registration and resolution with support for:
+ * - Singleton and transient lifetimes
+ * - Circular dependency detection
+ * - Type-safe resolution
+ * - Factory pattern for lazy instantiation
+ *
+ * @example
+ * ```typescript
+ * const container = new Container();
+ *
+ * // Register singleton service
+ * container.singleton('config', () => loadConfig());
+ *
+ * // Register transient service
+ * container.bind('strategy', (c) => new SearchStrategy(c.get('config')));
+ *
+ * // Resolve service
+ * const config = container.get<Config>('config');
+ * ```
+ */
+export class Container {
+  /** Internal storage for service bindings */
+  private bindings = new Map<ServiceIdentifier, ContainerBinding<unknown>>();
+
+  /** Stack to detect circular dependencies during resolution */
+  private resolutionStack = new Set<ServiceIdentifier>();
+
+  /**
+   * Register a transient service (new instance each time)
+   *
+   * @param id - Service identifier
+   * @param factory - Factory function that creates the service
+   * @template T - Service type
+   *
+   * @example
+   * ```typescript
+   * container.bind('searchStrategy', (c) => new AllProvidersStrategy());
+   * ```
+   */
+  bind<T>(id: ServiceIdentifier<T>, factory: (container: Container) => T): void {
+    this.bindings.set(id, {
+      factory,
+      singleton: false,
+    });
+  }
+
+  /**
+   * Register a singleton service (cached instance)
+   *
+   * @param id - Service identifier
+   * @param factory - Factory function that creates the service
+   * @template T - Service type
+   *
+   * @example
+   * ```typescript
+   * container.singleton('config', () => loadConfiguration());
+   * container.singleton('creditManager', (c) => new CreditManager(
+   *   c.get('engines'),
+   *   c.get('creditProvider')
+   * ));
+   * ```
+   */
+  singleton<T>(id: ServiceIdentifier<T>, factory: (container: Container) => T): void {
+    this.bindings.set(id, {
+      factory,
+      singleton: true,
+    });
+  }
+
+  /**
+   * Resolve a service instance
+   *
+   * @param id - Service identifier
+   * @returns Service instance
+   * @template T - Service type
+   * @throws {Error} If service is not registered or circular dependency detected
+   *
+   * @example
+   * ```typescript
+   * const config = container.get<Config>('config');
+   * const manager = container.get<CreditManager>('creditManager');
+   * ```
+   */
+  get<T>(id: ServiceIdentifier<T>): T {
+    // Check for circular dependency
+    if (this.resolutionStack.has(id)) {
+      const chain = [...this.resolutionStack, id].map(String).join(" -> ");
+      throw new Error(`Circular dependency detected: ${chain}`);
+    }
+
+    const binding = this.bindings.get(id);
+    if (!binding) {
+      const registered = Array.from(this.bindings.keys()).map(String);
+      throw new Error(
+        `No binding found for '${String(id)}'. Registered services: [${registered.join(", ")}]`,
+      );
+    }
+
+    // Handle singleton caching
+    if (binding.singleton && binding.cached !== undefined) {
+      return binding.cached;
+    }
+
+    // Track resolution for circular dependency detection
+    this.resolutionStack.add(id);
+
+    try {
+      // Create instance using factory
+      const instance = binding.factory(this);
+
+      // Cache singleton instances
+      if (binding.singleton) {
+        binding.cached = instance;
+      }
+
+      return instance;
+    } catch (error) {
+      // Enhance error message with context
+      if (error instanceof Error) {
+        throw new Error(`Failed to resolve service '${String(id)}': ${error.message}`);
+      }
+      throw error;
+    } finally {
+      // Clean up resolution stack
+      this.resolutionStack.delete(id);
+    }
+  }
+
+  /**
+   * Check if a service is registered
+   *
+   * @param id - Service identifier
+   * @returns true if service is registered
+   *
+   * @example
+   * ```typescript
+   * if (container.has('optionalService')) {
+   *   const service = container.get('optionalService');
+   * }
+   * ```
+   */
+  has(id: ServiceIdentifier): boolean {
+    return this.bindings.has(id);
+  }
+
+  /**
+   * Remove a service binding
+   *
+   * @param id - Service identifier to remove
+   * @returns true if binding was removed, false if it didn't exist
+   *
+   * @example
+   * ```typescript
+   * container.unbind('oldService');
+   * ```
+   */
+  unbind(id: ServiceIdentifier): boolean {
+    return this.bindings.delete(id);
+  }
+
+  /**
+   * Clear all service bindings
+   * Useful for testing or resetting container state
+   *
+   * @example
+   * ```typescript
+   * container.reset();
+   * // Container is now empty
+   * ```
+   */
+  reset(): void {
+    this.bindings.clear();
+    this.resolutionStack.clear();
+  }
+
+  /**
+   * Get list of all registered service identifiers
+   *
+   * @returns Array of service identifiers
+   *
+   * @example
+   * ```typescript
+   * const services = container.getRegisteredServices();
+   * console.log('Available services:', services);
+   * ```
+   */
+  getRegisteredServices(): ServiceIdentifier[] {
+    return Array.from(this.bindings.keys());
+  }
+
+  /**
+   * Get service information including lifetime and factory details
+   * Useful for debugging and introspection
+   *
+   * @param id - Service identifier
+   * @returns Service information or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const info = container.getServiceInfo('config');
+   * console.log('Service lifetime:', info?.singleton ? 'singleton' : 'transient');
+   * ```
+   */
+  getServiceInfo(id: ServiceIdentifier):
+    | {
+        singleton: boolean;
+        cached: boolean;
+        factory: (container: Container) => unknown;
+      }
+    | undefined {
+    const binding = this.bindings.get(id);
+    if (!binding) {
+      return undefined;
+    }
+
+    return {
+      singleton: binding.singleton,
+      cached: binding.cached !== undefined,
+      factory: binding.factory,
+    };
+  }
+}
+
+/**
+ * Global container instance for convenience
+ * Use this for application-wide dependency injection
+ *
+ * @example
+ * ```typescript
+ * import { container } from './core/container';
+ *
+ * // Register services globally
+ * container.singleton('config', () => loadConfig());
+ *
+ * // Use in any module
+ * const config = container.get<Config>('config');
+ * ```
+ */
+export const container = new Container();

package/src/core/credits/CreditManager.ts

@@ -0,0 +1,158 @@
+/**
+ * Credit management system for tracking usage across providers
+ * Refactored to use dependency injection - no file I/O dependencies
+ */
+
+import type { EngineConfig } from "../../config/types";
+import type { EngineId } from "../types";
+import type { CreditState, CreditStateProvider } from "./CreditStateProvider";
+
+export interface CreditSnapshot {
+  engineId: EngineId;
+  quota: number;
+  used: number;
+  remaining: number;
+  isExhausted: boolean;
+}
+
+export class CreditManager {
+  private engines: Map<EngineId, EngineConfig>;
+  private state: CreditState = {};
+
+  constructor(
+    engines: EngineConfig[],
+    private stateProvider: CreditStateProvider,
+  ) {
+    this.engines = new Map(engines.map((e) => [e.id, e]));
+  }
+
+  /**
+   * Initialize the credit manager by loading state from provider
+   * Must be called after construction
+   */
+  async initialize(): Promise<void> {
+    this.state = await this.stateProvider.loadState();
+    await this.resetIfNeeded();
+  }
+
+  /**
+   * Check if we need to reset monthly usage (first day of month)
+   */
+  private async resetIfNeeded(): Promise<void> {
+    const now = new Date();
+    const currentMonth = now.toISOString().slice(0, 7); // YYYY-MM
+
+    for (const [engineId, _config] of this.engines) {
+      const record = this.state[engineId];
+
+      if (!record) {
+        this.state[engineId] = {
+          used: 0,
+          lastReset: now.toISOString(),
+        };
+        continue;
+      }
+
+      const lastResetMonth = record.lastReset.slice(0, 7);
+      if (lastResetMonth !== currentMonth) {
+        // New month - reset counter
+        record.used = 0;
+        record.lastReset = now.toISOString();
+      }
+    }
+
+    await this.stateProvider.saveState(this.state);
+  }
+
+  /**
+   * Deduct credits for a search (synchronous version for immediate checks)
+   * @returns true if successful, false if exhausted
+   * @note This does NOT persist the state - call saveState() separately
+   */
+  charge(engineId: EngineId): boolean {
+    const config = this.engines.get(engineId);
+    if (!config) {
+      throw new Error(`Unknown engine: ${engineId}`);
+    }
+
+    const record = this.state[engineId];
+    if (!record) {
+      throw new Error(`No credit record for engine: ${engineId}`);
+    }
+
+    if (record.used + config.creditCostPerSearch > config.monthlyQuota) {
+      return false; // Exhausted
+    }
+
+    record.used += config.creditCostPerSearch;
+    return true;
+  }
+
+  /**
+   * Deduct credits for a search and persist state
+   * @returns true if successful, false if exhausted
+   */
+  async chargeAndSave(engineId: EngineId): Promise<boolean> {
+    const result = this.charge(engineId);
+    if (result) {
+      await this.stateProvider.saveState(this.state);
+    }
+    return result;
+  }
+
+  /**
+   * Check if engine has sufficient credits
+   */
+  hasSufficientCredits(engineId: EngineId): boolean {
+    const config = this.engines.get(engineId);
+    if (!config) {
+      return false;
+    }
+
+    const record = this.state[engineId];
+    if (!record) {
+      return true; // No usage yet
+    }
+
+    return record.used + config.creditCostPerSearch <= config.monthlyQuota;
+  }
+
+  /**
+   * Get credit snapshot for an engine
+   */
+  getSnapshot(engineId: EngineId): CreditSnapshot {
+    const config = this.engines.get(engineId);
+    if (!config) {
+      throw new Error(`Unknown engine: ${engineId}`);
+    }
+
+    const record = this.state[engineId] ?? {
+      used: 0,
+      lastReset: new Date().toISOString(),
+    };
+
+    const remaining = Math.max(0, config.monthlyQuota - record.used);
+
+    return {
+      engineId,
+      quota: config.monthlyQuota,
+      used: record.used,
+      remaining,
+      isExhausted: remaining < config.creditCostPerSearch,
+    };
+  }
+
+  /**
+   * Save current state to persistence layer
+   */
+  async saveState(): Promise<void> {
+    await this.stateProvider.saveState(this.state);
+  }
+
+  /**
+   * Get snapshots for all engines
+   */
+  listSnapshots(): CreditSnapshot[] {
+    return Array.from(this.engines.keys()).map((id) => this.getSnapshot(id));
+  }
+}

package/src/core/credits/CreditStateProvider.ts

@@ -0,0 +1,151 @@
+/**
+ * Credit state persistence abstraction layer
+ *
+ * This module defines interfaces for credit state persistence operations,
+ * separating persistence concerns from business logic. Enables unit testing
+ * without file I/O and supports multiple persistence implementations.
+ *
+ * @module credits/CreditStateProvider
+ */
+
+import type { EngineId } from "../types";
+
+/**
+ * Represents the persistent state of credit usage for search engines.
+ * Maps engine IDs to their usage tracking data.
+ *
+ * @interface CreditState
+ */
+export interface CreditState {
+  /**
+   * Maps engine identifiers to their credit usage information.
+   * Each entry tracks the total credits used and the last reset timestamp.
+   */
+  [engineId: EngineId]: {
+    /**
+     * Total number of credits used by this engine in the current billing period.
+     */
+    used: number;
+
+    /**
+     * ISO 8601 date string indicating when the credits were last reset.
+     * Used to determine when monthly quotas should be refreshed.
+     */
+    lastReset: string;
+  };
+}
+
+/**
+ * Abstraction for credit state persistence operations.
+ *
+ * This interface defines the contract for loading, saving, and checking
+ * the existence of credit state data. Implementations can use various
+ * persistence mechanisms (file system, memory, database, etc.) while
+ * maintaining the same API for the business logic layer.
+ *
+ * All methods are asynchronous to support both synchronous and
+ * asynchronous persistence backends without blocking the main thread.
+ *
+ * @interface CreditStateProvider
+ *
+ * @example
+ * ```typescript
+ * // File-based implementation
+ * class FileCreditStateProvider implements CreditStateProvider {
+ *   async loadState(): Promise<CreditState> {
+ *     const data = await fs.readFile(this.filePath, 'utf8');
+ *     return JSON.parse(data);
+ *   }
+ *
+ *   async saveState(state: CreditState): Promise<void> {
+ *     await fs.writeFile(this.filePath, JSON.stringify(state));
+ *   }
+ *
+ *   async stateExists(): Promise<boolean> {
+ *     return fs.exists(this.filePath);
+ *   }
+ * }
+ *
+ * // Memory-based implementation for testing
+ * class MemoryCreditStateProvider implements CreditStateProvider {
+ *   private state: CreditState = {};
+ *
+ *   async loadState(): Promise<CreditState> {
+ *     return { ...this.state };
+ *   }
+ *
+ *   async saveState(state: CreditState): Promise<void> {
+ *     this.state = { ...state };
+ *   }
+ *
+ *   async stateExists(): Promise<boolean> {
+ *     return Object.keys(this.state).length > 0;
+ *   }
+ * }
+ * ```
+ */
+export interface CreditStateProvider {
+  /**
+   * Load the current credit state from persistence.
+   *
+   * @returns Promise resolving to the current credit state.
+   *          Returns empty object `{}` if no state exists.
+   *
+   * @throws May throw errors related to persistence layer failures
+   *         (file system errors, network issues, etc.).
+   *
+   * @example
+   * ```typescript
+   * const provider = new FileCreditStateProvider();
+   * const state = await provider.loadState();
+   * console.log(`Loaded state for ${Object.keys(state).length} engines`);
+   * ```
+   */
+  loadState(): Promise<CreditState>;
+
+  /**
+   * Save the credit state to persistence.
+   *
+   * @param state - The credit state to persist.
+   *                Should be a complete snapshot of current usage.
+   *
+   * @returns Promise that resolves when the state has been successfully saved.
+   *
+   * @throws May throw errors related to persistence layer failures
+   *         (file system errors, network issues, permission errors, etc.).
+   *
+   * @example
+   * ```typescript
+   * const newState: CreditState = {
+   *   'google': { used: 50, lastReset: '2024-01-15T10:30:00.000Z' },
+   *   'bing': { used: 25, lastReset: '2024-01-15T10:30:00.000Z' }
+   * };
+   * await provider.saveState(newState);
+   * ```
+   */
+  saveState(state: CreditState): Promise<void>;
+
+  /**
+   * Check if credit state exists in persistence.
+   *
+   * Used to determine whether to load existing state or initialize
+   * with default values.
+   *
+   * @returns Promise resolving to true if state exists in persistence,
+   *          false otherwise.
+   *
+   * @throws May throw errors related to persistence layer failures.
+   *
+   * @example
+   * ```typescript
+   * if (await provider.stateExists()) {
+   *   const state = await provider.loadState();
+   *   // Process existing state
+   * } else {
+   *   // Initialize with default state
+   *   await provider.saveState({});
+   * }
+   * ```
+   */
+  stateExists(): Promise<boolean>;
+}

package/src/core/credits/FileCreditStateProvider.ts

@@ -0,0 +1,137 @@
+/**
+ * File-based implementation of CreditStateProvider
+ * Handles file I/O operations for credit state persistence using Bun's async APIs
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createLogger } from "../logger";
+import type { CreditState, CreditStateProvider } from "./CreditStateProvider";
+
+const log = createLogger("CreditState");
+
+/**
+ * File-based persistence implementation of CreditStateProvider.
+ * Manages credit state storage using the local filesystem with async I/O.
+ *
+ * @remarks
+ * This provider stores credit state as JSON in the following locations:
+ * - Default: ~/.local/state/allsearch/credits.json
+ * - With XDG_STATE_HOME: $XDG_STATE_HOME/allsearch/credits.json
+ *
+ * Uses Bun's async file APIs for non-blocking I/O operations.
+ * The provider handles directory creation automatically and never throws errors,
+ * instead logging warnings and returning sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const provider = new FileCreditStateProvider();
+ * const state = await provider.loadState();
+ * await provider.saveState(newState);
+ * ```
+ */
+export class FileCreditStateProvider implements CreditStateProvider {
+  private readonly statePath: string;
+
+  /**
+   * Creates a new FileCreditStateProvider instance.
+   *
+   * @param statePath - Optional custom path for the state file.
+   *                   If not provided, uses the default location based on
+   *                   XDG_STATE_HOME or ~/.local/state/allsearch/credits.json
+   */
+  constructor(statePath?: string) {
+    this.statePath = statePath ?? this.getDefaultStatePath();
+  }
+
+  /**
+   * Gets the default state file path following XDG Base Directory Specification.
+   *
+   * @returns The resolved state file path
+   * @private
+   */
+  private getDefaultStatePath(): string {
+    const base = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(base, "allsearch", "credits.json");
+  }
+
+  /**
+   * Load credit state from the file system using async I/O.
+   *
+   * @returns The loaded credit state, or an empty object if the file doesn't exist
+   *          or cannot be parsed
+   *
+   * @remarks
+   * This method never throws. If the file doesn't exist, an empty state is returned.
+   * If the file exists but cannot be parsed, a warning is logged and an empty state
+   * is returned. Uses Bun.file() for non-blocking file reads.
+   */
+  async loadState(): Promise<CreditState> {
+    const file = Bun.file(this.statePath);
+
+    // Check if file exists
+    if (!(await file.exists())) {
+      return {};
+    }
+
+    try {
+      const raw = await file.text();
+      return JSON.parse(raw) as CreditState;
+    } catch (error) {
+      log.warn(`Failed to load credit state from ${this.statePath}:`, error);
+      return {};
+    }
+  }
+
+  /**
+   * Save credit state to the file system using async I/O.
+   *
+   * @param state - The credit state to save
+   *
+   * @remarks
+   * This method never throws. If the directory doesn't exist, it will be created
+   * recursively. If saving fails, a warning is logged but no error is thrown.
+   * Uses Bun.write() for non-blocking file writes.
+   */
+  async saveState(state: CreditState): Promise<void> {
+    try {
+      // Ensure parent directory exists
+      const { dirname } = await import("node:path");
+      const { mkdir } = await import("node:fs/promises");
+      const dir = dirname(this.statePath);
+
+      try {
+        await mkdir(dir, { recursive: true });
+      } catch (mkdirError) {
+        // Ignore EEXIST errors
+        if ((mkdirError as NodeJS.ErrnoException).code !== "EEXIST") {
+          throw mkdirError;
+        }
+      }
+
+      // Write file using Bun's async API
+      await Bun.write(this.statePath, JSON.stringify(state, null, 2));
+    } catch (error) {
+      log.warn(`Failed to save credit state to ${this.statePath}:`, error);
+    }
+  }
+
+  /**
+   * Check if the state file exists in the file system.
+   *
+   * @returns true if the state file exists, false otherwise
+   */
+  async stateExists(): Promise<boolean> {
+    const file = Bun.file(this.statePath);
+    return await file.exists();
+  }
+
+  /**
+   * Get the path where state is stored.
+   *
+   * @returns The absolute path to the state file
+   */
+  getStatePath(): string {
+    return this.statePath;
+  }
+}

package/src/core/credits/index.ts

@@ -0,0 +1,3 @@
+export * from "./CreditManager";
+export * from "./CreditStateProvider";
+export * from "./FileCreditStateProvider";