@cacheable/net 1.0.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 [<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
 
-> High Performance Network Caching for Node.js with fetch, request, http 1.1, and http 2 support
+> High Performance Network Caching for Node.js with fetch support and HTTP cache semantics
 
 [![codecov](https://codecov.io/gh/jaredwray/cacheable/graph/badge.svg?token=lWZ9OBQ7GM)](https://codecov.io/gh/jaredwray/cacheable)
 [![tests](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml)
@@ -10,18 +10,16 @@
 
 
 Features:
-* `fetch` from [undici](https://github.com/nodejs/undici) cache enabled via `cacheable`
-* `fetch` quick helpers such as `get`, `post`, `put`, and `delete` for easier development
-* `request` from [undici](https://github.com/nodejs/undici) cache enabled via `cacheable`
-* HTTP/1.1 and HTTP/2 caching support via Node.js `http` and `https` modules
-* [RFC 7234](http://httpwg.org/specs/rfc7234.html) compliant HTTP caching for native Node.js HTTP/HTTPS requests
-* Drop in replacement for `http` `https`, `fetch` modules with caching enabled
-* DNS caching for `dns.lookup` and `dns.resolve` methods via `cacheable`
-* WHOIS caching for `whois.lookup` method via `cacheable`
-* Advanced key generation via built in hashing and custom key generation functions
-* Benchmarks for performance comparison
-* All the features of [cacheable](https://npmjs.com/package/cacheable) - layered caching, LRU, expiration, hooks, backed by Keyv, and more!
-* Highly Tested and Maintained on a regular basis with a focus on performance and reliability
+* `fetch` from [undici](https://github.com/nodejs/undici) with caching enabled via `cacheable`
+* HTTP method helpers: `get`, `post`, `put`, `patch`, `delete`, and `head` for easier development
+* [RFC 7234](http://httpwg.org/specs/rfc7234.html) compliant HTTP caching with `http-cache-semantics`
+* Smart caching with automatic cache key generation
+* Support for custom serialization/deserialization with `stringify` and `parse` functions
+* Configurable cache policies - use HTTP cache semantics or simple TTL-based caching
+* Full TypeScript support with comprehensive type definitions
+* Request-level cache control with the `caching` option
+* All the features of [cacheable](https://npmjs.com/package/cacheable) - layered caching, LRU, TTL expiration, and more!
+* Extensively tested with 100% code coverage
 
 # Table of Contents
 * [Getting Started](#getting-started)
@@ -34,6 +32,151 @@ Features:
 npm install @cacheable/net
 ```
 
+## Basic Usage
+
+```javascript
+import { CacheableNet } from '@cacheable/net';
+
+const net = new CacheableNet();
+
+// Simple GET request with caching
+const response = await net.get('https://api.example.com/data');
+console.log(response.data);
+
+// POST request with data
+const result = await net.post('https://api.example.com/users', {
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Using fetch directly with caching
+const fetchResponse = await net.fetch('https://api.example.com/data', {
+  method: 'GET',
+  headers: {
+    'Authorization': 'Bearer token'
+  }
+});
+```
+
+## Custom Serialization
+
+You can provide custom `stringify` and `parse` functions for handling data serialization. This is particularly useful when working with complex data types that JSON doesn't natively support:
+
+```javascript
+import { CacheableNet } from '@cacheable/net';
+import superjson from 'superjson';
+
+// Using superjson for enhanced serialization
+// Supports Dates, BigInt, RegExp, Set, Map, Error and more
+const net = new CacheableNet({
+  stringify: (value) => superjson.stringify(value),
+  parse: (text) => superjson.parse(text)
+});
+
+// Now you can work with complex data types
+const response = await net.post('https://api.example.com/data', {
+  timestamp: new Date(),
+  userId: BigInt(12345),
+  pattern: /[a-z]+/gi,
+  metadata: new Map([['key', 'value']]),
+  tags: new Set(['important', 'urgent'])
+});
+
+// Or provide per-request custom serialization
+const result = await net.get('https://api.example.com/data', {
+  parse: (text) => {
+    // Custom parsing with superjson for this request only
+    return superjson.parse(text);
+  }
+});
+```
+
+## Caching Control
+
+You can control caching behavior at multiple levels:
+
+```javascript
+import { CacheableNet } from '@cacheable/net';
+
+const net = new CacheableNet({
+  httpCachePolicy: true  // Enable HTTP cache semantics globally (default)
+});
+
+// GET requests are cached by default
+const data1 = await net.get('https://api.example.com/data');
+
+// Disable caching for a specific GET request
+const data2 = await net.get('https://api.example.com/data', {
+  caching: false
+});
+
+// POST requests are NOT cached by default
+const result1 = await net.post('https://api.example.com/data', { value: 1 });
+
+// Enable caching for a specific POST request
+const result2 = await net.post('https://api.example.com/data', { value: 1 }, {
+  caching: true
+});
+```
+
+## API Reference
+
+### CacheableNet Class
+
+The main class that provides cached network operations.
+
+#### Constructor Options
+
+```typescript
+interface CacheableNetOptions {
+  cache?: Cacheable | CacheableOptions;   // Cacheable instance or options
+  httpCachePolicy?: boolean;              // Enable HTTP cache semantics (default: true)
+  stringify?: (value: unknown) => string; // Custom JSON stringifier (default: JSON.stringify)
+  parse?: (value: string) => unknown;     // Custom JSON parser (default: JSON.parse)
+}
+```
+
+#### Methods
+
+All methods accept request options of type `FetchOptions` (excluding the `cache` property which is managed internally):
+
+- **fetch(url: string, options?: FetchOptions)**: Fetch with caching support
+- **get(url: string, options?: NetFetchOptions)**: GET request helper with caching control
+- **post(url: string, data?: unknown, options?: NetFetchOptions)**: POST request helper with caching control
+- **put(url: string, data?: unknown, options?: NetFetchOptions)**: PUT request helper with caching control
+- **patch(url: string, data?: unknown, options?: NetFetchOptions)**: PATCH request helper with caching control
+- **delete(url: string, data?: unknown, options?: NetFetchOptions)**: DELETE request helper with caching control
+- **head(url: string, options?: NetFetchOptions)**: HEAD request helper with caching control
+
+The `FetchOptions` type extends the standard fetch `RequestInit` options with additional caching controls:
+
+```typescript
+type FetchOptions = Omit<RequestInit, 'cache'> & {
+  cache?: Cacheable;          // Optional cache instance (if not provided, no caching)
+  httpCachePolicy?: boolean;     // Override instance-level HTTP cache setting
+};
+```
+
+The `NetFetchOptions` type (used by all HTTP method helpers) provides additional control:
+
+```typescript
+type NetFetchOptions = {
+  caching?: boolean;          // Enable/disable caching for this request
+  stringify?: (value: unknown) => string;  // Custom JSON stringifier
+  parse?: (value: string) => unknown;      // Custom JSON parser
+} & Omit<FetchOptions, 'method' | 'cache'>;
+```
+
+**Note**: When using the CacheableNet methods, you don't need to provide the `cache` property as it's automatically injected from the instance.
+
+#### Caching Behavior
+
+By default:
+- **GET** and **HEAD** requests are cached automatically
+- **POST**, **PUT**, **PATCH**, and **DELETE** requests are NOT cached by default
+- To enable caching for POST/PUT/PATCH/DELETE, set `caching: true` in the options
+- To disable caching for GET/HEAD, set `caching: false` in the options
+
 
 # How to Contribute
 

package/dist/index.cjs

@@ -47,13 +47,17 @@ var import_hookified = require("hookified");
 var import_http_cache_semantics = __toESM(require("http-cache-semantics"), 1);
 var import_undici = require("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"
   };
+  if (!options.cache) {
+    const response2 = await (0, import_undici.fetch)(url, fetchOptions);
+    if (!response2.ok) {
+      throw new Error(`Fetch failed with status ${response2.status}`);
+    }
+    return response2;
+  }
   if (options.method === "POST" || options.method === "PATCH" || options.method === "DELETE" || options.method === "HEAD") {
     const response2 = await (0, import_undici.fetch)(url, fetchOptions);
     if (!response2.ok) {
@@ -61,10 +65,10 @@ async function fetch(url, options) {
     }
     return response2;
   }
-  const useHttpCache = options.useHttpCache !== false;
+  const httpCachePolicy = options.httpCachePolicy !== false;
   const method = options.method || "GET";
   const cacheKey = `${method}:${url}`;
-  if (!useHttpCache) {
+  if (!httpCachePolicy) {
     const cachedData = await options.cache.getOrSet(cacheKey, async () => {
       const response2 = await (0, import_undici.fetch)(url, fetchOptions);
       if (!response2.ok) {
@@ -340,67 +344,122 @@ async function head(url, options) {
 // src/index.ts
 var CacheableNet = class extends import_hookified.Hookified {
   _cache = new import_cacheable.Cacheable();
-  _useHttpCache = true;
+  _httpCachePolicy = true;
+  _stringify = JSON.stringify;
+  _parse = JSON.parse;
   constructor(options) {
     super(options);
     if (options?.cache) {
       this._cache = options.cache instanceof import_cacheable.Cacheable ? options.cache : new import_cacheable.Cacheable(options.cache);
     }
-    if (options?.useHttpCache !== void 0) {
-      this._useHttpCache = options.useHttpCache;
+    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 setting.
+   * Get the current HTTP cache policy setting.
    * @returns {boolean} Whether HTTP cache semantics are enabled
    */
-  get useHttpCache() {
-    return this._useHttpCache;
+  get httpCachePolicy() {
+    return this._httpCachePolicy;
   }
   /**
    * Set whether to use HTTP cache semantics.
    * @param {boolean} value - Enable or disable HTTP cache semantics
    */
-  set useHttpCache(value) {
-    this._useHttpCache = value;
+  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 `useHttpCache` is enabled (default), cache entries will have their TTL
+   * 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,
-      useHttpCache: this._useHttpCache
+      httpCachePolicy: this._httpCachePolicy
     };
     return fetch(url, fetchOptions);
   }
   /**
-   * Perform a GET request to a URL with optional request options. Will use the cache that is already set in the instance.
+   * 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 {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to GET).
+   * @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 response = await this.fetch(url, { ...options, method: "GET" });
+    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 = JSON.parse(text);
+      data = parseFn(text);
     } catch {
       data = text;
     }
@@ -415,10 +474,11 @@ var CacheableNet = class extends import_hookified.Hookified {
     };
   }
   /**
-   * Perform a POST request to a URL with data and optional request options. Will use the cache that is already set in the instance.
+   * 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<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @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) {
@@ -429,21 +489,28 @@ var CacheableNet = class extends import_hookified.Hookified {
     } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
       body = data;
     } else {
-      body = JSON.stringify(data);
+      const stringifyFn = options?.stringify || this._stringify;
+      body = stringifyFn(data);
       if (!headers["Content-Type"] && !headers["content-type"]) {
         headers["Content-Type"] = "application/json";
       }
     }
-    const response = await this.fetch(url, {
+    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 = JSON.parse(text);
+      responseData = parseFn(text);
     } catch {
       responseData = text;
     }
@@ -458,20 +525,82 @@ var CacheableNet = class extends import_hookified.Hookified {
     };
   }
   /**
-   * Perform a HEAD request to a URL with optional request options. Will use the cache that is already set in the instance.
+   * 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 {Omit<FetchRequestInit, 'method'>} options Optional request options (method will be set to HEAD).
+   * @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 response = await this.fetch(url, { ...options, method: "HEAD" });
+    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 PATCH request to a URL with data and optional request options. Will use the cache that is already set in the instance.
+   * 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<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @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) {
@@ -482,21 +611,28 @@ var CacheableNet = class extends import_hookified.Hookified {
     } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
       body = data;
     } else {
-      body = JSON.stringify(data);
+      const stringifyFn = options?.stringify || this._stringify;
+      body = stringifyFn(data);
       if (!headers["Content-Type"] && !headers["content-type"]) {
         headers["Content-Type"] = "application/json";
       }
     }
-    const response = await this.fetch(url, {
+    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 = JSON.parse(text);
+      responseData = parseFn(text);
     } catch {
       responseData = text;
     }
@@ -511,10 +647,11 @@ var CacheableNet = class extends import_hookified.Hookified {
     };
   }
   /**
-   * Perform a DELETE request to a URL with optional data and request options. Will use the cache that is already set in the instance.
+   * 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<FetchRequestInit, 'method' | 'body'>} options Optional request options (method and body will be set).
+   * @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) {
@@ -526,22 +663,29 @@ var CacheableNet = class extends import_hookified.Hookified {
       } else if (data instanceof FormData || data instanceof URLSearchParams || data instanceof Blob) {
         body = data;
       } else {
-        body = JSON.stringify(data);
+        const stringifyFn = options?.stringify || this._stringify;
+        body = stringifyFn(data);
         if (!headers["Content-Type"] && !headers["content-type"]) {
           headers["Content-Type"] = "application/json";
         }
       }
     }
-    const response = await this.fetch(url, {
+    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 = JSON.parse(text);
+      responseData = parseFn(text);
     } catch {
       responseData = text;
     }