fss-link 1.2.0 → 1.2.1

package/dist/src/config/archive-repository-pattern/settings-repository.js

@@ -0,0 +1,531 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseRepository } from './base-repository.js';
+/**
+ * Settings Repository - Thread-safe application settings management
+ *
+ * Provides comprehensive settings management with async coordination,
+ * type safety, categorization, and validation. All operations use
+ * Emma's BaseRepository async-safe database patterns.
+ */
+export class SettingsRepository extends BaseRepository {
+    constructor(db) {
+        super(db);
+        console.log('⚙️ [SETTINGS-REPO] Settings repository initialized with async coordination');
+    }
+    /**
+     * Get the table name for settings
+     */
+    getTableName() {
+        return 'app_settings';
+    }
+    /**
+     * ======================================================================================
+     * CORE CRUD OPERATIONS (IMPLEMENTING ABSTRACT METHODS)
+     * ======================================================================================
+     */
+    /**
+     * Create a new setting
+     *
+     * @param setting - Setting data
+     * @returns Promise<number> ID of created setting
+     */
+    async create(setting) {
+        console.log(`⚙️ [SETTINGS-REPO] Creating setting: ${setting.key}`);
+        // Validate required fields
+        if (!setting.key || !setting.value) {
+            throw new Error('Setting key and value are required');
+        }
+        // Set default type if not provided
+        const settingType = setting.type || this.inferType(setting.value);
+        const now = new Date().toISOString();
+        const result = await this.exec(`INSERT INTO app_settings (key, value, type, description, category, is_system, is_readonly, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+            setting.key,
+            setting.value,
+            settingType,
+            setting.description || null,
+            setting.category || 'general',
+            setting.is_system || false,
+            setting.is_readonly || false,
+            now,
+            now
+        ]);
+        void result; // Suppress unused variable warning
+        // Get the last insert ID
+        const lastId = await this.queryFirst('SELECT last_insert_rowid() as last_insert_rowid');
+        const insertId = lastId?.last_insert_rowid || 0;
+        console.log(`✅ [SETTINGS-REPO] Setting created: ${setting.key} (ID: ${insertId})`);
+        return insertId;
+    }
+    /**
+     * Find setting by ID
+     *
+     * @param id - Setting ID
+     * @returns Promise<AppSetting | null>
+     */
+    async findById(id) {
+        console.log(`⚙️ [SETTINGS-REPO] Finding setting by ID: ${id}`);
+        const setting = await this.queryFirst('SELECT * FROM app_settings WHERE id = ?', [id]);
+        console.log(`${setting ? '✅' : '❌'} [SETTINGS-REPO] Setting ${id}: ${setting ? 'Found' : 'Not found'}`);
+        return setting;
+    }
+    /**
+     * Update setting by ID
+     *
+     * @param id - Setting ID
+     * @param updates - Setting updates
+     * @returns Promise<boolean> true if updated
+     */
+    async update(id, updates) {
+        console.log(`⚙️ [SETTINGS-REPO] Updating setting ID: ${id}`);
+        // Check if setting exists and is not readonly
+        const existing = await this.findById(id);
+        if (!existing) {
+            console.log(`❌ [SETTINGS-REPO] Setting ${id} not found for update`);
+            return false;
+        }
+        if (existing.is_readonly) {
+            throw new Error(`Setting '${existing.key}' is readonly and cannot be updated`);
+        }
+        // Build dynamic update query
+        const updateFields = [];
+        const updateValues = [];
+        if (updates.value !== undefined) {
+            updateFields.push('value = ?');
+            updateValues.push(updates.value);
+            // Update type if value changed
+            if (updates.type === undefined) {
+                updateFields.push('type = ?');
+                updateValues.push(this.inferType(updates.value));
+            }
+        }
+        if (updates.type !== undefined) {
+            updateFields.push('type = ?');
+            updateValues.push(updates.type);
+        }
+        if (updates.description !== undefined) {
+            updateFields.push('description = ?');
+            updateValues.push(updates.description);
+        }
+        if (updates.category !== undefined) {
+            updateFields.push('category = ?');
+            updateValues.push(updates.category);
+        }
+        if (updates.is_system !== undefined) {
+            updateFields.push('is_system = ?');
+            updateValues.push(updates.is_system);
+        }
+        if (updates.is_readonly !== undefined) {
+            updateFields.push('is_readonly = ?');
+            updateValues.push(updates.is_readonly);
+        }
+        // Always update timestamp
+        updateFields.push('updated_at = ?');
+        updateValues.push(new Date().toISOString());
+        updateValues.push(id); // For WHERE clause
+        if (updateFields.length === 1) { // Only timestamp
+            console.log(`⚠️ [SETTINGS-REPO] No updates provided for setting ${id}`);
+            return false;
+        }
+        const rowsAffected = await this.exec(`UPDATE app_settings SET ${updateFields.join(', ')} WHERE id = ?`, updateValues);
+        const success = rowsAffected > 0;
+        console.log(`${success ? '✅' : '❌'} [SETTINGS-REPO] Setting ${id} update: ${success ? 'Success' : 'Failed'}`);
+        return success;
+    }
+    /**
+     * Delete setting by ID
+     *
+     * @param id - Setting ID
+     * @returns Promise<boolean> true if deleted
+     */
+    async delete(id) {
+        console.log(`⚙️ [SETTINGS-REPO] Deleting setting ID: ${id}`);
+        // Check if setting exists and is not system/readonly
+        const existing = await this.findById(id);
+        if (!existing) {
+            console.log(`❌ [SETTINGS-REPO] Setting ${id} not found for deletion`);
+            return false;
+        }
+        if (existing.is_system) {
+            throw new Error(`Setting '${existing.key}' is a system setting and cannot be deleted`);
+        }
+        if (existing.is_readonly) {
+            throw new Error(`Setting '${existing.key}' is readonly and cannot be deleted`);
+        }
+        const rowsAffected = await this.exec('DELETE FROM app_settings WHERE id = ?', [id]);
+        const success = rowsAffected > 0;
+        console.log(`${success ? '✅' : '❌'} [SETTINGS-REPO] Setting ${id} deletion: ${success ? 'Success' : 'Failed'}`);
+        return success;
+    }
+    /**
+     * Find all settings with optional filtering
+     *
+     * @param whereClause - Optional WHERE clause
+     * @param params - Parameters for WHERE clause
+     * @param orderBy - Optional ORDER BY clause
+     * @param limit - Optional LIMIT
+     * @returns Promise<AppSetting[]>
+     */
+    async findAll(whereClause, params = [], orderBy = 'category ASC, key ASC', limit) {
+        console.log(`⚙️ [SETTINGS-REPO] Finding all settings${whereClause ? ' with filter' : ''}`);
+        let sql = 'SELECT * FROM app_settings';
+        if (whereClause) {
+            sql += ` WHERE ${whereClause}`;
+        }
+        if (orderBy) {
+            sql += ` ORDER BY ${orderBy}`;
+        }
+        if (limit) {
+            sql += ` LIMIT ${limit}`;
+        }
+        const settings = await this.query(sql, params);
+        console.log(`✅ [SETTINGS-REPO] Found ${settings.length} settings`);
+        return settings;
+    }
+    /**
+     * Find first setting matching criteria
+     *
+     * @param whereClause - WHERE clause
+     * @param params - Parameters for WHERE clause
+     * @returns Promise<AppSetting | null>
+     */
+    async findFirst(whereClause, params) {
+        console.log(`⚙️ [SETTINGS-REPO] Finding first setting matching criteria`);
+        const setting = await this.queryFirst(`SELECT * FROM app_settings WHERE ${whereClause}`, params);
+        console.log(`${setting ? '✅' : '❌'} [SETTINGS-REPO] First setting: ${setting ? 'Found' : 'Not found'}`);
+        return setting;
+    }
+    /**
+     * ======================================================================================
+     * SETTINGS-SPECIFIC OPERATIONS
+     * ======================================================================================
+     */
+    /**
+     * Get setting value by key with type safety
+     *
+     * @param key - Setting key
+     * @returns Promise<TypedSettingResult<T>> typed setting result
+     */
+    async getSetting(key) {
+        console.log(`⚙️ [SETTINGS-REPO] Getting setting: ${key}`);
+        const setting = await this.findFirst('key = ?', [key]);
+        if (!setting) {
+            console.log(`❌ [SETTINGS-REPO] Setting '${key}' not found`);
+            return {
+                key,
+                value: null,
+                type: 'string',
+                exists: false
+            };
+        }
+        // Parse value based on type
+        const parsedValue = this.parseValue(setting.value, setting.type);
+        console.log(`✅ [SETTINGS-REPO] Setting '${key}' retrieved: ${setting.type}`);
+        return {
+            key,
+            value: parsedValue,
+            type: setting.type,
+            exists: true
+        };
+    }
+    /**
+     * Set setting value by key (create or update)
+     *
+     * @param key - Setting key
+     * @param value - Setting value
+     * @param options - Additional setting options
+     * @returns Promise<boolean> true if successful
+     */
+    /**
+     * Alias for getSetting for test compatibility
+     * @param key Setting key
+     * @returns Setting value result
+     */
+    async get(key) {
+        return this.getSetting(key);
+    }
+    async setSetting(key, value, options = {}) {
+        console.log(`⚙️ [SETTINGS-REPO] Setting value for: ${key}`);
+        const existing = await this.findFirst('key = ?', [key]);
+        const stringValue = this.stringifyValue(value);
+        const settingType = options.type || this.inferType(value);
+        try {
+            if (existing) {
+                // Update existing setting
+                const success = await this.update(existing.id, {
+                    value: stringValue,
+                    type: settingType,
+                    description: options.description,
+                    category: options.category,
+                    is_system: options.is_system,
+                    is_readonly: options.is_readonly
+                });
+                console.log(`✅ [SETTINGS-REPO] Setting '${key}' updated`);
+                return success;
+            }
+            else {
+                // Create new setting
+                await this.create({
+                    key,
+                    value: stringValue,
+                    type: settingType,
+                    description: options.description,
+                    category: options.category || 'general',
+                    is_system: options.is_system || false,
+                    is_readonly: options.is_readonly || false
+                });
+                console.log(`✅ [SETTINGS-REPO] Setting '${key}' created`);
+                return true;
+            }
+        }
+        catch (error) {
+            console.error(`❌ [SETTINGS-REPO] Failed to set '${key}':`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get multiple settings by keys
+     *
+     * @param keys - Array of setting keys
+     * @returns Promise<Record<string, TypedSettingResult>> settings map
+     */
+    async getMultipleSettings(keys) {
+        console.log(`⚙️ [SETTINGS-REPO] Getting ${keys.length} settings`);
+        const placeholders = keys.map(() => '?').join(',');
+        const settings = await this.query(`SELECT * FROM app_settings WHERE key IN (${placeholders})`, keys);
+        const result = {};
+        // Initialize all keys as not found
+        for (const key of keys) {
+            result[key] = {
+                key,
+                value: null,
+                type: 'string',
+                exists: false
+            };
+        }
+        // Fill in found settings
+        for (const setting of settings) {
+            result[setting.key] = {
+                key: setting.key,
+                value: this.parseValue(setting.value, setting.type),
+                type: setting.type,
+                exists: true
+            };
+        }
+        console.log(`✅ [SETTINGS-REPO] Retrieved ${settings.length}/${keys.length} settings`);
+        return result;
+    }
+    /**
+     * Get all settings in a category
+     *
+     * @param category - Settings category
+     * @returns Promise<AppSetting[]> category settings
+     */
+    async getSettingsByCategory(category) {
+        console.log(`⚙️ [SETTINGS-REPO] Getting settings for category: ${category}`);
+        const settings = await this.findAll('category = ?', [category]);
+        console.log(`✅ [SETTINGS-REPO] Found ${settings.length} settings in '${category}' category`);
+        return settings;
+    }
+    /**
+     * Get all settings categories with counts
+     *
+     * @returns Promise<SettingsCategory[]> categories list
+     */
+    async getCategories() {
+        console.log(`⚙️ [SETTINGS-REPO] Getting all settings categories`);
+        const categories = await this.query(`SELECT 
+         category,
+         '' as description,
+         COUNT(*) as count
+       FROM app_settings 
+       GROUP BY category 
+       ORDER BY category`);
+        const result = categories.map(cat => ({
+            name: cat.category,
+            description: cat.description || `Settings for ${cat.category}`,
+            settingsCount: cat.count
+        }));
+        console.log(`✅ [SETTINGS-REPO] Found ${result.length} categories`);
+        return result;
+    }
+    /**
+     * Delete setting by key
+     *
+     * @param key - Setting key
+     * @returns Promise<boolean> true if deleted
+     */
+    async deleteSetting(key) {
+        console.log(`⚙️ [SETTINGS-REPO] Deleting setting by key: ${key}`);
+        const setting = await this.findFirst('key = ?', [key]);
+        if (!setting) {
+            console.log(`❌ [SETTINGS-REPO] Setting '${key}' not found for deletion`);
+            return false;
+        }
+        return this.delete(setting.id);
+    }
+    /**
+     * Reset all settings in a category
+     *
+     * @param category - Category to reset
+     * @param excludeSystem - Exclude system settings from reset
+     * @returns Promise<number> number of settings reset
+     */
+    async resetCategory(category, excludeSystem = true) {
+        console.log(`⚙️ [SETTINGS-REPO] Resetting category: ${category}`);
+        return this.withTransaction(async () => {
+            let whereClause = 'category = ?';
+            const params = [category];
+            if (excludeSystem) {
+                whereClause += ' AND is_system = 0';
+            }
+            const settingsToDelete = await this.findAll(whereClause, params);
+            let deletedCount = 0;
+            for (const setting of settingsToDelete) {
+                if (!setting.is_readonly) {
+                    const deleted = await this.delete(setting.id);
+                    if (deleted)
+                        deletedCount++;
+                }
+            }
+            console.log(`✅ [SETTINGS-REPO] Reset ${deletedCount} settings in '${category}' category`);
+            return deletedCount;
+        });
+    }
+    /**
+     * ======================================================================================
+     * UTILITY METHODS
+     * ======================================================================================
+     */
+    /**
+     * Infer setting type from value
+     */
+    inferType(value) {
+        if (typeof value === 'boolean')
+            return 'boolean';
+        if (typeof value === 'number')
+            return 'number';
+        if (typeof value === 'object' && value !== null)
+            return 'json';
+        return 'string';
+    }
+    /**
+     * Parse setting value based on type
+     */
+    parseValue(value, type) {
+        try {
+            switch (type) {
+                case 'boolean':
+                    return value === 'true' || value === '1';
+                case 'number':
+                    return Number(value);
+                case 'json':
+                    return JSON.parse(value);
+                default:
+                    return value;
+            }
+        }
+        catch (error) {
+            console.warn(`⚠️ [SETTINGS-REPO] Failed to parse value as ${type}, returning string:`, error);
+            return value;
+        }
+    }
+    /**
+     * Convert value to string for storage
+     */
+    stringifyValue(value) {
+        if (typeof value === 'object' && value !== null) {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    }
+    /**
+     * Validate setting key format
+     */
+    // @ts-expect-error: Method reserved for future validation implementation
+    isValidKey(key) {
+        // Keys should be alphanumeric with dots, dashes, underscores
+        return /^[a-zA-Z0-9._-]+$/.test(key);
+    }
+    /**
+     * Find settings by category (backward compatibility)
+     * @param category Category name
+     * @returns Settings in the category
+     */
+    async findByCategory(category) {
+        return this.getSettingsByCategory(category);
+    }
+    /**
+     * Set value alias for backward compatibility
+     * @param key Setting key
+     * @param value Setting value
+     * @returns Success status
+     */
+    async setValue(key, value) {
+        const result = await this.setSetting(key, value, {});
+        return result;
+    }
+    /**
+     * Get value alias for backward compatibility
+     * @param key Setting key
+     * @returns Setting value
+     */
+    async getValue(key) {
+        const result = await this.getSetting(key);
+        return result.exists ? result.value : null;
+    }
+    /**
+     * Execute operations within a transaction (PUBLIC API for tests)
+     *
+     * @param operations - Async function containing database operations
+     * @returns Promise<T> result of operations
+     */
+    async executeTransaction(operations) {
+        return this.withTransaction(operations);
+    }
+}
+/**
+ * ======================================================================================
+ * SETTINGS REPOSITORY USAGE EXAMPLES
+ * ======================================================================================
+ *
+ * // Initialize repository
+ * const settingsRepo = new SettingsRepository(database);
+ *
+ * // Basic operations
+ * await settingsRepo.setSetting('app.theme', 'dark');
+ * await settingsRepo.setSetting('app.debug', true);
+ * await settingsRepo.setSetting('api.timeout', 5000);
+ *
+ * // Type-safe retrieval
+ * const theme = await settingsRepo.getSetting<string>('app.theme');
+ * const debug = await settingsRepo.getSetting<boolean>('app.debug');
+ * const timeout = await settingsRepo.getSetting<number>('api.timeout');
+ *
+ * // Multiple settings
+ * const settings = await settingsRepo.getMultipleSettings(['app.theme', 'app.debug']);
+ *
+ * // Category operations
+ * const appSettings = await settingsRepo.getSettingsByCategory('app');
+ * const categories = await settingsRepo.getCategories();
+ *
+ * // Advanced operations
+ * await settingsRepo.setSetting('system.version', '1.0.0', {
+ *   category: 'system',
+ *   description: 'Application version',
+ *   is_system: true,
+ *   is_readonly: true
+ * });
+ *
+ * // Bulk operations
+ * const resetCount = await settingsRepo.resetCategory('temp');
+ *
+ * // Diagnostics
+ * const stats = await settingsRepo.getStatistics();
+ * const validation = await settingsRepo.validateSchema();
+ */ 
+//# sourceMappingURL=settings-repository.js.map

package/dist/src/config/archive-repository-pattern/settings-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-repository.js","sourceRoot":"","sources":["../../../../src/config/archive-repository-pattern/settings-repository.ts"],"names":[],"mappings":"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"}

package/dist/src/config/async-mutex.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * AsyncMutex - Thread-safe mutual exclusion for async operations
+ *
+ * Prevents concurrent database access that causes "Statement closed" errors.
+ * Uses a wait queue to serialize operations and guarantee only one
+ * database operation executes at a time.
+ *
+ * @author George - Database locking specialist
+ */
+export declare class AsyncMutex {
+    private locked;
+    private waitQueue;
+    private debugEnabled;
+    /**
+     * Acquire the mutex lock
+     *
+     * @returns Promise that resolves to a release function
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Release the mutex and notify next waiter
+     */
+    private release;
+    /**
+     * Get current mutex state for debugging
+     */
+    getState(): {
+        locked: boolean;
+        queueLength: number;
+    };
+    /**
+     * Check if mutex is currently locked
+     */
+    isLocked(): boolean;
+    /**
+     * Get number of operations waiting in queue
+     */
+    getQueueLength(): number;
+    /**
+     * Debug logging (enabled with DEBUG_MUTEX=true)
+     */
+    private debugLog;
+    /**
+     * Force release the mutex (emergency use only)
+     * WARNING: Only use this for cleanup/testing
+     */
+    forceRelease(): void;
+}
+/**
+ * Utility function to run an operation with mutex protection
+ *
+ * @param mutex The AsyncMutex instance
+ * @param operation The async operation to run
+ * @returns Promise with the operation result
+ */
+export declare function withMutex<T>(mutex: AsyncMutex, operation: () => Promise<T>): Promise<T>;