Streaming Cache Tee

A utility that fetches HTTP resources while simultaneously streaming bodies to callers and persisting cached copies. Integrity and size metadata must be available even when listeners subscribe after streaming begins.

Capabilities

Stream to sink and cache simultaneously

• Fetching a small text resource writes the full body to the provided writable stream while also persisting a cached copy at cachePath; the returned metadata reports the HTTP status and cache location once streaming completes. @test

Integrity/size events for late listeners

• Adding integrity and size listeners after data has started flowing still receives the final integrity digest and total byte count when the stream finishes. @test

Cache reuse for repeat fetches

• A second fetch of the same URL with preferCache: true reads from the cache even if the network source is unavailable, still streaming the cached body to the destination and emitting cache metadata plus integrity/size events. @test

Implementation

@generates

API

/**
 * Streams an HTTP resource to the provided writable stream while persisting a cached copy.
 * Returns an EventEmitter that buffers integrity/size payloads for listeners added mid-stream,
 * plus metadata about the response and cache interaction.
 */
export interface StreamResult {
  status: number;
  headers: Record<string, string>;
  bytes: number;
  integrity?: string;
  cache: {
    path: string;
    hit: boolean;
  };
  events: import('node:events').EventEmitter;
}

export interface StreamOptions {
  cachePath: string;
  preferCache?: boolean;
  expectedIntegrity?: string;
  signal?: AbortSignal;
}

export function streamWithCache(
  url: string,
  destination: NodeJS.WritableStream,
  options: StreamOptions
): Promise<StreamResult>;

Dependencies { .dependencies }

make-fetch-happen { .dependency }

Provides HTTP fetching with caching and integrity-aware streaming pipelines.