fss-link 1.2.0 → 1.2.1

package/dist/src/config/archive-repository-pattern/repository-types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ======================================================================================
+ * REPOSITORY TYPE DEFINITIONS - TASK 3: EXPLICIT ANY TYPE ELIMINATION
+ * ======================================================================================
+ *
+ * Proper TypeScript types to replace explicit 'any' types in repository classes.
+ * These types provide type safety while maintaining flexibility for database operations.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ * @task Task 3: Replace Explicit 'any' Types with Proper TypeScript Types
+ */
+import { AuthType } from 'fss-link-core';
+/**
+ * ======================================================================================
+ * DATABASE ROW TYPES
+ * ======================================================================================
+ */
+/**
+ * Generic database row interface extending Record<string, any> for database results
+ * Provides base structure while allowing additional properties from database queries
+ */
+export interface DatabaseRow extends Record<string, any> {
+    id?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * ======================================================================================
+ * QUERY PARAMETER TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid SQL parameter types for prepared statements
+ * Matches SQLite supported parameter types
+ */
+export type QueryParameter = string | number | boolean | null | Buffer | undefined;
+/**
+ * Array of query parameters for prepared statements
+ */
+export type QueryParameters = QueryParameter[];
+/**
+ * ======================================================================================
+ * SETTING VALUE TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid setting value types for application settings
+ * Covers all common configuration value types
+ */
+export type SettingValue = string | number | boolean | null;
+/**
+ * Setting value with JSON support for complex configurations
+ */
+export type SettingValueWithJson = SettingValue | object;
+/**
+ * ======================================================================================
+ * PREFERENCE VALUE TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid preference value types for user preferences
+ * Includes object support for complex preference structures
+ */
+export type PreferenceValue = string | number | boolean | object | null;
+/**
+ * ======================================================================================
+ * MODEL CONFIGURATION TYPES
+ * ======================================================================================
+ */
+/**
+ * Model configuration value types for model repository
+ * Includes AuthType enum for proper auth type validation
+ */
+export type ModelConfigValue = string | number | boolean | AuthType | null;
+/**
+ * ======================================================================================
+ * VALIDATION AND UTILITY TYPES
+ * ======================================================================================
+ */
+/**
+ * Unknown type for input validation before type assertion
+ * Use when receiving untyped input that needs validation
+ */
+export type UnknownInput = unknown;
+/**
+ * Generic JSON value type for JSON parsing/stringifying
+ */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+/**
+ * JSON object type
+ */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON array type
+ */
+export type JsonArray = JsonValue[];
+/**
+ * ======================================================================================
+ * DATABASE OPERATION RESULT TYPES
+ * ======================================================================================
+ */
+/**
+ * Database query result for operations that return rows
+ */
+export interface QueryResult<T = DatabaseRow> {
+    rows: T[];
+    rowCount: number;
+}
+/**
+ * Database execution result for INSERT/UPDATE/DELETE operations
+ */
+export interface ExecResult {
+    rowsAffected: number;
+    lastInsertId?: number;
+}
+/**
+ * ======================================================================================
+ * TYPE GUARDS AND VALIDATION HELPERS
+ * ======================================================================================
+ */
+/**
+ * Type guard to check if value is a valid QueryParameter
+ */
+export declare function isQueryParameter(value: unknown): value is QueryParameter;
+/**
+ * Type guard to check if value is a valid SettingValue
+ */
+export declare function isSettingValue(value: unknown): value is SettingValue;
+/**
+ * Type guard to check if value is a valid PreferenceValue
+ */
+export declare function isPreferenceValue(value: unknown): value is PreferenceValue;
+/**
+ * ======================================================================================
+ * MIGRATION MAPPING
+ * ======================================================================================
+ *
+ * This file replaces explicit 'any' types found in:
+ *
+ * BaseRepository:
+ * - params: any[] → QueryParameters
+ * - mapRow(row: any) → mapRow(row: DatabaseRow)
+ * - query parameters → QueryParameter[]
+ *
+ * SettingsRepository:
+ * - value: any → SettingValue | SettingValueWithJson
+ * - validateSettingValue(value: any) → validateSettingValue(value: unknown)
+ * - parseValue/stringifyValue(value: any) → proper typing
+ *
+ * PreferencesRepository:
+ * - value: any → PreferenceValue
+ * - setPreference(value: any) → setPreference(value: PreferenceValue)
+ * - preference operations → PreferenceValue
+ *
+ * ModelRepository:
+ * - auth_type: any → AuthType
+ * - configuration values → ModelConfigValue
+ * - database result mapping → proper typing
+ */ 

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

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ======================================================================================
+ * TYPE GUARDS AND VALIDATION HELPERS
+ * ======================================================================================
+ */
+/**
+ * Type guard to check if value is a valid QueryParameter
+ */
+export function isQueryParameter(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null ||
+        value instanceof Buffer);
+}
+/**
+ * Type guard to check if value is a valid SettingValue
+ */
+export function isSettingValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null);
+}
+/**
+ * Type guard to check if value is a valid PreferenceValue
+ */
+export function isPreferenceValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null ||
+        (typeof value === 'object' && value !== null));
+}
+/**
+ * ======================================================================================
+ * MIGRATION MAPPING
+ * ======================================================================================
+ *
+ * This file replaces explicit 'any' types found in:
+ *
+ * BaseRepository:
+ * - params: any[] → QueryParameters
+ * - mapRow(row: any) → mapRow(row: DatabaseRow)
+ * - query parameters → QueryParameter[]
+ *
+ * SettingsRepository:
+ * - value: any → SettingValue | SettingValueWithJson
+ * - validateSettingValue(value: any) → validateSettingValue(value: unknown)
+ * - parseValue/stringifyValue(value: any) → proper typing
+ *
+ * PreferencesRepository:
+ * - value: any → PreferenceValue
+ * - setPreference(value: any) → setPreference(value: PreferenceValue)
+ * - preference operations → PreferenceValue
+ *
+ * ModelRepository:
+ * - auth_type: any → AuthType
+ * - configuration values → ModelConfigValue
+ * - database result mapping → proper typing
+ */ 
+//# sourceMappingURL=repository-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository-types.js","sourceRoot":"","sources":["../../../../src/config/archive-repository-pattern/repository-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2IH;;;;GAIG;AAEH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI;QACd,KAAK,YAAY,MAAM,CACxB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI,CACf,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI;QACd,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

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