family-ai-agent 1.0.6 → 1.0.7

package/src/database/cache/cache-keys.ts

@@ -0,0 +1,150 @@
+/**
+ * Cache Key Generation
+ *
+ * Utilities for generating consistent cache keys.
+ */
+
+/**
+ * Generate a cache key from operation, table, and parameters
+ */
+export function generateCacheKey(
+  operation: string,
+  table: string,
+  params: Record<string, unknown>
+): string {
+  const sortedParams = Object.keys(params)
+    .sort()
+    .map((key) => `${key}:${JSON.stringify(params[key])}`)
+    .join('|');
+
+  return `${operation}:${table}:${sortedParams}`;
+}
+
+/**
+ * Cache key generators for common operations
+ */
+export const cacheKeys = {
+  /**
+   * Get conversation by thread ID
+   */
+  conversation: (threadId: string): string =>
+    generateCacheKey('get', 'conversations', { threadId }),
+
+  /**
+   * Get conversation by ID
+   */
+  conversationById: (id: string): string =>
+    generateCacheKey('get', 'conversations', { id }),
+
+  /**
+   * List messages for a conversation
+   */
+  messages: (conversationId: string, limit: number, offset: number): string =>
+    generateCacheKey('list', 'messages', { conversationId, limit, offset }),
+
+  /**
+   * Get document by ID
+   */
+  document: (id: string): string =>
+    generateCacheKey('get', 'documents', { id }),
+
+  /**
+   * List documents for a user
+   */
+  userDocuments: (userId: string, limit: number, offset: number): string =>
+    generateCacheKey('list', 'documents', { userId, limit, offset }),
+
+  /**
+   * Get memory by ID
+   */
+  memory: (id: string): string =>
+    generateCacheKey('get', 'long_term_memories', { id }),
+
+  /**
+   * List recent memories for a user
+   */
+  userMemories: (userId: string, limit: number): string =>
+    generateCacheKey('list', 'long_term_memories', { userId, limit }),
+
+  /**
+   * Vector search results
+   */
+  vectorSearch: (
+    embeddingHash: string,
+    options: Record<string, unknown>
+  ): string =>
+    generateCacheKey('search', 'embeddings', { hash: embeddingHash, ...options }),
+
+  /**
+   * Task by ID
+   */
+  task: (id: string): string =>
+    generateCacheKey('get', 'tasks', { id }),
+
+  /**
+   * List tasks for a user
+   */
+  userTasks: (userId: string, status: string, limit: number): string =>
+    generateCacheKey('list', 'tasks', { userId, status, limit }),
+};
+
+/**
+ * Invalidation patterns for write operations
+ */
+export const invalidationPatterns = {
+  /**
+   * Invalidate all conversation-related cache
+   */
+  conversation: (conversationId: string): RegExp =>
+    new RegExp(`conversations.*${conversationId}`),
+
+  /**
+   * Invalidate all message-related cache for a conversation
+   */
+  messages: (conversationId: string): RegExp =>
+    new RegExp(`messages.*${conversationId}`),
+
+  /**
+   * Invalidate all document-related cache
+   */
+  document: (documentId: string): RegExp =>
+    new RegExp(`documents.*${documentId}`),
+
+  /**
+   * Invalidate user's document list
+   */
+  userDocuments: (userId: string): string => `list:documents:userId:"${userId}"`,
+
+  /**
+   * Invalidate all memory-related cache
+   */
+  memory: (memoryId: string): RegExp =>
+    new RegExp(`long_term_memories.*${memoryId}`),
+
+  /**
+   * Invalidate user's memory list
+   */
+  userMemories: (userId: string): string =>
+    `list:long_term_memories:userId:"${userId}"`,
+
+  /**
+   * Invalidate all vector search results
+   */
+  vectorSearchAll: (): string => 'search:embeddings',
+
+  /**
+   * Invalidate all task-related cache
+   */
+  task: (taskId: string): RegExp => new RegExp(`tasks.*${taskId}`),
+
+  /**
+   * Invalidate user's task list
+   */
+  userTasks: (userId: string): string => `list:tasks:userId:"${userId}"`,
+};
+
+export default {
+  generateCacheKey,
+  cacheKeys,
+  invalidationPatterns,
+};

package/src/database/cache/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Cache Layer Exports
+ *
+ * Central export for query caching functionality.
+ */
+
+export { QueryCache } from './query-cache.js';
+export {
+  generateCacheKey,
+  cacheKeys,
+  invalidationPatterns,
+} from './cache-keys.js';
+
+import { QueryCache } from './query-cache.js';
+import type { QueryCacheOptions } from '../types.js';
+
+// Singleton cache instance
+let cacheInstance: QueryCache | null = null;
+
+/**
+ * Get the global query cache instance
+ */
+export function getQueryCache(options?: Partial<QueryCacheOptions>): QueryCache {
+  if (!cacheInstance) {
+    cacheInstance = new QueryCache(options);
+  }
+  return cacheInstance;
+}
+
+/**
+ * Reset the global cache instance
+ */
+export function resetQueryCache(): void {
+  if (cacheInstance) {
+    cacheInstance.clear();
+    cacheInstance = null;
+  }
+}
+
+export default {
+  QueryCache,
+  getQueryCache,
+  resetQueryCache,
+};

package/src/database/cache/query-cache.ts

@@ -0,0 +1,213 @@
+/**
+ * Query Cache
+ *
+ * LRU cache for database query results.
+ * Improves performance by avoiding redundant queries.
+ */
+
+import type { CacheStats, CacheEntry, QueryCacheOptions } from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('QueryCache');
+
+/**
+ * Default cache options
+ */
+const DEFAULT_OPTIONS: QueryCacheOptions = {
+  maxSize: 1000,
+  defaultTtlMs: 300000, // 5 minutes
+};
+
+/**
+ * LRU query cache
+ */
+export class QueryCache {
+  private cache: Map<string, CacheEntry<unknown>> = new Map();
+  private options: QueryCacheOptions;
+  private hitCount: number = 0;
+  private missCount: number = 0;
+
+  constructor(options: Partial<QueryCacheOptions> = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  /**
+   * Get value from cache
+   */
+  get<T>(key: string): T | undefined {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this.missCount++;
+      return undefined;
+    }
+
+    // Check expiration
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      this.missCount++;
+      return undefined;
+    }
+
+    // Update access metadata and move to end for LRU
+    entry.hits++;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    this.hitCount++;
+    return entry.value as T;
+  }
+
+  /**
+   * Set value in cache
+   */
+  set<T>(key: string, value: T, ttlMs?: number): void {
+    // Evict oldest if at capacity
+    if (this.cache.size >= this.options.maxSize && !this.cache.has(key)) {
+      this.evictLRU();
+    }
+
+    const entry: CacheEntry<T> = {
+      value,
+      expiresAt: Date.now() + (ttlMs ?? this.options.defaultTtlMs),
+      hits: 0,
+    };
+
+    // Delete first to ensure it's at the end
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+  }
+
+  /**
+   * Check if key exists (without updating access)
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Delete key from cache
+   */
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Invalidate entries matching a pattern
+   */
+  invalidate(pattern: string | RegExp): number {
+    let count = 0;
+    for (const key of this.cache.keys()) {
+      const matches =
+        typeof pattern === 'string'
+          ? key.includes(pattern)
+          : pattern.test(key);
+
+      if (matches) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      logger.debug('Cache invalidated', { pattern: String(pattern), count });
+    }
+
+    return count;
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    this.cache.clear();
+    logger.debug('Cache cleared');
+  }
+
+  /**
+   * Evict least recently used entry
+   */
+  private evictLRU(): void {
+    const firstKey = this.cache.keys().next().value;
+    if (firstKey) {
+      this.cache.delete(firstKey);
+    }
+  }
+
+  /**
+   * Remove expired entries
+   */
+  prune(): number {
+    const now = Date.now();
+    let count = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      logger.debug('Cache pruned', { removed: count });
+    }
+
+    return count;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const totalRequests = this.hitCount + this.missCount;
+
+    return {
+      size: this.cache.size,
+      maxSize: this.options.maxSize,
+      hitCount: this.hitCount,
+      missCount: this.missCount,
+      hitRate: totalRequests > 0 ? this.hitCount / totalRequests : 0,
+    };
+  }
+
+  /**
+   * Get cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.hitCount = 0;
+    this.missCount = 0;
+  }
+
+  /**
+   * Get or set pattern - fetch from cache or execute function and cache result
+   */
+  async getOrSet<T>(
+    key: string,
+    fn: () => Promise<T>,
+    ttlMs?: number
+  ): Promise<T> {
+    const cached = this.get<T>(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const result = await fn();
+    this.set(key, result, ttlMs);
+    return result;
+  }
+}
+
+export default QueryCache;

package/src/database/client.ts

@@ -1,103 +1,201 @@
+/**
+ * Database Client
+ *
+ * Unified database client with backward-compatible API.
+ * Automatically detects and uses PostgreSQL or SQLite.
+ */
+
 import pg from 'pg';
-import { getDatabaseUrl } from '../config/index.js';
+import { getAdapter, closeAdapter, isAdapterInitialized, getAdapterType } from './adapters/index.js';
+import { createMigrator } from './migrations/index.js';
+import { createHealthSystem } from './health/index.js';
+import { getDatabaseConfig } from './db-config.js';
+import type { DatabaseAdapter, QueryResult, TransactionClient } from './types.js';
 import { createLogger } from '../utils/logger.js';
 import { MemoryError } from '../utils/errors.js';
 
-const { Pool } = pg;
 const logger = createLogger('Database');
 
-let pool: pg.Pool | null = null;
-
-export function getPool(): pg.Pool {
-  if (!pool) {
-    pool = new Pool({
-      connectionString: getDatabaseUrl(),
-      max: 20,
-      idleTimeoutMillis: 30000,
-      connectionTimeoutMillis: 5000,
-    });
+// Health system instance
+let healthSystem: ReturnType<typeof createHealthSystem> | null = null;
 
-    pool.on('error', (err) => {
-      logger.error('Unexpected pool error', { error: err.message });
-    });
+/**
+ * Get the current database adapter
+ */
+async function getAdapterInstance(): Promise<DatabaseAdapter> {
+  return getAdapter();
+}
 
-    pool.on('connect', () => {
-      logger.debug('New client connected to pool');
-    });
+/**
+ * Get PostgreSQL pool (for backward compatibility)
+ * Returns null if using SQLite
+ */
+export function getPool(): pg.Pool | null {
+  if (getAdapterType() === 'postgresql') {
+    // Access the raw pool from PostgreSQL adapter
+    try {
+      const adapter = require('./adapters/postgres-adapter.js').PostgresAdapter;
+      // This is a simplified compatibility layer
+      return null; // Actual pool access requires async initialization
+    } catch {
+      return null;
+    }
   }
-
-  return pool;
+  return null;
 }
 
-export async function query<T extends pg.QueryResultRow = pg.QueryResultRow>(
+/**
+ * Execute a database query
+ * Compatible with both PostgreSQL and SQLite
+ */
+export async function query<T extends Record<string, any> = Record<string, any>>(
   text: string,
   params?: unknown[]
-): Promise<pg.QueryResult<T>> {
-  const pool = getPool();
-  const start = Date.now();
-
-  try {
-    const result = await pool.query<T>(text, params);
-    const duration = Date.now() - start;
-    logger.debug('Query executed', { duration, rows: result.rowCount });
-    return result;
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-    logger.error('Query failed', { error: errorMessage, query: text.slice(0, 100) });
-    throw new MemoryError(`Database query failed: ${errorMessage}`);
-  }
+): Promise<QueryResult<T>> {
+  const adapter = await getAdapterInstance();
+  return adapter.query<T>(text, params);
 }
 
-export async function getClient(): Promise<pg.PoolClient> {
-  const pool = getPool();
-  return pool.connect();
+/**
+ * Get a transaction client
+ * For PostgreSQL: returns PoolClient
+ * For SQLite: returns a wrapper
+ */
+export async function getClient(): Promise<TransactionClient> {
+  const adapter = await getAdapterInstance();
+  return {
+    query: async <T extends Record<string, any> = Record<string, any>>(
+      sql: string,
+      params?: unknown[]
+    ): Promise<QueryResult<T>> => {
+      return adapter.query<T>(sql, params);
+    },
+  };
 }
 
+/**
+ * Execute a transaction
+ */
 export async function transaction<T>(
-  callback: (client: pg.PoolClient) => Promise<T>
+  callback: (client: TransactionClient) => Promise<T>
 ): Promise<T> {
-  const client = await getClient();
-
-  try {
-    await client.query('BEGIN');
-    const result = await callback(client);
-    await client.query('COMMIT');
-    return result;
-  } catch (error) {
-    await client.query('ROLLBACK');
-    throw error;
-  } finally {
-    client.release();
-  }
+  const adapter = await getAdapterInstance();
+  return adapter.transaction(callback);
 }
 
+/**
+ * Check database health
+ */
 export async function healthCheck(): Promise<boolean> {
   try {
-    const result = await query('SELECT 1 as health');
-    return result.rows.length > 0;
+    const adapter = await getAdapterInstance();
+    return adapter.healthCheck();
   } catch {
     return false;
   }
 }
 
+/**
+ * Close the database connection
+ */
 export async function closePool(): Promise<void> {
-  if (pool) {
-    await pool.end();
-    pool = null;
-    logger.info('Database pool closed');
+  if (healthSystem) {
+    healthSystem.healthMonitor.stop();
+    healthSystem = null;
   }
+  await closeAdapter();
+  logger.info('Database connection closed');
 }
 
-// Initialize the database connection
+/**
+ * Initialize the database
+ * Performs auto-detection, runs migrations, and starts health monitoring
+ */
 export async function initDatabase(): Promise<void> {
-  const healthy = await healthCheck();
-  if (healthy) {
-    logger.info('Database connection established');
-  } else {
-    throw new MemoryError('Failed to connect to database');
+  try {
+    const adapter = await getAdapterInstance();
+    const config = getDatabaseConfig();
+
+    logger.info('Database initialized', {
+      type: adapter.type,
+      path: adapter.type === 'sqlite' ? config.sqlitePath : undefined,
+    });
+
+    // Run migrations
+    const migrator = createMigrator(adapter);
+    const pending = await migrator.getPendingMigrations();
+
+    if (pending.length > 0) {
+      logger.info('Running pending migrations', { count: pending.length });
+      const results = await migrator.migrate();
+      const failed = results.filter((r) => !r.success);
+      if (failed.length > 0) {
+        logger.error('Some migrations failed', { failed });
+        throw new MemoryError(`Migration failed: ${failed[0]?.error}`);
+      }
+      logger.info('Migrations completed', { count: results.length });
+    }
+
+    // Start health monitoring
+    healthSystem = createHealthSystem(adapter, {
+      circuitBreaker: {
+        failureThreshold: config.circuitBreakerThreshold,
+        resetTimeoutMs: config.circuitBreakerTimeoutMs,
+      },
+      healthMonitor: {
+        checkIntervalMs: config.healthCheckIntervalMs,
+      },
+    });
+    healthSystem.healthMonitor.start();
+
+    // Verify connection
+    const healthy = await adapter.healthCheck();
+    if (!healthy) {
+      throw new MemoryError('Database health check failed after initialization');
+    }
+
+    logger.info('Database ready', { type: adapter.type });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logger.error('Database initialization failed', { error: message });
+    throw new MemoryError(`Failed to initialize database: ${message}`);
   }
 }
 
+/**
+ * Get database type
+ */
+export function getDatabaseType(): 'postgresql' | 'sqlite' | null {
+  return getAdapterType();
+}
+
+/**
+ * Check if database is initialized
+ */
+export function isDatabaseInitialized(): boolean {
+  return isAdapterInitialized();
+}
+
+/**
+ * Get health status
+ */
+export function getHealthStatus() {
+  return healthSystem?.healthMonitor.getStatus() ?? null;
+}
+
+/**
+ * Get health summary
+ */
+export function getHealthSummary() {
+  return healthSystem?.healthMonitor.getSummary() ?? {
+    healthy: false,
+    status: 'unknown',
+    database: 'unknown',
+    latencyMs: -1,
+    circuitBreaker: 'unknown',
+  };
+}
+
 export default {
   getPool,
   query,
@@ -106,4 +204,8 @@ export default {
   healthCheck,
   closePool,
   initDatabase,
+  getDatabaseType,
+  isDatabaseInitialized,
+  getHealthStatus,
+  getHealthSummary,
 };