feat: implement exponential backoff in retryOnTransientError

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

src/paths.d.mts

@@ -79,31 +79,32 @@ export function isTransientError(error: Error & { code?: string }): boolean
 export interface RetryOptions {
 	/** Number of retry attempts (default: 3) */
 	retries?: number
-	/** Delay between retries in milliseconds (default: 100) */
-	delayMs?: number
+	/** Initial delay in milliseconds, doubles on each retry (default: 100) */
+	initialDelayMs?: number
 }
 
 /**
- * Retries a function on transient filesystem errors.
+ * Retries a function on transient filesystem errors with exponential backoff.
  *
  * If the function throws a transient error (EAGAIN, EBUSY), it will be retried
- * up to the specified number of times with a delay between attempts.
+ * up to the specified number of times with exponentially increasing delays
+ * between attempts (e.g., 100ms, 200ms, 400ms).
  *
  * @template T - The return type of the function
  * @param fn - The function to execute
- * @param options - Retry options (retries, delayMs)
+ * @param options - Retry options (retries, initialDelayMs)
  * @returns The result of the function
  * @throws The last error if all retries fail
  *
  * @example
- * // Retry a file copy operation
+ * // Retry a file copy operation (delays: 100ms, 200ms, 400ms)
  * await retryOnTransientError(() => copyFileSync(src, dest))
  *
  * @example
- * // Custom retry options
+ * // Custom retry options (delays: 50ms, 100ms, 200ms, 400ms, 800ms)
  * await retryOnTransientError(
  *   () => unlinkSync(path),
- *   { retries: 5, delayMs: 200 }
+ *   { retries: 5, initialDelayMs: 50 }
  * )
  */
 export function retryOnTransientError<T>(

src/paths.mjs

@@ -121,30 +121,31 @@ function delay(ms) {
 }
 
 /**
- * Retries a function on transient filesystem errors.
+ * Retries a function on transient filesystem errors with exponential backoff.
  *
  * If the function throws a transient error (EAGAIN, EBUSY), it will be retried
- * up to the specified number of times with a delay between attempts.
+ * up to the specified number of times with exponentially increasing delays
+ * between attempts (e.g., 100ms, 200ms, 400ms).
  *
  * @template T
  * @param {() => T | Promise<T>} fn - The function to execute
- * @param {{ retries?: number, delayMs?: number }} [options] - Retry options
+ * @param {{ retries?: number, initialDelayMs?: number }} [options] - Retry options
  * @returns {Promise<T>} The result of the function
  * @throws {Error} The last error if all retries fail
  *
  * @example
- * // Retry a file copy operation
+ * // Retry a file copy operation (delays: 100ms, 200ms, 400ms)
  * await retryOnTransientError(() => copyFileSync(src, dest))
  *
  * @example
- * // Custom retry options
+ * // Custom retry options (delays: 50ms, 100ms, 200ms, 400ms, 800ms)
  * await retryOnTransientError(
  *   () => unlinkSync(path),
- *   { retries: 5, delayMs: 200 }
+ *   { retries: 5, initialDelayMs: 50 }
  * )
  */
 export async function retryOnTransientError(fn, options = {}) {
-	const { retries = 3, delayMs = 100 } = options
+	const { retries = 3, initialDelayMs = 100 } = options
 	let lastError
 
 	for (let attempt = 0; attempt <= retries; attempt++) {
@@ -159,8 +160,9 @@ export async function retryOnTransientError(fn, options = {}) {
 				throw err
 			}
 
-			// Wait before retrying
-			await delay(delayMs)
+			// Calculate exponential backoff delay: initialDelayMs * 2^attempt
+			const backoffDelay = initialDelayMs * 2 ** attempt
+			await delay(backoffDelay)
 		}
 	}
 

tests/paths.test.ts

@@ -355,26 +355,65 @@ describe("paths.mjs exports", () => {
 			expect(callCount).toBe(2)
 		})
 
-		it("should use default delay of 100ms", async () => {
+		it("should use exponential backoff with default initial delay of 100ms", async () => {
 			let callCount = 0
+			const timestamps: number[] = []
 			const start = Date.now()
 			await retryOnTransientError(
 				() => {
+					timestamps.push(Date.now() - start)
 					callCount++
-					if (callCount < 3) {
+					if (callCount < 4) {
 						const err = Object.assign(new Error("EAGAIN"), { code: "EAGAIN" })
 						throw err
 					}
 					return "success"
 				},
 				{ retries: 3 },
 			)
+			// 3 retries with exponential backoff: 100ms, 200ms, 400ms = 700ms total
 			const elapsed = Date.now() - start
-			// Should have at least 2 delays of ~100ms each
-			expect(elapsed).toBeGreaterThanOrEqual(150)
+			expect(elapsed).toBeGreaterThanOrEqual(600) // Allow some timing variance
+			expect(elapsed).toBeLessThan(1000) // Should not be too long
 		})
 
-		it("should respect custom delay option", async () => {
+		it("should double delay on each retry (exponential backoff)", async () => {
+			const delays: number[] = []
+			let lastTimestamp = Date.now()
+			let callCount = 0
+
+			await retryOnTransientError(
+				() => {
+					const now = Date.now()
+					if (callCount > 0) {
+						delays.push(now - lastTimestamp)
+					}
+					lastTimestamp = now
+					callCount++
+					if (callCount < 4) {
+						const err = Object.assign(new Error("EAGAIN"), { code: "EAGAIN" })
+						throw err
+					}
+					return "success"
+				},
+				{ retries: 3, initialDelayMs: 50 },
+			)
+
+			// With initialDelayMs=50, delays should be approximately: 50, 100, 200
+			expect(delays).toHaveLength(3)
+			// Verify each delay is approximately double the previous (with tolerance)
+			// First delay should be ~50ms
+			expect(delays[0]).toBeGreaterThanOrEqual(40)
+			expect(delays[0]).toBeLessThan(100)
+			// Second delay should be ~100ms (2x first)
+			expect(delays[1]).toBeGreaterThanOrEqual(80)
+			expect(delays[1]).toBeLessThan(180)
+			// Third delay should be ~200ms (2x second)
+			expect(delays[2]).toBeGreaterThanOrEqual(160)
+			expect(delays[2]).toBeLessThan(320)
+		})
+
+		it("should respect custom initialDelayMs option", async () => {
 			let callCount = 0
 			const start = Date.now()
 			await retryOnTransientError(
@@ -386,7 +425,7 @@ describe("paths.mjs exports", () => {
 					}
 					return "success"
 				},
-				{ delayMs: 50 },
+				{ initialDelayMs: 50 },
 			)
 			const elapsed = Date.now() - start
 			// Should have 1 delay of ~50ms