fss-link 1.2.4 → 1.2.6

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

@@ -0,0 +1,274 @@
+/**
+ * @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, SettingValue, SettingValueWithJson } from './repository-types.js';
+/**
+ * ======================================================================================
+ * SETTINGS REPOSITORY - PHASE 2 REPOSITORY PATTERN IMPLEMENTATION
+ * ======================================================================================
+ *
+ * Thread-safe settings management repository built on Emma's BaseRepository foundation.
+ * Eliminates "Statement closed" errors through async-safe database operations for all
+ * application settings and preferences.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ * @task Task 7: SettingsRepository Implementation
+ * @dependencies Task 5 (BaseRepository Class)
+ */
+/**
+ * Application setting entity interface
+ */
+export interface AppSetting extends BaseEntity {
+    id?: number;
+    key: string;
+    value: string;
+    type: 'string' | 'number' | 'boolean' | 'json';
+    description?: string;
+    category?: string;
+    is_system?: boolean;
+    is_readonly?: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * Settings category for organization
+ */
+export interface SettingsCategory {
+    name: string;
+    description: string;
+    settingsCount: number;
+}
+/**
+ * Typed setting result for type-safe value retrieval
+ */
+export interface TypedSettingResult<T = SettingValue> {
+    key: string;
+    value: T;
+    type: string;
+    exists: boolean;
+}
+/**
+ * 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 declare class SettingsRepository extends BaseRepository<AppSetting> {
+    constructor(db: Database);
+    /**
+     * Get the table name for settings
+     */
+    protected getTableName(): string;
+    /**
+     * ======================================================================================
+     * CORE CRUD OPERATIONS (IMPLEMENTING ABSTRACT METHODS)
+     * ======================================================================================
+     */
+    /**
+     * Create a new setting
+     *
+     * @param setting - Setting data
+     * @returns Promise<number> ID of created setting
+     */
+    create(setting: Partial<AppSetting>): Promise<number>;
+    /**
+     * Find setting by ID
+     *
+     * @param id - Setting ID
+     * @returns Promise<AppSetting | null>
+     */
+    findById(id: number): Promise<AppSetting | null>;
+    /**
+     * Update setting by ID
+     *
+     * @param id - Setting ID
+     * @param updates - Setting updates
+     * @returns Promise<boolean> true if updated
+     */
+    update(id: number, updates: Partial<AppSetting>): Promise<boolean>;
+    /**
+     * Delete setting by ID
+     *
+     * @param id - Setting ID
+     * @returns Promise<boolean> true if deleted
+     */
+    delete(id: number): Promise<boolean>;
+    /**
+     * 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[]>
+     */
+    findAll(whereClause?: string, params?: QueryParameters, orderBy?: string, limit?: number): Promise<AppSetting[]>;
+    /**
+     * Find first setting matching criteria
+     *
+     * @param whereClause - WHERE clause
+     * @param params - Parameters for WHERE clause
+     * @returns Promise<AppSetting | null>
+     */
+    findFirst(whereClause: string, params: QueryParameters): Promise<AppSetting | null>;
+    /**
+     * ======================================================================================
+     * SETTINGS-SPECIFIC OPERATIONS
+     * ======================================================================================
+     */
+    /**
+     * Get setting value by key with type safety
+     *
+     * @param key - Setting key
+     * @returns Promise<TypedSettingResult<T>> typed setting result
+     */
+    getSetting<T = string>(key: string): Promise<TypedSettingResult<T>>;
+    /**
+     * 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
+     */
+    get<T = string>(key: string): Promise<TypedSettingResult<T>>;
+    setSetting(key: string, value: SettingValueWithJson, options?: {
+        description?: string;
+        category?: string;
+        type?: AppSetting['type'];
+        is_system?: boolean;
+        is_readonly?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Get multiple settings by keys
+     *
+     * @param keys - Array of setting keys
+     * @returns Promise<Record<string, TypedSettingResult>> settings map
+     */
+    getMultipleSettings(keys: string[]): Promise<Record<string, TypedSettingResult>>;
+    /**
+     * Get all settings in a category
+     *
+     * @param category - Settings category
+     * @returns Promise<AppSetting[]> category settings
+     */
+    getSettingsByCategory(category: string): Promise<AppSetting[]>;
+    /**
+     * Get all settings categories with counts
+     *
+     * @returns Promise<SettingsCategory[]> categories list
+     */
+    getCategories(): Promise<SettingsCategory[]>;
+    /**
+     * Delete setting by key
+     *
+     * @param key - Setting key
+     * @returns Promise<boolean> true if deleted
+     */
+    deleteSetting(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    resetCategory(category: string, excludeSystem?: boolean): Promise<number>;
+    /**
+     * ======================================================================================
+     * UTILITY METHODS
+     * ======================================================================================
+     */
+    /**
+     * Infer setting type from value
+     */
+    private inferType;
+    /**
+     * Parse setting value based on type
+     */
+    private parseValue;
+    /**
+     * Convert value to string for storage
+     */
+    private stringifyValue;
+    /**
+     * Validate setting key format
+     */
+    private isValidKey;
+    /**
+     * Find settings by category (backward compatibility)
+     * @param category Category name
+     * @returns Settings in the category
+     */
+    findByCategory(category: string): Promise<AppSetting[]>;
+    /**
+     * Set value alias for backward compatibility
+     * @param key Setting key
+     * @param value Setting value
+     * @returns Success status
+     */
+    setValue(key: string, value: any): Promise<boolean>;
+    /**
+     * Get value alias for backward compatibility
+     * @param key Setting key
+     * @returns Setting value
+     */
+    getValue<T = string>(key: string): Promise<T | null>;
+    /**
+     * Execute operations within a transaction (PUBLIC API for tests)
+     *
+     * @param operations - Async function containing database operations
+     * @returns Promise<T> result of operations
+     */
+    executeTransaction<U>(operations: (db: Database) => Promise<U>): Promise<U>;
+}
+/**
+ * ======================================================================================
+ * 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();
+ */