fss-link 1.2.1 → 1.2.2

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

@@ -1,281 +0,0 @@
-/**
- * @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);
- */