or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-caching.mdevents.mdhooks.mdindex.mdstorage.md
tile.json

tessl/npm-cacheable-request

Wrap native HTTP requests with RFC compliant cache support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cacheable-request@13.0.x

To install, run

npx @tessl/cli install tessl/npm-cacheable-request@13.0.0

index.mddocs/

Cacheable Request

Cacheable Request is a TypeScript library that wraps native Node.js HTTP/HTTPS requests with RFC 7234 compliant cache support. It provides intelligent caching capabilities with automatic revalidation, pluggable storage adapters, and advanced features like TTL limits, automatic failover, and response hooks.

Package Information

  • Package Name: cacheable-request
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install cacheable-request

Core Imports

import CacheableRequest from "cacheable-request";
import { request } from "node:http";
import { request as httpsRequest } from "node:https";

For CommonJS:

const CacheableRequest = require("cacheable-request");
const { request } = require("node:http");

Basic Usage

import CacheableRequest from "cacheable-request";
import { request } from "node:http";

// Create a cacheable request instance
const cacheableRequest = new CacheableRequest(request).request();

// Make a cached request
const req = cacheableRequest("http://example.com/api/data", (response) => {
  let data = "";
  response.on("data", chunk => data += chunk);
  response.on("end", () => {
    console.log("Response from cache:", response.fromCache);
    console.log("Data:", data);
  });
});

// Handle the request event to actually send the request
req.on("request", (request) => request.end());

// Handle errors
req.on("error", (error) => {
  console.error("Cache error:", error);
});

Architecture

Cacheable Request is built around several key components:

  • CacheableRequest Class: Main wrapper class that adds caching to any HTTP request function
  • Cache Storage: Uses Keyv for pluggable storage adapters (memory, Redis, SQLite, etc.)
  • RFC 7234 Compliance: Uses http-cache-semantics for proper HTTP caching behavior
  • Event System: Emits request, response, and error events for full control
  • Hook System: Allows response modification before caching
  • Automatic Revalidation: Uses If-None-Match/If-Modified-Since headers for stale entries

Capabilities

Core Caching

Basic caching functionality that wraps HTTP request functions with intelligent cache support. Handles cache storage, retrieval, and RFC 7234 compliant cache-control.

class CacheableRequest {
  constructor(cacheRequest: RequestFn, cacheAdapter?: any);
  request(): CacheableRequestFunction;
}

type CacheableRequestFunction = (
  options: CacheableOptions,
  callback?: (response: CacheResponse) => void
) => Emitter;

type CacheableOptions = Options & RequestOptions | string | URL;

interface Options {
  cache?: boolean;
  strictTtl?: boolean;
  maxTtl?: number;
  automaticFailover?: boolean;
  forceRefresh?: boolean;
  remoteAddress?: boolean;
  url?: string;
  headers?: Record<string, string | string[] | undefined>;
  body?: Buffer;
}

Core Caching

Hook System

Response processing hooks that allow modification of cached data before storage. Useful for compression, data transformation, and adding metadata.

class CacheableRequest {
  addHook(name: string, fn: Function): void;
  removeHook(name: string): boolean;
  getHook(name: string): Function | undefined;
  runHook(name: string, value: CacheValue, response: any): Promise<CacheValue>;
}

interface CacheValue {
  url: string;
  statusCode: number;
  body: Buffer | string;
  cachePolicy: CachePolicyObject;
  [key: string]: any;
}

Hook System

Storage Configuration

Configuration and setup of cache storage adapters using Keyv. Supports in-memory caching, Redis, SQLite, MongoDB, and custom adapters.

class CacheableRequest {
  cache: Keyv;
  constructor(cacheRequest: RequestFn, cacheAdapter?: any);
}

Storage Configuration

Event Handling

Event-driven architecture for handling requests, responses, and errors. Provides full control over the request lifecycle and error management.

interface Emitter extends EventEmitter {
  on(event: 'request', listener: (request: ClientRequest) => void): this;
  on(event: 'response', listener: (response: CacheResponse) => void): this;
  on(event: 'error', listener: (error: RequestError | CacheError) => void): this;
}

class RequestError extends Error {
  constructor(error: Error);
}

class CacheError extends Error {
  constructor(error: Error);
}

Event Handling

Utility Exports

Additional utility functions and constants exported by the package.

/**
 * Parses URL strings using WHATWG URL API
 * @param raw - URL string to parse
 * @returns Parsed URL object with standard properties
 */
function parseWithWhatwg(raw: string): UrlParsedObject;

/**
 * String constant for the standard response hook identifier
 */
const onResponse: string;

Types

type RequestFn = typeof request;
type RequestFunction = typeof request;
type CacheResponse = ServerResponse | typeof ResponseLike;

interface UrlOption {
  path: string;
  pathname?: string;
  search?: string;
}

interface UrlParsedObject {
  protocol: string;
  slashes: boolean;
  auth?: string;
  host: string;
  port: string;
  hostname: string;
  hash: string;
  search: string;
  query: Record<string, string>;
  pathname: string;
  path: string;
  href: string;
}