Function readCache

src/utils/cache.ts:129–167

(
  endpoint: string,
  params: Record<string, string | number | string[] | undefined>,
  ttlMs?: number,
)

 * Returns null on cache miss or any read/parse error.
 */
export function readCache(
  endpoint: string,
  params: Record<string, string | number | string[] | undefined>,
  ttlMs?: number,
): { data: Record<string, unknown>; url: string } | null {
  const cacheKey = buildCacheKey(endpoint, params);
  const filepath = join(CACHE_DIR, cacheKey);
  const label = describeRequest(endpoint, params);

  if (!existsSync(filepath)) {
    return null;
  }

  try {
    const content = readFileSync(filepath, 'utf-8');
    const parsed: unknown = JSON.parse(content);

    if (!isValidCacheEntry(parsed)) {
      logger.warn(`Cache corrupted (invalid structure): ${label}`, { filepath });
      removeCacheFile(filepath);
      return null;
    }

    // TTL enforcement: return null if entry has expired
    if (ttlMs !== undefined) {
      const age = Date.now() - Date.parse(parsed.cachedAt);
      if (age > ttlMs) {
        return null;
      }
    }

    return { data: parsed.data, url: parsed.url };
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    logger.warn(`Cache read error: ${label} — ${message}`, { filepath });
    removeCacheFile(filepath);
    return null;
  }
}

/**
 * Write an API response to the cache.