@feltdb/core 0.2.0 → 0.4.0

package/dist/index-dashboard.js

@@ -0,0 +1,256 @@
+/**
+ * Index Performance Dashboard
+ *
+ * Real-time visualization and monitoring of index performance metrics.
+ */
+/**
+ * Dashboard formatter - converts raw metrics to display format.
+ */
+export class DashboardFormatter {
+    /**
+     * Format index metrics for display.
+     */
+    static formatIndexMetrics(metrics) {
+        const now = Date.now();
+        const lastUsedMs = now - metrics.lastUsedAt;
+        const lastUsedRelative = this.formatDuration(lastUsedMs);
+        // Determine health status
+        let health = 'healthy';
+        let healthReason;
+        if (metrics.hitRate < 0.01 && lastUsedMs > 86400000) {
+            health = 'warning';
+            healthReason = 'Unused for 24+ hours';
+        }
+        else if (metrics.avgQueryTimeMs > 100) {
+            health = 'warning';
+            healthReason = 'Slow average query time';
+        }
+        else if (metrics.hitRate > 0.8 && metrics.reads > 1000) {
+            health = 'healthy';
+            healthReason = 'High-value index';
+        }
+        return {
+            name: metrics.name,
+            type: metrics.name.split('_').pop() || 'unknown',
+            reads: metrics.reads,
+            writes: metrics.writes,
+            hitRate: metrics.hitRate,
+            avgQueryMs: Math.round(metrics.avgQueryTimeMs * 100) / 100,
+            avgWriteMs: Math.round(metrics.avgWriteTimeMs * 100) / 100,
+            entries: metrics.entries,
+            lastUsedRelative,
+            health,
+            healthReason,
+        };
+    }
+    /**
+     * Format performance report for display.
+     */
+    static formatReport(report) {
+        const queryTraces = report.indexMetrics; // Simplified - would have actual traces
+        const indexUsageRate = report.indexedQueries / Math.max(report.totalQueries, 1);
+        // Calculate percentiles (simplified)
+        const avgQueryMs = report.avgQueryTimeMs;
+        const p50 = avgQueryMs;
+        const p95 = avgQueryMs * 1.5;
+        const p99 = avgQueryMs * 2;
+        return {
+            timestamp: report.timestamp,
+            indexes: report.indexMetrics.map(m => this.formatIndexMetrics(m)),
+            queryPerformance: {
+                totalQueries: report.totalQueries,
+                indexedQueries: report.indexedQueries,
+                fullScans: report.fullScans,
+                indexUsageRate,
+                avgQueryMs: Math.round(avgQueryMs * 100) / 100,
+                p50QueryMs: Math.round(p50 * 100) / 100,
+                p95QueryMs: Math.round(p95 * 100) / 100,
+                p99QueryMs: Math.round(p99 * 100) / 100,
+                slowQueries: Math.ceil(report.totalQueries * 0.05), // Estimate 5% slow
+            },
+            recommendations: report.recommendations,
+        };
+    }
+    /**
+     * Format duration for display.
+     */
+    static formatDuration(ms) {
+        if (ms < 1000)
+            return 'just now';
+        const seconds = Math.floor(ms / 1000);
+        if (seconds < 60)
+            return `${seconds} seconds ago`;
+        const minutes = Math.floor(seconds / 60);
+        if (minutes < 60)
+            return `${minutes} minutes ago`;
+        const hours = Math.floor(minutes / 60);
+        if (hours < 24)
+            return `${hours} hours ago`;
+        const days = Math.floor(hours / 24);
+        return `${days} days ago`;
+    }
+    /**
+     * Generate ASCII dashboard.
+     */
+    static renderASCII(dashboard) {
+        const lines = [];
+        lines.push('╔═══════════════════════════════════════════════════════════════╗');
+        lines.push('║          FeltDB Index Performance Dashboard                  ║');
+        lines.push('╠═══════════════════════════════════════════════════════════════╣');
+        // Query Performance Summary
+        const qp = dashboard.queryPerformance;
+        lines.push(`║ Queries: ${qp.totalQueries.toString().padEnd(10)} | Indexed: ${(qp.indexUsageRate * 100).toFixed(1)}% ${' '.repeat(10)} ║`);
+        lines.push(`║ Avg: ${qp.avgQueryMs.toFixed(2)}ms | P95: ${qp.p95QueryMs.toFixed(2)}ms | P99: ${qp.p99QueryMs.toFixed(2)}ms ${' '.repeat(5)} ║`);
+        lines.push('╟───────────────────────────────────────────────────────────────╢');
+        lines.push('║ Index Name          │ Type    │ Reads  │ Hit  │ Avg(ms) │ Health ║');
+        lines.push('╟─────────────────────┼─────────┼────────┼──────┼─────────┼────────╢');
+        for (const idx of dashboard.indexes) {
+            const health = idx.health === 'healthy' ? '✓' : idx.health === 'warning' ? '⚠' : '✗';
+            const line = `║ ${idx.name.padEnd(19)} │ ${idx.type.padEnd(7)} │ ${idx.reads.toString().padEnd(6)} │ ${(idx.hitRate * 100).toFixed(1).padEnd(4)}% │ ${idx.avgQueryMs.toFixed(3).padEnd(7)} │ ${health.padEnd(6)} ║`;
+            lines.push(line);
+        }
+        lines.push('╟───────────────────────────────────────────────────────────────╢');
+        lines.push('║ Recommendations                                               ║');
+        lines.push('╟───────────────────────────────────────────────────────────────╢');
+        for (const rec of dashboard.recommendations.slice(0, 3)) {
+            const priority = rec.priority === 'high' ? '🔴' : rec.priority === 'medium' ? '🟡' : '🟢';
+            lines.push(`║ ${priority} ${rec.reason.substring(0, 57).padEnd(57)} ║`);
+        }
+        lines.push('╚═══════════════════════════════════════════════════════════════╝');
+        return lines.join('\n');
+    }
+    /**
+     * Generate JSON dashboard data.
+     */
+    static renderJSON(dashboard) {
+        return JSON.stringify(dashboard, null, 2);
+    }
+}
+/**
+ * Real-time dashboard updates via events.
+ */
+export class LiveDashboard {
+    constructor() {
+        this.metrics = null;
+        this.listeners = new Set();
+        this.updateInterval = 10000; // 10 seconds
+    }
+    /**
+     * Start streaming dashboard updates.
+     */
+    start(updateFn, interval = 10000) {
+        this.updateInterval = interval;
+        this.intervalHandle = setInterval(() => {
+            this.metrics = updateFn();
+            this.notifyListeners();
+        }, this.updateInterval);
+    }
+    /**
+     * Stop streaming updates.
+     */
+    stop() {
+        if (this.intervalHandle) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = undefined;
+        }
+    }
+    /**
+     * Subscribe to dashboard updates.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        if (this.metrics) {
+            listener(this.metrics);
+        }
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Get current dashboard state.
+     */
+    getCurrent() {
+        return this.metrics;
+    }
+    notifyListeners() {
+        if (!this.metrics)
+            return;
+        for (const listener of this.listeners) {
+            listener(this.metrics);
+        }
+    }
+}
+export class PerformanceAlerter {
+    constructor() {
+        this.alerts = [];
+        this.thresholds = {
+            slowQueryMs: 100,
+            fullScanThreshold: 0.2, // 20% full scans is warning
+            indexOverhead: 0.1, // 10% write overhead is warning
+        };
+    }
+    /**
+     * Check dashboard against thresholds and generate alerts.
+     */
+    checkThresholds(dashboard) {
+        const newAlerts = [];
+        const qp = dashboard.queryPerformance;
+        // Alert on slow average query time
+        if (qp.avgQueryMs > this.thresholds.slowQueryMs) {
+            newAlerts.push({
+                severity: 'warning',
+                type: 'slow_query',
+                message: `Average query time ${qp.avgQueryMs.toFixed(2)}ms exceeds threshold`,
+                timestamp: Date.now(),
+                metrics: {
+                    avgQueryMs: qp.avgQueryMs,
+                    threshold: this.thresholds.slowQueryMs,
+                },
+            });
+        }
+        // Alert on high full scan rate
+        const fullScanRate = qp.fullScans / qp.totalQueries;
+        if (fullScanRate > this.thresholds.fullScanThreshold) {
+            newAlerts.push({
+                severity: 'warning',
+                type: 'high_full_scans',
+                message: `Full scans at ${(fullScanRate * 100).toFixed(1)}% exceeds threshold`,
+                timestamp: Date.now(),
+                metrics: {
+                    fullScanRate: (fullScanRate * 100).toFixed(1),
+                    threshold: this.thresholds.fullScanThreshold * 100,
+                },
+            });
+        }
+        // Alert on unused indexes
+        for (const idx of dashboard.indexes) {
+            if (idx.hitRate < 0.01 && idx.lastUsedRelative.includes('day')) {
+                newAlerts.push({
+                    severity: 'info',
+                    type: 'unused_index',
+                    message: `Index '${idx.name}' has low hit rate and is unused`,
+                    timestamp: Date.now(),
+                    metrics: {
+                        index: idx.name,
+                        hitRate: (idx.hitRate * 100).toFixed(2),
+                    },
+                });
+            }
+        }
+        this.alerts.push(...newAlerts);
+        return newAlerts;
+    }
+    /**
+     * Get recent alerts.
+     */
+    getRecentAlerts(limit = 50) {
+        return this.alerts.slice(-limit);
+    }
+    /**
+     * Clear old alerts.
+     */
+    clearOldAlerts(olderThanMs = 3600000) {
+        const cutoff = Date.now() - olderThanMs;
+        this.alerts = this.alerts.filter(a => a.timestamp > cutoff);
+    }
+}

package/dist/index-manager.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Index Manager
+ *
+ * Manages creation, maintenance, and query optimization using indexes.
+ */
+import type { IndexConfig, IndexQuery, IndexStats, QueryPlan } from './index-types.js';
+export declare class IndexManager {
+    private indexes;
+    private config;
+    private indexStats;
+    createIndex(config: IndexConfig): void;
+    updateRecord(recordId: string, oldValue: Record<string, any> | null, newValue: Record<string, any>): void;
+    queryIndex(name: string, query: IndexQuery): string[];
+    listIndexes(): IndexConfig[];
+    getStats(name: string): IndexStats | null;
+    planQuery(fields: string[]): QueryPlan;
+}
+//# sourceMappingURL=index-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-manager.d.ts","sourceRoot":"","sources":["../src/index-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAc,UAAU,EAAE,UAAU,EAAe,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AAyN/H,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAyE;IACxF,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,UAAU,CAAsC;IAExD,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IA8BtC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IA6BzG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;IA0BrD,WAAW,IAAI,WAAW,EAAE;IAI5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIzC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS;CAwCvC"}

package/dist/index-manager.js

@@ -0,0 +1,333 @@
+/**
+ * Index Manager
+ *
+ * Manages creation, maintenance, and query optimization using indexes.
+ */
+class HashIndex {
+    constructor(field) {
+        this.entries = new Map();
+        this.stats = { reads: 0, writes: 0, selectivity: 0 };
+        this.field = field;
+    }
+    add(recordId, value) {
+        const key = this.normalizeKey(value);
+        if (!this.entries.has(key)) {
+            this.entries.set(key, new Set());
+        }
+        this.entries.get(key).add(recordId);
+        this.stats.writes++;
+    }
+    remove(recordId, value) {
+        const key = this.normalizeKey(value);
+        const ids = this.entries.get(key);
+        if (ids) {
+            ids.delete(recordId);
+            if (ids.size === 0) {
+                this.entries.delete(key);
+            }
+        }
+        this.stats.writes++;
+    }
+    query(value) {
+        const key = this.normalizeKey(value);
+        this.stats.reads++;
+        const ids = this.entries.get(key);
+        return ids ? Array.from(ids) : [];
+    }
+    size() {
+        return this.entries.size;
+    }
+    getStats() {
+        return {
+            entries: this.entries.size,
+            reads: this.stats.reads,
+            writes: this.stats.writes,
+            selectivity: this.entries.size > 0 ? 1 / this.entries.size : 0,
+        };
+    }
+    normalizeKey(value) {
+        if (value === null || value === undefined)
+            return '__null__';
+        if (typeof value === 'object')
+            return JSON.stringify(value);
+        return String(value);
+    }
+}
+class SortedIndex {
+    constructor(field) {
+        this.entries = [];
+        this.stats = { reads: 0, writes: 0, selectivity: 0 };
+        this.field = field;
+    }
+    add(recordId, value) {
+        let entry = this.entries.find(e => this.compareKeys(e.key, value) === 0);
+        if (!entry) {
+            entry = { key: value, recordIds: new Set() };
+            this.entries.push(entry);
+            this.entries.sort((a, b) => this.compareKeys(a.key, b.key));
+        }
+        entry.recordIds.add(recordId);
+        this.stats.writes++;
+    }
+    remove(recordId, value) {
+        const entry = this.entries.find(e => this.compareKeys(e.key, value) === 0);
+        if (entry) {
+            entry.recordIds.delete(recordId);
+            if (entry.recordIds.size === 0) {
+                this.entries = this.entries.filter(e => e !== entry);
+            }
+        }
+        this.stats.writes++;
+    }
+    queryEqual(value) {
+        this.stats.reads++;
+        const entry = this.entries.find(e => this.compareKeys(e.key, value) === 0);
+        return entry ? Array.from(entry.recordIds) : [];
+    }
+    queryRange(min, max, includeMin = true, includeMax = true) {
+        this.stats.reads++;
+        const result = new Set();
+        for (const entry of this.entries) {
+            const cmpMin = this.compareKeys(entry.key, min);
+            const cmpMax = this.compareKeys(entry.key, max);
+            const inRange = (includeMin ? cmpMin >= 0 : cmpMin > 0) && (includeMax ? cmpMax <= 0 : cmpMax < 0);
+            if (inRange) {
+                entry.recordIds.forEach(id => result.add(id));
+            }
+        }
+        return Array.from(result);
+    }
+    size() {
+        return this.entries.length;
+    }
+    getStats() {
+        const totalIds = this.entries.reduce((sum, e) => sum + e.recordIds.size, 0);
+        return {
+            entries: this.entries.length,
+            reads: this.stats.reads,
+            writes: this.stats.writes,
+            selectivity: this.entries.length > 0 ? 1 / this.entries.length : 0,
+        };
+    }
+    compareKeys(a, b) {
+        if (a === null || a === undefined)
+            return -1;
+        if (b === null || b === undefined)
+            return 1;
+        if (a < b)
+            return -1;
+        if (a > b)
+            return 1;
+        return 0;
+    }
+}
+class TextIndex {
+    constructor(fields) {
+        this.tokenIndex = new Map();
+        this.stats = { reads: 0, writes: 0, selectivity: 0 };
+        this.fields = fields;
+    }
+    add(recordId, data) {
+        const text = this.extractText(data);
+        const tokens = this.tokenize(text);
+        for (const token of tokens) {
+            if (!this.tokenIndex.has(token)) {
+                this.tokenIndex.set(token, new Set());
+            }
+            this.tokenIndex.get(token).add(recordId);
+        }
+        this.stats.writes++;
+    }
+    remove(recordId, data) {
+        const text = this.extractText(data);
+        const tokens = this.tokenize(text);
+        for (const token of tokens) {
+            const ids = this.tokenIndex.get(token);
+            if (ids) {
+                ids.delete(recordId);
+                if (ids.size === 0) {
+                    this.tokenIndex.delete(token);
+                }
+            }
+        }
+        this.stats.writes++;
+    }
+    query(searchText) {
+        this.stats.reads++;
+        const tokens = this.tokenize(searchText);
+        if (tokens.length === 0)
+            return [];
+        let result = this.tokenIndex.get(tokens[0]);
+        if (!result)
+            return [];
+        result = new Set(result);
+        for (let i = 1; i < tokens.length; i++) {
+            const tokenIds = this.tokenIndex.get(tokens[i]);
+            if (!tokenIds)
+                return [];
+            result = new Set([...result].filter(id => tokenIds.has(id)));
+        }
+        return Array.from(result);
+    }
+    size() {
+        return this.tokenIndex.size;
+    }
+    getStats() {
+        return {
+            entries: this.tokenIndex.size,
+            reads: this.stats.reads,
+            writes: this.stats.writes,
+            selectivity: this.tokenIndex.size > 0 ? 1 / this.tokenIndex.size : 0,
+        };
+    }
+    extractText(data) {
+        return this.fields
+            .map(field => {
+            const value = data[field];
+            return value ? String(value) : '';
+        })
+            .join(' ');
+    }
+    tokenize(text) {
+        return text
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(t => t.length > 0);
+    }
+}
+export class IndexManager {
+    constructor() {
+        this.indexes = new Map();
+        this.config = new Map();
+        this.indexStats = new Map();
+    }
+    createIndex(config) {
+        if (this.indexes.has(config.name)) {
+            throw new Error(`Index ${config.name} already exists`);
+        }
+        let index;
+        if (config.type === 'hash' && config.field) {
+            index = new HashIndex(config.field);
+        }
+        else if (config.type === 'sorted' && config.field) {
+            index = new SortedIndex(config.field);
+        }
+        else if (config.type === 'text' && config.textFields) {
+            index = new TextIndex(config.textFields);
+        }
+        else {
+            throw new Error(`Invalid index config: ${JSON.stringify(config)}`);
+        }
+        this.indexes.set(config.name, index);
+        this.config.set(config.name, config);
+        this.indexStats.set(config.name, {
+            name: config.name,
+            type: config.type,
+            entries: 0,
+            size: 0,
+            lastUpdated: Date.now(),
+            reads: 0,
+            writes: 0,
+            selectivity: 0,
+        });
+    }
+    updateRecord(recordId, oldValue, newValue) {
+        for (const [name, index] of this.indexes) {
+            const config = this.config.get(name);
+            if (oldValue) {
+                if (config.type === 'hash' && config.field) {
+                    index.remove(recordId, oldValue[config.field]);
+                }
+                else if (config.type === 'sorted' && config.field) {
+                    index.remove(recordId, oldValue[config.field]);
+                }
+                else if (config.type === 'text') {
+                    index.remove(recordId, oldValue);
+                }
+            }
+            if (config.type === 'hash' && config.field) {
+                index.add(recordId, newValue[config.field]);
+            }
+            else if (config.type === 'sorted' && config.field) {
+                index.add(recordId, newValue[config.field]);
+            }
+            else if (config.type === 'text') {
+                index.add(recordId, newValue);
+            }
+            const stats = this.indexStats.get(name);
+            stats.lastUpdated = Date.now();
+            const indexStats = index.getStats();
+            Object.assign(stats, indexStats);
+        }
+    }
+    queryIndex(name, query) {
+        const index = this.indexes.get(name);
+        if (!index)
+            throw new Error(`Index ${name} not found`);
+        const config = this.config.get(name);
+        if (config.type === 'hash') {
+            return index.query(query.value);
+        }
+        else if (config.type === 'sorted') {
+            const sorted = index;
+            if (query.operator === 'eq') {
+                return sorted.queryEqual(query.value);
+            }
+            else if (query.operator === 'range') {
+                return sorted.queryRange(query.min, query.max);
+            }
+            else if (query.operator === 'gte') {
+                return sorted.queryRange(query.value, Number.MAX_VALUE);
+            }
+            else if (query.operator === 'lte') {
+                return sorted.queryRange(Number.MIN_VALUE, query.value);
+            }
+        }
+        else if (config.type === 'text') {
+            return index.query(query.value);
+        }
+        return [];
+    }
+    listIndexes() {
+        return Array.from(this.config.values());
+    }
+    getStats(name) {
+        return this.indexStats.get(name) || null;
+    }
+    planQuery(fields) {
+        const plans = [];
+        for (const field of fields) {
+            for (const [name, config] of this.config) {
+                if (config.field === field || config.fields?.includes(field)) {
+                    const stats = this.indexStats.get(name);
+                    plans.push({
+                        indexName: name,
+                        indexType: config.type,
+                        estimatedRows: Math.ceil(100 / (stats.selectivity || 1)),
+                        cost: stats.reads + stats.writes,
+                        canPruneAll: config.type === 'hash',
+                        requiresPostFilter: config.type === 'text' || config.type === 'sorted',
+                    });
+                }
+            }
+        }
+        if (plans.length === 0) {
+            return {
+                strategy: 'full-scan',
+                indexes: [],
+                estimatedRows: 1000,
+                totalCost: 1000,
+                explanation: 'No suitable index found, using full collection scan',
+            };
+        }
+        plans.sort((a, b) => a.cost - b.cost);
+        const best = plans[0];
+        return {
+            strategy: 'index-scan',
+            indexes: [best],
+            estimatedRows: best.estimatedRows,
+            totalCost: best.cost,
+            explanation: `Using ${best.indexType} index on ${best.indexName}`,
+        };
+    }
+}