github-to-mcp-monorepo 1.0.0

package/packages/core/src/cache/cache-interface.ts

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Cache interface for pluggable cache backends
+ * @copyright Copyright (c) 2024-2026 nirholas
+ * @license MIT
+ */
+
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry<T = unknown> {
+  /** The cached data */
+  data: T;
+  /** Timestamp when the entry was created (ms since epoch) */
+  timestamp: number;
+  /** Time-to-live in seconds */
+  ttl: number;
+  /** Optional ETag for HTTP caching */
+  etag?: string;
+  /** Optional version for cache invalidation */
+  version?: string;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  /** Number of cache hits */
+  hits: number;
+  /** Number of cache misses */
+  misses: number;
+  /** Number of entries in cache */
+  size: number;
+  /** Total bytes used (if available) */
+  bytes?: number;
+  /** Cache hit ratio */
+  hitRatio: number;
+}
+
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+  /** Default TTL in seconds */
+  defaultTTL?: number;
+  /** Maximum entries (for memory cache) */
+  maxEntries?: number;
+  /** Prefix for cache keys */
+  keyPrefix?: string;
+  /** Enable stale-while-revalidate */
+  staleWhileRevalidate?: boolean;
+  /** Stale tolerance (multiple of TTL) */
+  staleTolerance?: number;
+  /** Serializer for complex objects */
+  serializer?: CacheSerializer;
+}
+
+/**
+ * Custom serializer interface
+ */
+export interface CacheSerializer {
+  serialize<T>(data: T): string;
+  deserialize<T>(data: string): T;
+}
+
+/**
+ * Default JSON serializer
+ */
+export const defaultSerializer: CacheSerializer = {
+  serialize: <T>(data: T) => JSON.stringify(data),
+  deserialize: <T>(data: string) => JSON.parse(data) as T
+};
+
+/**
+ * Base cache interface that all cache implementations must follow
+ */
+export interface CacheInterface {
+  /**
+   * Get a cached value
+   * @param key - Cache key
+   * @returns The cached entry or null if not found/expired
+   */
+  get<T>(key: string): Promise<CacheEntry<T> | null>;
+
+  /**
+   * Set a cached value
+   * @param key - Cache key
+   * @param entry - The entry to cache
+   */
+  set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+
+  /**
+   * Delete a cached value
+   * @param key - Cache key
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Clear all cached values
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Check if a key exists
+   * @param key - Cache key
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * Get multiple values at once
+   * @param keys - Array of cache keys
+   */
+  getMany<T>(keys: string[]): Promise<Map<string, CacheEntry<T> | null>>;
+
+  /**
+   * Set multiple values at once
+   * @param entries - Map of key to entry
+   */
+  setMany<T>(entries: Map<string, CacheEntry<T>>): Promise<void>;
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): Promise<CacheStats>;
+
+  /**
+   * Close the cache connection (for Redis, etc.)
+   */
+  close?(): Promise<void>;
+}
+
+/**
+ * Helper to check if a cache entry is fresh
+ */
+export function isFresh(entry: CacheEntry): boolean {
+  const age = Date.now() - entry.timestamp;
+  return age < entry.ttl * 1000;
+}
+
+/**
+ * Helper to check if a cache entry is stale but within tolerance
+ */
+export function isStale(entry: CacheEntry, tolerance: number = 2): boolean {
+  const age = Date.now() - entry.timestamp;
+  return age >= entry.ttl * 1000 && age < entry.ttl * tolerance * 1000;
+}
+
+/**
+ * Helper to create a cache entry
+ */
+export function createCacheEntry<T>(data: T, ttl: number, etag?: string): CacheEntry<T> {
+  return {
+    data,
+    timestamp: Date.now(),
+    ttl,
+    etag
+  };
+}
+
+/**
+ * Cache key generator helper
+ */
+export function generateCacheKey(parts: string[], prefix?: string): string {
+  const key = parts.filter(Boolean).join(':');
+  return prefix ? `${prefix}:${key}` : key;
+}
+
+/**
+ * Type guard to check if an object is a CacheInterface
+ */
+export function isCacheInterface(obj: unknown): obj is CacheInterface {
+  if (!obj || typeof obj !== 'object') return false;
+  const cache = obj as CacheInterface;
+  return (
+    typeof cache.get === 'function' &&
+    typeof cache.set === 'function' &&
+    typeof cache.delete === 'function' &&
+    typeof cache.clear === 'function'
+  );
+}

package/packages/core/src/cache/index.ts

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Cache module exports
+ * @copyright Copyright (c) 2024-2026 nirholas
+ * @license MIT
+ */
+
+// Export interfaces and types
+export {
+  CacheInterface,
+  CacheEntry,
+  CacheStats,
+  CacheConfig,
+  CacheSerializer,
+  defaultSerializer,
+  isFresh,
+  isStale,
+  createCacheEntry,
+  generateCacheKey,
+  isCacheInterface
+} from './cache-interface';
+
+// Export Redis cache
+export {
+  RedisCache,
+  RedisCacheConfig,
+  RedisClientInterface,
+  createRedisCache,
+  createRedisCacheFromUrl
+} from './redis-cache';
+
+// Export Upstash cache
+export {
+  UpstashCache,
+  UpstashCacheConfig,
+  createUpstashCache,
+  createUpstashCacheFromEnv
+} from './upstash-cache';
+
+// Re-export memory cache from parent
+import { MemoryCacheAdapter, GitHubCache, DEFAULT_TTL } from '../cache';
+export { MemoryCacheAdapter, GitHubCache, DEFAULT_TTL };
+
+import type { CacheInterface, CacheConfig } from './cache-interface';
+import type { RedisCacheConfig, RedisClientInterface } from './redis-cache';
+import type { UpstashCacheConfig } from './upstash-cache';
+
+/**
+ * Cache backend types
+ */
+export type CacheBackend = 'memory' | 'redis' | 'upstash';
+
+/**
+ * Unified cache factory configuration
+ */
+export interface CacheFactoryConfig {
+  backend: CacheBackend;
+  /** Redis-specific configuration */
+  redis?: {
+    client: RedisClientInterface;
+  } & Omit<RedisCacheConfig, 'client'>;
+  /** Upstash-specific configuration */
+  upstash?: {
+    url: string;
+    token: string;
+  } & Omit<UpstashCacheConfig, 'url' | 'token'>;
+  /** Common cache options */
+  options?: CacheConfig;
+}
+
+/**
+ * Create a cache instance based on configuration
+ */
+export function createCache(config: CacheFactoryConfig): CacheInterface {
+  const { backend, redis, upstash, options } = config;
+
+  switch (backend) {
+    case 'memory':
+      // Return memory cache wrapped as CacheInterface
+      return new MemoryCacheWrapper(options);
+
+    case 'redis':
+      if (!redis?.client) {
+        throw new Error('Redis client is required for redis backend');
+      }
+      const { createRedisCache } = require('./redis-cache');
+      return createRedisCache({
+        ...options,
+        ...redis
+      });
+
+    case 'upstash':
+      if (!upstash?.url || !upstash?.token) {
+        // Try environment variables
+        const url = upstash?.url || process.env.UPSTASH_REDIS_REST_URL;
+        const token = upstash?.token || process.env.UPSTASH_REDIS_REST_TOKEN;
+
+        if (!url || !token) {
+          throw new Error('Upstash URL and token are required for upstash backend');
+        }
+
+        const { createUpstashCache } = require('./upstash-cache');
+        return createUpstashCache({
+          url,
+          token,
+          ...options,
+          ...upstash
+        });
+      }
+
+      const { createUpstashCache: createUpstash } = require('./upstash-cache');
+      return createUpstash({
+        ...options,
+        ...upstash
+      });
+
+    default:
+      throw new Error(`Unknown cache backend: ${backend}`);
+  }
+}
+
+/**
+ * Memory cache wrapper that implements CacheInterface
+ */
+class MemoryCacheWrapper implements CacheInterface {
+  private cache: Map<string, any> = new Map();
+  private config: CacheConfig;
+  private stats = { hits: 0, misses: 0 };
+
+  constructor(config?: CacheConfig) {
+    this.config = {
+      defaultTTL: 3600,
+      maxEntries: 1000,
+      ...config
+    };
+  }
+
+  async get<T>(key: string): Promise<{ data: T; timestamp: number; ttl: number } | null> {
+    const prefixedKey = this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key;
+    const entry = this.cache.get(prefixedKey);
+
+    if (!entry) {
+      this.stats.misses++;
+      return null;
+    }
+
+    // Check expiration
+    if (Date.now() - entry.timestamp > entry.ttl * 1000) {
+      this.cache.delete(prefixedKey);
+      this.stats.misses++;
+      return null;
+    }
+
+    this.stats.hits++;
+    return entry;
+  }
+
+  async set<T>(key: string, entry: { data: T; timestamp: number; ttl: number }): Promise<void> {
+    const prefixedKey = this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key;
+
+    // Enforce max entries
+    if (this.config.maxEntries && this.cache.size >= this.config.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(prefixedKey, entry);
+  }
+
+  async delete(key: string): Promise<void> {
+    const prefixedKey = this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key;
+    this.cache.delete(prefixedKey);
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+    this.stats = { hits: 0, misses: 0 };
+  }
+
+  async has(key: string): Promise<boolean> {
+    const prefixedKey = this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key;
+    return this.cache.has(prefixedKey);
+  }
+
+  async getMany<T>(keys: string[]): Promise<Map<string, { data: T; timestamp: number; ttl: number } | null>> {
+    const result = new Map();
+    for (const key of keys) {
+      result.set(key, await this.get<T>(key));
+    }
+    return result;
+  }
+
+  async setMany<T>(entries: Map<string, { data: T; timestamp: number; ttl: number }>): Promise<void> {
+    for (const [key, entry] of entries) {
+      await this.set(key, entry);
+    }
+  }
+
+  async getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    return {
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      size: this.cache.size,
+      hitRatio: total > 0 ? this.stats.hits / total : 0
+    };
+  }
+}

package/packages/core/src/cache/redis-cache.ts

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview Redis cache implementation
+ * @copyright Copyright (c) 2024-2026 nirholas
+ * @license MIT
+ */
+
+import type {
+  CacheInterface,
+  CacheEntry,
+  CacheStats,
+  CacheConfig,
+  CacheSerializer
+} from './cache-interface';
+import { defaultSerializer, generateCacheKey } from './cache-interface';
+
+/**
+ * Redis client interface (compatible with ioredis and node-redis)
+ */
+export interface RedisClientInterface {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: any[]): Promise<any>;
+  del(key: string | string[]): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+  exists(key: string | string[]): Promise<number>;
+  mget(...keys: string[]): Promise<(string | null)[]>;
+  mset(...keysAndValues: string[]): Promise<any>;
+  flushdb?(): Promise<any>;
+  quit(): Promise<any>;
+  info?(section?: string): Promise<string>;
+  dbsize?(): Promise<number>;
+}
+
+/**
+ * Redis cache configuration
+ */
+export interface RedisCacheConfig extends CacheConfig {
+  /** Redis client instance */
+  client: RedisClientInterface;
+  /** Key prefix for namespacing */
+  keyPrefix?: string;
+  /** Use SETEX for automatic expiration */
+  useExpiration?: boolean;
+}
+
+/**
+ * Redis-based cache implementation
+ */
+export class RedisCache implements CacheInterface {
+  private client: RedisClientInterface;
+  private config: RedisCacheConfig;
+  private serializer: CacheSerializer;
+  private stats: { hits: number; misses: number };
+
+  constructor(config: RedisCacheConfig) {
+    this.client = config.client;
+    this.config = {
+      keyPrefix: 'mcp-cache',
+      defaultTTL: 3600,
+      useExpiration: true,
+      ...config
+    };
+    this.serializer = config.serializer || defaultSerializer;
+    this.stats = { hits: 0, misses: 0 };
+  }
+
+  /**
+   * Generate prefixed key
+   */
+  private prefixKey(key: string): string {
+    return this.config.keyPrefix ? `${this.config.keyPrefix}:${key}` : key;
+  }
+
+  /**
+   * Get a cached value
+   */
+  async get<T>(key: string): Promise<CacheEntry<T> | null> {
+    const prefixedKey = this.prefixKey(key);
+
+    try {
+      const value = await this.client.get(prefixedKey);
+
+      if (!value) {
+        this.stats.misses++;
+        return null;
+      }
+
+      const entry = this.serializer.deserialize<CacheEntry<T>>(value);
+
+      // Check if entry is expired (in case TTL wasn't set in Redis)
+      if (Date.now() - entry.timestamp > entry.ttl * 1000) {
+        this.stats.misses++;
+        // Delete expired entry
+        await this.delete(key);
+        return null;
+      }
+
+      this.stats.hits++;
+      return entry;
+    } catch (error) {
+      this.stats.misses++;
+      return null;
+    }
+  }
+
+  /**
+   * Set a cached value
+   */
+  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
+    const prefixedKey = this.prefixKey(key);
+    const serialized = this.serializer.serialize(entry);
+
+    if (this.config.useExpiration && entry.ttl > 0) {
+      // Use SETEX or SET with EX option for automatic expiration
+      // Add extra time for stale-while-revalidate if enabled
+      const expirationSeconds = this.config.staleWhileRevalidate
+        ? Math.ceil(entry.ttl * (this.config.staleTolerance || 2))
+        : entry.ttl;
+
+      await this.client.set(prefixedKey, serialized, 'EX', expirationSeconds);
+    } else {
+      await this.client.set(prefixedKey, serialized);
+    }
+  }
+
+  /**
+   * Delete a cached value
+   */
+  async delete(key: string): Promise<void> {
+    const prefixedKey = this.prefixKey(key);
+    await this.client.del(prefixedKey);
+  }
+
+  /**
+   * Clear all cached values with the prefix
+   */
+  async clear(): Promise<void> {
+    const pattern = this.config.keyPrefix ? `${this.config.keyPrefix}:*` : '*';
+    const keys = await this.client.keys(pattern);
+
+    if (keys.length > 0) {
+      // Delete in batches to avoid blocking
+      const batchSize = 1000;
+      for (let i = 0; i < keys.length; i += batchSize) {
+        const batch = keys.slice(i, i + batchSize);
+        await this.client.del(batch);
+      }
+    }
+
+    // Reset stats
+    this.stats = { hits: 0, misses: 0 };
+  }
+
+  /**
+   * Check if a key exists
+   */
+  async has(key: string): Promise<boolean> {
+    const prefixedKey = this.prefixKey(key);
+    const exists = await this.client.exists(prefixedKey);
+    return exists > 0;
+  }
+
+  /**
+   * Get multiple values at once
+   */
+  async getMany<T>(keys: string[]): Promise<Map<string, CacheEntry<T> | null>> {
+    const result = new Map<string, CacheEntry<T> | null>();
+
+    if (keys.length === 0) {
+      return result;
+    }
+
+    const prefixedKeys = keys.map(k => this.prefixKey(k));
+    const values = await this.client.mget(...prefixedKeys);
+
+    keys.forEach((key, index) => {
+      const value = values[index];
+      if (value) {
+        try {
+          const entry = this.serializer.deserialize<CacheEntry<T>>(value);
+          if (Date.now() - entry.timestamp <= entry.ttl * 1000) {
+            this.stats.hits++;
+            result.set(key, entry);
+          } else {
+            this.stats.misses++;
+            result.set(key, null);
+          }
+        } catch {
+          this.stats.misses++;
+          result.set(key, null);
+        }
+      } else {
+        this.stats.misses++;
+        result.set(key, null);
+      }
+    });
+
+    return result;
+  }
+
+  /**
+   * Set multiple values at once
+   */
+  async setMany<T>(entries: Map<string, CacheEntry<T>>): Promise<void> {
+    if (entries.size === 0) {
+      return;
+    }
+
+    // For entries with TTL, we need to set them individually to use SETEX
+    if (this.config.useExpiration) {
+      const promises = Array.from(entries.entries()).map(([key, entry]) =>
+        this.set(key, entry)
+      );
+      await Promise.all(promises);
+    } else {
+      // Use MSET for entries without TTL
+      const args: string[] = [];
+      entries.forEach((entry, key) => {
+        args.push(this.prefixKey(key), this.serializer.serialize(entry));
+      });
+      await this.client.mset(...args);
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  async getStats(): Promise<CacheStats> {
+    const pattern = this.config.keyPrefix ? `${this.config.keyPrefix}:*` : '*';
+    let size = 0;
+    let bytes: number | undefined;
+
+    try {
+      if (this.client.dbsize) {
+        size = await this.client.dbsize();
+      } else {
+        const keys = await this.client.keys(pattern);
+        size = keys.length;
+      }
+
+      // Try to get memory usage if available
+      if (this.client.info) {
+        const info = await this.client.info('memory');
+        const match = info.match(/used_memory:(\d+)/);
+        if (match) {
+          bytes = parseInt(match[1], 10);
+        }
+      }
+    } catch {
+      // Ignore stats errors
+    }
+
+    const total = this.stats.hits + this.stats.misses;
+
+    return {
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      size,
+      bytes,
+      hitRatio: total > 0 ? this.stats.hits / total : 0
+    };
+  }
+
+  /**
+   * Close the Redis connection
+   */
+  async close(): Promise<void> {
+    await this.client.quit();
+  }
+}
+
+/**
+ * Create a Redis cache instance
+ */
+export function createRedisCache(config: RedisCacheConfig): RedisCache {
+  return new RedisCache(config);
+}
+
+/**
+ * Helper to create Redis cache from connection URL
+ * Note: This is a stub - actual implementation depends on the Redis client library used
+ */
+export async function createRedisCacheFromUrl(
+  url: string,
+  options?: Omit<RedisCacheConfig, 'client'>
+): Promise<RedisCache> {
+  // This would need ioredis or node-redis to be installed
+  throw new Error(
+    'createRedisCacheFromUrl requires a Redis client library. ' +
+    'Please install ioredis or redis and pass the client directly.'
+  );
+}