@ls-stack/utils 3.28.0 → 3.30.0

package/docs/retryOnError/-internal-.md

@@ -14,7 +14,7 @@
 type RetryOptions = object;
 ```
 
-Defined in: [packages/utils/src/retryOnError.ts:6](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L6)
+Defined in: [packages/utils/src/retryOnError.ts:7](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L7)
 
 Configuration options for retryOnError function.
 
@@ -26,7 +26,7 @@ Configuration options for retryOnError function.
 optional debugId: string;
 ```
 
-Defined in: [packages/utils/src/retryOnError.ts:15](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L15)
+Defined in: [packages/utils/src/retryOnError.ts:16](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L16)
 
 Optional ID for debug logging
 
@@ -36,17 +36,57 @@ Optional ID for debug logging
 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)
+Defined in: [packages/utils/src/retryOnError.ts:9](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L9)
 
 Delay between retries in milliseconds or function returning delay
 
+##### disableRetries?
+
+```ts
+optional disableRetries: boolean;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:18](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L18)
+
+Disable retries
+
+##### onRetry()?
+
+```ts
+optional onRetry: (error, lastAttempt) => void;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:20](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L20)
+
+Function to call when retry happens
+
+###### Parameters
+
+###### error
+
+`Error`
+
+###### lastAttempt
+
+###### duration
+
+`number`
+
+###### retry
+
+`number`
+
+###### Returns
+
+`void`
+
 ##### 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)
+Defined in: [packages/utils/src/retryOnError.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L11)
 
 Function to determine if retry should happen, receives error and duration of last attempt
 
@@ -54,7 +94,7 @@ Function to determine if retry should happen, receives error and duration of las
 
 ###### error
 
-`unknown`
+`Error`
 
 ###### lastAttempt
 

package/docs/retryOnError/README.md

@@ -23,7 +23,7 @@ function retryOnError<T>(
 originalMaxRetries): Promise<T>;
 ```
 
-Defined in: [packages/utils/src/retryOnError.ts:38](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L38)
+Defined in: [packages/utils/src/retryOnError.ts:46](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L46)
 
 Retries a function on error with configurable retry logic.
 
@@ -57,10 +57,14 @@ Configuration options
 
 `number` = `0`
 
+internal use only
+
 ##### originalMaxRetries
 
 `number` = `maxRetries`
 
+internal use only
+
 #### Returns
 
 `Promise`\<`T`\>
@@ -79,3 +83,86 @@ await retryOnError(
   { delayBetweenRetriesMs: 1000 }
 );
 ```
+
+***
+
+### retryResultOnError()
+
+```ts
+function retryResultOnError<T, E>(
+   fn, 
+   maxRetries, 
+   options, 
+   __retry, 
+__originalMaxRetries): Promise<Result<T, E>>;
+```
+
+Defined in: [packages/utils/src/retryOnError.ts:132](https://github.com/lucasols/utils/blob/main/packages/utils/src/retryOnError.ts#L132)
+
+Retries a result function on error with configurable retry logic.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### E
+
+`E` *extends* `ResultValidErrors`
+
+#### Parameters
+
+##### fn
+
+(`ctx`) => `Promise`\<`Result`\<`T`, `E`\>\>
+
+Function to retry that receives context with retry count
+
+##### maxRetries
+
+`number`
+
+Maximum number of retries
+
+##### options
+
+Configuration options
+
+###### debugId?
+
+`string`
+
+###### delayBetweenRetriesMs?
+
+`number` \| (`retry`) => `number`
+
+###### disableRetries?
+
+`boolean`
+
+###### onRetry?
+
+(`error`, `lastAttempt`) => `void`
+
+###### retryCondition?
+
+(`error`, `lastAttempt`) => `boolean`
+
+##### \_\_retry
+
+`number` = `0`
+
+internal use only
+
+##### \_\_originalMaxRetries
+
+`number` = `maxRetries`
+
+internal use only
+
+#### Returns
+
+`Promise`\<`Result`\<`T`, `E`\>\>
+
+Promise resolving to the function result or rejecting with the final error

package/lib/retryOnError.cjs

@@ -20,9 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/retryOnError.ts
 var retryOnError_exports = {};
 __export(retryOnError_exports, {
-  retryOnError: () => retryOnError
+  retryOnError: () => retryOnError,
+  retryResultOnError: () => retryResultOnError
 });
 module.exports = __toCommonJS(retryOnError_exports);
+var import_t_result = require("t-result");
 
 // src/sleep.ts
 function sleep(ms) {
@@ -31,7 +33,7 @@ function sleep(ms) {
 
 // src/retryOnError.ts
 async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMaxRetries = maxRetries) {
-  const { delayBetweenRetriesMs, retryCondition } = options;
+  const { delayBetweenRetriesMs, retryCondition, disableRetries, onRetry } = options;
   if (options.debugId) {
     if (retry > 0) {
       console.info(
@@ -43,11 +45,21 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMax
   try {
     return await fn({ retry });
   } catch (error) {
-    if (maxRetries > 0) {
+    if (maxRetries > 0 && !disableRetries) {
       const errorDuration = Date.now() - startTime;
-      const shouldRetry = retryCondition ? retryCondition(error, { duration: errorDuration, retry }) : true;
+      const normalizedError = (0, import_t_result.unknownToError)(error);
+      const shouldRetry = retryCondition ? retryCondition(normalizedError, {
+        duration: errorDuration,
+        retry
+      }) : true;
       if (!shouldRetry) {
-        throw error;
+        throw normalizedError;
+      }
+      if (onRetry) {
+        onRetry(normalizedError, {
+          duration: errorDuration,
+          retry
+        });
       }
       if (delayBetweenRetriesMs) {
         await sleep(
@@ -66,7 +78,53 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMax
     }
   }
 }
+async function retryResultOnError(fn, maxRetries, options = {}, __retry = 0, __originalMaxRetries = maxRetries) {
+  const { delayBetweenRetriesMs, retryCondition, onRetry } = options;
+  if (options.debugId) {
+    if (__retry > 0) {
+      console.info(
+        `Retrying ${options.debugId} (retry ${__retry}/${__originalMaxRetries}) after error`
+      );
+    }
+  }
+  const startTime = Date.now();
+  const result = await fn({ retry: __retry });
+  if (result.ok) {
+    return result;
+  }
+  if (maxRetries > 0 && !options.disableRetries) {
+    const errorDuration = Date.now() - startTime;
+    const shouldRetry = retryCondition ? retryCondition(result.error, {
+      duration: errorDuration,
+      retry: __retry
+    }) : true;
+    if (!shouldRetry) {
+      return result;
+    }
+    if (onRetry) {
+      onRetry(result.error, {
+        duration: errorDuration,
+        retry: __retry
+      });
+    }
+    if (delayBetweenRetriesMs) {
+      await sleep(
+        typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(__retry) : delayBetweenRetriesMs
+      );
+    }
+    return retryResultOnError(
+      fn,
+      maxRetries - 1,
+      options,
+      __retry + 1,
+      __originalMaxRetries
+    );
+  } else {
+    return result;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  retryOnError
+  retryOnError,
+  retryResultOnError
 });

package/lib/retryOnError.d.cts

@@ -1,3 +1,5 @@
+import { ResultValidErrors, Result } from 't-result';
+
 /**
  * Configuration options for retryOnError function.
  */
@@ -5,12 +7,19 @@ type RetryOptions = {
     /** Delay between retries in milliseconds or function returning delay */
     delayBetweenRetriesMs?: number | ((retry: number) => number);
     /** Function to determine if retry should happen, receives error and duration of last attempt */
-    retryCondition?: (error: unknown, lastAttempt: {
+    retryCondition?: (error: Error, lastAttempt: {
         duration: number;
         retry: number;
     }) => boolean;
     /** Optional ID for debug logging */
     debugId?: string;
+    /** Disable retries */
+    disableRetries?: boolean;
+    /** Function to call when retry happens */
+    onRetry?: (error: Error, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => void;
 };
 /**
  * Retries a function on error with configurable retry logic.
@@ -18,8 +27,8 @@ type RetryOptions = {
  * @param fn - Function to retry that receives context with retry count
  * @param maxRetries - Maximum number of retries
  * @param options - Configuration options
- * @param retry
- * @param originalMaxRetries
+ * @param retry - internal use only
+ * @param originalMaxRetries - internal use only
  * @returns Promise resolving to the function result or rejecting with the final error
  *
  * @example
@@ -36,5 +45,36 @@ declare function retryOnError<T>(fn: (ctx: {
     /** Current retry count, (0 for first attempt) */
     retry: number;
 }) => Promise<T>, maxRetries: number, options?: RetryOptions, retry?: number, originalMaxRetries?: number): Promise<T>;
+/**
+ * Retries a result 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 options.delayBetweenRetriesMs
+ * @param options.retryCondition
+ * @param options.debugId
+ * @param options.disableRetries
+ * @param options.onRetry
+ * @param __retry - internal use only
+ * @param __originalMaxRetries - internal use only
+ * @returns Promise resolving to the function result or rejecting with the final error
+ */
+declare function retryResultOnError<T, E extends ResultValidErrors>(fn: (ctx: {
+    /** Current retry count, (0 for first attempt) */
+    retry: number;
+}) => Promise<Result<T, E>>, maxRetries: number, options?: {
+    delayBetweenRetriesMs?: number | ((retry: number) => number);
+    retryCondition?: (error: E, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => boolean;
+    debugId?: string;
+    disableRetries?: boolean;
+    onRetry?: (error: E, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => void;
+}, __retry?: number, __originalMaxRetries?: number): Promise<Result<T, E>>;
 
-export { retryOnError };
+export { retryOnError, retryResultOnError };

package/lib/retryOnError.d.ts

@@ -1,3 +1,5 @@
+import { ResultValidErrors, Result } from 't-result';
+
 /**
  * Configuration options for retryOnError function.
  */
@@ -5,12 +7,19 @@ type RetryOptions = {
     /** Delay between retries in milliseconds or function returning delay */
     delayBetweenRetriesMs?: number | ((retry: number) => number);
     /** Function to determine if retry should happen, receives error and duration of last attempt */
-    retryCondition?: (error: unknown, lastAttempt: {
+    retryCondition?: (error: Error, lastAttempt: {
         duration: number;
         retry: number;
     }) => boolean;
     /** Optional ID for debug logging */
     debugId?: string;
+    /** Disable retries */
+    disableRetries?: boolean;
+    /** Function to call when retry happens */
+    onRetry?: (error: Error, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => void;
 };
 /**
  * Retries a function on error with configurable retry logic.
@@ -18,8 +27,8 @@ type RetryOptions = {
  * @param fn - Function to retry that receives context with retry count
  * @param maxRetries - Maximum number of retries
  * @param options - Configuration options
- * @param retry
- * @param originalMaxRetries
+ * @param retry - internal use only
+ * @param originalMaxRetries - internal use only
  * @returns Promise resolving to the function result or rejecting with the final error
  *
  * @example
@@ -36,5 +45,36 @@ declare function retryOnError<T>(fn: (ctx: {
     /** Current retry count, (0 for first attempt) */
     retry: number;
 }) => Promise<T>, maxRetries: number, options?: RetryOptions, retry?: number, originalMaxRetries?: number): Promise<T>;
+/**
+ * Retries a result 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 options.delayBetweenRetriesMs
+ * @param options.retryCondition
+ * @param options.debugId
+ * @param options.disableRetries
+ * @param options.onRetry
+ * @param __retry - internal use only
+ * @param __originalMaxRetries - internal use only
+ * @returns Promise resolving to the function result or rejecting with the final error
+ */
+declare function retryResultOnError<T, E extends ResultValidErrors>(fn: (ctx: {
+    /** Current retry count, (0 for first attempt) */
+    retry: number;
+}) => Promise<Result<T, E>>, maxRetries: number, options?: {
+    delayBetweenRetriesMs?: number | ((retry: number) => number);
+    retryCondition?: (error: E, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => boolean;
+    debugId?: string;
+    disableRetries?: boolean;
+    onRetry?: (error: E, lastAttempt: {
+        duration: number;
+        retry: number;
+    }) => void;
+}, __retry?: number, __originalMaxRetries?: number): Promise<Result<T, E>>;
 
-export { retryOnError };
+export { retryOnError, retryResultOnError };

package/lib/retryOnError.js

@@ -3,8 +3,9 @@ import {
 } from "./chunk-5DZT3Z5Z.js";
 
 // src/retryOnError.ts
+import { unknownToError } from "t-result";
 async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMaxRetries = maxRetries) {
-  const { delayBetweenRetriesMs, retryCondition } = options;
+  const { delayBetweenRetriesMs, retryCondition, disableRetries, onRetry } = options;
   if (options.debugId) {
     if (retry > 0) {
       console.info(
@@ -16,11 +17,21 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMax
   try {
     return await fn({ retry });
   } catch (error) {
-    if (maxRetries > 0) {
+    if (maxRetries > 0 && !disableRetries) {
       const errorDuration = Date.now() - startTime;
-      const shouldRetry = retryCondition ? retryCondition(error, { duration: errorDuration, retry }) : true;
+      const normalizedError = unknownToError(error);
+      const shouldRetry = retryCondition ? retryCondition(normalizedError, {
+        duration: errorDuration,
+        retry
+      }) : true;
       if (!shouldRetry) {
-        throw error;
+        throw normalizedError;
+      }
+      if (onRetry) {
+        onRetry(normalizedError, {
+          duration: errorDuration,
+          retry
+        });
       }
       if (delayBetweenRetriesMs) {
         await sleep(
@@ -39,6 +50,52 @@ async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMax
     }
   }
 }
+async function retryResultOnError(fn, maxRetries, options = {}, __retry = 0, __originalMaxRetries = maxRetries) {
+  const { delayBetweenRetriesMs, retryCondition, onRetry } = options;
+  if (options.debugId) {
+    if (__retry > 0) {
+      console.info(
+        `Retrying ${options.debugId} (retry ${__retry}/${__originalMaxRetries}) after error`
+      );
+    }
+  }
+  const startTime = Date.now();
+  const result = await fn({ retry: __retry });
+  if (result.ok) {
+    return result;
+  }
+  if (maxRetries > 0 && !options.disableRetries) {
+    const errorDuration = Date.now() - startTime;
+    const shouldRetry = retryCondition ? retryCondition(result.error, {
+      duration: errorDuration,
+      retry: __retry
+    }) : true;
+    if (!shouldRetry) {
+      return result;
+    }
+    if (onRetry) {
+      onRetry(result.error, {
+        duration: errorDuration,
+        retry: __retry
+      });
+    }
+    if (delayBetweenRetriesMs) {
+      await sleep(
+        typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(__retry) : delayBetweenRetriesMs
+      );
+    }
+    return retryResultOnError(
+      fn,
+      maxRetries - 1,
+      options,
+      __retry + 1,
+      __originalMaxRetries
+    );
+  } else {
+    return result;
+  }
+}
 export {
-  retryOnError
+  retryOnError,
+  retryResultOnError
 };

package/package.json

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