From 531beb0bcad431a9ecf3a9c648a3bf568c9b0816 Mon Sep 17 00:00:00 2001
From: krutoo <dima.krutoo@yandex.ru>
Date: Fri, 1 Nov 2024 00:16:55 +0500
Subject: [PATCH] retry revision

- middleware/retry: RetryConfig renamed to RetryOptions
- response/dump: JSDoc enhanced
- readme updated
---
 README.md               | 42 +++++++++++++++++++++++++++++++++--------
 src/middleware/mod.ts   |  2 +-
 src/middleware/retry.ts |  7 ++++---
 src/response/dump.ts    |  7 ++++++-
 4 files changed, 45 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index d7e730c..281dbcb 100644
--- a/README.md
+++ b/README.md
@@ -157,14 +157,36 @@ const myFetch = configureFetch(
       token: '...',
 
       // Determines whether to add a header
-      filter: req => req.url.includes('/api/'),
-    })
-
+      filter: (req) => req.url.includes('/api/'),
+    }),
     // ...or like this
     jwt({
       // "token" can be function that should return string or null or Promise<string | null>
       token: () => getJwtFromSomewhere(),
-    })
+    }),
+  ),
+);
+```
+
+### `retry`
+
+Returns a middleware that will retry the request until either:
+
+- or the retries count is exceeded;
+- or until a successful response is received.
+
+```ts
+import { applyMiddleware, configureFetch } from '@krutoo/fetch-tools';
+import { retry } from '@krutoo/fetch-tools/middleware';
+
+const myFetch = configureFetch(
+  fetch,
+  applyMiddleware(
+    retry({
+      count: 5,
+      whenNotOk: true,
+      whenCatch: false,
+    }),
   ),
 );
 ```
@@ -310,8 +332,8 @@ his cookies in requests.
 
 In this case you can use just `defaultHeaders` middleware:
 
-```js
-import { configureFetch, applyMiddleware } from '@krutoo/fetch-tools';
+```ts
+import { applyMiddleware, configureFetch } from '@krutoo/fetch-tools';
 import { defaultHeaders } from '@krutoo/fetch-tools/middleware';
 
 // example of server handler
@@ -325,9 +347,13 @@ async function handler(request: Request) {
   );
 
   // this request will contain cookies from the incoming request
-  const orders = await myFetch('http://something.com/api/user/orders').then(res => res.json());
+  const orders = await myFetch('http://something.com/api/user/orders').then(
+    (res) => res.json(),
+  );
 
-  return new Response(JSON.stringify({ orders }), { 'content-type': 'application/json' });
+  return new Response(JSON.stringify({ orders }), {
+    'content-type': 'application/json',
+  });
 }
 ```
 
diff --git a/src/middleware/mod.ts b/src/middleware/mod.ts
index 4358417..25ae5fc 100644
--- a/src/middleware/mod.ts
+++ b/src/middleware/mod.ts
@@ -9,7 +9,7 @@ export {
   type LogHandlerFactory,
 } from './log.ts';
 
-export { retry, type RetryConfig } from './retry.ts';
+export { retry, type RetryOptions } from './retry.ts';
 
 export { validateStatus, type ValidateStatusOptions } from './validate-status.ts';
 
diff --git a/src/middleware/retry.ts b/src/middleware/retry.ts
index 95fdf78..9a9e73f 100644
--- a/src/middleware/retry.ts
+++ b/src/middleware/retry.ts
@@ -2,7 +2,7 @@ import type { Middleware } from '#fetch';
 import { dump } from '#response';
 
 /** Retry middleware config. */
-export interface RetryConfig {
+export interface RetryOptions {
   /** Retries count. */
   count?: number;
 
@@ -17,11 +17,12 @@ export interface RetryConfig {
  * Returns a middleware that will retry the request until either:
  * - or the retries count is exceeded;
  * - or until a successful response is received.
- * @param init Count or config.
+ * @param init Repeat count or options.
  * @returns Middleware.
+ * @todo Consider AbortSignal.
  */
 export function retry(
-  init: number | RetryConfig,
+  init: number | RetryOptions,
 ): Middleware {
   const { count = 1, whenNotOk = true, whenCatch = true } = typeof init === 'number'
     ? { count: init }
diff --git a/src/response/dump.ts b/src/response/dump.ts
index b77defa..14ecf3f 100644
--- a/src/response/dump.ts
+++ b/src/response/dump.ts
@@ -1,6 +1,11 @@
 /**
- * This function need for Node.js and undici.
+ * Calls cancel on response.body if it is present.
+ *
+ * This is need for Node.js and undici.
  * Details: https://github.com/nodejs/undici/discussions/2979#discussioncomment-8865341.
+ *
+ * This is also useful in Deno when you don't read the response body.
+ * For example in `deno test`.
  * @param response Response.
  */
 export async function dump(response: Response) {