@ls-stack/utils 3.20.0 → 3.21.0

package/docs/_media/modules.md

@@ -32,7 +32,7 @@
 - [objUtils](objUtils.md)
 - [parallelAsyncCalls](parallelAsyncCalls/README.md)
 - [promiseUtils](promiseUtils/README.md)
-- [retryOnError](retryOnError.md)
+- [retryOnError](retryOnError/README.md)
 - [runShellCmd](runShellCmd/README.md)
 - [safeJson](safeJson.md)
 - [saferTyping](saferTyping.md)

package/docs/modules.md

@@ -32,7 +32,7 @@
 - [objUtils](objUtils.md)
 - [parallelAsyncCalls](parallelAsyncCalls/README.md)
 - [promiseUtils](promiseUtils/README.md)
-- [retryOnError](retryOnError.md)
+- [retryOnError](retryOnError/README.md)
 - [runShellCmd](runShellCmd/README.md)
 - [safeJson](safeJson.md)
 - [saferTyping](saferTyping.md)

package/docs/retryOnError/-internal-.md

@@ -0,0 +1,71 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [retryOnError](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### RetryOptions
+
+```ts
+type RetryOptions = object;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:6](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L6)
+
+Configuration options for retryOnError function.
+
+#### Properties
+
+##### debugId?
+
+```ts
+optional debugId: string;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:15](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L15)
+
+Optional ID for debug logging
+
+##### delayBetweenRetriesMs?
+
+```ts
+optional delayBetweenRetriesMs: number | (retry) => number;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:8](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L8)
+
+Delay between retries in milliseconds or function returning delay
+
+##### retryCondition()?
+
+```ts
+optional retryCondition: (error, lastAttempt) => boolean;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L10)
+
+Function to determine if retry should happen, receives error and duration of last attempt
+
+###### Parameters
+
+###### error
+
+`unknown`
+
+###### lastAttempt
+
+###### duration
+
+`number`
+
+###### retry
+
+`number`
+
+###### Returns
+
+`boolean`

package/docs/retryOnError/README.md

@@ -0,0 +1,85 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / retryOnError
+
+# retryOnError
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Functions
+
+### retryOnError()
+
+```ts
+function retryOnError<T>(
+   fn, 
+   maxRetries, 
+   options, 
+   retry, 
+originalMaxRetries): Promise<T>;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:38](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L38)
+
+Retries a function on error with configurable retry logic.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### fn
+
+(`ctx`) => `Promise`\<`T`\>
+
+Function to retry that receives context with retry count
+
+##### maxRetries
+
+`number`
+
+Maximum number of retries
+
+##### options
+
+[`RetryOptions`](-internal-.md#retryoptions) = `{}`
+
+Configuration options
+
+##### retry
+
+`number` = `0`
+
+Internal parameter tracking current retry count
+
+##### originalMaxRetries
+
+`number` = `maxRetries`
+
+Internal parameter tracking original max retries for logging
+
+#### Returns
+
+`Promise`\<`T`\>
+
+Promise resolving to the function result or rejecting with the final error
+
+#### Example
+
+```ts
+await retryOnError(
+  async (ctx) => {
+    console.log(`Attempt ${ctx.retry + 1}`);
+    return await fetchData();
+  },
+  3,
+  { delayBetweenRetriesMs: 1000 }
+);
+```

package/lib/retryOnError.cjs

@@ -30,33 +30,23 @@ function sleep(ms) {
 }
 
 // src/retryOnError.ts
-async function retryOnError(fn, maxRetries, options = {}, retry = 0) {
-  const {
-    delayBetweenRetriesMs,
-    retryCondition,
-    maxErrorDurationMs = 400
-  } = options;
+async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMaxRetries = maxRetries) {
+  const { delayBetweenRetriesMs, retryCondition } = options;
   if (options.debugId) {
     if (retry > 0) {
       console.info(
-        `Retrying ${options.debugId} (retry ${retry}/${maxRetries}) after error`
+        `Retrying ${options.debugId} (retry ${retry}/${originalMaxRetries}) after error`
       );
     }
   }
   const startTime = Date.now();
   try {
-    return await fn();
+    return await fn({ retry });
   } catch (error) {
     if (maxRetries > 0) {
       const errorDuration = Date.now() - startTime;
-      const shouldRetry = retryCondition ? retryCondition(error) : true;
-      let maxErrorDurationMsToUse = maxErrorDurationMs;
-      if (typeof shouldRetry === "boolean") {
-        if (!shouldRetry) throw error;
-      } else {
-        maxErrorDurationMsToUse = shouldRetry.maxErrorDurationMs;
-      }
-      if (errorDuration > maxErrorDurationMsToUse) {
+      const shouldRetry = retryCondition ? retryCondition(error, { duration: errorDuration, retry }) : true;
+      if (!shouldRetry) {
         throw error;
       }
       if (delayBetweenRetriesMs) {
@@ -64,7 +54,7 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0) {
           typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(retry) : delayBetweenRetriesMs
         );
       }
-      return retryOnError(fn, maxRetries - 1, options, retry + 1);
+      return retryOnError(fn, maxRetries - 1, options, retry + 1, originalMaxRetries);
     } else {
       throw error;
     }

package/lib/retryOnError.d.cts

@@ -1,10 +1,39 @@
-declare function retryOnError<T>(fn: () => Promise<T>, maxRetries: number, options?: {
+/**
+ * Configuration options for retryOnError function.
+ */
+type RetryOptions = {
+    /** Delay between retries in milliseconds or function returning delay */
     delayBetweenRetriesMs?: number | ((retry: number) => number);
-    retryCondition?: (error: unknown) => boolean | {
-        maxErrorDurationMs: number;
-    };
-    maxErrorDurationMs?: number;
+    /** Function to determine if retry should happen, receives error and duration of last attempt */
+    retryCondition?: (error: unknown, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => boolean;
+    /** Optional ID for debug logging */
     debugId?: string;
-}, retry?: number): Promise<T>;
+};
+/**
+ * Retries a function on error with configurable retry logic.
+ *
+ * @param fn - Function to retry that receives context with retry count
+ * @param maxRetries - Maximum number of retries
+ * @param options - Configuration options
+ * @param retry - Internal parameter tracking current retry count
+ * @param originalMaxRetries - Internal parameter tracking original max retries for logging
+ * @returns Promise resolving to the function result or rejecting with the final error
+ *
+ * @example
+ * await retryOnError(
+ *   async (ctx) => {
+ *     console.log(`Attempt ${ctx.retry + 1}`);
+ *     return await fetchData();
+ *   },
+ *   3,
+ *   { delayBetweenRetriesMs: 1000 }
+ * );
+ */
+declare function retryOnError<T>(fn: (ctx: {
+    retry: number;
+}) => Promise<T>, maxRetries: number, options?: RetryOptions, retry?: number, originalMaxRetries?: number): Promise<T>;
 
 export { retryOnError };

package/lib/retryOnError.d.ts

@@ -1,10 +1,39 @@
-declare function retryOnError<T>(fn: () => Promise<T>, maxRetries: number, options?: {
+/**
+ * Configuration options for retryOnError function.
+ */
+type RetryOptions = {
+    /** Delay between retries in milliseconds or function returning delay */
     delayBetweenRetriesMs?: number | ((retry: number) => number);
-    retryCondition?: (error: unknown) => boolean | {
-        maxErrorDurationMs: number;
-    };
-    maxErrorDurationMs?: number;
+    /** Function to determine if retry should happen, receives error and duration of last attempt */
+    retryCondition?: (error: unknown, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => boolean;
+    /** Optional ID for debug logging */
     debugId?: string;
-}, retry?: number): Promise<T>;
+};
+/**
+ * Retries a function on error with configurable retry logic.
+ *
+ * @param fn - Function to retry that receives context with retry count
+ * @param maxRetries - Maximum number of retries
+ * @param options - Configuration options
+ * @param retry - Internal parameter tracking current retry count
+ * @param originalMaxRetries - Internal parameter tracking original max retries for logging
+ * @returns Promise resolving to the function result or rejecting with the final error
+ *
+ * @example
+ * await retryOnError(
+ *   async (ctx) => {
+ *     console.log(`Attempt ${ctx.retry + 1}`);
+ *     return await fetchData();
+ *   },
+ *   3,
+ *   { delayBetweenRetriesMs: 1000 }
+ * );
+ */
+declare function retryOnError<T>(fn: (ctx: {
+    retry: number;
+}) => Promise<T>, maxRetries: number, options?: RetryOptions, retry?: number, originalMaxRetries?: number): Promise<T>;
 
 export { retryOnError };

package/lib/retryOnError.js

@@ -3,33 +3,23 @@ import {
 } from "./chunk-5DZT3Z5Z.js";
 
 // src/retryOnError.ts
-async function retryOnError(fn, maxRetries, options = {}, retry = 0) {
-  const {
-    delayBetweenRetriesMs,
-    retryCondition,
-    maxErrorDurationMs = 400
-  } = options;
+async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMaxRetries = maxRetries) {
+  const { delayBetweenRetriesMs, retryCondition } = options;
   if (options.debugId) {
     if (retry > 0) {
       console.info(
-        `Retrying ${options.debugId} (retry ${retry}/${maxRetries}) after error`
+        `Retrying ${options.debugId} (retry ${retry}/${originalMaxRetries}) after error`
       );
     }
   }
   const startTime = Date.now();
   try {
-    return await fn();
+    return await fn({ retry });
   } catch (error) {
     if (maxRetries > 0) {
       const errorDuration = Date.now() - startTime;
-      const shouldRetry = retryCondition ? retryCondition(error) : true;
-      let maxErrorDurationMsToUse = maxErrorDurationMs;
-      if (typeof shouldRetry === "boolean") {
-        if (!shouldRetry) throw error;
-      } else {
-        maxErrorDurationMsToUse = shouldRetry.maxErrorDurationMs;
-      }
-      if (errorDuration > maxErrorDurationMsToUse) {
+      const shouldRetry = retryCondition ? retryCondition(error, { duration: errorDuration, retry }) : true;
+      if (!shouldRetry) {
         throw error;
       }
       if (delayBetweenRetriesMs) {
@@ -37,7 +27,7 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0) {
           typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(retry) : delayBetweenRetriesMs
         );
       }
-      return retryOnError(fn, maxRetries - 1, options, retry + 1);
+      return retryOnError(fn, maxRetries - 1, options, retry + 1, originalMaxRetries);
     } else {
       throw error;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "license": "MIT",
   "files": [
     "lib",

package/docs/retryOnError.md

@@ -1,67 +0,0 @@
-[**@ls-stack/utils**](README.md)
-
-***
-
-[@ls-stack/utils](modules.md) / retryOnError
-
-# retryOnError
-
-## Functions
-
-### retryOnError()
-
-```ts
-function retryOnError<T>(
-   fn, 
-   maxRetries, 
-   options, 
-retry): Promise<T>;
-```
-
-Defined in: [packages/utils/src/retryOnError.ts:3](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L3)
-
-#### Type Parameters
-
-##### T
-
-`T`
-
-#### Parameters
-
-##### fn
-
-() => `Promise`\<`T`\>
-
-##### maxRetries
-
-`number`
-
-##### options
-
-###### debugId?
-
-`string`
-
-###### delayBetweenRetriesMs?
-
-`number` \| (`retry`) => `number`
-
-###### maxErrorDurationMs?
-
-`number`
-
-###### retryCondition?
-
-(`error`) => 
-  \| `boolean`
-  \| \{
-  `maxErrorDurationMs`: `number`;
-\}
-
-##### retry
-
-`number` = `0`
-
-#### Returns
-
-`Promise`\<`T`\>