Merge pull request #11 from junctor/fix/10-local-cache-firestore

Fix #10: Add data-layer caching to eliminate repeated Firestore reads

Author: cak

src/lib/db/cache.ts

@@ -0,0 +1,208 @@
+const CACHE_PREFIX = "htw:v1";
+
+// Conference schedule data changes infrequently, so prefer fast navigation
+// over frequent Firestore revalidation.
+export const DEFAULT_CACHE_TTL_MS = 4 * 60 * 60 * 1000;
+
+type CacheEntry<T> = {
+  storedAt: number;
+  value: T;
+};
+
+type CacheValidator<T> = (value: unknown) => value is T;
+
+type CacheReadOptions<T> = {
+  ttlMs?: number;
+  validate?: CacheValidator<T>;
+};
+
+const memoryCache = new Map<string, CacheEntry<unknown>>();
+let hasPrunedCache = false;
+
+const namespacedKey = (key: string) => `${CACHE_PREFIX}:${key}`;
+
+function getBrowserStorage(): Storage | null {
+  if (typeof window === "undefined") return null;
+
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function isCacheEntry(value: unknown): value is CacheEntry<unknown> {
+  if (value === null || typeof value !== "object") return false;
+
+  const candidate = value as { storedAt?: unknown; value?: unknown };
+  return typeof candidate.storedAt === "number" && "value" in candidate;
+}
+
+function isFresh(entry: CacheEntry<unknown>, ttlMs: number): boolean {
+  if (ttlMs <= 0) return false;
+
+  const age = Date.now() - entry.storedAt;
+  return Number.isFinite(entry.storedAt) && age >= 0 && age <= ttlMs;
+}
+
+export function pruneCache(ttlMs = DEFAULT_CACHE_TTL_MS): void {
+  const storage = getBrowserStorage();
+  if (!storage) return;
+
+  const prefix = `${CACHE_PREFIX}:`;
+  const keysToRemove: string[] = [];
+
+  try {
+    for (let i = 0; i < storage.length; i += 1) {
+      const key = storage.key(i);
+      if (!key || !key.startsWith(prefix)) continue;
+
+      const raw = storage.getItem(key);
+      if (!raw) {
+        keysToRemove.push(key);
+        continue;
+      }
+
+      try {
+        const parsed: unknown = JSON.parse(raw);
+
+        if (!isCacheEntry(parsed) || !isFresh(parsed, ttlMs)) {
+          keysToRemove.push(key);
+        }
+      } catch {
+        keysToRemove.push(key);
+      }
+    }
+
+    for (const key of keysToRemove) {
+      try {
+        storage.removeItem(key);
+        memoryCache.delete(key);
+      } catch {
+        // Ignore cleanup failures.
+      }
+    }
+  } catch {
+    // Ignore pruning failures.
+  }
+}
+
+function pruneCacheOnce(): void {
+  if (hasPrunedCache) return;
+
+  hasPrunedCache = true;
+  pruneCache();
+}
+
+function isValidValue<T>(value: unknown, validate?: CacheValidator<T>): value is T {
+  try {
+    return validate ? validate(value) : true;
+  } catch {
+    return false;
+  }
+}
+
+function readMemory<T>(
+  storageKey: string,
+  ttlMs: number,
+  validate?: CacheValidator<T>,
+): T | undefined {
+  try {
+    const entry = memoryCache.get(storageKey);
+    if (!entry) return undefined;
+
+    if (!isFresh(entry, ttlMs) || !isValidValue(entry.value, validate)) {
+      memoryCache.delete(storageKey);
+      return undefined;
+    }
+
+    return entry.value;
+  } catch {
+    return undefined;
+  }
+}
+
+function readLocalStorage<T>(
+  storageKey: string,
+  ttlMs: number,
+  validate?: CacheValidator<T>,
+): T | undefined {
+  const storage = getBrowserStorage();
+  if (!storage) return undefined;
+
+  try {
+    const raw = storage.getItem(storageKey);
+    if (!raw) return undefined;
+
+    const parsed: unknown = JSON.parse(raw);
+    if (!isCacheEntry(parsed) || !isFresh(parsed, ttlMs)) {
+      try {
+        storage.removeItem(storageKey);
+      } catch {
+        // Ignore cache cleanup failures.
+      }
+      return undefined;
+    }
+
+    if (!isValidValue(parsed.value, validate)) {
+      try {
+        storage.removeItem(storageKey);
+      } catch {
+        // Ignore cache cleanup failures.
+      }
+      return undefined;
+    }
+
+    const entry: CacheEntry<unknown> = {
+      storedAt: parsed.storedAt,
+      value: parsed.value,
+    };
+
+    try {
+      memoryCache.set(storageKey, entry);
+    } catch {
+      // Ignore in-memory cache failures.
+    }
+
+    return parsed.value;
+  } catch {
+    return undefined;
+  }
+}
+
+export function getCached<T>(key: string, options: CacheReadOptions<T> = {}): T | undefined {
+  pruneCacheOnce();
+
+  const storageKey = namespacedKey(key);
+  const ttlMs = options.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  const memoryValue = readMemory<T>(storageKey, ttlMs, options.validate);
+
+  if (memoryValue !== undefined) return memoryValue;
+
+  return readLocalStorage<T>(storageKey, ttlMs, options.validate);
+}
+
+export function setCached<T>(key: string, value: T): void {
+  pruneCacheOnce();
+
+  const storageKey = namespacedKey(key);
+  const entry: CacheEntry<T> = {
+    storedAt: Date.now(),
+    value,
+  };
+
+  try {
+    memoryCache.set(storageKey, entry);
+  } catch {
+    // Ignore in-memory cache failures.
+  }
+
+  const storage = getBrowserStorage();
+  if (!storage) return;
+
+  try {
+    storage.setItem(storageKey, JSON.stringify(entry));
+  } catch {
+    // Ignore quota, serialization, and security failures.
+  }
+}

src/lib/db/conferences.ts

@@ -10,28 +10,71 @@ import {
 } from "firebase/firestore/lite";
 import { db } from "../firebase";
 import type { HTConference } from "@/types/db";
+import { getCached, setCached } from "./cache";
+
+const conferencesKey = (count: number) => `conferences:list:${count}`;
+const conferenceKey = (code: string) => `conference:${code}`;
+const upcomingConferencesKey = "conferences:upcoming";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
+function isConference(value: unknown): value is HTConference {
+  return isRecord(value) && typeof value.code === "string";
+}
+
+function isConferenceList(value: unknown): value is HTConference[] {
+  return Array.isArray(value) && value.every(isConference);
+}
+
+function cacheConferences(conferences: HTConference[]) {
+  for (const conf of conferences) {
+    if (conf.code) setCached(conferenceKey(conf.code), conf);
+  }
+}
 
 export async function getConferences(count = 50): Promise<HTConference[]> {
+  const cached = getCached<HTConference[]>(conferencesKey(count), {
+    validate: isConferenceList,
+  });
+  if (cached) return cached;
+
   const ref = collection(db, "conferences");
   const q = query(ref, orderBy("start_timestamp", "desc"), limit(count));
   const snap = await getDocs(q);
-  return snap.docs.map((doc) => {
+  const conferences = snap.docs.map((doc) => {
     const data = doc.data() as HTConference;
     return data;
   });
+
+  setCached(conferencesKey(count), conferences);
+  cacheConferences(conferences);
+  return conferences;
 }
 
 export async function getConferenceByCode(
   code: string
 ): Promise<HTConference | null> {
+  const cached = getCached<HTConference>(conferenceKey(code), {
+    validate: isConference,
+  });
+  if (cached) return cached;
+
   const ref = doc(db, "conferences", code);
   const snap = await getDoc(ref);
   if (!snap.exists()) return null;
   const data = snap.data() as HTConference;
+  setCached(conferenceKey(code), data);
   return data;
 }
 
 export async function getUpcomingConferences(): Promise<HTConference[]> {
+  const cached = getCached<HTConference[]>(upcomingConferencesKey, {
+    validate: isConferenceList,
+  });
+  if (cached) return cached;
+
   const ref = collection(db, "conferences");
   const q = query(
     ref,
@@ -40,8 +83,12 @@ export async function getUpcomingConferences(): Promise<HTConference[]> {
     limit(50)
   );
   const snap = await getDocs(q);
-  return snap.docs.map((doc) => {
+  const conferences = snap.docs.map((doc) => {
     const data = doc.data() as HTConference;
     return data;
   });
+
+  setCached(upcomingConferencesKey, conferences);
+  cacheConferences(conferences);
+  return conferences;
 }