0
# make-fetch-happen
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: make-fetch-happen
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install make-fetch-happen`
10

11
## Core Imports
12

13
```javascript
14
const fetch = require('make-fetch-happen');
15
```
16

17
ESM:
18
```javascript
19
import fetch from 'make-fetch-happen';
20
```
21

22
You can also import specific classes:
23
```javascript
24
const { FetchError, Headers, Request, Response } = require('make-fetch-happen');
25
```
26

27
## Basic Usage
28

29
```javascript
30
const fetch = require('make-fetch-happen');
31

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

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

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

47
## Architecture
48

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

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

58
## Capabilities
59

60
### Core Fetch API
61

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

64
```javascript { .api }
65
/**
66
 * Enhanced fetch function with caching, retries, and proxy support
67
 * @param {string|Request} url - URL string or Request object
68
 * @param {Object} options - Fetch options with make-fetch-happen extensions
69
 * @returns {Promise<Response>} Promise resolving to Response object
70
 */
71
function fetch(url, options);
72
```
73

74
[Core Fetch Operations](./core-fetch.md)
75

76
### Configuration and Defaults
77

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

80
```javascript { .api }
81
/**
82
 * Creates a new fetch function with default options
83
 * @param {string} [defaultUrl] - Default URL to use if none provided
84
 * @param {Object} [defaultOptions] - Default options to merge with each request
85
 * @returns {Function} New fetch function with defaults applied
86
 */
87
function fetch.defaults(defaultUrl, defaultOptions);
88
```
89

90
[Configuration and Defaults](./configuration.md)
91

92
### HTTP Caching
93

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

96
```javascript { .api }
97
/**
98
 * Cache options for HTTP caching behavior
99
 */
100
interface CacheOptions {
101
  cachePath?: string;          // Path to cache directory
102
  cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached';
103
  cacheAdditionalHeaders?: string[];  // Additional headers to store in cache
104
}
105
```
106

107
[HTTP Caching](./caching.md)
108

109
### Request Retry Logic
110

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

113
```javascript { .api }
114
/**
115
 * Retry configuration options
116
 */
117
interface RetryOptions {
118
  retries?: number;      // Number of retry attempts (default: 0)
119
  factor?: number;       // Exponential backoff factor
120
  minTimeout?: number;   // Minimum retry timeout
121
  maxTimeout?: number;   // Maximum retry timeout
122
  randomize?: boolean;   // Whether to randomize retry intervals
123
}
124

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

132
[Request Retry Logic](./retry.md)
133

134
### Proxy and Network Configuration
135

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

138
```javascript { .api }
139
/**
140
 * Network and proxy configuration options
141
 */
142
interface NetworkOptions {
143
  proxy?: string | URL;        // Proxy URL
144
  noProxy?: string | string[]; // Domains to bypass proxy
145
  maxSockets?: number;         // Maximum concurrent connections
146
  localAddress?: string;       // Local address to bind to
147
  agent?: object;             // Custom HTTP agent
148
}
149
```
150

151
[Proxy and Network Configuration](./network.md)
152

153
### Security and Integrity
154

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

157
```javascript { .api }
158
/**
159
 * Security and integrity options
160
 */
161
interface SecurityOptions {
162
  strictSSL?: boolean;    // SSL certificate validation
163
  ca?: string | Buffer;   // Certificate authority certificates
164
  cert?: string | Buffer; // Client certificate
165
  key?: string | Buffer;  // Client private key
166
  integrity?: string;     // Subresource integrity hash
167
}
168
```
169

170
[Security and Integrity](./security.md)
171

172
## Core Types
173

174
```javascript { .api }
175
/**
176
 * Main fetch function signature
177
 */
178
type FetchFunction = (url: string | Request, options?: FetchOptions) => Promise<Response>;
179

180
/**
181
 * Complete options interface combining all feature options
182
 */
183
interface FetchOptions extends CacheOptions, RetryOptions, NetworkOptions, SecurityOptions {
184
  // Standard fetch options
185
  method?: string;
186
  headers?: object;
187
  body?: any;
188
  redirect?: 'follow' | 'manual' | 'error';
189
  timeout?: number;
190
  size?: number;
191
  compress?: boolean;
192
  
193
  // make-fetch-happen specific
194
  onRetry?: OnRetryCallback;
195
  dns?: DNSOptions;
196
}
197

198
/**
199
 * DNS configuration options
200
 */
201
interface DNSOptions {
202
  ttl?: number;        // DNS cache TTL in milliseconds
203
  lookup?: Function;   // Custom DNS lookup function
204
}
205
```
206

207
## Error Handling
208

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

211
```javascript { .api }
212
/**
213
 * Error thrown by fetch operations
214
 */
215
class FetchError extends Error {
216
  code: string;
217
  type: string;
218
  errno?: string;
219
}
220
```
221

222
Common error codes include:
223
- `ENOTCACHED`: Cache-only mode with no cached response
224
- `EINTEGRITY`: Subresource integrity verification failed
225
- `ENOREDIRECT`: Redirect mode set to error but redirect encountered
226
- `EINVALIDREDIRECT`: Invalid redirect response
227
- `EMAXREDIRECT`: Maximum redirects exceeded