@nahisaho/yata-local 1.6.6 → 1.7.0

package/dist/index-optimizer.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Index Optimizer for YATA Local
+ *
+ * Analyzes database indexes and provides optimization recommendations.
+ *
+ * @packageDocumentation
+ * @module @nahisaho/yata-local/index-optimizer
+ *
+ * @see REQ-YI-IDX-001 - Index Analysis
+ * @see REQ-YI-IDX-002 - Composite Index Generation
+ * @see REQ-YI-IDX-003 - Query Performance Monitoring
+ * @see DES-YATA-IMPROVEMENTS-001 - Design Document
+ */
+import type Database from 'better-sqlite3';
+/**
+ * Information about a database index
+ */
+export interface IndexInfo {
+    /** Index name */
+    name: string;
+    /** Table name */
+    table: string;
+    /** Columns in the index */
+    columns: string[];
+    /** Whether the index is unique */
+    unique: boolean;
+    /** Estimated number of rows */
+    rowCount: number;
+    /** SQLite internal sequential number */
+    seq: number;
+}
+/**
+ * Index recommendation
+ */
+export interface IndexRecommendation {
+    /** Recommendation type */
+    type: 'create' | 'drop' | 'modify';
+    /** Target table */
+    table: string;
+    /** Columns to index */
+    columns: string[];
+    /** Reason for recommendation */
+    reason: string;
+    /** Estimated improvement percentage */
+    estimatedImprovement: number;
+    /** SQL statement to execute */
+    sql: string;
+    /** Priority (1-5, 1 is highest) */
+    priority: number;
+}
+/**
+ * Query statistics from monitoring
+ */
+export interface QueryStats {
+    /** Query pattern (normalized) */
+    queryPattern: string;
+    /** Query hash for grouping */
+    queryHash: string;
+    /** Average execution time in milliseconds */
+    avgTimeMs: number;
+    /** Minimum execution time */
+    minTimeMs: number;
+    /** Maximum execution time */
+    maxTimeMs: number;
+    /** Total execution count */
+    executionCount: number;
+    /** Average rows examined */
+    avgRowsExamined: number;
+    /** Indexes used (if available) */
+    indexesUsed: string[];
+    /** Last execution timestamp */
+    lastExecuted: string;
+}
+/**
+ * Complete index analysis result
+ * @see REQ-YI-IDX-001
+ */
+export interface IndexAnalysisResult {
+    /** List of existing indexes */
+    indexes: IndexInfo[];
+    /** Optimization recommendations */
+    recommendations: IndexRecommendation[];
+    /** Query statistics (if monitoring enabled) */
+    queryStats: QueryStats[];
+    /** Analysis timestamp */
+    analyzedAt: string;
+    /** Analysis duration in milliseconds */
+    analysisTimeMs: number;
+    /** Database file path */
+    databasePath: string;
+    /** Total entities count */
+    entityCount: number;
+    /** Total relationships count */
+    relationshipCount: number;
+}
+/**
+ * Options for index analysis
+ */
+export interface AnalysisOptions {
+    /** Include query statistics */
+    includeQueryStats?: boolean;
+    /** Maximum recommendations to return */
+    maxRecommendations?: number;
+    /** Minimum improvement threshold for recommendations */
+    minImprovementThreshold?: number;
+}
+/**
+ * Options for creating composite index
+ */
+export interface CompositeIndexOptions {
+    /** Index name (auto-generated if not provided) */
+    name?: string;
+    /** Whether to create unique index */
+    unique?: boolean;
+    /** Execute immediately or return SQL only */
+    execute?: boolean;
+}
+/**
+ * Schema for query logging table
+ * @see REQ-YI-IDX-003
+ */
+export declare const QUERY_LOG_SCHEMA = "\n-- Query log table for performance monitoring\nCREATE TABLE IF NOT EXISTS query_log (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  query_hash TEXT NOT NULL,\n  query_pattern TEXT NOT NULL,\n  execution_time_ms INTEGER NOT NULL,\n  rows_examined INTEGER,\n  indexes_used TEXT,\n  timestamp TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_query_log_hash ON query_log(query_hash);\nCREATE INDEX IF NOT EXISTS idx_query_log_timestamp ON query_log(timestamp);\nCREATE INDEX IF NOT EXISTS idx_query_log_time ON query_log(execution_time_ms);\n";
+/**
+ * Index Optimizer for YATA Local database
+ *
+ * Provides index analysis, recommendations, and monitoring capabilities.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = new IndexOptimizer(db);
+ * const result = await optimizer.analyzeIndexes();
+ * console.log(result.recommendations);
+ * ```
+ *
+ * @see REQ-YI-IDX-001
+ * @see REQ-YI-IDX-002
+ * @see REQ-YI-IDX-003
+ */
+export declare class IndexOptimizer {
+    private db;
+    private monitoringEnabled;
+    constructor(db: Database.Database);
+    /**
+     * Analyze database indexes and generate recommendations
+     *
+     * Performance target: Complete within 5 seconds for up to 100,000 entities
+     *
+     * @param options - Analysis options
+     * @returns Index analysis result with recommendations
+     *
+     * @see REQ-YI-IDX-001
+     */
+    analyzeIndexes(options?: AnalysisOptions): Promise<IndexAnalysisResult>;
+    /**
+     * Get all existing indexes in the database
+     */
+    private getExistingIndexes;
+    /**
+     * Generate index recommendations based on analysis
+     */
+    private generateRecommendations;
+    /**
+     * Get row count for a table
+     */
+    private getTableRowCount;
+    /**
+     * Create a composite index on the specified table and columns
+     *
+     * @param table - Table name
+     * @param columns - Column names for the composite index
+     * @param options - Creation options
+     * @returns SQL statement (and executes if options.execute is true)
+     *
+     * @see REQ-YI-IDX-002
+     */
+    createCompositeIndex(table: string, columns: string[], options?: CompositeIndexOptions): string;
+    /**
+     * Apply all recommended indexes
+     *
+     * @param recommendations - List of recommendations to apply
+     * @returns Applied index names
+     */
+    applyRecommendations(recommendations: IndexRecommendation[]): string[];
+    /**
+     * Enable query performance monitoring
+     *
+     * Creates query_log table if it doesn't exist.
+     *
+     * @see REQ-YI-IDX-003
+     */
+    enableMonitoring(): void;
+    /**
+     * Disable query performance monitoring
+     */
+    disableMonitoring(): void;
+    /**
+     * Check if monitoring is enabled
+     */
+    isMonitoringEnabled(): boolean;
+    /**
+     * Log a query execution for monitoring
+     *
+     * @param queryPattern - Normalized query pattern
+     * @param executionTimeMs - Execution time in milliseconds
+     * @param rowsExamined - Number of rows examined (optional)
+     * @param indexesUsed - List of indexes used (optional)
+     */
+    logQuery(queryPattern: string, executionTimeMs: number, rowsExamined?: number, indexesUsed?: string[]): void;
+    /**
+     * Get query statistics from monitoring data
+     *
+     * @param limit - Maximum number of query patterns to return
+     * @returns Aggregated query statistics
+     */
+    getQueryStats(limit?: number): QueryStats[];
+    /**
+     * Get slow queries (queries exceeding threshold)
+     *
+     * @param thresholdMs - Minimum execution time to consider slow
+     * @param limit - Maximum results to return
+     * @returns Slow query entries
+     */
+    getSlowQueries(thresholdMs?: number, limit?: number): QueryStats[];
+    /**
+     * Clear query log (older than specified days)
+     *
+     * @param olderThanDays - Delete logs older than this many days (0 = all)
+     * @returns Number of deleted entries
+     */
+    clearQueryLog(olderThanDays?: number): number;
+    /**
+     * Check if query_log table exists
+     */
+    private isQueryLogTableExists;
+    /**
+     * Generate a hash for query pattern grouping
+     */
+    private hashQuery;
+    /**
+     * Run ANALYZE to update SQLite statistics
+     */
+    runAnalyze(): void;
+    /**
+     * Get database statistics summary
+     */
+    getDatabaseStats(): {
+        entityCount: number;
+        relationshipCount: number;
+        patternCount: number;
+        indexCount: number;
+        dbSizeBytes: number;
+    };
+}
+//# sourceMappingURL=index-optimizer.d.ts.map

package/dist/index-optimizer.d.ts.map

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