Cached Asset Reader

A utility that reads cached assets by key and returns both payload and metadata for downstream consumers needing content-type and expiry awareness.

Capabilities

Reads payload and metadata by key

• Given a cache directory and key that were previously populated with data and metadata, returns an object containing the stored bytes and metadata fields unchanged, including contentType and version. @test

Marks stale entries using metadata

• If metadata carries an expiresAt timestamp that is less than or equal to the provided current time, the result includes stale: true while still returning the stored data, integrity, and metadata. @test

Handles missing entries

• When the key is not present in the cache, the read resolves to null without throwing. @test

Implementation

@generates

API

export type CacheReadResult = {
  data: Buffer;
  metadata: Record<string, any>;
  integrity: string;
  size: number;
  stale: boolean;
};

/**
 * Reads a cached asset by key, returning both content and metadata.
 * @param cacheDir - Cache directory location.
 * @param key - Cache key to read.
 * @param now - Optional function returning current epoch millis; defaults to Date.now.
 * @returns CacheReadResult when present, or null when missing.
 */
export async function readCachedAsset(
  cacheDir: string,
  key: string,
  now?: () => number
): Promise<CacheReadResult | null>;

Dependencies { .dependencies }

cacache { .dependency }

Content-addressable cache used for keyed retrieval of cached content and metadata.