fss-link 1.2.0 → 1.2.1

package/dist/src/config/database-utils.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Database } from 'sql.js';
+/**
+ * TEMPORARY DATABASE UTILITIES
+ *
+ * These wrapper functions provide immediate relief from manual memory management
+ * while we transition to a proper ORM/repository pattern.
+ *
+ * @todo PHASE 2: Replace with Repository pattern (BaseRepository, ModelRepository, etc.)
+ * @todo PHASE 3: Consider migrating to Drizzle ORM or similar for full type safety
+ *
+ * Current problems these wrappers solve:
+ * - Manual .free() calls causing memory leaks
+ * - Inconsistent error handling patterns
+ * - No automatic cleanup on exceptions
+ * - Raw SQL scattered throughout business logic
+ */
+/**
+ * Safe query execution with automatic statement cleanup.
+ * Returns all matching rows as an array.
+ *
+ * @todo UPGRADE: Replace with repository.findMany() method
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL query string
+ * @param params - Query parameters (optional)
+ * @returns Array of query results
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeQuery<T = any>(db: Database, sql: string, params?: any[]): T[];
+/**
+ * Safe query execution returning first result or null.
+ * Automatically handles statement cleanup.
+ *
+ * @todo UPGRADE: Replace with repository.findFirst() method
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL query string
+ * @param params - Query parameters (optional)
+ * @returns First matching row or null
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeQueryFirst<T = any>(db: Database, sql: string, params?: any[]): T | null;
+/**
+ * Safe execution of INSERT/UPDATE/DELETE statements.
+ * Automatically handles statement cleanup.
+ *
+ * @todo UPGRADE: Replace with repository.create()/update()/delete() methods
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL statement string
+ * @param params - Statement parameters (optional)
+ * @returns Number of affected rows
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeExec(db: Database, sql: string, params?: any[]): number;
+/**
+ * Safe transaction execution with automatic rollback on error.
+ * Ensures consistent database state even if operations fail.
+ *
+ * @todo UPGRADE: Replace with repository.withTransaction() method
+ *
+ * @param db - SQLite database instance
+ * @param operations - Function containing database operations
+ * @returns Result of operations function
+ * @throws DatabaseError for transaction failures
+ */
+export declare function safeTransaction<T>(db: Database, operations: () => T): T;
+/**
+ * Get the last inserted row ID from an INSERT operation.
+ * Helper for operations that need the new record ID.
+ *
+ * @todo UPGRADE: Repository pattern will handle this automatically
+ *
+ * @param db - SQLite database instance
+ * @returns Last inserted row ID
+ */
+export declare function getLastInsertId(db: Database): number;
+/**
+ * Custom error class for database operations.
+ * Provides consistent error handling across all database functions.
+ *
+ * @todo UPGRADE: Repository pattern will have more specific error types
+ */
+export declare class DatabaseError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * MIGRATION HELPERS
+ *
+ * These functions help gradually replace manual prepare/free patterns
+ * throughout the existing codebase.
+ */
+/**
+ * Check if a table exists in the database.
+ * Common pattern used in migration logic.
+ *
+ * @param db - SQLite database instance
+ * @param tableName - Name of table to check
+ * @returns True if table exists
+ */
+export declare function tableExists(db: Database, tableName: string): boolean;
+/**
+ * Check if a column exists in a table.
+ * Useful for schema validation and migrations.
+ *
+ * @param db - SQLite database instance
+ * @param tableName - Name of table
+ * @param columnName - Name of column to check
+ * @returns True if column exists
+ */
+export declare function columnExists(db: Database, tableName: string, columnName: string): boolean;
+/**
+ * COMMON UTILITY PATTERNS
+ *
+ * These higher-level helpers encapsulate frequent database patterns
+ */
+/**
+ * Check if any records exist matching the criteria
+ * @param db - SQLite database instance
+ * @param table - Table name
+ * @param whereClause - WHERE clause (without WHERE keyword)
+ * @param params - Parameters for WHERE clause
+ * @returns True if any records exist
+ */
+export declare function recordExists(db: Database, table: string, whereClause: string, params?: any[]): boolean;
+/**
+ * Count records matching criteria
+ * @param db - SQLite database instance
+ * @param table - Table name
+ * @param whereClause - WHERE clause (without WHERE keyword, optional)
+ * @param params - Parameters for WHERE clause
+ * @returns Number of matching records
+ */
+export declare function countRecords(db: Database, table: string, whereClause?: string, params?: any[]): number;
+/**
+ * Delete records with safe execution
+ * @param db - SQLite database instance
+ * @param table - Table name
+ * @param whereClause - WHERE clause (without WHERE keyword)
+ * @param params - Parameters for WHERE clause
+ * @returns Number of deleted records
+ */
+export declare function deleteRecords(db: Database, table: string, whereClause: string, params?: any[]): number;
+/**
+ * Update records with safe execution
+ * @param db - SQLite database instance
+ * @param table - Table name
+ * @param setClause - SET clause (without SET keyword)
+ * @param whereClause - WHERE clause (without WHERE keyword)
+ * @param params - Parameters for SET and WHERE clauses
+ * @returns Number of updated records
+ */
+export declare function updateRecords(db: Database, table: string, setClause: string, whereClause: string, params?: any[]): number;
+/**
+ * Thread-safe query execution with async locking protection.
+ * Wraps safeQuery() with DatabaseOperationQueue serialization.
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL query string
+ * @param params - Query parameters (optional)
+ * @returns Promise<Array> of query results
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeQueryWithLocking<T = any>(db: Database, sql: string, params?: any[]): Promise<T[]>;
+/**
+ * Thread-safe query first execution with async locking protection.
+ * Wraps safeQueryFirst() with DatabaseOperationQueue serialization.
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL query string
+ * @param params - Query parameters (optional)
+ * @returns Promise<T | null> first matching row or null
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeQueryFirstWithLocking<T = any>(db: Database, sql: string, params?: any[]): Promise<T | null>;
+/**
+ * Thread-safe execution with async locking protection.
+ * Wraps safeExec() with DatabaseOperationQueue serialization.
+ *
+ * @param db - SQLite database instance
+ * @param sql - SQL statement string
+ * @param params - Statement parameters (optional)
+ * @returns Promise<number> of affected rows
+ * @throws DatabaseError for SQL execution errors
+ */
+export declare function safeExecWithLocking(db: Database, sql: string, params?: any[]): Promise<number>;
+/**
+ * Thread-safe transaction execution with async locking protection.
+ * Wraps safeTransaction() with DatabaseOperationQueue serialization.
+ *
+ * CRITICAL: This ensures atomic transactions with NO race conditions.
+ * Multiple transactions CANNOT run concurrently - GUARANTEED serialization.
+ *
+ * @param db - SQLite database instance
+ * @param operations - Function containing database operations
+ * @returns Promise<T> result of operations function
+ * @throws DatabaseError for transaction failures
+ */
+export declare function safeTransactionWithLocking<T>(db: Database, operations: (db: Database) => Promise<T>): Promise<T>;
+/**
+ * UTILITY WRAPPERS WITH ASYNC LOCKING
+ *
+ * These provide async-safe versions of common utility functions
+ */
+/**
+ * Thread-safe record existence check with async locking protection.
+ */
+export declare function recordExistsWithLocking(db: Database, table: string, whereClause: string, params?: any[]): Promise<boolean>;
+/**
+ * Thread-safe record counting with async locking protection.
+ */
+export declare function countRecordsWithLocking(db: Database, table: string, whereClause?: string, params?: any[]): Promise<number>;
+/**
+ * Thread-safe record deletion with async locking protection.
+ */
+export declare function deleteRecordsWithLocking(db: Database, table: string, whereClause: string, params?: any[]): Promise<number>;
+/**
+ * Thread-safe record updating with async locking protection.
+ */
+export declare function updateRecordsWithLocking(db: Database, table: string, setClause: string, whereClause: string, params?: any[]): Promise<number>;
+/**
+ * Thread-safe last insert ID retrieval with async locking protection.
+ */
+export declare function getLastInsertIdWithLocking(db: Database): Promise<number>;
+/**
+ * ======================================================================================
+ * MIGRATION GUIDE: FROM UNSAFE TO ASYNC-SAFE DATABASE OPERATIONS
+ * ======================================================================================
+ *
+ * OLD (race condition prone):
+ * const results = safeQuery(db, 'SELECT * FROM model_configs WHERE auth_type = ?', [authType]);
+ * const count = safeExec(db, 'UPDATE model_configs SET is_active = 0');
+ *
+ * NEW (thread-safe with async locking):
+ * const results = await safeQueryWithLocking(db, 'SELECT * FROM model_configs WHERE auth_type = ?', [authType]);
+ * const count = await safeExecWithLocking(db, 'UPDATE model_configs SET is_active = 0');
+ *
+ * TRANSACTION EXAMPLE:
+ * const result = await safeTransactionWithLocking(db, async (db) => {
+ *   await safeExecWithLocking(db, 'UPDATE model_configs SET is_active = 0');
+ *   await safeExecWithLocking(db, 'UPDATE model_configs SET is_active = 1 WHERE id = ?', [modelId]);
+ *   return { success: true };
+ * });
+ *
+ * UTILITY EXAMPLES:
+ * const exists = await recordExistsWithLocking(db, 'model_configs', 'is_active = 1');
+ * const count = await countRecordsWithLocking(db, 'model_configs', 'auth_type = ?', ['ollama']);
+ * const deleted = await deleteRecordsWithLocking(db, 'model_configs', 'is_active = 0 AND last_used < ?', [cutoffDate]);
+ */
+/**
+ * EXAMPLE MIGRATION FROM OLD PATTERN TO NEW PATTERN:
+ *
+ * // OLD (manual memory management):
+ * const stmt = db.prepare('SELECT * FROM model_configs WHERE auth_type = ?');
+ * stmt.bind([authType]);
+ * const results = [];
+ * while (stmt.step()) {
+ *   results.push(stmt.getAsObject());
+ * }
+ * stmt.free(); // Easy to forget!
+ *
+ * // NEW (automatic cleanup):
+ * const results = safeQuery(db, 'SELECT * FROM model_configs WHERE auth_type = ?', [authType]);
+ *
+ * // UTILITY HELPERS:
+ * const hasActiveModels = recordExists(db, 'model_configs', 'is_active = 1');
+ * const modelCount = countRecords(db, 'model_configs', 'auth_type = ?', ['ollama']);
+ * const deletedCount = deleteRecords(db, 'model_configs', 'is_active = 0 AND last_used < ?', [cutoffDate]);
+ *
+ * // FUTURE (repository pattern):
+ * const results = await modelRepo.findByAuthType(authType);
+ * const hasActive = await modelRepo.hasActive();
+ * const count = await modelRepo.countByAuthType('ollama');
+ * const deleted = await modelRepo.deleteInactive(cutoffDate);
+ */