@cacheable/net 1.0.1 → 2.0.0

package/dist/index.js

@@ -3,58 +3,672 @@ import { Cacheable } from "cacheable";
 import { Hookified } from "hookified";
 
 // src/fetch.ts
+import CachePolicy from "http-cache-semantics";
 import {
   fetch as undiciFetch
 } from "undici";
 async function fetch(url, options) {
-  if (!options.cache) {
-    throw new Error("Fetch options must include a cache instance or options.");
-  }
   const fetchOptions = {
     ...options,
     cache: "no-cache"
   };
-  return options.cache.getOrSet(url, async () => {
-    const response = await undiciFetch(url, fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Fetch failed with status ${response.status}`);
+  if (!options.cache) {
+    const response2 = await undiciFetch(url, fetchOptions);
+    if (!response2.ok) {
+      throw new Error(`Fetch failed with status ${response2.status}`);
     }
-    return response;
+    return response2;
+  }
+  if (options.method === "POST" || options.method === "PATCH" || options.method === "DELETE" || options.method === "HEAD") {
+    const response2 = await undiciFetch(url, fetchOptions);
+    if (!response2.ok) {
+      throw new Error(`Fetch failed with status ${response2.status}`);
+    }
+    return response2;
+  }
+  const httpCachePolicy = options.httpCachePolicy !== false;
+  const method = options.method || "GET";
+  const cacheKey = `${method}:${url}`;
+  if (!httpCachePolicy) {
+    const cachedData = await options.cache.getOrSet(cacheKey, async () => {
+      const response2 = await undiciFetch(url, fetchOptions);
+      if (!response2.ok) {
+        throw new Error(`Fetch failed with status ${response2.status}`);
+      }
+      const body2 = await response2.text();
+      return {
+        body: body2,
+        status: response2.status,
+        statusText: response2.statusText,
+        headers: Object.fromEntries(response2.headers.entries())
+      };
+    });
+    if (!cachedData) {
+      throw new Error("Failed to get or set cache data");
+    }
+    return new Response(cachedData.body, {
+      status: cachedData.status,
+      statusText: cachedData.statusText,
+      headers: cachedData.headers
+    });
+  }
+  const policyKey = `${cacheKey}:policy`;
+  const [cachedResponse, cachedPolicyData] = await Promise.all([
+    options.cache.get(cacheKey),
+    options.cache.get(policyKey)
+  ]);
+  let policy;
+  let cachedBody;
+  let cachedStatus;
+  let cachedStatusText;
+  let cachedHeaders;
+  if (cachedPolicyData && cachedResponse) {
+    policy = CachePolicy.fromObject(
+      cachedPolicyData
+    );
+    cachedBody = cachedResponse.body;
+    cachedStatus = cachedResponse.status;
+    cachedStatusText = cachedResponse.statusText;
+    cachedHeaders = cachedResponse.headers;
+  }
+  const requestHeaders = fetchOptions.headers || {};
+  const request = {
+    url,
+    method,
+    headers: requestHeaders
+  };
+  if (policy?.satisfiesWithoutRevalidation(request)) {
+    const headers = policy.responseHeaders();
+    return new Response(cachedBody, {
+      status: cachedStatus,
+      statusText: cachedStatusText,
+      headers
+    });
+  }
+  let revalidationHeaders = {};
+  if (policy?.revalidationHeaders(request)) {
+    revalidationHeaders = policy.revalidationHeaders(request);
+  }
+  const response = await undiciFetch(url, {
+    ...fetchOptions,
+    headers: {
+      ...fetchOptions.headers,
+      ...revalidationHeaders
+    }
+  });
+  if (response.status === 304 && policy) {
+    const { policy: updatedPolicy, modified } = policy.revalidatedPolicy(
+      request,
+      {
+        status: response.status,
+        headers: Object.fromEntries(response.headers.entries())
+      }
+    );
+    if (!modified) {
+      const ttl = updatedPolicy.timeToLive();
+      await options.cache.set(policyKey, updatedPolicy.toObject(), ttl);
+      await options.cache.set(
+        cacheKey,
+        {
+          body: cachedBody,
+          status: cachedStatus,
+          statusText: cachedStatusText,
+          headers: cachedHeaders
+        },
+        ttl
+      );
+      const headers = updatedPolicy.responseHeaders();
+      return new Response(cachedBody, {
+        status: cachedStatus,
+        statusText: cachedStatusText,
+        headers
+      });
+    }
+  }
+  if (!response.ok && response.status !== 304) {
+    throw new Error(`Fetch failed with status ${response.status}`);
+  }
+  const body = await response.text();
+  const responseForPolicy = {
+    status: response.status,
+    statusText: response.statusText,
+    headers: Object.fromEntries(response.headers.entries())
+  };
+  const newPolicy = new CachePolicy(request, responseForPolicy);
+  if (newPolicy.storable()) {
+    const ttl = newPolicy.timeToLive();
+    await Promise.all([
+      options.cache.set(
+        cacheKey,
+        {
+          body,
+          status: response.status,
+          statusText: response.statusText,
+          headers: responseForPolicy.headers
+        },
+        ttl
+      ),
+      options.cache.set(policyKey, newPolicy.toObject(), ttl)
+    ]);
+  }
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+}
+async function get(url, options) {
+  const response = await fetch(url, { ...options, method: "GET" });
+  const text = await response.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = text;
+  }
+  const newResponse = new Response(text, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+  return {
+    data,
+    response: newResponse
+  };
+}
+async function post(url, data, options) {
+  let body;
+  const headers = { ...options.headers };
+  if (typeof data === "string") {
+    body = data;
+  } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+    body = data;
+  } else {
+    body = JSON.stringify(data);
+    if (!headers["Content-Type"] && !headers["content-type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+  }
+  const response = await fetch(url, {
+    ...options,
+    headers,
+    body,
+    method: "POST"
+  });
+  const text = await response.text();
+  let responseData;
+  try {
+    responseData = JSON.parse(text);
+  } catch {
+    responseData = text;
+  }
+  const newResponse = new Response(text, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+  return {
+    data: responseData,
+    response: newResponse
+  };
+}
+async function patch(url, data, options) {
+  let body;
+  const headers = { ...options.headers };
+  if (typeof data === "string") {
+    body = data;
+  } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+    body = data;
+  } else {
+    body = JSON.stringify(data);
+    if (!headers["Content-Type"] && !headers["content-type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+  }
+  const response = await fetch(url, {
+    ...options,
+    headers,
+    body,
+    method: "PATCH"
+  });
+  const text = await response.text();
+  let responseData;
+  try {
+    responseData = JSON.parse(text);
+  } catch {
+    responseData = text;
+  }
+  const newResponse = new Response(text, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+  return {
+    data: responseData,
+    response: newResponse
+  };
+}
+async function del(url, data, options) {
+  let actualData;
+  let actualOptions;
+  if (data !== void 0 && typeof data === "object" && data !== null && "cache" in data) {
+    actualData = void 0;
+    actualOptions = data;
+  } else if (options) {
+    actualData = data;
+    actualOptions = options;
+  } else {
+    throw new Error("Fetch options must include a cache instance or options.");
+  }
+  let body;
+  const headers = { ...actualOptions.headers };
+  if (actualData !== void 0) {
+    if (typeof actualData === "string") {
+      body = actualData;
+    } else if (actualData instanceof FormData || actualData instanceof URLSearchParams || actualData instanceof Blob) {
+      body = actualData;
+    } else {
+      body = JSON.stringify(actualData);
+      if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+  }
+  const response = await fetch(url, {
+    ...actualOptions,
+    headers,
+    body,
+    method: "DELETE"
+  });
+  const text = await response.text();
+  let responseData;
+  try {
+    responseData = JSON.parse(text);
+  } catch {
+    responseData = text;
+  }
+  const newResponse = new Response(text, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
   });
+  return {
+    data: responseData,
+    response: newResponse
+  };
+}
+async function head(url, options) {
+  const response = await fetch(url, { ...options, method: "HEAD" });
+  return response;
 }
 
 // src/index.ts
 var CacheableNet = class extends Hookified {
   _cache = new Cacheable();
+  _httpCachePolicy = true;
+  _stringify = JSON.stringify;
+  _parse = JSON.parse;
   constructor(options) {
     super(options);
     if (options?.cache) {
       this._cache = options.cache instanceof Cacheable ? options.cache : new Cacheable(options.cache);
     }
+    if (options?.httpCachePolicy !== void 0) {
+      this._httpCachePolicy = options.httpCachePolicy;
+    }
+    if (options?.stringify) {
+      this._stringify = options?.stringify;
+    }
+    if (options?.parse) {
+      this._parse = options?.parse;
+    }
   }
+  /**
+   * Get the stringify function used for converting objects to strings.
+   * @returns {StringifyType} The current stringify function
+   */
+  get stringify() {
+    return this._stringify;
+  }
+  /**
+   * Set the stringify function for converting objects to strings.
+   * @param {StringifyType} value - The stringify function to use
+   */
+  set stringify(value) {
+    this._stringify = value;
+  }
+  /**
+   * Get the parse function used for converting strings to objects.
+   * @returns {ParseType} The current parse function
+   */
+  get parse() {
+    return this._parse;
+  }
+  /**
+   * Set the parse function for converting strings to objects.
+   * @param {ParseType} value - The parse function to use
+   */
+  set parse(value) {
+    this._parse = value;
+  }
+  /**
+   * Get the Cacheable instance used for caching fetch operations.
+   * @returns {Cacheable} The current Cacheable instance
+   */
   get cache() {
     return this._cache;
   }
+  /**
+   * Set the Cacheable instance for caching fetch operations.
+   * @param {Cacheable} value - The Cacheable instance to use for caching
+   */
   set cache(value) {
     this._cache = value;
   }
+  /**
+   * Get the current HTTP cache policy setting.
+   * @returns {boolean} Whether HTTP cache semantics are enabled
+   */
+  get httpCachePolicy() {
+    return this._httpCachePolicy;
+  }
+  /**
+   * Set whether to use HTTP cache semantics.
+   * @param {boolean} value - Enable or disable HTTP cache semantics
+   */
+  set httpCachePolicy(value) {
+    this._httpCachePolicy = value;
+  }
   /**
    * Fetch data from a URL with optional request options. Will use the cache that is already set in the instance.
+   *
+   * When `httpCachePolicy` is enabled (default), cache entries will have their TTL
+   * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
+   * the default TTL from the Cacheable instance is used.
+   *
    * @param {string} url The URL to fetch.
-   * @param {FetchRequestInit} options Optional request options.
+   * @param {Omit<FetchOptions, "cache">} options Optional request options.
    * @returns {Promise<FetchResponse>} The response from the fetch.
    */
   async fetch(url, options) {
     const fetchOptions = {
       ...options,
-      cache: this._cache
+      cache: this._cache,
+      httpCachePolicy: this._httpCachePolicy
     };
     return fetch(url, fetchOptions);
   }
+  /**
+   * Perform a GET request to a URL with optional request options. By default caching is enabled on all requests. To
+   * disable set `options.caching` to false.
+   * @param {string} url The URL to fetch.
+   * @param {NetFetchOptions} options Optional request options (method will be set to GET).
+   * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
+   */
+  async get(url, options) {
+    const fetchOptions = {
+      ...options,
+      cache: this._cache,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "GET"
+    };
+    if (options?.caching !== void 0) {
+      delete fetchOptions.cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    const text = await response.text();
+    let data;
+    const parseFn = options?.parse || this._parse;
+    try {
+      data = parseFn(text);
+    } catch {
+      data = text;
+    }
+    const newResponse = new Response(text, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    return {
+      data,
+      response: newResponse
+    };
+  }
+  /**
+   * Perform a POST request to a URL with data and optional request options. By default caching is not enabled. To enable it
+   * set `options.caching` to true. Note, setting caching to tru means it will not post if the data is the same.
+   * @param {string} url The URL to fetch.
+   * @param {unknown} data The data to send in the request body.
+   * @param {Omit<NetFetchOptions, "method" | "body" >} options Optional request options (method and body will be set).
+   * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
+   */
+  async post(url, data, options) {
+    let body;
+    const headers = { ...options?.headers };
+    if (typeof data === "string") {
+      body = data;
+    } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+      body = data;
+    } else {
+      const stringifyFn = options?.stringify || this._stringify;
+      body = stringifyFn(data);
+      if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+    const fetchOptions = {
+      ...options,
+      headers,
+      body,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "POST"
+    };
+    if (options?.caching === true) {
+      fetchOptions.cache = this._cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    const text = await response.text();
+    let responseData;
+    const parseFn = options?.parse || this._parse;
+    try {
+      responseData = parseFn(text);
+    } catch {
+      responseData = text;
+    }
+    const newResponse = new Response(text, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    return {
+      data: responseData,
+      response: newResponse
+    };
+  }
+  /**
+   * Perform a HEAD request to a URL with optional request options. By default caching is enabled on all requests. To
+   * disable set `options.caching` to false.
+   * @param {string} url The URL to fetch.
+   * @param {NetFetchOptions} options Optional request options (method will be set to HEAD).
+   * @returns {Promise<FetchResponse>} The response from the fetch (no body).
+   */
+  async head(url, options) {
+    const fetchOptions = {
+      ...options,
+      cache: this._cache,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "HEAD"
+    };
+    if (options?.caching !== void 0 && !options.caching) {
+      delete fetchOptions.cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    return response;
+  }
+  /**
+   * Perform a PUT request to a URL with data and optional request options. By default caching is not enabled. To enable it
+   * set `options.caching` to true. Note, setting caching to true means it will not put if the data is the same.
+   * @param {string} url The URL to fetch.
+   * @param {unknown} data The data to send in the request body.
+   * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
+   */
+  async put(url, data, options) {
+    let body;
+    const headers = { ...options?.headers };
+    if (typeof data === "string") {
+      body = data;
+    } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+      body = data;
+    } else {
+      const stringifyFn = options?.stringify || this._stringify;
+      body = stringifyFn(data);
+      if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+    const fetchOptions = {
+      ...options,
+      headers,
+      body,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "PUT"
+    };
+    if (options?.caching === true) {
+      fetchOptions.cache = this._cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    const text = await response.text();
+    let responseData;
+    const parseFn = options?.parse || this._parse;
+    try {
+      responseData = parseFn(text);
+    } catch {
+      responseData = text;
+    }
+    const newResponse = new Response(text, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    return {
+      data: responseData,
+      response: newResponse
+    };
+  }
+  /**
+   * Perform a PATCH request to a URL with data and optional request options. By default caching is not enabled. To enable it
+   * set `options.caching` to true. Note, setting caching to true means it will not patch if the data is the same.
+   * @param {string} url The URL to fetch.
+   * @param {unknown} data The data to send in the request body.
+   * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
+   */
+  async patch(url, data, options) {
+    let body;
+    const headers = { ...options?.headers };
+    if (typeof data === "string") {
+      body = data;
+    } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+      body = data;
+    } else {
+      const stringifyFn = options?.stringify || this._stringify;
+      body = stringifyFn(data);
+      if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+    const fetchOptions = {
+      ...options,
+      headers,
+      body,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "PATCH"
+    };
+    if (options?.caching === true) {
+      fetchOptions.cache = this._cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    const text = await response.text();
+    let responseData;
+    const parseFn = options?.parse || this._parse;
+    try {
+      responseData = parseFn(text);
+    } catch {
+      responseData = text;
+    }
+    const newResponse = new Response(text, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    return {
+      data: responseData,
+      response: newResponse
+    };
+  }
+  /**
+   * Perform a DELETE request to a URL with optional data and request options. By default caching is not enabled. To enable it
+   * set `options.caching` to true. Note, setting caching to true means it will not delete if the data is the same.
+   * @param {string} url The URL to fetch.
+   * @param {unknown} data Optional data to send in the request body.
+   * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
+   */
+  async delete(url, data, options) {
+    let body;
+    const headers = { ...options?.headers };
+    if (data !== void 0) {
+      if (typeof data === "string") {
+        body = data;
+      } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
+        body = data;
+      } else {
+        const stringifyFn = options?.stringify || this._stringify;
+        body = stringifyFn(data);
+        if (!headers["Content-Type"] && !headers["content-type"]) {
+          headers["Content-Type"] = "application/json";
+        }
+      }
+    }
+    const fetchOptions = {
+      ...options,
+      headers,
+      body,
+      httpCachePolicy: this._httpCachePolicy,
+      method: "DELETE"
+    };
+    if (options?.caching === true) {
+      fetchOptions.cache = this._cache;
+    }
+    const response = await fetch(url, fetchOptions);
+    const text = await response.text();
+    let responseData;
+    const parseFn = options?.parse || this._parse;
+    try {
+      responseData = parseFn(text);
+    } catch {
+      responseData = text;
+    }
+    const newResponse = new Response(text, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    return {
+      data: responseData,
+      response: newResponse
+    };
+  }
 };
 var Net = CacheableNet;
 export {
   CacheableNet,
   Net,
-  fetch
+  del,
+  fetch,
+  get,
+  head,
+  patch,
+  post
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cacheable/net",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "High Performance Network Caching for Node.js with fetch, request, http 1.1, and http 2 support",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,9 +21,10 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "@biomejs/biome": "^2.2.2",
+    "@biomejs/biome": "^2.2.4",
     "@faker-js/faker": "^10.0.0",
-    "@types/node": "^24.3.0",
+    "@types/http-cache-semantics": "^4.0.4",
+    "@types/node": "^24.5.2",
     "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
@@ -31,9 +32,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "hookified": "^1.12.0",
-    "undici": "^7.15.0",
-    "cacheable": "^1.10.4"
+    "hookified": "^1.12.1",
+    "http-cache-semantics": "^4.2.0",
+    "undici": "^7.16.0",
+    "cacheable": "^2.0.3"
   },
   "keywords": [
     "cacheable",