@od-oneapp/ai-platform 0.1.0

package/dist/caching-strategies.mjs

@@ -0,0 +1,703 @@
+//#region src/caching/strategies/index.ts
+/**
+* Create an LRU (Least Recently Used) eviction strategy.
+* Evicts the least recently accessed items when capacity is reached.
+*
+* @example
+* ```typescript
+* const cache = createLRUStrategy<string>({ maxSize: 100 });
+* cache.set('user:1', 'Alice');
+* cache.get('user:1'); // Returns 'Alice', updates access time
+* ```
+*/
+function createLRUStrategy(config) {
+	const { maxSize, defaultTtlMs, onEvict } = config;
+	const cache = /* @__PURE__ */ new Map();
+	let hits = 0;
+	let misses = 0;
+	let evictions = 0;
+	function evictExpired() {
+		const now = Date.now();
+		for (const [key, entry] of cache) if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+		}
+	}
+	function evictLRU() {
+		if (cache.size === 0) return;
+		let oldestKey = null;
+		let oldestTime = Infinity;
+		for (const [key, entry] of cache) if (entry.meta.lastAccessedAt < oldestTime) {
+			oldestTime = entry.meta.lastAccessedAt;
+			oldestKey = key;
+		}
+		if (oldestKey) {
+			const entry = cache.get(oldestKey);
+			cache.delete(oldestKey);
+			if (entry) onEvict?.(oldestKey, entry.value);
+			evictions++;
+		}
+	}
+	function get(key) {
+		evictExpired();
+		const entry = cache.get(key);
+		if (!entry) {
+			misses++;
+			return;
+		}
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+			misses++;
+			return;
+		}
+		entry.meta.lastAccessedAt = Date.now();
+		entry.meta.accessCount++;
+		hits++;
+		cache.delete(key);
+		cache.set(key, entry);
+		return entry.value;
+	}
+	function set(key, value, ttlMs) {
+		evictExpired();
+		if (!cache.has(key) && cache.size >= maxSize) evictLRU();
+		const now = Date.now();
+		const effectiveTtl = ttlMs ?? defaultTtlMs;
+		const entry = {
+			key,
+			value,
+			meta: {
+				createdAt: now,
+				lastAccessedAt: now,
+				accessCount: 1,
+				expiresAt: effectiveTtl ? now + effectiveTtl : void 0
+			}
+		};
+		cache.delete(key);
+		cache.set(key, entry);
+	}
+	function has(key) {
+		const entry = cache.get(key);
+		if (!entry) return false;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			return false;
+		}
+		return true;
+	}
+	function del(key) {
+		if (cache.get(key)) {
+			cache.delete(key);
+			return true;
+		}
+		return false;
+	}
+	function clear() {
+		cache.clear();
+	}
+	function size() {
+		evictExpired();
+		return cache.size;
+	}
+	function keys() {
+		evictExpired();
+		return Array.from(cache.keys());
+	}
+	function stats() {
+		const total = hits + misses;
+		return {
+			hits,
+			misses,
+			evictions,
+			currentSize: cache.size,
+			maxSize,
+			hitRate: total > 0 ? hits / total : 0
+		};
+	}
+	function peek(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry.value;
+	}
+	function peekEntry(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry;
+	}
+	return {
+		get,
+		set,
+		has,
+		delete: del,
+		clear,
+		size,
+		keys,
+		stats,
+		peek,
+		peekEntry
+	};
+}
+/**
+* Create an LFU (Least Frequently Used) eviction strategy.
+* Evicts the least frequently accessed items when capacity is reached.
+*
+* @example
+* ```typescript
+* const cache = createLFUStrategy<string>({ maxSize: 100 });
+* cache.set('popular', 'data');
+* cache.get('popular'); // Increases frequency
+* cache.get('popular'); // Now won't be evicted easily
+* ```
+*/
+function createLFUStrategy(config) {
+	const { maxSize, defaultTtlMs, onEvict } = config;
+	const cache = /* @__PURE__ */ new Map();
+	let hits = 0;
+	let misses = 0;
+	let evictions = 0;
+	function evictExpired() {
+		const now = Date.now();
+		for (const [key, entry] of cache) if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+		}
+	}
+	function evictLFU() {
+		if (cache.size === 0) return;
+		let lfuKey = null;
+		let minFreq = Infinity;
+		let oldestTime = Infinity;
+		for (const [key, entry] of cache) if (entry.meta.accessCount < minFreq || entry.meta.accessCount === minFreq && entry.meta.lastAccessedAt < oldestTime) {
+			minFreq = entry.meta.accessCount;
+			oldestTime = entry.meta.lastAccessedAt;
+			lfuKey = key;
+		}
+		if (lfuKey) {
+			const entry = cache.get(lfuKey);
+			cache.delete(lfuKey);
+			if (entry) onEvict?.(lfuKey, entry.value);
+			evictions++;
+		}
+	}
+	function get(key) {
+		evictExpired();
+		const entry = cache.get(key);
+		if (!entry) {
+			misses++;
+			return;
+		}
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+			misses++;
+			return;
+		}
+		entry.meta.lastAccessedAt = Date.now();
+		entry.meta.accessCount++;
+		hits++;
+		return entry.value;
+	}
+	function set(key, value, ttlMs) {
+		evictExpired();
+		if (!cache.has(key) && cache.size >= maxSize) evictLFU();
+		const now = Date.now();
+		const effectiveTtl = ttlMs ?? defaultTtlMs;
+		const existing = cache.get(key);
+		const entry = {
+			key,
+			value,
+			meta: {
+				createdAt: existing?.meta.createdAt ?? now,
+				lastAccessedAt: now,
+				accessCount: existing ? existing.meta.accessCount + 1 : 1,
+				expiresAt: effectiveTtl ? now + effectiveTtl : void 0
+			}
+		};
+		cache.set(key, entry);
+	}
+	function has(key) {
+		const entry = cache.get(key);
+		if (!entry) return false;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			return false;
+		}
+		return true;
+	}
+	function del(key) {
+		return cache.delete(key);
+	}
+	function clear() {
+		cache.clear();
+	}
+	function size() {
+		evictExpired();
+		return cache.size;
+	}
+	function keys() {
+		evictExpired();
+		return Array.from(cache.keys());
+	}
+	function stats() {
+		const total = hits + misses;
+		return {
+			hits,
+			misses,
+			evictions,
+			currentSize: cache.size,
+			maxSize,
+			hitRate: total > 0 ? hits / total : 0
+		};
+	}
+	function peek(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry.value;
+	}
+	function peekEntry(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry;
+	}
+	return {
+		get,
+		set,
+		has,
+		delete: del,
+		clear,
+		size,
+		keys,
+		stats,
+		peek,
+		peekEntry
+	};
+}
+/**
+* Create a FIFO (First In First Out) eviction strategy.
+* Evicts the oldest items first when capacity is reached.
+*
+* @example
+* ```typescript
+* const cache = createFIFOStrategy<string>({ maxSize: 100 });
+* cache.set('first', 'data'); // Will be evicted first
+* cache.set('second', 'data');
+* ```
+*/
+function createFIFOStrategy(config) {
+	const { maxSize, defaultTtlMs, onEvict } = config;
+	const cache = /* @__PURE__ */ new Map();
+	let hits = 0;
+	let misses = 0;
+	let evictions = 0;
+	function evictExpired() {
+		const now = Date.now();
+		for (const [key, entry] of cache) if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+		}
+	}
+	function evictFIFO() {
+		if (cache.size === 0) return;
+		const firstKey = cache.keys().next().value;
+		if (firstKey) {
+			const entry = cache.get(firstKey);
+			cache.delete(firstKey);
+			if (entry) onEvict?.(firstKey, entry.value);
+			evictions++;
+		}
+	}
+	function get(key) {
+		evictExpired();
+		const entry = cache.get(key);
+		if (!entry) {
+			misses++;
+			return;
+		}
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+			misses++;
+			return;
+		}
+		entry.meta.lastAccessedAt = Date.now();
+		entry.meta.accessCount++;
+		hits++;
+		return entry.value;
+	}
+	function set(key, value, ttlMs) {
+		evictExpired();
+		if (!cache.has(key) && cache.size >= maxSize) evictFIFO();
+		const now = Date.now();
+		const effectiveTtl = ttlMs ?? defaultTtlMs;
+		const existing = cache.get(key);
+		const entry = {
+			key,
+			value,
+			meta: {
+				createdAt: existing?.meta.createdAt ?? now,
+				lastAccessedAt: now,
+				accessCount: existing ? existing.meta.accessCount + 1 : 1,
+				expiresAt: effectiveTtl ? now + effectiveTtl : void 0
+			}
+		};
+		if (existing) cache.set(key, entry);
+		else cache.set(key, entry);
+	}
+	function has(key) {
+		const entry = cache.get(key);
+		if (!entry) return false;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			return false;
+		}
+		return true;
+	}
+	function del(key) {
+		return cache.delete(key);
+	}
+	function clear() {
+		cache.clear();
+	}
+	function size() {
+		evictExpired();
+		return cache.size;
+	}
+	function keys() {
+		evictExpired();
+		return Array.from(cache.keys());
+	}
+	function stats() {
+		const total = hits + misses;
+		return {
+			hits,
+			misses,
+			evictions,
+			currentSize: cache.size,
+			maxSize,
+			hitRate: total > 0 ? hits / total : 0
+		};
+	}
+	function peek(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry.value;
+	}
+	function peekEntry(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry;
+	}
+	return {
+		get,
+		set,
+		has,
+		delete: del,
+		clear,
+		size,
+		keys,
+		stats,
+		peek,
+		peekEntry
+	};
+}
+/**
+* Create a TTL (Time To Live) eviction strategy.
+* Items automatically expire after their TTL.
+*
+* @example
+* ```typescript
+* const cache = createTTLStrategy<string>({
+*   maxSize: 1000,
+*   defaultTtlMs: 60000 // 1 minute default
+* });
+* cache.set('temp', 'data', 5000); // Expires in 5 seconds
+* ```
+*/
+function createTTLStrategy(config) {
+	const { maxSize, defaultTtlMs = 6e4, onEvict } = config;
+	const cache = /* @__PURE__ */ new Map();
+	let hits = 0;
+	let misses = 0;
+	let evictions = 0;
+	function evictExpired() {
+		const now = Date.now();
+		let count = 0;
+		for (const [key, entry] of cache) if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+			count++;
+		}
+		return count;
+	}
+	function evictOldest() {
+		if (cache.size === 0) return;
+		let oldestKey = null;
+		let oldestExpiry = Infinity;
+		for (const [key, entry] of cache) {
+			const expiry = entry.meta.expiresAt ?? entry.meta.createdAt;
+			if (expiry < oldestExpiry) {
+				oldestExpiry = expiry;
+				oldestKey = key;
+			}
+		}
+		if (oldestKey) {
+			const entry = cache.get(oldestKey);
+			cache.delete(oldestKey);
+			if (entry) onEvict?.(oldestKey, entry.value);
+			evictions++;
+		}
+	}
+	function get(key) {
+		evictExpired();
+		const entry = cache.get(key);
+		if (!entry) {
+			misses++;
+			return;
+		}
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			evictions++;
+			misses++;
+			return;
+		}
+		entry.meta.lastAccessedAt = Date.now();
+		entry.meta.accessCount++;
+		hits++;
+		return entry.value;
+	}
+	function set(key, value, ttlMs) {
+		evictExpired();
+		if (!cache.has(key) && cache.size >= maxSize) evictOldest();
+		const now = Date.now();
+		const entry = {
+			key,
+			value,
+			meta: {
+				createdAt: now,
+				lastAccessedAt: now,
+				accessCount: 1,
+				expiresAt: now + (ttlMs ?? defaultTtlMs)
+			}
+		};
+		cache.set(key, entry);
+	}
+	function has(key) {
+		const entry = cache.get(key);
+		if (!entry) return false;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+			cache.delete(key);
+			onEvict?.(key, entry.value);
+			return false;
+		}
+		return true;
+	}
+	function del(key) {
+		return cache.delete(key);
+	}
+	function clear() {
+		cache.clear();
+	}
+	function size() {
+		evictExpired();
+		return cache.size;
+	}
+	function keys() {
+		evictExpired();
+		return Array.from(cache.keys());
+	}
+	function stats() {
+		const total = hits + misses;
+		return {
+			hits,
+			misses,
+			evictions,
+			currentSize: cache.size,
+			maxSize,
+			hitRate: total > 0 ? hits / total : 0
+		};
+	}
+	function peek(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry.value;
+	}
+	function peekEntry(key) {
+		const entry = cache.get(key);
+		if (!entry) return void 0;
+		if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) return;
+		return entry;
+	}
+	return {
+		get,
+		set,
+		has,
+		delete: del,
+		clear,
+		size,
+		keys,
+		stats,
+		peek,
+		peekEntry
+	};
+}
+/**
+* Create an Adaptive eviction strategy.
+* Dynamically switches between LRU and LFU based on access patterns.
+*
+* @example
+* ```typescript
+* const cache = createAdaptiveStrategy<string>({
+*   maxSize: 1000,
+*   analysisWindowMs: 60000 // Analyze every minute
+* });
+* ```
+*/
+function createAdaptiveStrategy(config) {
+	const { maxSize, defaultTtlMs, onEvict, analysisWindowMs = 6e4, analysisIntervalMs = 1e4 } = config;
+	let currentStrategy = "lru";
+	const lruCache = createLRUStrategy({
+		maxSize,
+		defaultTtlMs,
+		onEvict
+	});
+	const lfuCache = createLFUStrategy({
+		maxSize,
+		defaultTtlMs,
+		onEvict
+	});
+	let activeCache = lruCache;
+	const accessLog = [];
+	let lastAnalysis = Date.now();
+	function analyzePatterns() {
+		const now = Date.now();
+		if (now - lastAnalysis < analysisIntervalMs) return;
+		lastAnalysis = now;
+		const windowStart = now - analysisWindowMs;
+		const recentAccesses = accessLog.filter((a) => a.time >= windowStart);
+		if (recentAccesses.length < 10) return;
+		const keyCounts = /* @__PURE__ */ new Map();
+		for (const access of recentAccesses) keyCounts.set(access.key, (keyCounts.get(access.key) ?? 0) + 1);
+		const counts = Array.from(keyCounts.values());
+		const mean = counts.reduce((a, b) => a + b, 0) / counts.length;
+		const variance = counts.reduce((sum, c) => sum + Math.pow(c - mean, 2), 0) / counts.length;
+		const shouldUseLFU = (mean > 0 ? Math.sqrt(variance) / mean : 0) > 1.5;
+		if (shouldUseLFU && currentStrategy !== "lfu") {
+			const entries = lruCache.keys().map((k) => lruCache.peekEntry?.(k)).filter((e) => e !== void 0);
+			lfuCache.clear();
+			for (const entry of entries) {
+				const remainingTtlMs = entry.meta.expiresAt ? Math.max(0, entry.meta.expiresAt - now) : void 0;
+				if (remainingTtlMs === void 0 || remainingTtlMs > 0) lfuCache.set(entry.key, entry.value, remainingTtlMs);
+			}
+			lruCache.clear();
+			activeCache = lfuCache;
+			currentStrategy = "lfu";
+		} else if (!shouldUseLFU && currentStrategy !== "lru") {
+			const entries = lfuCache.keys().map((k) => lfuCache.peekEntry?.(k)).filter((e) => e !== void 0);
+			lruCache.clear();
+			for (const entry of entries) {
+				const remainingTtlMs = entry.meta.expiresAt ? Math.max(0, entry.meta.expiresAt - now) : void 0;
+				if (remainingTtlMs === void 0 || remainingTtlMs > 0) lruCache.set(entry.key, entry.value, remainingTtlMs);
+			}
+			lfuCache.clear();
+			activeCache = lruCache;
+			currentStrategy = "lru";
+		}
+		const maxLogLength = 1e4;
+		while (accessLog.length > 0 && (accessLog[0]?.time ?? 0) < windowStart) accessLog.shift();
+		if (accessLog.length > maxLogLength) accessLog.splice(0, accessLog.length - maxLogLength);
+	}
+	function get(key) {
+		analyzePatterns();
+		if (accessLog.length >= 1e4) accessLog.shift();
+		accessLog.push({
+			key,
+			time: Date.now()
+		});
+		return activeCache.get(key);
+	}
+	function set(key, value, ttlMs) {
+		analyzePatterns();
+		activeCache.set(key, value, ttlMs);
+	}
+	function has(key) {
+		return activeCache.has(key);
+	}
+	function del(key) {
+		lruCache.delete(key);
+		lfuCache.delete(key);
+		return activeCache.delete(key);
+	}
+	function clear() {
+		lruCache.clear();
+		lfuCache.clear();
+		accessLog.length = 0;
+	}
+	function size() {
+		return activeCache.size();
+	}
+	function keys() {
+		return activeCache.keys();
+	}
+	function stats() {
+		return { ...activeCache.stats() };
+	}
+	function peek(key) {
+		return activeCache.peek(key);
+	}
+	function peekEntry(key) {
+		return activeCache.peekEntry?.(key);
+	}
+	return {
+		get,
+		set,
+		has,
+		delete: del,
+		clear,
+		size,
+		keys,
+		stats,
+		peek,
+		peekEntry
+	};
+}
+/**
+* Create a cache strategy by type.
+*
+* @example
+* ```typescript
+* const cache = createCacheStrategy('lru', { maxSize: 1000 });
+* const adaptiveCache = createCacheStrategy('adaptive', { maxSize: 1000 });
+* ```
+*/
+function createCacheStrategy(strategy, config) {
+	switch (strategy) {
+		case "lru": return createLRUStrategy(config);
+		case "lfu": return createLFUStrategy(config);
+		case "fifo": return createFIFOStrategy(config);
+		case "ttl": return createTTLStrategy(config);
+		case "adaptive": return createAdaptiveStrategy(config);
+		default: throw new Error(`Unknown cache strategy: ${strategy}`);
+	}
+}
+
+//#endregion
+export { createAdaptiveStrategy, createCacheStrategy, createFIFOStrategy, createLFUStrategy, createLRUStrategy, createTTLStrategy };
+//# sourceMappingURL=caching-strategies.mjs.map