@superutils/fetch 1.5.14 → 1.5.16

package/dist/index.d.cts

@@ -155,40 +155,33 @@ type FetchInterceptorResponse = Interceptor<Response, FetchArgsInterceptor>;
  * ```javascript
  * import fetch from '@superutils/fetch'
  *
- * // first transform result (user object) and ensure user result alwasy contain a hexadecimal crypto balance
- * const ensureBalanceHex = (user = {}) => {
- *   user.crypto ??= {}
- *   user.crypto.balance ??= '0x0'
- *   return user
- * }
- * // then check convert hexadecimal number to BigInt
- * const hexToBigInt = user => {
- *   user.crypto.balance = BigInt(user.crypto.balance)
- *   return user
- * }
- * // then log balance (no transformation)
- * const logBalance = (result, url) => {
- *   // only log balance for single user requests
- *   const shouldLog = result?.hasOwnProperty('crypto') && /^[0-9]+$/.test(
- *     url?.split('/users/')[1].replace('/', '')
- *   )
- *   shouldLog && console.log(
- *     new Date().toISOString(),
- *     '[UserBalance] UserID:', result.id,
- *     result.crypto.balance
- *   )
- * }
- * // now we make the actaul fetch request
  * const result = await fetch.get('[DUMMYJSON-DOT-COM]/users/1', {
  *   interceptors: {
  *     result: [
- * 	     ensureBalanceHex,
- * 	     hexToBigInt,
- * 	     logBalance
+ *       // 1. check & convert user crypto balance to BigInt
+ * 	     userCryptoBalanceToBigInt,
+ *
+ *       // 2. log balance (no transformation)
+ * 	     logUserBalance
  * 	   ]
  *   }
  * })
  * console.log({result})
+ *
+ * function userCryptoBalanceToBigInt(user = {}) {
+ *   user.crypto ??= {}
+ *   user.crypto.balance ??= '0x0'
+ *   user.crypto.balance = BigInt(user.crypto.balance || '0x0')
+ *   return user
+ * }
+ *
+ * function logUserBalance(user, url) {
+ *   console.log(
+ *     new Date().toISOString(),
+ *     '[UserBalance] UserID:', user.id,
+ *     user.crypto.balance
+ *   )
+ * }
  * ```
  */
 type FetchInterceptorResult<Args extends unknown[] = FetchArgsInterceptor> = Interceptor<unknown, Args>;
@@ -377,6 +370,61 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
      * Default: `0`
      */
     retry?: number;
+    /**
+     * An optional predicate function to determine retry eligibility.
+     * Also useful for side effects like logging or analytics.
+     *
+     * Returning `true` explicitly triggers a retry, while `false` prevents it.
+     * If the function returns `undefined` or `void`, the default library logic is used
+     * (retry if an exception was thrown or if `response.ok` is `false`).
+     *
+     * @param response The Response object from the last attempt, if available.
+     * @param retryCount The current retry attempt number (starting from 1).
+     * @param error The error encountered during the request, if any.
+     *
+     * @returns A boolean indicating whether to retry, or a promise resolving to boolean.
+     *
+     *
+     * @example
+     * #### Example: Retry on specific status codes
+     * ```javascript
+     * import fetch from '@superutils/fetch'
+     *
+     * fetch
+     * 	.get('[DUMMYJSON-DOT-COM]/products/1', {
+     * 		retry: 3, // If request fails, retry up to three more times
+     * 		// Retry on rate limits (429) or transient server errors (5xx).
+     * 		retryIf: r => r.status === 429 || r.status >= 500,
+     * 	})
+     * 	.then(console.log)
+     * ```
+     *
+     * @example
+     * #### Example: Polling (Retry until a condition is met)
+     * Keep retrying every minute until a product is back in stock.
+     * ```javascript
+     * import fetch from '@superutils/fetch'
+     *
+     * fetch
+     * 	.get('[DUMMYJSON-DOT-COM]/products/1', {
+     * 	  delay: 60_000, // Wait 1 minute between attempts
+     * 	  retry: 10, // Attempt up to 10 more times
+     * 	  retryIf: async (response) => {
+     * 	    if (!response?.ok) return true // Retry on network or server errors
+     *
+     * 		// Use response.clone() to avoid consuming the body stream used by the final result.
+     * 		const result = await response.clone().json()
+     *
+     * 		// Retry if the product is still NOT in stock
+     * 		return result?.availabilityStatus !== 'In Stock'
+     * 	  },
+     *
+     *    // Ensure the overall timeout accounts for the polling duration
+     * 	  timeout: 60_000 * 15
+     * 	})
+     * 	.then(product => console.log('Product is back in stock:', product))
+     * ```
+     */
     retryIf?: RetryIfFunc<Response>;
 };
 /**
@@ -487,6 +535,11 @@ type ClientData<FixedOptions> = ExtractAs<[FixedOptions]> extends FetchAs.json ?
  * which minimizes code repetition across your application. If a method is not specified during creation, the client
  * will default to `GET`.
  *
+ * **Option Priority:**
+ * 1. `fixedOptions`: Highest priority. Cannot be overridden by the caller.
+ * 2. `options`: Options passed during the specific call.
+ * 3. `commonOptions`: Default options set at creation time.
+ *
  * The returned client also includes a `.deferred()` method, providing the same debounce, throttle, and sequential
  * execution capabilities found in functions like `fetch.get.deferred()`.
  *

package/dist/index.d.ts

@@ -155,40 +155,33 @@ type FetchInterceptorResponse = Interceptor<Response, FetchArgsInterceptor>;
  * ```javascript
  * import fetch from '@superutils/fetch'
  *
- * // first transform result (user object) and ensure user result alwasy contain a hexadecimal crypto balance
- * const ensureBalanceHex = (user = {}) => {
- *   user.crypto ??= {}
- *   user.crypto.balance ??= '0x0'
- *   return user
- * }
- * // then check convert hexadecimal number to BigInt
- * const hexToBigInt = user => {
- *   user.crypto.balance = BigInt(user.crypto.balance)
- *   return user
- * }
- * // then log balance (no transformation)
- * const logBalance = (result, url) => {
- *   // only log balance for single user requests
- *   const shouldLog = result?.hasOwnProperty('crypto') && /^[0-9]+$/.test(
- *     url?.split('/users/')[1].replace('/', '')
- *   )
- *   shouldLog && console.log(
- *     new Date().toISOString(),
- *     '[UserBalance] UserID:', result.id,
- *     result.crypto.balance
- *   )
- * }
- * // now we make the actaul fetch request
  * const result = await fetch.get('[DUMMYJSON-DOT-COM]/users/1', {
  *   interceptors: {
  *     result: [
- * 	     ensureBalanceHex,
- * 	     hexToBigInt,
- * 	     logBalance
+ *       // 1. check & convert user crypto balance to BigInt
+ * 	     userCryptoBalanceToBigInt,
+ *
+ *       // 2. log balance (no transformation)
+ * 	     logUserBalance
  * 	   ]
  *   }
  * })
  * console.log({result})
+ *
+ * function userCryptoBalanceToBigInt(user = {}) {
+ *   user.crypto ??= {}
+ *   user.crypto.balance ??= '0x0'
+ *   user.crypto.balance = BigInt(user.crypto.balance || '0x0')
+ *   return user
+ * }
+ *
+ * function logUserBalance(user, url) {
+ *   console.log(
+ *     new Date().toISOString(),
+ *     '[UserBalance] UserID:', user.id,
+ *     user.crypto.balance
+ *   )
+ * }
  * ```
  */
 type FetchInterceptorResult<Args extends unknown[] = FetchArgsInterceptor> = Interceptor<unknown, Args>;
@@ -377,6 +370,61 @@ type FetchRetryOptions = Omit<Partial<RetryOptions>, 'retry' | 'retryIf'> & {
      * Default: `0`
      */
     retry?: number;
+    /**
+     * An optional predicate function to determine retry eligibility.
+     * Also useful for side effects like logging or analytics.
+     *
+     * Returning `true` explicitly triggers a retry, while `false` prevents it.
+     * If the function returns `undefined` or `void`, the default library logic is used
+     * (retry if an exception was thrown or if `response.ok` is `false`).
+     *
+     * @param response The Response object from the last attempt, if available.
+     * @param retryCount The current retry attempt number (starting from 1).
+     * @param error The error encountered during the request, if any.
+     *
+     * @returns A boolean indicating whether to retry, or a promise resolving to boolean.
+     *
+     *
+     * @example
+     * #### Example: Retry on specific status codes
+     * ```javascript
+     * import fetch from '@superutils/fetch'
+     *
+     * fetch
+     * 	.get('[DUMMYJSON-DOT-COM]/products/1', {
+     * 		retry: 3, // If request fails, retry up to three more times
+     * 		// Retry on rate limits (429) or transient server errors (5xx).
+     * 		retryIf: r => r.status === 429 || r.status >= 500,
+     * 	})
+     * 	.then(console.log)
+     * ```
+     *
+     * @example
+     * #### Example: Polling (Retry until a condition is met)
+     * Keep retrying every minute until a product is back in stock.
+     * ```javascript
+     * import fetch from '@superutils/fetch'
+     *
+     * fetch
+     * 	.get('[DUMMYJSON-DOT-COM]/products/1', {
+     * 	  delay: 60_000, // Wait 1 minute between attempts
+     * 	  retry: 10, // Attempt up to 10 more times
+     * 	  retryIf: async (response) => {
+     * 	    if (!response?.ok) return true // Retry on network or server errors
+     *
+     * 		// Use response.clone() to avoid consuming the body stream used by the final result.
+     * 		const result = await response.clone().json()
+     *
+     * 		// Retry if the product is still NOT in stock
+     * 		return result?.availabilityStatus !== 'In Stock'
+     * 	  },
+     *
+     *    // Ensure the overall timeout accounts for the polling duration
+     * 	  timeout: 60_000 * 15
+     * 	})
+     * 	.then(product => console.log('Product is back in stock:', product))
+     * ```
+     */
     retryIf?: RetryIfFunc<Response>;
 };
 /**
@@ -487,6 +535,11 @@ type ClientData<FixedOptions> = ExtractAs<[FixedOptions]> extends FetchAs.json ?
  * which minimizes code repetition across your application. If a method is not specified during creation, the client
  * will default to `GET`.
  *
+ * **Option Priority:**
+ * 1. `fixedOptions`: Highest priority. Cannot be overridden by the caller.
+ * 2. `options`: Options passed during the specific call.
+ * 3. `commonOptions`: Default options set at creation time.
+ *
  * The returned client also includes a `.deferred()` method, providing the same debounce, throttle, and sequential
  * execution capabilities found in functions like `fetch.get.deferred()`.
  *

package/package.json

@@ -5,8 +5,8 @@
 	},
 	"description": "A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate.",
 	"dependencies": {
-		"@superutils/core": "^1.2.13",
-		"@superutils/promise": "^1.3.12"
+		"@superutils/core": "^1.2.15",
+		"@superutils/promise": "^1.3.14"
 	},
 	"files": [
 		"dist",
@@ -53,6 +53,6 @@
 	"module": "./dist/index.js",
 	"type": "module",
 	"types": "./dist/index.d.ts",
-	"version": "1.5.14",
-	"gitHead": "1661eeeed9d00cb6b960e76563cdd3cee2cac8a7"
+	"version": "1.5.16",
+	"gitHead": "7be3be6fb4a8cb1955ee5f704fc49bbb792bd961"
 }