@linklabjs/core 0.1.0 → 0.1.1

package/dist/runtime/CompiledGraphEngine.js

@@ -0,0 +1,211 @@
+/**
+ * CompiledGraphEngine - Production engine using precompiled graph
+ *
+ * - O(1) route lookup
+ * - Automatic fallback
+ * - Live metrics
+ * - Hot reload support
+ */
+export class CompiledGraphEngine {
+    compiled;
+    provider;
+    liveMetrics;
+    routeCache;
+    constructor(compiled, provider) {
+        this.compiled = compiled;
+        this.provider = provider;
+        this.liveMetrics = new Map();
+        this.routeCache = this.buildRouteCache(compiled);
+        console.log('🚀 Compiled Graph Engine initialized');
+        console.log(`   Routes loaded: ${compiled.routes.length}`);
+        console.log(`   Nodes: ${compiled.nodes.length}`);
+    }
+    /**
+     * Build fast lookup cache
+     */
+    buildRouteCache(compiled) {
+        const cache = new Map();
+        for (const route of compiled.routes) {
+            const key = `${route.from}→${route.to}`;
+            cache.set(key, route);
+        }
+        return cache;
+    }
+    /**
+     * Execute query from -> to
+     */
+    async query(from, to, data = {}) {
+        const key = `${from}→${to}`;
+        // O(1) lookup!
+        const route = this.routeCache.get(key);
+        if (!route) {
+            throw new Error(`No compiled route from ${from} to ${to}`);
+        }
+        // Try primary path
+        try {
+            const start = performance.now();
+            const result = await this.executePath(route.primary.path, data);
+            const duration = performance.now() - start;
+            // Update metrics
+            this.updateMetrics(route.primary.path, duration, true);
+            return result;
+        }
+        catch (err) {
+            console.warn(`⚠️  Primary path failed: ${err.message}`);
+            // Try fallbacks
+            return await this.fallback(route, data);
+        }
+    }
+    /**
+     * Execute path with JOINs
+     */
+    async executePath(path, data) {
+        // Build SQL with JOINs
+        let sql = `SELECT * FROM ${path[0]}`;
+        const params = [];
+        // Add JOINs
+        for (let i = 1; i < path.length; i++) {
+            const from = path[i - 1];
+            const to = path[i];
+            // Find edge in compiled graph
+            const edge = this.findEdge(from, to);
+            if (edge) {
+                sql += ` JOIN ${to} ON ${from}.${edge.via} = ${to}.id`;
+            }
+        }
+        // Add WHERE if ID provided
+        if (data.id) {
+            sql += ` WHERE ${path[0]}.id = $${params.length + 1}`;
+            params.push(data.id);
+        }
+        // Execute
+        return await this.provider.query(sql, params);
+    }
+    /**
+     * Find edge between nodes
+     */
+    findEdge(from, to) {
+        // Simplified - would look in compiled graph edges
+        return { via: 'id' };
+    }
+    /**
+     * Fallback to alternative paths
+     */
+    async fallback(route, data) {
+        for (const [index, fallback] of route.fallbacks.entries()) {
+            try {
+                console.log(`   Trying fallback ${index + 1}/${route.fallbacks.length}...`);
+                const start = performance.now();
+                const result = await this.executePath(fallback.path, data);
+                const duration = performance.now() - start;
+                // Success!
+                console.log(`   ✅ Fallback worked: ${fallback.path.join('→')}`);
+                this.updateMetrics(fallback.path, duration, true);
+                // Maybe promote this fallback?
+                this.considerPromotion(route, index);
+                return result;
+            }
+            catch (err) {
+                console.warn(`   ✗ Fallback ${index + 1} failed: ${err.message}`);
+                this.updateMetrics(fallback.path, 0, false);
+                continue;
+            }
+        }
+        throw new Error('All paths failed');
+    }
+    /**
+     * Update live metrics
+     */
+    updateMetrics(path, duration, success) {
+        const key = path.join('→');
+        if (!this.liveMetrics.has(key)) {
+            this.liveMetrics.set(key, {
+                path,
+                executions: 0,
+                successes: 0,
+                failures: 0,
+                totalTime: 0,
+                avgTime: 0
+            });
+        }
+        const metric = this.liveMetrics.get(key);
+        metric.executions++;
+        if (success) {
+            metric.successes++;
+            metric.totalTime += duration;
+            metric.avgTime = metric.totalTime / metric.successes;
+        }
+        else {
+            metric.failures++;
+        }
+    }
+    /**
+     * Consider promoting a fallback to primary
+     */
+    considerPromotion(route, fallbackIndex) {
+        const fallback = route.fallbacks[fallbackIndex];
+        const fallbackKey = fallback.path.join('→');
+        const primaryKey = route.primary.path.join('→');
+        const fallbackMetric = this.liveMetrics.get(fallbackKey);
+        const primaryMetric = this.liveMetrics.get(primaryKey);
+        if (!fallbackMetric || !primaryMetric)
+            return;
+        // Promote if fallback is faster AND more reliable
+        const fallbackBetter = fallbackMetric.avgTime < primaryMetric.avgTime && fallbackMetric.successes > 5; // Min sample size
+        if (fallbackBetter) {
+            console.log(`🔄 Promoting fallback to primary: ${fallbackKey}`);
+            // Swap
+            const temp = route.primary;
+            route.primary = fallback;
+            route.fallbacks[fallbackIndex] = temp;
+            // Update cache
+            const key = `${route.from}→${route.to}`;
+            this.routeCache.set(key, route);
+        }
+    }
+    /**
+     * Get live statistics
+     */
+    getStats() {
+        const metrics = Array.from(this.liveMetrics.values());
+        if (metrics.length === 0) {
+            return {
+                totalExecutions: 0,
+                totalSuccesses: 0,
+                successRate: '0%',
+                avgTime: '0ms',
+                uniquePaths: 0
+            };
+        }
+        const totalExecutions = metrics.reduce((sum, m) => sum + m.executions, 0);
+        const totalSuccesses = metrics.reduce((sum, m) => sum + m.successes, 0);
+        const avgTime = metrics.reduce((sum, m) => sum + m.avgTime * m.successes, 0) / totalSuccesses;
+        const fastest = metrics.reduce((min, m) => (m.avgTime < min.avgTime ? m : min));
+        const slowest = metrics.reduce((max, m) => (m.avgTime > max.avgTime ? m : max));
+        return {
+            totalExecutions,
+            totalSuccesses,
+            successRate: ((totalSuccesses / totalExecutions) * 100).toFixed(1) + '%',
+            avgTime: avgTime.toFixed(2) + 'ms',
+            uniquePaths: metrics.length,
+            fastest,
+            slowest
+        };
+    }
+    /**
+     * Export metrics for recompilation
+     */
+    exportMetrics() {
+        return new Map(this.liveMetrics);
+    }
+    /**
+     * Hot reload compiled graph
+     */
+    reload(compiled) {
+        console.log('🔄 Hot reloading compiled graph...');
+        this.compiled = compiled;
+        this.routeCache = this.buildRouteCache(compiled);
+        console.log(`✅ Reloaded: ${compiled.routes.length} routes`);
+    }
+}
+//# sourceMappingURL=CompiledGraphEngine.js.map

package/dist/runtime/CompiledGraphEngine.js.map

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

package/dist/runtime/DataLoader.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DataLoader — Fetch les données pour un Trail résolu
+ *
+ * Fait le pont entre :
+ *   Trail (sémantique — où on est, d'où on vient)
+ *   QueryEngine (technique — comment fetcher les données)
+ *   Provider (physique — SQL ou JSON en mémoire)
+ *
+ * Principe :
+ *   Pour chaque frame RESOLVED dans le Trail, DataLoader
+ *   construit la requête optimale depuis le graphe compilé
+ *   et remplit frame.data avec les résultats.
+ *
+ * Deux modes de fetch :
+ *   SQL  — via Provider (PostgreSQL, MySQL...)
+ *   JSON — via dataset en mémoire (mock, tests, Netflix JSON)
+ *
+ * Usage :
+ * ```typescript
+ * const loader = new DataLoader(compiledGraph, { dataset })
+ * await loader.load(trail)
+ * // trail.current.data contient maintenant les données
+ * ```
+ */
+import type { CompiledGraph, Frame } from '../types/index.js';
+import type { Trail } from '../navigation/Trail.js';
+export interface DataLoaderOptions {
+    /**
+     * Dataset JSON en mémoire — pour les providers mock ou Netflix JSON.
+     * Clé = nom de l'entité, valeur = tableau de rows.
+     */
+    dataset?: Record<string, any[]>;
+    /**
+     * Provider SQL — pour PostgreSQL, MySQL, etc.
+     * Si fourni, prend la priorité sur dataset.
+     */
+    provider?: {
+        query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    };
+    /**
+     * Transforme les filtres d'une frame en paramètres SQL.
+     * Par défaut : { field: 'id', value: 1 } → WHERE entity.id = 1
+     */
+    buildFilters?: (frame: Frame) => Record<string, any>;
+}
+export declare class DataLoader {
+    private queryEngine;
+    private options;
+    constructor(compiledGraph: CompiledGraph, options?: DataLoaderOptions);
+    /**
+     * Charge les données pour la frame courante du Trail.
+     *
+     * Stratégie :
+     *   1. Si la frame courante est UNRESOLVED → rien à fetcher
+     *   2. Si depth === 1 → fetch direct de l'entité (avec id si présent)
+     *   3. Si depth > 1  → traverse depuis le dernier ancêtre résolu
+     *
+     * Mutate trail.current.data avec les résultats.
+     */
+    load(trail: Trail): Promise<void>;
+    /**
+     * Charge les données pour toutes les frames RESOLVED du Trail.
+     * Utile pour les réponses enrichies (chaque frame a ses données).
+     */
+    loadAll(trail: Trail): Promise<void>;
+    /**
+     * Trouve le premier ancêtre résolu avec un id dans le Trail.
+     * C'est le point de départ de la traversée.
+     */
+    private findAnchor;
+    /**
+     * Construit les filtres depuis le Trail.
+     * Combine les filtres de resolvedBy + l'id de l'ancêtre.
+     */
+    private buildFilters;
+    /**
+     * Résout la clé primaire d'une entité depuis le graphe compilé.
+     * Fallback : {entity}_id (convention dvdrental, PostgreSQL standard).
+     */
+    private pkOf;
+    /**
+     * Fetch direct — une seule entité, sans traversée.
+     */
+    private fetchDirect;
+    /**
+     * Fetch via route compilée — traverse from → to.
+     */
+    private fetchViaRoute;
+}
+//# sourceMappingURL=DataLoader.d.ts.map

package/dist/runtime/DataLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataLoader.d.ts","sourceRoot":"","sources":["../../src/runtime/DataLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAO,mBAAmB,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAuB,wBAAwB,CAAA;AAKpE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAE/B;;;OAGG;IACH,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;KAC1D,CAAA;IAED;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACrD;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,OAAO,CAAuB;gBAE1B,aAAa,EAAE,aAAa,EAAE,OAAO,GAAE,iBAAsB;IAKzE;;;;;;;;;OASG;IACG,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvC;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1C;;;OAGG;IACH,OAAO,CAAC,UAAU;IAWlB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA0BpB;;;OAGG;IACH,OAAO,CAAC,IAAI;IAMZ;;OAEG;YACW,WAAW;IAoCzB;;OAEG;YACW,aAAa;CA4B5B"}

package/dist/runtime/DataLoader.js

@@ -0,0 +1,178 @@
+/**
+ * DataLoader — Fetch les données pour un Trail résolu
+ *
+ * Fait le pont entre :
+ *   Trail (sémantique — où on est, d'où on vient)
+ *   QueryEngine (technique — comment fetcher les données)
+ *   Provider (physique — SQL ou JSON en mémoire)
+ *
+ * Principe :
+ *   Pour chaque frame RESOLVED dans le Trail, DataLoader
+ *   construit la requête optimale depuis le graphe compilé
+ *   et remplit frame.data avec les résultats.
+ *
+ * Deux modes de fetch :
+ *   SQL  — via Provider (PostgreSQL, MySQL...)
+ *   JSON — via dataset en mémoire (mock, tests, Netflix JSON)
+ *
+ * Usage :
+ * ```typescript
+ * const loader = new DataLoader(compiledGraph, { dataset })
+ * await loader.load(trail)
+ * // trail.current.data contient maintenant les données
+ * ```
+ */
+import { QueryEngine } from './QueryEngine.js';
+// ── DataLoader ────────────────────────────────────────────────
+export class DataLoader {
+    queryEngine;
+    options;
+    constructor(compiledGraph, options = {}) {
+        this.queryEngine = new QueryEngine(compiledGraph);
+        this.options = options;
+    }
+    /**
+     * Charge les données pour la frame courante du Trail.
+     *
+     * Stratégie :
+     *   1. Si la frame courante est UNRESOLVED → rien à fetcher
+     *   2. Si depth === 1 → fetch direct de l'entité (avec id si présent)
+     *   3. Si depth > 1  → traverse depuis le dernier ancêtre résolu
+     *
+     * Mutate trail.current.data avec les résultats.
+     */
+    async load(trail) {
+        const current = trail.current;
+        if (!current)
+            return;
+        if (current.state === 'UNRESOLVED')
+            return;
+        // Trouver l'ancêtre — point d'entrée de la traversée
+        const anchor = this.findAnchor(trail);
+        let data;
+        if (!anchor || anchor.entity === current.entity) {
+            const filters = current.id !== undefined ? { id: current.id } : {};
+            data = await this.fetchDirect(current.entity, filters);
+        }
+        else {
+            const filters = anchor.id !== undefined ? { id: anchor.id } : {};
+            data = await this.fetchViaRoute(anchor.entity, current.entity, filters);
+        }
+        ;
+        current.data = data;
+    }
+    /**
+     * Charge les données pour toutes les frames RESOLVED du Trail.
+     * Utile pour les réponses enrichies (chaque frame a ses données).
+     */
+    async loadAll(trail) {
+        for (let i = 0; i < trail.depth; i++) {
+            const frame = trail.at(i);
+            if (!frame || frame.state !== 'RESOLVED')
+                continue;
+            const subTrail = trail.slice(i + 1);
+            await this.load(subTrail);
+        }
+    }
+    // ── Privé ──────────────────────────────────────────────────
+    /**
+     * Trouve le premier ancêtre résolu avec un id dans le Trail.
+     * C'est le point de départ de la traversée.
+     */
+    findAnchor(trail) {
+        // Remonter le Trail depuis l'avant-dernière frame
+        for (let i = trail.depth - 2; i >= 0; i--) {
+            const frame = trail.at(i);
+            if (frame?.state === 'RESOLVED' && frame.id !== undefined) {
+                return frame;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Construit les filtres depuis le Trail.
+     * Combine les filtres de resolvedBy + l'id de l'ancêtre.
+     */
+    buildFilters(trail) {
+        const current = trail.current;
+        const filters = {};
+        // Filtre sur l'id de la frame courante si présent
+        if (current.id !== undefined) {
+            filters['id'] = current.id;
+        }
+        // Filtres portés par resolvedBy (conditions sémantiques)
+        if (current.resolvedBy?.filters) {
+            for (const f of current.resolvedBy.filters) {
+                if (f.operator === 'equals') {
+                    filters[f.field] = f.value;
+                }
+            }
+        }
+        // Override par buildFilters custom si fourni
+        if (this.options.buildFilters) {
+            return { ...filters, ...this.options.buildFilters(current) };
+        }
+        return filters;
+    }
+    /**
+     * Résout la clé primaire d'une entité depuis le graphe compilé.
+     * Fallback : {entity}_id (convention dvdrental, PostgreSQL standard).
+     */
+    pkOf(entity) {
+        const node = this.queryEngine.compiledGraph.nodes.find((n) => n.id === entity);
+        const pk = node?.primaryKey;
+        return Array.isArray(pk) ? pk[0] : (pk ?? `${entity}_id`);
+    }
+    /**
+     * Fetch direct — une seule entité, sans traversée.
+     */
+    async fetchDirect(entity, filters) {
+        if (this.options.provider) {
+            // SQL via provider — résoudre la PK réelle au lieu de supposer 'id'
+            const conditions = Object.entries(filters)
+                .map(([k, v], i) => {
+                const col = k === 'id' ? this.pkOf(entity) : k;
+                return `${entity}.${col} = $${i + 1}`;
+            })
+                .join(' AND ');
+            const sql = conditions
+                ? `SELECT * FROM ${entity} WHERE ${conditions}`
+                : `SELECT * FROM ${entity}`;
+            const params = Object.values(filters);
+            return this.options.provider.query(sql, params);
+        }
+        if (this.options.dataset) {
+            // JSON en mémoire — chercher sur la PK réelle ou 'id'
+            const pk = this.pkOf(entity);
+            const rows = this.options.dataset[entity] ?? [];
+            return rows.filter(row => Object.entries(filters).every(([k, v]) => {
+                const col = k === 'id' ? pk : k;
+                return row[col] === v;
+            }));
+        }
+        return [];
+    }
+    /**
+     * Fetch via route compilée — traverse from → to.
+     */
+    async fetchViaRoute(from, to, filters) {
+        // Vérifier que la route existe
+        let route;
+        try {
+            route = this.queryEngine.getRoute(from, to);
+        }
+        catch {
+            return this.fetchDirect(to, filters);
+        }
+        if (this.options.provider) {
+            const sql = this.queryEngine.generateSQL({ from, to, filters });
+            return this.options.provider.query(sql);
+        }
+        if (this.options.dataset) {
+            const result = this.queryEngine.executeInMemory({ from, to, filters }, this.options.dataset);
+            return result;
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=DataLoader.js.map

package/dist/runtime/DataLoader.js.map

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

package/dist/runtime/Engine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Engine - Core runtime engine with LRU cache
+ *
+ * Bus exposés :
+ *   engine.events  — cache.hit, cache.miss
+ *   engine.errors  — (extensible)
+ */
+import type { Provider, EngineConfig, CacheStats } from '../types/index.js';
+import { EventBus, ErrorBus } from '../core/EventBus.js';
+import type { CacheHitPayload, CacheMissPayload, GraphErrors } from '../core/GraphEvents.js';
+interface EngineEventMap {
+    'cache.hit': CacheHitPayload;
+    'cache.miss': CacheMissPayload;
+}
+export declare class Engine {
+    private provider;
+    maxSize: number;
+    private cache;
+    private hits;
+    private misses;
+    readonly events: EventBus<EngineEventMap>;
+    readonly errors: ErrorBus<GraphErrors>;
+    constructor(provider: Provider, config?: EngineConfig);
+    get<T = any>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    set<T = any>(key: string, value: T): void;
+    private evictIfNeeded;
+    clearCache(): void;
+    getStats(): CacheStats;
+    private getCurrentSize;
+    private estimateSize;
+    private formatSize;
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=Engine.d.ts.map

package/dist/runtime/Engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../src/runtime/Engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC3E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAW5F,UAAU,cAAc;IACtB,WAAW,EAAG,eAAe,CAAA;IAC7B,YAAY,EAAE,gBAAgB,CAAA;CAC/B;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAU;IACnB,OAAO,EAAI,MAAM,CAAA;IACxB,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,MAAM,CAAU;IAGxB,SAAgB,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;IAChD,SAAgB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;gBAEjC,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAE,YAAiB;IAUnD,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BtE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAiBzC,OAAO,CAAC,aAAa;IAmBrB,UAAU,IAAI,IAAI;IAOlB,QAAQ,IAAI,UAAU;IAmBtB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IAMZ,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,GAAG,EAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAI7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/runtime/Engine.js

@@ -0,0 +1,128 @@
+/**
+ * Engine - Core runtime engine with LRU cache
+ *
+ * Bus exposés :
+ *   engine.events  — cache.hit, cache.miss
+ *   engine.errors  — (extensible)
+ */
+import { EventBus, ErrorBus } from '../core/EventBus.js';
+export class Engine {
+    provider;
+    maxSize;
+    cache;
+    hits;
+    misses;
+    // ── Bus ──────────────────────────────────────────────────────
+    events;
+    errors;
+    constructor(provider, config = {}) {
+        this.provider = provider;
+        this.maxSize = config.cache?.maxSize ?? 10 * 1024 * 1024;
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        this.events = new EventBus();
+        this.errors = new ErrorBus();
+    }
+    async get(key, fetcher) {
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.hits++;
+            cached.accessCount++;
+            cached.lastAccess = Date.now();
+            // ── Event : cache.hit ──────────────────────────────────
+            this.events.emit('cache.hit', {
+                key,
+                accessCount: cached.accessCount,
+            });
+            return cached.value;
+        }
+        this.misses++;
+        // ── Event : cache.miss ─────────────────────────────────
+        this.events.emit('cache.miss', {
+            key,
+            requestedAt: Date.now(),
+        });
+        const value = await fetcher();
+        this.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        const size = this.estimateSize(value);
+        this.evictIfNeeded(size);
+        this.cache.set(key, {
+            key,
+            value,
+            size,
+            accessCount: 1,
+            lastAccess: Date.now(),
+        });
+        const formatted = this.formatSize(size);
+        const maxFormatted = this.formatSize(this.maxSize);
+        console.log(`💾 RAM CACHED: ${key} (${formatted}/${maxFormatted})`);
+    }
+    evictIfNeeded(neededSize) {
+        const currentSize = this.getCurrentSize();
+        if (currentSize + neededSize <= this.maxSize)
+            return;
+        const entries = Array.from(this.cache.values()).sort((a, b) => {
+            const scoreA = a.accessCount * 1000 + a.lastAccess;
+            const scoreB = b.accessCount * 1000 + b.lastAccess;
+            return scoreA - scoreB;
+        });
+        let freedSize = 0;
+        for (const entry of entries) {
+            if (currentSize - freedSize + neededSize <= this.maxSize)
+                break;
+            this.cache.delete(entry.key);
+            freedSize += entry.size;
+            console.log(`🗑️  RAM EVICTED: ${entry.key}`);
+        }
+    }
+    clearCache() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+        console.log('💾 RAM CLEARED');
+    }
+    getStats() {
+        const size = this.getCurrentSize();
+        const totalAccesses = this.hits + this.misses;
+        const hitRate = totalAccesses > 0
+            ? ((this.hits / totalAccesses) * 100).toFixed(1) + '%'
+            : '0%';
+        return {
+            entries: this.cache.size,
+            size,
+            sizeFormatted: this.formatSize(size),
+            maxSize: this.maxSize,
+            usage: ((size / this.maxSize) * 100).toFixed(1) + '%',
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+        };
+    }
+    getCurrentSize() {
+        let total = 0;
+        for (const entry of this.cache.values())
+            total += entry.size;
+        return total;
+    }
+    estimateSize(obj) {
+        return JSON.stringify(obj).length;
+    }
+    formatSize(bytes) {
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    }
+    async query(sql, params = []) {
+        return this.provider.query(sql, params);
+    }
+    async close() {
+        await this.provider.close();
+    }
+}
+//# sourceMappingURL=Engine.js.map