fansunited-data-layer 0.13.0 → 0.14.2

package/cache/cache-manager.js

@@ -0,0 +1,136 @@
+import { memoryStore } from "./memory-store.js";
+let l2 = null;
+function initL2(store) {
+  l2 = store;
+}
+const ENTITY_TTL_CONFIG = {
+  competitions: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },
+  teams: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
+  athletes: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
+  venues: { staleTTL: 72 * 3600, maxTTL: 168 * 3600 },
+  countries: { staleTTL: 96 * 3600, maxTTL: 168 * 3600 },
+  coaches: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
+  search: { staleTTL: 300, maxTTL: 1800 }
+};
+const refreshing = /* @__PURE__ */ new Set();
+function getConfig(entity) {
+  const config = ENTITY_TTL_CONFIG[entity];
+  if (!config) {
+    throw new Error(`Unknown entity type: ${entity}`);
+  }
+  return config;
+}
+function isFresh(entry, staleTTL) {
+  return Date.now() - entry.storedAt < staleTTL * 1e3;
+}
+function isExpired(entry, maxTTL) {
+  return Date.now() - entry.storedAt >= maxTTL * 1e3;
+}
+function backgroundRefresh(key, entity, fetcher) {
+  if (refreshing.has(key)) return;
+  refreshing.add(key);
+  fetcher().then((data) => {
+    memoryStore.set(key, data);
+    if (l2?.isInitialized) {
+      l2.set(key, entity, data);
+    }
+  }).catch((err) => {
+    console.error(`[cache] Background refresh failed for ${key}:`, err);
+  }).finally(() => {
+    refreshing.delete(key);
+  });
+}
+async function cached(key, entity, fetcher) {
+  const { staleTTL, maxTTL } = getConfig(entity);
+  const l1 = memoryStore.get(key);
+  if (l1) {
+    if (isFresh(l1, staleTTL)) {
+      return l1.data;
+    }
+    if (!isExpired(l1, maxTTL)) {
+      backgroundRefresh(key, entity, fetcher);
+      return l1.data;
+    }
+  }
+  if (l2?.isInitialized) {
+    const l2Entry = l2.get(key);
+    if (l2Entry && !isExpired(l2Entry, maxTTL)) {
+      memoryStore.set(key, l2Entry.data);
+      if (isFresh(l2Entry, staleTTL)) {
+        return l2Entry.data;
+      }
+      backgroundRefresh(key, entity, fetcher);
+      return l2Entry.data;
+    }
+  }
+  const data = await fetcher();
+  memoryStore.set(key, data);
+  if (l2?.isInitialized) {
+    l2.set(key, entity, data);
+  }
+  return data;
+}
+async function cachedBatch(ids, entity, batchFetcher, keyFn) {
+  const { staleTTL, maxTTL } = getConfig(entity);
+  const results = /* @__PURE__ */ new Map();
+  const missingIds = [];
+  for (const id of ids) {
+    const key = keyFn(id);
+    let found = false;
+    const l1 = memoryStore.get(key);
+    if (l1 && !isExpired(l1, maxTTL)) {
+      results.set(id, l1.data);
+      if (!isFresh(l1, staleTTL)) {
+        backgroundRefresh(key, entity, async () => {
+          const fetched = await batchFetcher([id]);
+          const item = fetched.get(id);
+          if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);
+          return item;
+        });
+      }
+      found = true;
+    }
+    if (!found && l2?.isInitialized) {
+      const l2Entry = l2.get(key);
+      if (l2Entry && !isExpired(l2Entry, maxTTL)) {
+        memoryStore.set(key, l2Entry.data);
+        results.set(id, l2Entry.data);
+        if (!isFresh(l2Entry, staleTTL)) {
+          backgroundRefresh(key, entity, async () => {
+            const fetched = await batchFetcher([id]);
+            const item = fetched.get(id);
+            if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);
+            return item;
+          });
+        }
+        found = true;
+      }
+    }
+    if (!found) {
+      missingIds.push(id);
+    }
+  }
+  if (missingIds.length > 0) {
+    const fetched = await batchFetcher(missingIds);
+    for (const [id, data] of fetched) {
+      const key = keyFn(id);
+      memoryStore.set(key, data);
+      if (l2?.isInitialized) {
+        l2.set(key, entity, data);
+      }
+      results.set(id, data);
+    }
+  }
+  return results;
+}
+function invalidate(key) {
+  memoryStore.delete(key);
+}
+export {
+  ENTITY_TTL_CONFIG,
+  cached,
+  cachedBatch,
+  initL2,
+  invalidate
+};
+//# sourceMappingURL=cache-manager.js.map

package/cache/cache-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.js","sources":["../../src/lib/cache/cache-manager.ts"],"sourcesContent":["/**\n * Cache Manager - Orchestrates L1 (memory) + optional L2 with SWR pattern\n *\n * L2 (SQLite) is never statically imported here — it's injected at runtime\n * via initL2() so that browser bundles don't pull in better-sqlite3.\n */\n\nimport { memoryStore } from \"./memory-store\";\nimport type { CacheEntry, EntityCacheConfig, EntityType } from \"./types\";\n\n/** Interface that L2 stores must satisfy */\nexport interface L2Store {\n    get isInitialized(): boolean;\n    get<T>(key: string): CacheEntry<T> | undefined;\n    set(key: string, entity: string, data: unknown): void;\n    setMany(entries: { key: string; entity: string; data: unknown }[]): void;\n    cleanup(entity: string, maxTTLSeconds: number): number;\n    clear(): void;\n}\n\n/** The active L2 store — null until initL2() is called */\nlet l2: L2Store | null = null;\n\n/**\n * Initialize L2 cache layer. Call on server startup.\n * Client-side apps skip this — L2 is never loaded.\n */\nexport function initL2(store: L2Store): void {\n    l2 = store;\n}\n\n/** Get the L2 store (if initialized) */\nexport function getL2(): L2Store | null {\n    return l2;\n}\n\nconst ENTITY_TTL_CONFIG: Record<EntityType, EntityCacheConfig> = {\n    competitions: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },\n    teams: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    athletes: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    venues: { staleTTL: 72 * 3600, maxTTL: 168 * 3600 },\n    countries: { staleTTL: 96 * 3600, maxTTL: 168 * 3600 },\n    coaches: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    search: { staleTTL: 300, maxTTL: 1800 },\n};\n\n/** Set of keys currently being refreshed in the background (thundering herd prevention) */\nconst refreshing = new Set<string>();\n\nfunction getConfig(entity: EntityType): EntityCacheConfig {\n    const config = ENTITY_TTL_CONFIG[entity];\n    if (!config) {\n        throw new Error(`Unknown entity type: ${entity}`);\n    }\n    return config;\n}\n\nfunction isFresh(entry: CacheEntry<unknown>, staleTTL: number): boolean {\n    return Date.now() - entry.storedAt < staleTTL * 1000;\n}\n\nfunction isExpired(entry: CacheEntry<unknown>, maxTTL: number): boolean {\n    return Date.now() - entry.storedAt >= maxTTL * 1000;\n}\n\nfunction backgroundRefresh<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): void {\n    if (refreshing.has(key)) return;\n    refreshing.add(key);\n\n    fetcher()\n        .then((data) => {\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                l2.set(key, entity, data);\n            }\n        })\n        .catch((err) => {\n            console.error(`[cache] Background refresh failed for ${key}:`, err);\n        })\n        .finally(() => {\n            refreshing.delete(key);\n        });\n}\n\n/**\n * Single-key cache-through with SWR (Stale-While-Revalidate)\n */\nexport async function cached<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): Promise<T> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n\n    // L1 check\n    const l1 = memoryStore.get<T>(key);\n    if (l1) {\n        if (isFresh(l1, staleTTL)) {\n            return l1.data;\n        }\n        if (!isExpired(l1, maxTTL)) {\n            backgroundRefresh(key, entity, fetcher);\n            return l1.data;\n        }\n    }\n\n    // L2 check\n    if (l2?.isInitialized) {\n        const l2Entry = l2.get<T>(key);\n        if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n            // Promote to L1\n            memoryStore.set(key, l2Entry.data);\n            if (isFresh(l2Entry, staleTTL)) {\n                return l2Entry.data;\n            }\n            backgroundRefresh(key, entity, fetcher);\n            return l2Entry.data;\n        }\n    }\n\n    // Full miss — await fetcher\n    const data = await fetcher();\n    memoryStore.set(key, data);\n    if (l2?.isInitialized) {\n        l2.set(key, entity, data);\n    }\n    return data;\n}\n\n/**\n * Smart batch cache — only fetches uncached IDs from the API\n */\nexport async function cachedBatch<T>(\n    ids: string[],\n    entity: EntityType,\n    batchFetcher: (missingIds: string[]) => Promise<Map<string, T>>,\n    keyFn: (id: string) => string\n): Promise<Map<string, T>> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n    const results = new Map<string, T>();\n    const missingIds: string[] = [];\n\n    for (const id of ids) {\n        const key = keyFn(id);\n        let found = false;\n\n        // L1 check\n        const l1 = memoryStore.get<T>(key);\n        if (l1 && !isExpired(l1, maxTTL)) {\n            results.set(id, l1.data);\n            if (!isFresh(l1, staleTTL)) {\n                backgroundRefresh(key, entity, async () => {\n                    const fetched = await batchFetcher([id]);\n                    const item = fetched.get(id);\n                    if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                    return item;\n                });\n            }\n            found = true;\n        }\n\n        // L2 check\n        if (!found && l2?.isInitialized) {\n            const l2Entry = l2.get<T>(key);\n            if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n                memoryStore.set(key, l2Entry.data);\n                results.set(id, l2Entry.data);\n                if (!isFresh(l2Entry, staleTTL)) {\n                    backgroundRefresh(key, entity, async () => {\n                        const fetched = await batchFetcher([id]);\n                        const item = fetched.get(id);\n                        if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                        return item;\n                    });\n                }\n                found = true;\n            }\n        }\n\n        if (!found) {\n            missingIds.push(id);\n        }\n    }\n\n    // Fetch missing IDs in a single batch\n    if (missingIds.length > 0) {\n        const fetched = await batchFetcher(missingIds);\n        for (const [id, data] of fetched) {\n            const key = keyFn(id);\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                l2.set(key, entity, data);\n            }\n            results.set(id, data);\n        }\n    }\n\n    return results;\n}\n\n/**\n * Remove an entry from both cache layers\n */\nexport function invalidate(key: string): void {\n    memoryStore.delete(key);\n}\n\n// Export for testing\nexport { ENTITY_TTL_CONFIG };\n"],"names":[],"mappings":"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"}

package/cache/memory-store.js

@@ -0,0 +1,29 @@
+import { LRUCache } from "lru-cache";
+const MAX_SIZE_BYTES = 50 * 1024 * 1024;
+const cache = new LRUCache({
+  maxSize: MAX_SIZE_BYTES,
+  sizeCalculation: (entry) => {
+    return JSON.stringify(entry.data).length;
+  }
+});
+const memoryStore = {
+  get(key) {
+    return cache.get(key);
+  },
+  set(key, data) {
+    cache.set(key, { data, storedAt: Date.now() });
+  },
+  delete(key) {
+    cache.delete(key);
+  },
+  clear() {
+    cache.clear();
+  },
+  get size() {
+    return cache.size;
+  }
+};
+export {
+  memoryStore
+};
+//# sourceMappingURL=memory-store.js.map

package/cache/memory-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.js","sources":["../../src/lib/cache/memory-store.ts"],"sourcesContent":["/**\n * L1 Cache - LRU in-memory store\n */\n\nimport { LRUCache } from \"lru-cache\";\nimport type { CacheEntry } from \"./types\";\n\nconst MAX_SIZE_BYTES = 50 * 1024 * 1024; // 50MB\n\nconst cache = new LRUCache<string, CacheEntry<unknown>>({\n    maxSize: MAX_SIZE_BYTES,\n    sizeCalculation: (entry) => {\n        return JSON.stringify(entry.data).length;\n    },\n});\n\nexport const memoryStore = {\n    get<T>(key: string): CacheEntry<T> | undefined {\n        return cache.get(key) as CacheEntry<T> | undefined;\n    },\n\n    set<T>(key: string, data: T): void {\n        cache.set(key, { data, storedAt: Date.now() });\n    },\n\n    delete(key: string): void {\n        cache.delete(key);\n    },\n\n    clear(): void {\n        cache.clear();\n    },\n\n    get size(): number {\n        return cache.size;\n    },\n};\n"],"names":[],"mappings":";AAOA,MAAM,iBAAiB,KAAK,OAAO;AAEnC,MAAM,QAAQ,IAAI,SAAsC;AAAA,EACpD,SAAS;AAAA,EACT,iBAAiB,CAAC,UAAU;AACxB,WAAO,KAAK,UAAU,MAAM,IAAI,EAAE;AAAA,EACtC;AACJ,CAAC;AAEM,MAAM,cAAc;AAAA,EACvB,IAAO,KAAwC;AAC3C,WAAO,MAAM,IAAI,GAAG;AAAA,EACxB;AAAA,EAEA,IAAO,KAAa,MAAe;AAC/B,UAAM,IAAI,KAAK,EAAE,MAAM,UAAU,KAAK,IAAA,GAAO;AAAA,EACjD;AAAA,EAEA,OAAO,KAAmB;AACtB,UAAM,OAAO,GAAG;AAAA,EACpB;AAAA,EAEA,QAAc;AACV,UAAM,MAAA;AAAA,EACV;AAAA,EAEA,IAAI,OAAe;AACf,WAAO,MAAM;AAAA,EACjB;AACJ;"}