Class FetchCache

scripts/sync/cache.ts:18–173

const STALE_CACHE_DAYS = 30;

export class FetchCache {
  private warnings: CacheWarning[] = [];
  private staleWarnings: StaleCacheWarning[] = [];
  private indexCache: Record<string, string> | null = null;
  private usedKeys = new Set<string>();

  constructor(private cacheDir: string) {}

  async fetch(url: string): Promise<string> {
    return this.cached(url, async () => {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP ${response.status} ${response.statusText}`);
      }
      return response.text();
    });
  }

  async cached(key: string, fresh: () => Promise<string>): Promise<string> {
    this.usedKeys.add(this.cacheKey(key));
    try {
      const text = await fresh();
      await this.write(key, text);
      return text;
    } catch (error) {
      const cachedEntry = await this.read(key);
      if (cachedEntry !== null) {
        this.warnings.push({
          url: key,
          reason: error instanceof Error ? error.message : String(error),
          cachedAt: cachedEntry.cachedAt
        });
        if (cachedEntry.cachedAt) {
          const ageDays = (Date.now() - new Date(cachedEntry.cachedAt).getTime()) / 86_400_000;
          if (ageDays > STALE_CACHE_DAYS) {
            this.staleWarnings.push({ url: key, ageDays: Math.floor(ageDays) });
          }
        }
        return cachedEntry.text;
      }
      throw new Error(
        `Failed to fetch ${key} and no cache available: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

  async pruneOrphans(): Promise<string[]> {
    const removed: string[] = [];
    const index = await this.readIndex();
    let indexChanged = false;

    for (const key of Object.keys(index)) {
      if (!this.usedKeys.has(key)) {
        const file = path.join(this.cacheDir, `${key}.txt`);
        await unlink(file).catch(() => undefined);
        removed.push(index[key] ?? key);