@cacheable/net 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.cjs +493 -8
  2. package/dist/index.d.cts +150 -3
  3. package/dist/index.d.ts +150 -3
  4. package/dist/index.js +477 -7
  5. package/package.json +4 -2
package/dist/index.d.cts CHANGED
@@ -5,33 +5,180 @@ export { RequestInit as FetchRequestInit } from 'undici';
5
5
 
6
6
  type FetchOptions = Omit<RequestInit, "cache"> & {
7
7
  cache: Cacheable;
8
+ /**
9
+ * Enable HTTP cache semantics for intelligent response caching.
10
+ *
11
+ * When enabled (default), the fetch function will:
12
+ * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
13
+ * - Store and validate cache policies according to RFC 7234
14
+ * - Handle conditional requests with If-None-Match and If-Modified-Since headers
15
+ * - Process 304 Not Modified responses to update cached entries
16
+ * - Only cache responses that are considered "storable" per HTTP specifications
17
+ * - Automatically revalidate stale cache entries when needed
18
+ * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
19
+ * - Refresh TTL when receiving 304 Not Modified responses
20
+ *
21
+ * When disabled, the fetch function will:
22
+ * - Use simple key-based caching without considering HTTP headers
23
+ * - Cache all successful GET responses regardless of cache directives
24
+ * - Never revalidate cached entries
25
+ * - Ignore cache-control directives from the server
26
+ * - **Use the default TTL from the Cacheable instance**
27
+ *
28
+ * @default true
29
+ */
30
+ useHttpCache?: boolean;
8
31
  };
9
32
  /**
10
33
  * Fetch data from a URL with optional request options.
34
+ *
35
+ * When `useHttpCache` is enabled (default), cache entries will have their TTL
36
+ * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
37
+ * the default TTL from the Cacheable instance is used.
38
+ *
11
39
  * @param {string} url The URL to fetch.
12
- * @param {FetchOptions} options Optional request options. The `cacheable` property is required and should be an
13
- * instance of `Cacheable` or a `CacheableOptions` object.
40
+ * @param {FetchOptions} options Optional request options. The `cache` property is required.
14
41
  * @returns {Promise<UndiciResponse>} The response from the fetch.
15
42
  */
16
43
  declare function fetch(url: string, options: FetchOptions): Promise<Response$1>;
44
+ type DataResponse<T = unknown> = {
45
+ data: T;
46
+ response: Response$1;
47
+ };
48
+ type GetResponse<T = unknown> = DataResponse<T>;
49
+ /**
50
+ * Perform a GET request to a URL with optional request options.
51
+ * @param {string} url The URL to fetch.
52
+ * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
53
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
54
+ */
55
+ declare function get<T = unknown>(url: string, options: Omit<FetchOptions, "method">): Promise<DataResponse<T>>;
56
+ /**
57
+ * Perform a POST request to a URL with data and optional request options.
58
+ * @param {string} url The URL to fetch.
59
+ * @param {unknown} data The data to send in the request body.
60
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
61
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
62
+ */
63
+ declare function post<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
64
+ /**
65
+ * Perform a PATCH request to a URL with data and optional request options.
66
+ * @param {string} url The URL to fetch.
67
+ * @param {unknown} data The data to send in the request body.
68
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
69
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
70
+ */
71
+ declare function patch<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
72
+ /**
73
+ * Perform a DELETE request to a URL with optional data and request options.
74
+ * @param {string} url The URL to fetch.
75
+ * @param {unknown} data Optional data to send in the request body.
76
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
77
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
78
+ */
79
+ declare function del<T = unknown>(url: string, data?: unknown, options?: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
80
+ /**
81
+ * Perform a HEAD request to a URL with optional request options.
82
+ * @param {string} url The URL to fetch.
83
+ * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
84
+ * @returns {Promise<UndiciResponse>} The response from the fetch (no body).
85
+ */
86
+ declare function head(url: string, options: Omit<FetchOptions, "method">): Promise<Response$1>;
17
87
  type Response = Response$1;
18
88
 
19
89
  type CacheableNetOptions = {
20
90
  cache?: Cacheable | CacheableOptions;
91
+ /**
92
+ * Enable HTTP cache semantics for intelligent response caching.
93
+ *
94
+ * When enabled (default), fetch operations will:
95
+ * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
96
+ * - Store and validate cache policies according to RFC 7234
97
+ * - Handle conditional requests with If-None-Match and If-Modified-Since headers
98
+ * - Process 304 Not Modified responses to update cached entries
99
+ * - Only cache responses that are considered "storable" per HTTP specifications
100
+ * - Automatically revalidate stale cache entries when needed
101
+ * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
102
+ * - Refresh TTL when receiving 304 Not Modified responses
103
+ *
104
+ * When disabled, fetch operations will:
105
+ * - Use simple key-based caching without considering HTTP headers
106
+ * - Cache all successful GET responses regardless of cache directives
107
+ * - Never revalidate cached entries
108
+ * - Ignore cache-control directives from the server
109
+ * - **Use the default TTL from the Cacheable instance**
110
+ *
111
+ * @default true
112
+ */
113
+ useHttpCache?: boolean;
21
114
  } & HookifiedOptions;
22
115
  declare class CacheableNet extends Hookified {
23
116
  private _cache;
117
+ private _useHttpCache;
24
118
  constructor(options?: CacheableNetOptions);
25
119
  get cache(): Cacheable;
26
120
  set cache(value: Cacheable);
121
+ /**
122
+ * Get the current HTTP cache setting.
123
+ * @returns {boolean} Whether HTTP cache semantics are enabled
124
+ */
125
+ get useHttpCache(): boolean;
126
+ /**
127
+ * Set whether to use HTTP cache semantics.
128
+ * @param {boolean} value - Enable or disable HTTP cache semantics
129
+ */
130
+ set useHttpCache(value: boolean);
27
131
  /**
28
132
  * Fetch data from a URL with optional request options. Will use the cache that is already set in the instance.
133
+ *
134
+ * When `useHttpCache` is enabled (default), cache entries will have their TTL
135
+ * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
136
+ * the default TTL from the Cacheable instance is used.
137
+ *
29
138
  * @param {string} url The URL to fetch.
30
139
  * @param {FetchRequestInit} options Optional request options.
31
140
  * @returns {Promise<FetchResponse>} The response from the fetch.
32
141
  */
33
142
  fetch(url: string, options?: RequestInit): Promise<Response>;
143
+ /**
144
+ * Perform a GET request to a URL with optional request options. Will use the cache that is already set in the instance.
145
+ * @param {string} url The URL to fetch.
146
+ * @param {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to GET).
147
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
148
+ */
149
+ get<T = unknown>(url: string, options?: Omit<RequestInit, "method">): Promise<DataResponse<T>>;
150
+ /**
151
+ * Perform a POST request to a URL with data and optional request options. Will use the cache that is already set in the instance.
152
+ * @param {string} url The URL to fetch.
153
+ * @param {unknown} data The data to send in the request body.
154
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
155
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
156
+ */
157
+ post<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
158
+ /**
159
+ * Perform a HEAD request to a URL with optional request options. Will use the cache that is already set in the instance.
160
+ * @param {string} url The URL to fetch.
161
+ * @param {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to HEAD).
162
+ * @returns {Promise<FetchResponse>} The response from the fetch (no body).
163
+ */
164
+ head(url: string, options?: Omit<RequestInit, "method">): Promise<Response>;
165
+ /**
166
+ * Perform a PATCH request to a URL with data and optional request options. Will use the cache that is already set in the instance.
167
+ * @param {string} url The URL to fetch.
168
+ * @param {unknown} data The data to send in the request body.
169
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
170
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
171
+ */
172
+ patch<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
173
+ /**
174
+ * Perform a DELETE request to a URL with optional data and request options. Will use the cache that is already set in the instance.
175
+ * @param {string} url The URL to fetch.
176
+ * @param {unknown} data Optional data to send in the request body.
177
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
178
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
179
+ */
180
+ delete<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
34
181
  }
35
182
  declare const Net: typeof CacheableNet;
36
183
 
37
- export { CacheableNet, type CacheableNetOptions, type FetchOptions, type Response as FetchResponse, Net, fetch };
184
+ export { CacheableNet, type CacheableNetOptions, type DataResponse, type FetchOptions, type Response as FetchResponse, type GetResponse, Net, del, fetch, get, head, patch, post };
package/dist/index.d.ts CHANGED
@@ -5,33 +5,180 @@ export { RequestInit as FetchRequestInit } from 'undici';
5
5
 
6
6
  type FetchOptions = Omit<RequestInit, "cache"> & {
7
7
  cache: Cacheable;
8
+ /**
9
+ * Enable HTTP cache semantics for intelligent response caching.
10
+ *
11
+ * When enabled (default), the fetch function will:
12
+ * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
13
+ * - Store and validate cache policies according to RFC 7234
14
+ * - Handle conditional requests with If-None-Match and If-Modified-Since headers
15
+ * - Process 304 Not Modified responses to update cached entries
16
+ * - Only cache responses that are considered "storable" per HTTP specifications
17
+ * - Automatically revalidate stale cache entries when needed
18
+ * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
19
+ * - Refresh TTL when receiving 304 Not Modified responses
20
+ *
21
+ * When disabled, the fetch function will:
22
+ * - Use simple key-based caching without considering HTTP headers
23
+ * - Cache all successful GET responses regardless of cache directives
24
+ * - Never revalidate cached entries
25
+ * - Ignore cache-control directives from the server
26
+ * - **Use the default TTL from the Cacheable instance**
27
+ *
28
+ * @default true
29
+ */
30
+ useHttpCache?: boolean;
8
31
  };
9
32
  /**
10
33
  * Fetch data from a URL with optional request options.
34
+ *
35
+ * When `useHttpCache` is enabled (default), cache entries will have their TTL
36
+ * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
37
+ * the default TTL from the Cacheable instance is used.
38
+ *
11
39
  * @param {string} url The URL to fetch.
12
- * @param {FetchOptions} options Optional request options. The `cacheable` property is required and should be an
13
- * instance of `Cacheable` or a `CacheableOptions` object.
40
+ * @param {FetchOptions} options Optional request options. The `cache` property is required.
14
41
  * @returns {Promise<UndiciResponse>} The response from the fetch.
15
42
  */
16
43
  declare function fetch(url: string, options: FetchOptions): Promise<Response$1>;
44
+ type DataResponse<T = unknown> = {
45
+ data: T;
46
+ response: Response$1;
47
+ };
48
+ type GetResponse<T = unknown> = DataResponse<T>;
49
+ /**
50
+ * Perform a GET request to a URL with optional request options.
51
+ * @param {string} url The URL to fetch.
52
+ * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
53
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
54
+ */
55
+ declare function get<T = unknown>(url: string, options: Omit<FetchOptions, "method">): Promise<DataResponse<T>>;
56
+ /**
57
+ * Perform a POST request to a URL with data and optional request options.
58
+ * @param {string} url The URL to fetch.
59
+ * @param {unknown} data The data to send in the request body.
60
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
61
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
62
+ */
63
+ declare function post<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
64
+ /**
65
+ * Perform a PATCH request to a URL with data and optional request options.
66
+ * @param {string} url The URL to fetch.
67
+ * @param {unknown} data The data to send in the request body.
68
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
69
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
70
+ */
71
+ declare function patch<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
72
+ /**
73
+ * Perform a DELETE request to a URL with optional data and request options.
74
+ * @param {string} url The URL to fetch.
75
+ * @param {unknown} data Optional data to send in the request body.
76
+ * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
77
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
78
+ */
79
+ declare function del<T = unknown>(url: string, data?: unknown, options?: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
80
+ /**
81
+ * Perform a HEAD request to a URL with optional request options.
82
+ * @param {string} url The URL to fetch.
83
+ * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
84
+ * @returns {Promise<UndiciResponse>} The response from the fetch (no body).
85
+ */
86
+ declare function head(url: string, options: Omit<FetchOptions, "method">): Promise<Response$1>;
17
87
  type Response = Response$1;
18
88
 
19
89
  type CacheableNetOptions = {
20
90
  cache?: Cacheable | CacheableOptions;
91
+ /**
92
+ * Enable HTTP cache semantics for intelligent response caching.
93
+ *
94
+ * When enabled (default), fetch operations will:
95
+ * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
96
+ * - Store and validate cache policies according to RFC 7234
97
+ * - Handle conditional requests with If-None-Match and If-Modified-Since headers
98
+ * - Process 304 Not Modified responses to update cached entries
99
+ * - Only cache responses that are considered "storable" per HTTP specifications
100
+ * - Automatically revalidate stale cache entries when needed
101
+ * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
102
+ * - Refresh TTL when receiving 304 Not Modified responses
103
+ *
104
+ * When disabled, fetch operations will:
105
+ * - Use simple key-based caching without considering HTTP headers
106
+ * - Cache all successful GET responses regardless of cache directives
107
+ * - Never revalidate cached entries
108
+ * - Ignore cache-control directives from the server
109
+ * - **Use the default TTL from the Cacheable instance**
110
+ *
111
+ * @default true
112
+ */
113
+ useHttpCache?: boolean;
21
114
  } & HookifiedOptions;
22
115
  declare class CacheableNet extends Hookified {
23
116
  private _cache;
117
+ private _useHttpCache;
24
118
  constructor(options?: CacheableNetOptions);
25
119
  get cache(): Cacheable;
26
120
  set cache(value: Cacheable);
121
+ /**
122
+ * Get the current HTTP cache setting.
123
+ * @returns {boolean} Whether HTTP cache semantics are enabled
124
+ */
125
+ get useHttpCache(): boolean;
126
+ /**
127
+ * Set whether to use HTTP cache semantics.
128
+ * @param {boolean} value - Enable or disable HTTP cache semantics
129
+ */
130
+ set useHttpCache(value: boolean);
27
131
  /**
28
132
  * Fetch data from a URL with optional request options. Will use the cache that is already set in the instance.
133
+ *
134
+ * When `useHttpCache` is enabled (default), cache entries will have their TTL
135
+ * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
136
+ * the default TTL from the Cacheable instance is used.
137
+ *
29
138
  * @param {string} url The URL to fetch.
30
139
  * @param {FetchRequestInit} options Optional request options.
31
140
  * @returns {Promise<FetchResponse>} The response from the fetch.
32
141
  */
33
142
  fetch(url: string, options?: RequestInit): Promise<Response>;
143
+ /**
144
+ * Perform a GET request to a URL with optional request options. Will use the cache that is already set in the instance.
145
+ * @param {string} url The URL to fetch.
146
+ * @param {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to GET).
147
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
148
+ */
149
+ get<T = unknown>(url: string, options?: Omit<RequestInit, "method">): Promise<DataResponse<T>>;
150
+ /**
151
+ * Perform a POST request to a URL with data and optional request options. Will use the cache that is already set in the instance.
152
+ * @param {string} url The URL to fetch.
153
+ * @param {unknown} data The data to send in the request body.
154
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
155
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
156
+ */
157
+ post<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
158
+ /**
159
+ * Perform a HEAD request to a URL with optional request options. Will use the cache that is already set in the instance.
160
+ * @param {string} url The URL to fetch.
161
+ * @param {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to HEAD).
162
+ * @returns {Promise<FetchResponse>} The response from the fetch (no body).
163
+ */
164
+ head(url: string, options?: Omit<RequestInit, "method">): Promise<Response>;
165
+ /**
166
+ * Perform a PATCH request to a URL with data and optional request options. Will use the cache that is already set in the instance.
167
+ * @param {string} url The URL to fetch.
168
+ * @param {unknown} data The data to send in the request body.
169
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
170
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
171
+ */
172
+ patch<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
173
+ /**
174
+ * Perform a DELETE request to a URL with optional data and request options. Will use the cache that is already set in the instance.
175
+ * @param {string} url The URL to fetch.
176
+ * @param {unknown} data Optional data to send in the request body.
177
+ * @param {Omit<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
178
+ * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
179
+ */
180
+ delete<T = unknown>(url: string, data?: unknown, options?: Omit<RequestInit, "method" | "body">): Promise<DataResponse<T>>;
34
181
  }
35
182
  declare const Net: typeof CacheableNet;
36
183
 
37
- export { CacheableNet, type CacheableNetOptions, type FetchOptions, type Response as FetchResponse, Net, fetch };
184
+ export { CacheableNet, type CacheableNetOptions, type DataResponse, type FetchOptions, type Response as FetchResponse, type GetResponse, Net, del, fetch, get, head, patch, post };