fss-link 1.2.0 → 1.2.1

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

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Database } from 'sql.js';
+export interface UserPreference {
+    key: string;
+    value: string;
+}
+interface DatabaseUserPreferenceValueRecord {
+    value: string;
+}
+interface DatabaseUserPreferenceRecord {
+    key: string;
+    value: string;
+}
+interface DatabaseUserPreferenceFullRecord {
+    key: string;
+    value: string;
+    updated_at: string;
+}
+/**
+ * Preferences Database Manager - Extracted from monolithic database.ts
+ *
+ * Handles all user preference operations:
+ * - User preference storage and retrieval
+ * - Preference validation and type conversion
+ * - Bulk preference operations
+ *
+ * ARCHITECTURAL IMPROVEMENT: Further reduces database.ts complexity
+ */
+export declare class PreferencesDatabase {
+    private db;
+    constructor(db: Database);
+    /**
+     * Set user preference (upsert operation)
+     */
+    setUserPreference(key: string, value: string): Promise<void>;
+    /**
+     * Get user preference by key
+     */
+    getUserPreference(key: string): Promise<string | null>;
+    /**
+     * Get user preference with default value if not found
+     */
+    getUserPreferenceWithDefault(key: string, defaultValue: string): Promise<string>;
+    /**
+     * Get all user preferences as key-value object
+     */
+    getAllUserPreferences(): Promise<Record<string, string>>;
+    /**
+     * Get all user preferences with metadata
+     */
+    getAllUserPreferencesWithMetadata(): Promise<DatabaseUserPreferenceFullRecord[]>;
+    /**
+     * Set multiple user preferences in a single transaction
+     */
+    setUserPreferences(preferences: Record<string, string>): Promise<void>;
+    /**
+     * Delete user preference by key
+     */
+    deleteUserPreference(key: string): Promise<void>;
+    /**
+     * Delete multiple user preferences
+     */
+    deleteUserPreferences(keys: string[]): Promise<void>;
+    /**
+     * Clear all user preferences
+     */
+    clearAllUserPreferences(): Promise<void>;
+    /**
+     * Check if user preference exists
+     */
+    hasUserPreference(key: string): Promise<boolean>;
+    /**
+     * Get user preferences matching a key pattern (useful for namespaced preferences)
+     */
+    getUserPreferencesByPattern(pattern: string): Promise<Record<string, string>>;
+    /**
+     * Get preference count
+     */
+    getPreferenceCount(): Promise<number>;
+    /**
+     * Get typed preference with validation
+     */
+    getTypedPreference<T>(key: string, parser: (value: string) => T, defaultValue: T): Promise<T>;
+    /**
+     * Convenience methods for common preference types
+     */
+    getBooleanPreference(key: string, defaultValue?: boolean): Promise<boolean>;
+    getNumberPreference(key: string, defaultValue?: number): Promise<number>;
+    getArrayPreference(key: string, defaultValue?: string[]): Promise<string[]>;
+    /**
+     * Set typed preferences
+     */
+    setBooleanPreference(key: string, value: boolean): Promise<void>;
+    setNumberPreference(key: string, value: number): Promise<void>;
+    setArrayPreference(key: string, value: string[]): Promise<void>;
+}
+export type { DatabaseUserPreferenceValueRecord, DatabaseUserPreferenceRecord, DatabaseUserPreferenceFullRecord };

package/dist/src/config/preferences-database.js

@@ -0,0 +1,209 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { safeQueryWithLocking, safeQueryFirstWithLocking, safeExecWithLocking } from './database-utils.js';
+/**
+ * Preferences Database Manager - Extracted from monolithic database.ts
+ *
+ * Handles all user preference operations:
+ * - User preference storage and retrieval
+ * - Preference validation and type conversion
+ * - Bulk preference operations
+ *
+ * ARCHITECTURAL IMPROVEMENT: Further reduces database.ts complexity
+ */
+export class PreferencesDatabase {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Set user preference (upsert operation)
+     */
+    async setUserPreference(key, value) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        await safeExecWithLocking(this.db, `
+      INSERT OR REPLACE INTO user_preferences (key, value, updated_at)
+      VALUES (?, ?, CURRENT_TIMESTAMP)
+    `, [key, value]);
+    }
+    /**
+     * Get user preference by key
+     */
+    async getUserPreference(key) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const result = await safeQueryFirstWithLocking(this.db, 'SELECT value FROM user_preferences WHERE key = ?', [key]);
+        return result?.value || null;
+    }
+    /**
+     * Get user preference with default value if not found
+     */
+    async getUserPreferenceWithDefault(key, defaultValue) {
+        const value = await this.getUserPreference(key);
+        return value !== null ? value : defaultValue;
+    }
+    /**
+     * Get all user preferences as key-value object
+     */
+    async getAllUserPreferences() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const rows = await safeQueryWithLocking(this.db, 'SELECT key, value FROM user_preferences');
+        const prefs = {};
+        for (const row of rows) {
+            prefs[row.key] = row.value;
+        }
+        return prefs;
+    }
+    /**
+     * Get all user preferences with metadata
+     */
+    async getAllUserPreferencesWithMetadata() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        return await safeQueryWithLocking(this.db, 'SELECT key, value, updated_at FROM user_preferences ORDER BY updated_at DESC');
+    }
+    /**
+     * Set multiple user preferences in a single transaction
+     */
+    async setUserPreferences(preferences) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        // Use individual statements within the safe locking mechanism
+        for (const [key, value] of Object.entries(preferences)) {
+            await safeExecWithLocking(this.db, `
+        INSERT OR REPLACE INTO user_preferences (key, value, updated_at)
+        VALUES (?, ?, CURRENT_TIMESTAMP)
+      `, [key, value]);
+        }
+    }
+    /**
+     * Delete user preference by key
+     */
+    async deleteUserPreference(key) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        await safeExecWithLocking(this.db, `
+      DELETE FROM user_preferences WHERE key = ?
+    `, [key]);
+    }
+    /**
+     * Delete multiple user preferences
+     */
+    async deleteUserPreferences(keys) {
+        if (!this.db || keys.length === 0) {
+            return;
+        }
+        for (const key of keys) {
+            await safeExecWithLocking(this.db, `
+        DELETE FROM user_preferences WHERE key = ?
+      `, [key]);
+        }
+    }
+    /**
+     * Clear all user preferences
+     */
+    async clearAllUserPreferences() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        await safeExecWithLocking(this.db, `
+      DELETE FROM user_preferences
+    `);
+    }
+    /**
+     * Check if user preference exists
+     */
+    async hasUserPreference(key) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const result = await safeQueryFirstWithLocking(this.db, 'SELECT COUNT(*) as count FROM user_preferences WHERE key = ?', [key]);
+        return (result?.count || 0) > 0;
+    }
+    /**
+     * Get user preferences matching a key pattern (useful for namespaced preferences)
+     */
+    async getUserPreferencesByPattern(pattern) {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const rows = await safeQueryWithLocking(this.db, 'SELECT key, value FROM user_preferences WHERE key LIKE ?', [pattern]);
+        const prefs = {};
+        for (const row of rows) {
+            prefs[row.key] = row.value;
+        }
+        return prefs;
+    }
+    /**
+     * Get preference count
+     */
+    async getPreferenceCount() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const result = await safeQueryFirstWithLocking(this.db, 'SELECT COUNT(*) as count FROM user_preferences');
+        return result?.count || 0;
+    }
+    /**
+     * Get typed preference with validation
+     */
+    async getTypedPreference(key, parser, defaultValue) {
+        const value = await this.getUserPreference(key);
+        if (value === null) {
+            return defaultValue;
+        }
+        try {
+            return parser(value);
+        }
+        catch (error) {
+            console.warn(`Failed to parse preference '${key}' with value '${value}':`, error);
+            return defaultValue;
+        }
+    }
+    /**
+     * Convenience methods for common preference types
+     */
+    async getBooleanPreference(key, defaultValue = false) {
+        return this.getTypedPreference(key, (value) => {
+            return value.toLowerCase() === 'true' || value === '1';
+        }, defaultValue);
+    }
+    async getNumberPreference(key, defaultValue = 0) {
+        return this.getTypedPreference(key, (value) => {
+            const parsed = parseFloat(value);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid number: ${value}`);
+            }
+            return parsed;
+        }, defaultValue);
+    }
+    async getArrayPreference(key, defaultValue = []) {
+        return this.getTypedPreference(key, (value) => {
+            return JSON.parse(value);
+        }, defaultValue);
+    }
+    /**
+     * Set typed preferences
+     */
+    async setBooleanPreference(key, value) {
+        await this.setUserPreference(key, value.toString());
+    }
+    async setNumberPreference(key, value) {
+        await this.setUserPreference(key, value.toString());
+    }
+    async setArrayPreference(key, value) {
+        await this.setUserPreference(key, JSON.stringify(value));
+    }
+}
+//# sourceMappingURL=preferences-database.js.map

package/dist/src/config/preferences-database.js.map

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

package/dist/src/config/preferences-repository.d.ts

@@ -0,0 +1,307 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Database } from 'sql.js';
+import { BaseRepository, BaseEntity } from './base-repository.js';
+import { QueryParameters, PreferenceValue } from './repository-types.js';
+/**
+ * ======================================================================================
+ * PREFERENCES REPOSITORY - PHASE 2 REPOSITORY PATTERN IMPLEMENTATION
+ * ======================================================================================
+ *
+ * Thread-safe user preferences management repository with statement lifecycle protection.
+ * Built on Emma's BaseRepository foundation to eliminate "Statement closed" errors for
+ * all user preference operations.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ * @task Task 8: PreferencesRepository Implementation
+ * @dependencies Task 5 (BaseRepository Class)
+ */
+/**
+ * User preference entity interface
+ */
+export interface UserPreference extends BaseEntity {
+    id?: number;
+    user_id?: string;
+    key: string;
+    value: string;
+    type: 'string' | 'number' | 'boolean' | 'json' | 'array';
+    scope: 'global' | 'workspace' | 'project' | 'session';
+    description?: string;
+    is_encrypted?: boolean;
+    is_synced?: boolean;
+    last_accessed?: string;
+    access_count?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * Preference scope for organization and access control
+ */
+export interface PreferenceScope {
+    name: string;
+    description: string;
+    preferencesCount: number;
+    isUserSpecific: boolean;
+}
+/**
+ * Typed preference result for type-safe value retrieval
+ */
+export interface TypedPreferenceResult<T = any> {
+    key: string;
+    value: T;
+    type: string;
+    scope: string;
+    exists: boolean;
+    lastAccessed?: string;
+    accessCount: number;
+}
+/**
+ * Preference access pattern for analytics
+ */
+export interface PreferenceAccessPattern {
+    key: string;
+    totalAccess: number;
+    recentAccess: number;
+    lastAccessed: string;
+    averageAccessPerDay: number;
+}
+/**
+ * Preferences Repository - Thread-safe user preferences management
+ *
+ * Provides comprehensive user preference management with statement lifecycle
+ * protection, scoping, encryption support, and access analytics. All operations
+ * use Emma's BaseRepository async-safe database patterns.
+ */
+export declare class PreferencesRepository extends BaseRepository<UserPreference> {
+    private defaultUserId;
+    constructor(db: Database, defaultUserId?: string);
+    /**
+     * Get the table name for preferences
+     */
+    protected getTableName(): string;
+    /**
+     * ======================================================================================
+     * CORE CRUD OPERATIONS (IMPLEMENTING ABSTRACT METHODS)
+     * ======================================================================================
+     */
+    /**
+     * Create a new preference
+     *
+     * @param preference - Preference data
+     * @returns Promise<number> ID of created preference
+     */
+    create(preference: Partial<UserPreference>): Promise<number>;
+    /**
+     * Find preference by ID
+     *
+     * @param id - Preference ID
+     * @returns Promise<UserPreference | null>
+     */
+    findById(id: number): Promise<UserPreference | null>;
+    /**
+     * Update preference by ID
+     *
+     * @param id - Preference ID
+     * @param updates - Preference updates
+     * @returns Promise<boolean> true if updated
+     */
+    update(id: number, updates: Partial<UserPreference>): Promise<boolean>;
+    /**
+     * Delete preference by ID
+     *
+     * @param id - Preference ID
+     * @returns Promise<boolean> true if deleted
+     */
+    delete(id: number): Promise<boolean>;
+    /**
+     * Find all preferences 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<Array<UserPreference>>
+     */
+    findAll(whereClause?: string, params?: QueryParameters, orderBy?: string, limit?: number): Promise<Array<UserPreference>>;
+    /**
+     * Find first preference matching criteria
+     *
+     * @param whereClause - WHERE clause
+     * @param params - Parameters for WHERE clause
+     * @returns Promise<UserPreference | null>
+     */
+    findFirst(whereClause: string, params: QueryParameters): Promise<UserPreference | null>;
+    /**
+     * ======================================================================================
+     * PREFERENCES-SPECIFIC OPERATIONS
+     * ======================================================================================
+     */
+    /**
+     * Get preference value by key with type safety
+     *
+     * @param key - Preference key
+     * @param userId - Optional user ID (defaults to instance default)
+     * @param scope - Optional scope filter
+     * @returns Promise<TypedPreferenceResult<T>> typed preference result
+     */
+    /**
+     * Alias for getPreference for test compatibility
+     * @param key Preference key
+     * @returns Preference value result
+     */
+    get<T = string>(key: string): Promise<TypedPreferenceResult<T>>;
+    getPreference<T = string>(key: string, userId?: string, scope?: string): Promise<TypedPreferenceResult<T>>;
+    /**
+     * Set preference value by key (create or update)
+     *
+     * @param key - Preference key
+     * @param value - Preference value
+     * @param options - Additional preference options
+     * @returns Promise<boolean> true if successful
+     */
+    setPreference(key: string, value: PreferenceValue, options?: {
+        userId?: string;
+        scope?: UserPreference['scope'];
+        description?: string;
+        type?: UserPreference['type'];
+        isEncrypted?: boolean;
+        isSynced?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Get all preferences for a user by scope
+     *
+     * @param scope - Preference scope
+     * @param userId - Optional user ID
+     * @returns Promise<Array<UserPreference>> scope preferences
+     */
+    getPreferencesByScope(scope: string, userId?: string): Promise<Array<UserPreference>>;
+    /**
+     * Get multiple preferences by keys
+     *
+     * @param keys - Array of preference keys
+     * @param userId - Optional user ID
+     * @returns Promise<Record<string, TypedPreferenceResult>> preferences map
+     */
+    getMultiplePreferences(keys: string[], userId?: string): Promise<Record<string, TypedPreferenceResult>>;
+    /**
+     * Delete preference by key
+     *
+     * @param key - Preference key
+     * @param userId - Optional user ID
+     * @returns Promise<boolean> true if deleted
+     */
+    deletePreference(key: string, userId?: string): Promise<boolean>;
+    /**
+     * Reset all preferences for a user in a scope
+     *
+     * @param scope - Scope to reset
+     * @param userId - Optional user ID
+     * @returns Promise<number> number of preferences reset
+     */
+    resetScope(scope: string, userId?: string): Promise<number>;
+    /**
+     * Get preference access analytics
+     *
+     * @param userId - Optional user ID
+     * @param limit - Optional limit for results
+     * @returns Promise<Array<PreferenceAccessPattern>> access patterns
+     */
+    getAccessPatterns(userId?: string, limit?: number): Promise<Array<PreferenceAccessPattern>>;
+    /**
+     * ======================================================================================
+     * UTILITY METHODS
+     * ======================================================================================
+     */
+    /**
+     * Track preference access for analytics
+     */
+    private trackAccess;
+    /**
+     * Infer preference type from value
+     */
+    private inferType;
+    /**
+     * Parse preference value based on type
+     */
+    private parseValue;
+    /**
+     * Convert value to string for storage
+     */
+    private stringifyValue;
+    /**
+     * Get all preference scopes with statistics
+     *
+     * @param userId - Optional user ID
+     * @returns Promise<Array<PreferenceScope>> scopes list
+     */
+    getScopes(userId?: string): Promise<Array<PreferenceScope>>;
+    /**
+     * Get description for preference scope
+     */
+    private getScopeDescription;
+    /**
+     * Find preferences by scope (backward compatibility)
+     * @param scope Scope name
+     * @returns Preferences in the scope
+     */
+    findByScope(scope: string): Promise<UserPreference[]>;
+    /**
+     * Set value alias for backward compatibility
+     * @param key Preference key
+     * @param value Preference value
+     * @returns Success status
+     */
+    setValue(key: string, value: any): Promise<boolean>;
+    /**
+     * Get value alias for backward compatibility
+     * @param key Preference key
+     * @returns Preference value
+     */
+    getValue<T = string>(key: string): Promise<T | null>;
+}
+/**
+ * ======================================================================================
+ * PREFERENCES REPOSITORY USAGE EXAMPLES
+ * ======================================================================================
+ *
+ * // Initialize repository
+ * const prefsRepo = new PreferencesRepository(database, 'user123');
+ *
+ * // Basic operations
+ * await prefsRepo.setPreference('editor.theme', 'dark');
+ * await prefsRepo.setPreference('editor.fontSize', 14);
+ * await prefsRepo.setPreference('workspace.autoSave', true);
+ *
+ * // Type-safe retrieval
+ * const theme = await prefsRepo.getPreference<string>('editor.theme');
+ * const fontSize = await prefsRepo.getPreference<number>('editor.fontSize');
+ * const autoSave = await prefsRepo.getPreference<boolean>('workspace.autoSave');
+ *
+ * // Scoped preferences
+ * await prefsRepo.setPreference('debug.enabled', true, { scope: 'project' });
+ * const projectPrefs = await prefsRepo.getPreferencesByScope('project');
+ *
+ * // Multiple preferences
+ * const settings = await prefsRepo.getMultiplePreferences([
+ *   'editor.theme', 'editor.fontSize', 'workspace.autoSave'
+ * ]);
+ *
+ * // Advanced options
+ * await prefsRepo.setPreference('api.credentials', 'encrypted_data', {
+ *   scope: 'global',
+ *   description: 'API authentication credentials',
+ *   isEncrypted: true,
+ *   isSynced: false
+ * });
+ *
+ * // Analytics and cleanup
+ * const patterns = await prefsRepo.getAccessPatterns();
+ * const resetCount = await prefsRepo.resetScope('session');
+ *
+ * // Diagnostics
+ * const stats = await prefsRepo.getStatistics();
+ * const scopes = await prefsRepo.getScopes();
+ */