@spoosh/plugin-retry 0.2.0 → 0.3.1

package/README.md

@@ -27,18 +27,59 @@ useRead((api) => api("posts").GET(), { retries: 5, retryDelay: 2000 });
 useRead((api) => api("posts").GET(), { retries: false });
 ```
 
+## Retry Behavior
+
+By default, the plugin retries on:
+
+- **Network errors** - Always retried (cannot be disabled via `shouldRetry`)
+- **Status codes** - `408`, `429`, `500`, `502`, `503`, `504`
+
+### Custom Retry Logic
+
+Use the `shouldRetry` callback for custom retry conditions:
+
+```typescript
+retryPlugin({
+  retries: 3,
+  shouldRetry: ({ status, error, attempt, maxRetries }) => {
+    // Only retry on 503 Service Unavailable
+    return status === 503;
+  },
+});
+
+// Per-request override
+useRead((api) => api("posts").GET(), {
+  shouldRetry: ({ status }) => status === 429,
+});
+```
+
+> **Note:** Network errors are always retried regardless of the `shouldRetry` callback return value.
+
 ## Options
 
 ### Plugin Config
 
-| Option       | Type              | Default | Description                                                  |
-| ------------ | ----------------- | ------- | ------------------------------------------------------------ |
-| `retries`    | `number \| false` | `3`     | Number of retry attempts. Set to `false` to disable retries. |
-| `retryDelay` | `number`          | `1000`  | Delay between retries in milliseconds                        |
+| Option        | Type                  | Default                                 | Description                                                      |
+| ------------- | --------------------- | --------------------------------------- | ---------------------------------------------------------------- |
+| `retries`     | `number \| false`     | `3`                                     | Number of retry attempts. Set to `false` to disable retries.     |
+| `retryDelay`  | `number`              | `1000`                                  | Delay between retries in milliseconds (uses exponential backoff) |
+| `shouldRetry` | `ShouldRetryCallback` | Retries on 408, 429, 500, 502, 503, 504 | Custom callback to determine if a request should be retried      |
 
 ### Per-Request Options
 
-| Option       | Type              | Description                              |
-| ------------ | ----------------- | ---------------------------------------- |
-| `retries`    | `number \| false` | Override retry attempts for this request |
-| `retryDelay` | `number`          | Override retry delay for this request    |
+| Option        | Type                  | Description                              |
+| ------------- | --------------------- | ---------------------------------------- |
+| `retries`     | `number \| false`     | Override retry attempts for this request |
+| `retryDelay`  | `number`              | Override retry delay for this request    |
+| `shouldRetry` | `ShouldRetryCallback` | Override retry logic for this request    |
+
+### ShouldRetryContext
+
+The `shouldRetry` callback receives a context object:
+
+| Property     | Type      | Description                          |
+| ------------ | --------- | ------------------------------------ |
+| `status`     | `number?` | HTTP status code from the response   |
+| `error`      | `unknown` | The error that occurred              |
+| `attempt`    | `number`  | Current attempt number (0-indexed)   |
+| `maxRetries` | `number`  | Maximum number of retries configured |

package/dist/index.d.mts

@@ -1,22 +1,62 @@
 import { SpooshPlugin } from '@spoosh/core';
 
+/**
+ * Context passed to the shouldRetry callback.
+ */
+interface ShouldRetryContext {
+    /** HTTP status code from the response, if available */
+    status?: number;
+    /** The error that occurred, if any */
+    error: unknown;
+    /** Current attempt number (0-indexed) */
+    attempt: number;
+    /** Maximum number of retries configured */
+    maxRetries: number;
+}
+/**
+ * Callback to determine if a request should be retried.
+ * Network errors are always retried regardless of this callback's return value.
+ *
+ * @returns `true` to retry, `false` to stop retrying
+ */
+type ShouldRetryCallback = (context: ShouldRetryContext) => boolean;
+/** Status codes that are retried by default: 408, 429, 500, 502, 503, 504 */
+declare const DEFAULT_RETRY_STATUS_CODES: readonly [408, 429, 500, 502, 503, 504];
 interface RetryPluginConfig {
     /** Number of retry attempts. Set to `false` to disable retries. Defaults to 3. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Defaults to 1000. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Defaults to retrying on status codes: 408, 429, 500, 502, 503, 504.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 interface RetryReadOptions {
     /** Number of retry attempts. Set to `false` to disable retries. Overrides plugin default. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Overrides plugin default. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Overrides plugin default.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 interface RetryWriteOptions {
     /** Number of retry attempts. Set to `false` to disable retries. Overrides plugin default. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Overrides plugin default. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Overrides plugin default.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 type RetryInfiniteReadOptions = RetryReadOptions;
 type RetryReadResult = object;
@@ -56,4 +96,4 @@ declare function retryPlugin(config?: RetryPluginConfig): SpooshPlugin<{
     writeResult: RetryWriteResult;
 }>;
 
-export { type RetryInfiniteReadOptions, type RetryPluginConfig, type RetryReadOptions, type RetryReadResult, type RetryWriteOptions, type RetryWriteResult, retryPlugin };
+export { DEFAULT_RETRY_STATUS_CODES, type RetryInfiniteReadOptions, type RetryPluginConfig, type RetryReadOptions, type RetryReadResult, type RetryWriteOptions, type RetryWriteResult, type ShouldRetryCallback, type ShouldRetryContext, retryPlugin };

package/dist/index.d.ts

@@ -1,22 +1,62 @@
 import { SpooshPlugin } from '@spoosh/core';
 
+/**
+ * Context passed to the shouldRetry callback.
+ */
+interface ShouldRetryContext {
+    /** HTTP status code from the response, if available */
+    status?: number;
+    /** The error that occurred, if any */
+    error: unknown;
+    /** Current attempt number (0-indexed) */
+    attempt: number;
+    /** Maximum number of retries configured */
+    maxRetries: number;
+}
+/**
+ * Callback to determine if a request should be retried.
+ * Network errors are always retried regardless of this callback's return value.
+ *
+ * @returns `true` to retry, `false` to stop retrying
+ */
+type ShouldRetryCallback = (context: ShouldRetryContext) => boolean;
+/** Status codes that are retried by default: 408, 429, 500, 502, 503, 504 */
+declare const DEFAULT_RETRY_STATUS_CODES: readonly [408, 429, 500, 502, 503, 504];
 interface RetryPluginConfig {
     /** Number of retry attempts. Set to `false` to disable retries. Defaults to 3. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Defaults to 1000. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Defaults to retrying on status codes: 408, 429, 500, 502, 503, 504.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 interface RetryReadOptions {
     /** Number of retry attempts. Set to `false` to disable retries. Overrides plugin default. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Overrides plugin default. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Overrides plugin default.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 interface RetryWriteOptions {
     /** Number of retry attempts. Set to `false` to disable retries. Overrides plugin default. */
     retries?: number | false;
     /** Delay between retries in milliseconds. Overrides plugin default. */
     retryDelay?: number;
+    /**
+     * Custom callback to determine if a request should be retried.
+     * Network errors are always retried regardless of this callback.
+     * Overrides plugin default.
+     */
+    shouldRetry?: ShouldRetryCallback;
 }
 type RetryInfiniteReadOptions = RetryReadOptions;
 type RetryReadResult = object;
@@ -56,4 +96,4 @@ declare function retryPlugin(config?: RetryPluginConfig): SpooshPlugin<{
     writeResult: RetryWriteResult;
 }>;
 
-export { type RetryInfiniteReadOptions, type RetryPluginConfig, type RetryReadOptions, type RetryReadResult, type RetryWriteOptions, type RetryWriteResult, retryPlugin };
+export { DEFAULT_RETRY_STATUS_CODES, type RetryInfiniteReadOptions, type RetryPluginConfig, type RetryReadOptions, type RetryReadResult, type RetryWriteOptions, type RetryWriteResult, type ShouldRetryCallback, type ShouldRetryContext, retryPlugin };

package/dist/index.js

@@ -20,81 +20,101 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DEFAULT_RETRY_STATUS_CODES: () => DEFAULT_RETRY_STATUS_CODES,
   retryPlugin: () => retryPlugin
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/plugin.ts
-var import_core = require("@spoosh/core");
-
-// src/cloneObject.ts
-function clone(value, seen = /* @__PURE__ */ new WeakMap()) {
-  if (value === void 0 || value === null || typeof value !== "object") {
-    return value;
-  }
-  if (seen.has(value)) {
-    return seen.get(value);
-  }
-  if (Array.isArray(value)) {
-    const arr = [];
-    seen.set(value, arr);
-    return value.map((v) => clone(v, seen));
-  }
-  if (value instanceof Date) {
-    return new Date(value.getTime());
-  }
-  if (value instanceof RegExp) {
-    return new RegExp(value.source, value.flags);
-  }
-  if (value.constructor !== Object) {
-    return value;
-  }
-  const obj = {};
-  seen.set(value, obj);
-  for (const key in value) {
-    if (Object.prototype.hasOwnProperty.call(value, key)) {
-      obj[key] = clone(value[key], seen);
-    }
-  }
-  return obj;
-}
+// src/types.ts
+var DEFAULT_RETRY_STATUS_CODES = [
+  408,
+  429,
+  500,
+  502,
+  503,
+  504
+];
 
 // src/plugin.ts
+var import_core = require("@spoosh/core");
+var PLUGIN_NAME = "spoosh:retry";
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultShouldRetry = ({ status }) => {
+  if (status === void 0) return false;
+  return DEFAULT_RETRY_STATUS_CODES.includes(status);
+};
 function retryPlugin(config = {}) {
-  const { retries: defaultRetries = 3, retryDelay: defaultRetryDelay = 1e3 } = config;
+  const {
+    retries: defaultRetries = 3,
+    retryDelay: defaultRetryDelay = 1e3,
+    shouldRetry: defaultShouldRetryFn = defaultShouldRetry
+  } = config;
   return {
-    name: "spoosh:retry",
+    name: PLUGIN_NAME,
     operations: ["read", "write", "infiniteRead"],
+    priority: 200,
     middleware: async (context, next) => {
+      const t = context.tracer?.(PLUGIN_NAME);
       const pluginOptions = context.pluginOptions;
       const retriesConfig = pluginOptions?.retries ?? defaultRetries;
       const retryDelayConfig = pluginOptions?.retryDelay ?? defaultRetryDelay;
+      const shouldRetryFn = pluginOptions?.shouldRetry ?? defaultShouldRetryFn;
       const maxRetries = retriesConfig === false ? 0 : retriesConfig;
       if (!maxRetries || maxRetries < 0) {
+        t?.skip("Disabled");
         return next();
       }
       const originalRequest = {
-        headers: clone(context.request.headers),
-        params: clone(context.request.params),
-        body: clone(context.request.body)
+        headers: (0, import_core.clone)(context.request.headers),
+        params: (0, import_core.clone)(context.request.params),
+        body: (0, import_core.clone)(context.request.body)
       };
       let res;
       for (let attempt = 0; attempt <= maxRetries; attempt++) {
         if (attempt > 0) {
-          context.request.headers = clone(originalRequest.headers);
-          context.request.params = clone(originalRequest.params);
-          context.request.body = clone(originalRequest.body);
+          context.request.headers = (0, import_core.clone)(originalRequest.headers);
+          context.request.params = (0, import_core.clone)(originalRequest.params);
+          context.request.body = (0, import_core.clone)(originalRequest.body);
+          t?.log(`Retry ${attempt}/${maxRetries}`, { color: "warning" });
         }
         res = await next();
         if ((0, import_core.isAbortError)(res.error)) {
+          t?.log("Aborted", { color: "muted" });
           return res;
         }
-        if ((0, import_core.isNetworkError)(res.error) && attempt < maxRetries) {
+        const isLastAttempt = attempt >= maxRetries;
+        if ((0, import_core.isNetworkError)(res.error)) {
+          if (isLastAttempt) {
+            t?.log("Max retries reached (network error)", { color: "error" });
+            return res;
+          }
           const delayMs = retryDelayConfig * Math.pow(2, attempt);
           await delay(delayMs);
           continue;
         }
+        if (res.error) {
+          const shouldRetryResult = shouldRetryFn({
+            status: res.status,
+            error: res.error,
+            attempt,
+            maxRetries
+          });
+          if (shouldRetryResult && !isLastAttempt) {
+            t?.log(`Status ${res.status} - will retry`, { color: "warning" });
+            const delayMs = retryDelayConfig * Math.pow(2, attempt);
+            await delay(delayMs);
+            continue;
+          }
+          if (attempt > 0) {
+            t?.log("Max retries reached or non-retryable error", {
+              color: "error"
+            });
+          }
+          return res;
+        }
+        if (attempt > 0) {
+          t?.log("Retry succeeded", { color: "success" });
+        }
         return res;
       }
       return res;

package/dist/index.mjs

@@ -1,51 +1,40 @@
-// src/plugin.ts
-import { isNetworkError, isAbortError } from "@spoosh/core";
-
-// src/cloneObject.ts
-function clone(value, seen = /* @__PURE__ */ new WeakMap()) {
-  if (value === void 0 || value === null || typeof value !== "object") {
-    return value;
-  }
-  if (seen.has(value)) {
-    return seen.get(value);
-  }
-  if (Array.isArray(value)) {
-    const arr = [];
-    seen.set(value, arr);
-    return value.map((v) => clone(v, seen));
-  }
-  if (value instanceof Date) {
-    return new Date(value.getTime());
-  }
-  if (value instanceof RegExp) {
-    return new RegExp(value.source, value.flags);
-  }
-  if (value.constructor !== Object) {
-    return value;
-  }
-  const obj = {};
-  seen.set(value, obj);
-  for (const key in value) {
-    if (Object.prototype.hasOwnProperty.call(value, key)) {
-      obj[key] = clone(value[key], seen);
-    }
-  }
-  return obj;
-}
+// src/types.ts
+var DEFAULT_RETRY_STATUS_CODES = [
+  408,
+  429,
+  500,
+  502,
+  503,
+  504
+];
 
 // src/plugin.ts
+import { isNetworkError, isAbortError, clone } from "@spoosh/core";
+var PLUGIN_NAME = "spoosh:retry";
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultShouldRetry = ({ status }) => {
+  if (status === void 0) return false;
+  return DEFAULT_RETRY_STATUS_CODES.includes(status);
+};
 function retryPlugin(config = {}) {
-  const { retries: defaultRetries = 3, retryDelay: defaultRetryDelay = 1e3 } = config;
+  const {
+    retries: defaultRetries = 3,
+    retryDelay: defaultRetryDelay = 1e3,
+    shouldRetry: defaultShouldRetryFn = defaultShouldRetry
+  } = config;
   return {
-    name: "spoosh:retry",
+    name: PLUGIN_NAME,
     operations: ["read", "write", "infiniteRead"],
+    priority: 200,
     middleware: async (context, next) => {
+      const t = context.tracer?.(PLUGIN_NAME);
       const pluginOptions = context.pluginOptions;
       const retriesConfig = pluginOptions?.retries ?? defaultRetries;
       const retryDelayConfig = pluginOptions?.retryDelay ?? defaultRetryDelay;
+      const shouldRetryFn = pluginOptions?.shouldRetry ?? defaultShouldRetryFn;
       const maxRetries = retriesConfig === false ? 0 : retriesConfig;
       if (!maxRetries || maxRetries < 0) {
+        t?.skip("Disabled");
         return next();
       }
       const originalRequest = {
@@ -59,16 +48,46 @@ function retryPlugin(config = {}) {
           context.request.headers = clone(originalRequest.headers);
           context.request.params = clone(originalRequest.params);
           context.request.body = clone(originalRequest.body);
+          t?.log(`Retry ${attempt}/${maxRetries}`, { color: "warning" });
         }
         res = await next();
         if (isAbortError(res.error)) {
+          t?.log("Aborted", { color: "muted" });
           return res;
         }
-        if (isNetworkError(res.error) && attempt < maxRetries) {
+        const isLastAttempt = attempt >= maxRetries;
+        if (isNetworkError(res.error)) {
+          if (isLastAttempt) {
+            t?.log("Max retries reached (network error)", { color: "error" });
+            return res;
+          }
           const delayMs = retryDelayConfig * Math.pow(2, attempt);
           await delay(delayMs);
           continue;
         }
+        if (res.error) {
+          const shouldRetryResult = shouldRetryFn({
+            status: res.status,
+            error: res.error,
+            attempt,
+            maxRetries
+          });
+          if (shouldRetryResult && !isLastAttempt) {
+            t?.log(`Status ${res.status} - will retry`, { color: "warning" });
+            const delayMs = retryDelayConfig * Math.pow(2, attempt);
+            await delay(delayMs);
+            continue;
+          }
+          if (attempt > 0) {
+            t?.log("Max retries reached or non-retryable error", {
+              color: "error"
+            });
+          }
+          return res;
+        }
+        if (attempt > 0) {
+          t?.log("Retry succeeded", { color: "success" });
+        }
         return res;
       }
       return res;
@@ -76,5 +95,6 @@ function retryPlugin(config = {}) {
   };
 }
 export {
+  DEFAULT_RETRY_STATUS_CODES,
   retryPlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/plugin-retry",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Automatic retry plugin for Spoosh with configurable attempts and delay",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,11 @@
     }
   },
   "peerDependencies": {
-    "@spoosh/core": ">=0.12.1"
+    "@spoosh/core": ">=0.13.0"
   },
   "devDependencies": {
-    "@spoosh/core": "0.12.1",
-    "@spoosh/test-utils": "0.1.8"
+    "@spoosh/core": "0.13.0",
+    "@spoosh/test-utils": "0.2.0"
   },
   "scripts": {
     "dev": "tsup --watch",