fss-link 1.2.5 → 1.2.6

package/dist/src/config/archive-repository-pattern/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();
+ */