or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

caching.mdconfiguration.mdcore-fetch.mdindex.mdnetwork.mdretry.mdsecurity.md
tile.json

tessl/npm-make-fetch-happen

Opinionated, caching, retrying fetch client for Node.js with enterprise-grade HTTP features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/make-fetch-happen@15.0.x

To install, run

npx @tessl/cli install tessl/npm-make-fetch-happen@15.0.0

index.mddocs/

make-fetch-happen

make-fetch-happen is a Node.js library that wraps minipass-fetch with additional enterprise-grade features including HTTP caching with cache semantics support, automatic request retries with configurable backoff strategies, connection pooling, comprehensive proxy support, subresource integrity validation, and DNS configuration options. It provides a fetch-compatible API that can serve as a drop-in replacement for native fetch while offering superior reliability and performance characteristics for production environments.

Package Information

  • Package Name: make-fetch-happen
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install make-fetch-happen

Core Imports

const fetch = require('make-fetch-happen');

ESM:

import fetch from 'make-fetch-happen';

You can also import specific classes:

const { FetchError, Headers, Request, Response } = require('make-fetch-happen');

Basic Usage

const fetch = require('make-fetch-happen');

// Basic fetch with caching
const response = await fetch('https://registry.npmjs.org/make-fetch-happen', {
  cachePath: './my-cache'
});
const data = await response.json();

// Create a fetch function with default options
const cachedFetch = fetch.defaults({
  cachePath: './my-cache',
  retry: { retries: 3 }
});

const response2 = await cachedFetch('https://api.example.com/data');

Architecture

make-fetch-happen is built around several key components:

  • Core Fetch Function: Main fetch implementation with caching, retries, and redirect handling
  • Options Configuration: Comprehensive option processing and validation system
  • HTTP Caching System: Full HTTP caching implementation with cache policies and entry management
  • Retry Logic: Automatic retry mechanism with configurable backoff strategies
  • Proxy Support: Complete proxy handling through @npmcli/agent
  • Pipeline System: Stream processing for integrity verification and caching

Capabilities

Core Fetch API

Primary fetch function that implements the standard Fetch API with additional enterprise features including caching, retries, and proxy support.

/**
 * Enhanced fetch function with caching, retries, and proxy support
 * @param {string|Request} url - URL string or Request object
 * @param {Object} options - Fetch options with make-fetch-happen extensions
 * @returns {Promise<Response>} Promise resolving to Response object
 */
function fetch(url, options);

Core Fetch Operations

Configuration and Defaults

Create pre-configured fetch functions with default options for consistent behavior across an application.

/**
 * Creates a new fetch function with default options
 * @param {string} [defaultUrl] - Default URL to use if none provided
 * @param {Object} [defaultOptions] - Default options to merge with each request
 * @returns {Function} New fetch function with defaults applied
 */
function fetch.defaults(defaultUrl, defaultOptions);

Configuration and Defaults

HTTP Caching

Advanced HTTP caching system that follows RFC 7234 specifications with cache control, ETags, and conditional requests.

/**
 * Cache options for HTTP caching behavior
 */
interface CacheOptions {
  cachePath?: string;          // Path to cache directory
  cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached';
  cacheAdditionalHeaders?: string[];  // Additional headers to store in cache
}

HTTP Caching

Request Retry Logic

Configurable retry mechanism for handling transient network failures and server errors.

/**
 * Retry configuration options
 */
interface RetryOptions {
  retries?: number;      // Number of retry attempts (default: 0)
  factor?: number;       // Exponential backoff factor
  minTimeout?: number;   // Minimum retry timeout
  maxTimeout?: number;   // Maximum retry timeout
  randomize?: boolean;   // Whether to randomize retry intervals
}

/**
 * Callback function called on each retry attempt
 * @param {Error|Response} cause - Error or response that caused the retry
 */
type OnRetryCallback = (cause: Error | Response) => void;

Request Retry Logic

Proxy and Network Configuration

Comprehensive proxy support with automatic proxy detection and network configuration options.

/**
 * Network and proxy configuration options
 */
interface NetworkOptions {
  proxy?: string | URL;        // Proxy URL
  noProxy?: string | string[]; // Domains to bypass proxy
  maxSockets?: number;         // Maximum concurrent connections
  localAddress?: string;       // Local address to bind to
  agent?: object;             // Custom HTTP agent
}

Proxy and Network Configuration

Security and Integrity

Security features including SSL configuration, certificate validation, and subresource integrity verification.

/**
 * Security and integrity options
 */
interface SecurityOptions {
  strictSSL?: boolean;    // SSL certificate validation
  ca?: string | Buffer;   // Certificate authority certificates
  cert?: string | Buffer; // Client certificate
  key?: string | Buffer;  // Client private key
  integrity?: string;     // Subresource integrity hash
}

Security and Integrity

Core Types

/**
 * Main fetch function signature
 */
type FetchFunction = (url: string | Request, options?: FetchOptions) => Promise<Response>;

/**
 * Complete options interface combining all feature options
 */
interface FetchOptions extends CacheOptions, RetryOptions, NetworkOptions, SecurityOptions {
  // Standard fetch options
  method?: string;
  headers?: object;
  body?: any;
  redirect?: 'follow' | 'manual' | 'error';
  timeout?: number;
  size?: number;
  compress?: boolean;
  
  // make-fetch-happen specific
  onRetry?: OnRetryCallback;
  dns?: DNSOptions;
}

/**
 * DNS configuration options
 */
interface DNSOptions {
  ttl?: number;        // DNS cache TTL in milliseconds
  lookup?: Function;   // Custom DNS lookup function
}

Error Handling

make-fetch-happen uses the same error types as the underlying minipass-fetch library:

/**
 * Error thrown by fetch operations
 */
class FetchError extends Error {
  code: string;
  type: string;
  errno?: string;
}

Common error codes include:

  • ENOTCACHED: Cache-only mode with no cached response
  • EINTEGRITY: Subresource integrity verification failed
  • ENOREDIRECT: Redirect mode set to error but redirect encountered
  • EINVALIDREDIRECT: Invalid redirect response
  • EMAXREDIRECT: Maximum redirects exceeded