Cache Metadata Client

A cache-aware HTTP helper that exposes persisted metadata for cached responses while respecting conditional requests and cache invalidation rules.

Capabilities

Persist selected headers in cache metadata

• First GET to a URL stores configured response headers in cache metadata and returns them alongside the body. @test
• Second GET to the same URL with cache available serves the cached body and surfaces stored header values without re-fetching. @test

Conditional requests bypass cache

• GET requests including If-None-Match or If-Modified-Since headers skip cache usage entirely, always contacting the origin and leaving any existing cached entries unchanged. @test

Successful non-GET invalidates cached GET

• After a successful POST, PUT, or DELETE to a cached URL, the next GET does not return cached data and instead re-fetches the resource. @test

Surface cache source

• Every response indicates whether it came from cache and includes any stored header metadata captured for that URL. @test

Implementation

@generates

API

export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH";

export interface CacheClientOptions {
  cachePath: string;
  trackedHeaders?: string[];
}

export interface RequestOptions {
  method?: HttpMethod;
  headers?: Record<string, string>;
  body?: string | Buffer;
}

export interface FetchDetails {
  status: number;
  bodyText: string;
  fromCache: boolean;
  cachedHeaders: Record<string, string>;
}

export class CacheMetadataClient {
  constructor(options: CacheClientOptions);

  fetch(url: string, request?: RequestOptions): Promise<FetchDetails>;

  clear(): Promise<void>;
}

Dependencies { .dependencies }

make-fetch-happen { .dependency }

Provides HTTP client with cache storage, metadata headers, and cache invalidation support.