Cache Inventory Utility

Create helper functions that expose cache inventory and lookup capabilities for a content-addressable cache directory.

Capabilities

List all entries

• Given a cache directory containing multiple keys, returns every entry sorted by key in ascending order and includes integrity strings, sizes, last-modified timestamps, and any stored metadata. @test

Retrieve one entry

• Given an existing key, returns its entry data including integrity, size, metadata (if present), and last-modified time. @test
• Requesting a missing key results in a rejected promise with a not-found style error message. @test

Summarize cache

• Produces a summary object containing the total number of entries and the cumulative size computed from the current listing. @test

Implementation

@generates

API

/**
 * Represents a cache entry discovered in the cache directory.
 */
export type CacheEntry = {
  key: string;
  integrity: string;
  size: number;
  time: number;
  metadata?: unknown;
};

/**
 * Lists all cache entries for the provided cache directory.
 * Entries must be sorted by key ascending and include integrity, size, metadata (when present), and time.
 */
export async function listEntries(cachePath: string): Promise<CacheEntry[]>;

/**
 * Retrieves a single cache entry by key and returns its integrity, size, metadata, and time.
 * Rejects when the key is not present.
 */
export async function getEntry(cachePath: string, key: string): Promise<CacheEntry>;

/**
 * Aggregates listing data into summary totals (entry count and cumulative size).
 */
export async function summarize(cachePath: string): Promise<{ count: number; totalSize: number }>;

Dependencies { .dependencies }

cacache { .dependency }

Provides content-addressable cache indexing and entry lookups.