net - feat: renaming useHttpCache to httpCachePolicy (#1371)

* net - feat: renaming useHttpCache to httpCachePolicy

* Update README.md

Author: jaredwray

packages/net/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)
@@ -93,6 +91,34 @@ const result = await net.get('https://api.example.com/data', {
 });
 ```
 
+## 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
@@ -103,10 +129,11 @@ The main class that provides cached network operations.
 
 ```typescript
 interface CacheableNetOptions {
-  cache?: Cacheable | CacheableOptions;  // Cacheable instance or options
-  useHttpCache?: boolean;                 // Enable HTTP cache semantics (default: true)
+  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
@@ -126,11 +153,11 @@ The `FetchOptions` type extends the standard fetch `RequestInit` options with ad
 ```typescript
 type FetchOptions = Omit<RequestInit, 'cache'> & {
   cache?: Cacheable;          // Optional cache instance (if not provided, no caching)
-  useHttpCache?: boolean;     // Override instance-level HTTP cache setting
+  httpCachePolicy?: boolean;     // Override instance-level HTTP cache setting
 };
 ```
 
-The `NetFetchOptions` type (used by `get()` and `head()` methods) provides additional control:
+The `NetFetchOptions` type (used by all HTTP method helpers) provides additional control:
 
 ```typescript
 type NetFetchOptions = {
@@ -142,6 +169,14 @@ type NetFetchOptions = {
 
 **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
 

packages/net/src/fetch.ts

@@ -30,13 +30,13 @@ export type FetchOptions = Omit<RequestInit, "cache"> & {
 	 *
 	 * @default true
 	 */
-	useHttpCache?: boolean;
+	httpCachePolicy?: boolean;
 };
 
 /**
  * Fetch data from a URL with optional request options.
  *
- * 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.
  *
@@ -80,13 +80,13 @@ export async function fetch(
 		return response;
 	}
 
-	const useHttpCache = options.useHttpCache !== false; // Default to true
+	const httpCachePolicy = options.httpCachePolicy !== false; // Default to true
 	const method = options.method || "GET";
 
 	// Create a cache key that includes the method
 	const cacheKey = `${method}:${url}`;
 
-	if (!useHttpCache) {
+	if (!httpCachePolicy) {
 		// Simple caching without HTTP cache semantics
 		const cachedData = await options.cache.getOrSet(cacheKey, async () => {
 			// Perform the fetch operation

packages/net/src/index.ts

@@ -64,7 +64,7 @@ export type CacheableNetOptions = {
 	 *
 	 * @default true
 	 */
-	useHttpCache?: boolean;
+	httpCachePolicy?: boolean;
 	/**
 	 * Custom function for converting JavaScript values to strings.
 	 * This is used when serializing request bodies for POST, PUT, PATCH, and DELETE methods.
@@ -105,7 +105,7 @@ export type ParseType = (value: string) => unknown;
 
 export class CacheableNet extends Hookified {
 	private _cache: Cacheable = new Cacheable();
-	private _useHttpCache = true;
+	private _httpCachePolicy = true;
 	private _stringify: StringifyType = JSON.stringify;
 	private _parse: ParseType = JSON.parse;
 
@@ -119,8 +119,8 @@ export class CacheableNet extends Hookified {
 					: new Cacheable(options.cache);
 		}
 
-		if (options?.useHttpCache !== undefined) {
-			this._useHttpCache = options.useHttpCache;
+		if (options?.httpCachePolicy !== undefined) {
+			this._httpCachePolicy = options.httpCachePolicy;
 		}
 
 		if (options?.stringify) {
@@ -181,25 +181,25 @@ export class CacheableNet extends Hookified {
 	}
 
 	/**
-	 * Get the current HTTP cache setting.
+	 * Get the current HTTP cache policy setting.
 	 * @returns {boolean} Whether HTTP cache semantics are enabled
 	 */
-	public get useHttpCache(): boolean {
-		return this._useHttpCache;
+	public get httpCachePolicy(): boolean {
+		return this._httpCachePolicy;
 	}
 
 	/**
 	 * Set whether to use HTTP cache semantics.
 	 * @param {boolean} value - Enable or disable HTTP cache semantics
 	 */
-	public set useHttpCache(value: boolean) {
-		this._useHttpCache = value;
+	public set httpCachePolicy(value: boolean) {
+		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.
 	 *
@@ -214,7 +214,7 @@ export class CacheableNet extends Hookified {
 		const fetchOptions: FetchOptions = {
 			...options,
 			cache: this._cache,
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 		};
 
 		return fetch(url, fetchOptions);
@@ -234,7 +234,7 @@ export class CacheableNet extends Hookified {
 		const fetchOptions: FetchOptions = {
 			...options,
 			cache: this._cache,
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "GET",
 		};
 
@@ -311,7 +311,7 @@ export class CacheableNet extends Hookified {
 			...options,
 			headers,
 			body: body as FetchOptions["body"],
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "POST",
 		};
 
@@ -361,7 +361,7 @@ export class CacheableNet extends Hookified {
 		const fetchOptions: FetchOptions = {
 			...options,
 			cache: this._cache,
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "HEAD",
 		};
 
@@ -414,7 +414,7 @@ export class CacheableNet extends Hookified {
 			...options,
 			headers,
 			body: body as FetchOptions["body"],
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "PUT",
 		};
 
@@ -490,7 +490,7 @@ export class CacheableNet extends Hookified {
 			...options,
 			headers,
 			body: body as FetchOptions["body"],
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "PATCH",
 		};
 
@@ -568,7 +568,7 @@ export class CacheableNet extends Hookified {
 			...options,
 			headers,
 			body: body as FetchOptions["body"],
-			useHttpCache: this._useHttpCache,
+			httpCachePolicy: this._httpCachePolicy,
 			method: "DELETE",
 		};