opticedge-cloud-utils 1.1.6 → 1.1.8

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './auth';
 export * from './env';
 export * from './parser';
 export * from './regex';
+export * from './retry';
 export * from './secrets';
 export * from './task';
 export * from './validator';

package/dist/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./auth"), exports);
 __exportStar(require("./env"), exports);
 __exportStar(require("./parser"), exports);
 __exportStar(require("./regex"), exports);
+__exportStar(require("./retry"), exports);
 __exportStar(require("./secrets"), exports);
 __exportStar(require("./task"), exports);
 __exportStar(require("./validator"), exports);

package/dist/retry.d.ts

@@ -0,0 +1,11 @@
+export type RetryOptions = {
+    retries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal | null;
+    isRetryable?: (err: any) => boolean;
+    onRetry?: (err: any, attempt: number, nextDelayMs: number) => void;
+};
+export declare function isRetryableDefault(err: any): boolean;
+export declare function retry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableDefault = isRetryableDefault;
+exports.retry = retry;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new Error('Aborted'));
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(t);
+            reject(new Error('Aborted'));
+        }
+        signal?.addEventListener('abort', onAbort);
+    });
+}
+function isRetryableDefault(err) {
+    if (!err)
+        return false;
+    // gRPC numeric code for UNAVAILABLE is 14
+    if (err?.code === 14 || err?.grpcCode === 14)
+        return true;
+    // Common Node network error codes
+    const syscode = String(err?.code ?? '').toLowerCase();
+    if (syscode === 'econnreset' ||
+        syscode === 'etimedout' ||
+        syscode === 'econnrefused' ||
+        syscode === 'enotfound' ||
+        syscode === 'enetunreach' ||
+        syscode === 'eai_again' ||
+        syscode === 'ehostunreach' ||
+        syscode === 'epipe') {
+        return true;
+    }
+    // HTTP/Fetch style errors (axios / fetch)
+    const status = err?.response?.status ?? err?.status;
+    if (typeof status === 'number') {
+        // retry on 429 (rate limit) and 5xx (server errors)
+        if (status === 429 || (status >= 500 && status < 600))
+            return true;
+    }
+    // Message-based heuristics: include variants like "timed out" as well as "timeout"
+    const msg = String(err?.message ?? '').toLowerCase();
+    // Check for common retryable phrases:
+    // - timeout, timed out, time out
+    // - temporary
+    // - unavailable
+    if (/(timeout|timed out|time out|temporary|unavailable)/.test(msg))
+        return true;
+    // Also accept explicit substrings for network-errno-like messages
+    if (msg.includes('econnreset') || msg.includes('etimedout'))
+        return true;
+    return false;
+}
+async function retry(fn, opts = {}) {
+    const retries = opts.retries ?? 4;
+    const base = opts.baseDelayMs ?? 200;
+    const max = opts.maxDelayMs ?? 5000;
+    const timeoutMs = opts.timeoutMs;
+    const signal = opts.signal ?? null;
+    const isRetryable = opts.isRetryable ?? isRetryableDefault;
+    const onRetry = opts.onRetry;
+    const start = Date.now();
+    let attempt = 0;
+    let lastErr;
+    /* eslint-disable no-constant-condition */
+    while (true) {
+        if (signal?.aborted)
+            throw new Error('Aborted');
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryable(err)) {
+                throw err;
+            }
+            if (attempt >= retries) {
+                break;
+            }
+            attempt++;
+            const exp = Math.min(max, base * Math.pow(2, attempt - 1));
+            const delay = Math.floor(Math.random() * exp);
+            if (typeof timeoutMs === 'number') {
+                const elapsed = Date.now() - start;
+                if (elapsed + delay > timeoutMs) {
+                    break;
+                }
+            }
+            try {
+                onRetry?.(err, attempt, delay);
+                /* eslint-disable @typescript-eslint/no-unused-vars */
+            }
+            catch (e) {
+                // ignore errors from onRetry
+            }
+            await sleep(delay, signal);
+        }
+    }
+    const finalErr = new Error(`Retry failed after ${attempt} retries: ${String(lastErr?.message ?? lastErr)}`);
+    finalErr.original = lastErr;
+    throw finalErr;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opticedge-cloud-utils",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Common utilities for cloud functions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './auth'
 export * from './env'
 export * from './parser'
 export * from './regex'
+export * from './retry'
 export * from './secrets'
 export * from './task'
 export * from './validator'

package/src/retry.ts

@@ -0,0 +1,129 @@
+// src/retry.ts
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type RetryOptions = {
+  retries?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  timeoutMs?: number
+  signal?: AbortSignal | null
+  isRetryable?: (err: any) => boolean
+  onRetry?: (err: any, attempt: number, nextDelayMs: number) => void
+}
+
+function sleep(ms: number, signal?: AbortSignal | null) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error('Aborted'))
+    const t = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    function onAbort() {
+      clearTimeout(t)
+      reject(new Error('Aborted'))
+    }
+    signal?.addEventListener('abort', onAbort)
+  })
+}
+
+export function isRetryableDefault(err: any): boolean {
+  if (!err) return false
+
+  // gRPC numeric code for UNAVAILABLE is 14
+  if (err?.code === 14 || err?.grpcCode === 14) return true
+
+  // Common Node network error codes
+  const syscode = String(err?.code ?? '').toLowerCase()
+  if (
+    syscode === 'econnreset' ||
+    syscode === 'etimedout' ||
+    syscode === 'econnrefused' ||
+    syscode === 'enotfound' ||
+    syscode === 'enetunreach' ||
+    syscode === 'eai_again' ||
+    syscode === 'ehostunreach' ||
+    syscode === 'epipe'
+  ) {
+    return true
+  }
+
+  // HTTP/Fetch style errors (axios / fetch)
+  const status = err?.response?.status ?? err?.status
+  if (typeof status === 'number') {
+    // retry on 429 (rate limit) and 5xx (server errors)
+    if (status === 429 || (status >= 500 && status < 600)) return true
+  }
+
+  // Message-based heuristics: include variants like "timed out" as well as "timeout"
+  const msg = String(err?.message ?? '').toLowerCase()
+
+  // Check for common retryable phrases:
+  // - timeout, timed out, time out
+  // - temporary
+  // - unavailable
+  if (/(timeout|timed out|time out|temporary|unavailable)/.test(msg)) return true
+
+  // Also accept explicit substrings for network-errno-like messages
+  if (msg.includes('econnreset') || msg.includes('etimedout')) return true
+
+  return false
+}
+
+export async function retry<T>(fn: () => Promise<T>, opts: RetryOptions = {}): Promise<T> {
+  const retries = opts.retries ?? 4
+  const base = opts.baseDelayMs ?? 200
+  const max = opts.maxDelayMs ?? 5000
+  const timeoutMs = opts.timeoutMs
+  const signal = opts.signal ?? null
+  const isRetryable = opts.isRetryable ?? isRetryableDefault
+  const onRetry = opts.onRetry
+
+  const start = Date.now()
+
+  let attempt = 0
+  let lastErr: any
+
+  /* eslint-disable no-constant-condition */
+  while (true) {
+    if (signal?.aborted) throw new Error('Aborted')
+
+    try {
+      return await fn()
+    } catch (err) {
+      lastErr = err
+
+      if (!isRetryable(err)) {
+        throw err
+      }
+
+      if (attempt >= retries) {
+        break
+      }
+
+      attempt++
+      const exp = Math.min(max, base * Math.pow(2, attempt - 1))
+      const delay = Math.floor(Math.random() * exp)
+
+      if (typeof timeoutMs === 'number') {
+        const elapsed = Date.now() - start
+        if (elapsed + delay > timeoutMs) {
+          break
+        }
+      }
+
+      try {
+        onRetry?.(err, attempt, delay)
+        /* eslint-disable @typescript-eslint/no-unused-vars */
+      } catch (e) {
+        // ignore errors from onRetry
+      }
+
+      await sleep(delay, signal)
+    }
+  }
+
+  const finalErr = new Error(
+    `Retry failed after ${attempt} retries: ${String(lastErr?.message ?? lastErr)}`
+  )
+  ;(finalErr as any).original = lastErr
+  throw finalErr
+}

package/tests/retry.test.ts

@@ -0,0 +1,298 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// tests/retry.test.ts
+import { retry, isRetryableDefault } from '../src'
+
+describe('isRetryableDefault', () => {
+  test('returns false for falsy errors (covers `if (!err) return false`)', () => {
+    expect(isRetryableDefault(null)).toBe(false)
+    expect(isRetryableDefault(undefined)).toBe(false)
+    // Also check a falsy-but-not-nullish value is handled (should coerce to false at top)
+    expect(isRetryableDefault(0 as unknown as any)).toBe(false)
+  })
+
+  test('returns false for an object with no retryable properties', () => {
+    expect(isRetryableDefault({})).toBe(false)
+    expect(isRetryableDefault({ foo: 'bar' })).toBe(false)
+  })
+
+  test('matches message containing "timeout" (case-insensitive)', () => {
+    expect(isRetryableDefault(new Error('Request timed out'))).toBe(true)
+    expect(isRetryableDefault(new Error('TIMEOUT occurred'))).toBe(true)
+    expect(isRetryableDefault({ message: 'this is a timeout error' })).toBe(true)
+  })
+
+  test('matches message containing "temporary"', () => {
+    expect(isRetryableDefault(new Error('Temporary failure contacting host'))).toBe(true)
+    expect(isRetryableDefault({ message: 'temporary issue' })).toBe(true)
+  })
+
+  test('matches message containing "unavailable"', () => {
+    expect(isRetryableDefault(new Error('Service Unavailable'))).toBe(true)
+    expect(isRetryableDefault({ message: 'unavailable resource' })).toBe(true)
+  })
+
+  test('matches message containing "econnreset" or "etimedout" (substrings, case-insensitive)', () => {
+    expect(isRetryableDefault(new Error('ECONNRESET by peer'))).toBe(true)
+    expect(isRetryableDefault(new Error('econnreset'))).toBe(true)
+    expect(isRetryableDefault(new Error('ETIMEDOUT waiting for response'))).toBe(true)
+    expect(isRetryableDefault({ message: 'some ETIMEDOUT occurred' })).toBe(true)
+  })
+
+  test('does not treat unrelated messages as retryable', () => {
+    expect(isRetryableDefault(new Error('Bad request'))).toBe(false)
+    expect(isRetryableDefault({ message: 'invalid parameter provided' })).toBe(false)
+  })
+
+  test('still returns true when message sits alongside other properties (defensive)', () => {
+    const errLike: any = {
+      code: undefined,
+      response: undefined,
+      message: 'temporary network hiccup'
+    }
+    expect(isRetryableDefault(errLike)).toBe(true)
+  })
+})
+
+describe('retry util', () => {
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  test('returns result when fn succeeds immediately', async () => {
+    const fn = jest.fn(async () => 'ok')
+    const res = await retry(fn, { retries: 3 })
+    expect(res).toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  test('retries on transient error and eventually succeeds; onRetry called expected times', async () => {
+    // fail twice with retryable error (gRPC code 14), then succeed
+    let calls = 0
+    const fn = jest.fn(async () => {
+      calls++
+      if (calls <= 2) {
+        const e: any = new Error('transient-gprc')
+        e.code = 14
+        throw e
+      }
+      return 'ok-after-retries'
+    })
+
+    const onRetry = jest.fn()
+    // Make delays zero by forcing Math.random to 0 so tests are deterministic and fast
+    const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(0)
+
+    const res = await retry(fn, { retries: 5, baseDelayMs: 10, onRetry })
+    expect(res).toBe('ok-after-retries')
+    expect(fn).toHaveBeenCalledTimes(3)
+    // onRetry called for the 2 transient failures
+    expect(onRetry).toHaveBeenCalledTimes(2)
+
+    mathSpy.mockRestore()
+  })
+
+  test('non-retryable error is rethrown immediately', async () => {
+    const fn = jest.fn(async () => {
+      const e = new Error('bad request')
+      // create non-retryable structure: status 400
+      ;(e as any).status = 400
+      throw e
+    })
+
+    await expect(retry(fn, { retries: 3 })).rejects.toThrow('bad request')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  test('exhausts retries and throws final error preserving original', async () => {
+    const original = new Error('permanent transient-like')
+    ;(original as any).code = 14 // make it retryable
+    const fn = jest.fn(async () => {
+      throw original
+    })
+
+    // make delays 0 to run fast
+    jest.spyOn(Math, 'random').mockReturnValue(0)
+
+    await expect(retry(fn, { retries: 2, baseDelayMs: 1 })).rejects.toHaveProperty(
+      'original',
+      original
+    )
+    // initial call + 2 retries = 3 attempts
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  test('isRetryableDefault recognizes common shapes', () => {
+    const e1: any = new Error('econnreset happened')
+    e1.code = 'ECONNRESET'
+    expect(isRetryableDefault(e1)).toBe(true)
+
+    const e2: any = new Error('http 500')
+    e2.response = { status: 500 }
+    expect(isRetryableDefault(e2)).toBe(true)
+
+    const e3: any = new Error('not retryable')
+    e3.status = 400
+    expect(isRetryableDefault(e3)).toBe(false)
+
+    const e4: any = new Error('gRPC unavailable')
+    e4.code = 14
+    expect(isRetryableDefault(e4)).toBe(true)
+  })
+
+  test('abort signal aborts immediately when already aborted', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const fn = jest.fn(async () => 'should-not-run')
+
+    await expect(retry(fn, { signal: controller.signal })).rejects.toThrow('Aborted')
+    // function should not be called at all because we check signal at loop start
+    expect(fn).toHaveBeenCalledTimes(0)
+  })
+
+  test('abort during wait causes rejection', async () => {
+    // Function will fail once (retryable), then retry -> sleep -> we abort during sleep.
+    let calls = 0
+    const fn = jest.fn(async () => {
+      calls++
+      if (calls === 1) {
+        const e: any = new Error('transient')
+        e.code = 14
+        throw e
+      }
+      return 'should-not-get-here'
+    })
+
+    // Make delay large so we can abort during sleep (but we will abort synchronously)
+    jest.spyOn(Math, 'random').mockReturnValue(1) // picks the max exp
+    const controller = new AbortController()
+
+    // Start the retry but abort immediately after allowing the utility to start.
+    // We do not await retry here yet; create a Promise and then abort and await
+    const p = retry(fn, { retries: 3, baseDelayMs: 200, signal: controller.signal })
+
+    // Abort immediately — this should cause the pending sleep to reject
+    controller.abort()
+
+    await expect(p).rejects.toThrow('Aborted')
+  })
+
+  test('abort during wait causes rejection and triggers onAbort (clears timeout)', async () => {
+    // Function will fail once (retryable), then retry -> sleep -> we abort during sleep.
+    let calls = 0
+    const fn = jest.fn(async () => {
+      calls++
+      if (calls === 1) {
+        const e: any = new Error('transient')
+        e.code = 14
+        throw e
+      }
+      return 'should-not-get-here'
+    })
+
+    // Make sure there is a non-zero delay so sleep schedules a timer
+    jest.spyOn(Math, 'random').mockReturnValue(0.5)
+    const controller = new AbortController()
+
+    // Start the retry (it will throw once, then call sleep)
+    const p = retry(fn, { retries: 3, baseDelayMs: 200, signal: controller.signal })
+
+    // Wait a tick so `sleep` has a chance to attach the abort listener and call setTimeout.
+    // Using setTimeout 0 (or small timeout) guarantees the timer and listener are attached.
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    // Now abort — this should call the onAbort handler inside sleep which clears the timeout
+    controller.abort()
+
+    await expect(p).rejects.toThrow('Aborted')
+
+    // restore mocks
+    ;(Math.random as jest.Mock).mockRestore()
+  })
+
+  test('respects timeoutMs and breaks before waiting (covers timeout check)', async () => {
+    // Make the wrapped fn throw a retryable error once
+    const original = new Error('transient-timeout')
+    ;(original as any).code = 14 // make it retryable via isRetryableDefault
+    const fn = jest.fn(async () => {
+      throw original
+    })
+
+    // Force Math.random to 1 so delay === exp (max for that attempt)
+    const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(1)
+
+    // Use a baseDelayMs larger than timeoutMs so elapsed + delay > timeoutMs triggers the "break"
+    await expect(
+      retry(fn, {
+        retries: 5,
+        baseDelayMs: 50, // exp for attempt 1 = 50
+        timeoutMs: 10 // 50 > 10 so we should break before sleeping
+      })
+    ).rejects.toHaveProperty('original', original)
+
+    // fn should only have been called once (no retry/sleep occurred)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    mathSpy.mockRestore()
+  })
+
+  test('omitted opts uses default retries and eventually succeeds', async () => {
+    // Fail twice with retryable error (gRPC code 14), then succeed
+    let calls = 0
+    const fn = jest.fn(async () => {
+      calls++
+      if (calls <= 2) {
+        const e: any = new Error('transient')
+        e.code = 14
+        throw e
+      }
+      return 'ok-defaults'
+    })
+
+    // Make delays deterministic & small (Math.random = 0 -> delay = 0)
+    jest.spyOn(Math, 'random').mockReturnValue(0)
+
+    const res = await retry(fn) // <- call WITHOUT opts to exercise default param
+    expect(res).toBe('ok-defaults')
+
+    // Called initial + 2 retries = 3 times
+    expect(fn).toHaveBeenCalledTimes(3)
+    ;(Math.random as jest.Mock).mockRestore()
+  })
+
+  test('omitted opts exhausts default retries (5 attempts total) and throws', async () => {
+    const original = new Error('always-transient')
+    ;(original as any).code = 14 // make it retryable
+    const fn = jest.fn(async () => {
+      throw original
+    })
+
+    // Make delays 0 so test runs fast
+    jest.spyOn(Math, 'random').mockReturnValue(0)
+
+    // Default retries is 4 -> total attempts = 5
+    await expect(retry(fn)).rejects.toHaveProperty('original', original)
+    expect(fn).toHaveBeenCalledTimes(5)
+    ;(Math.random as jest.Mock).mockRestore()
+  })
+
+  test('final error message falls back to String(lastErr) when lastErr.message is undefined', async () => {
+    // original is a plain object (no .message)
+    const original: any = { code: 14, detail: 'plain-object-no-message' }
+
+    const fn = jest.fn(async () => {
+      throw original // will be assigned to lastErr in retry()
+    })
+
+    // Make delays deterministic & fast
+    const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(0)
+
+    // retries = 1 -> attempt will be 1 in finalErr message
+    await expect(retry(fn, { retries: 1, baseDelayMs: 1 })).rejects.toMatchObject({
+      message: expect.stringContaining('[object Object]'),
+      // Ensure original error was preserved on the thrown final error
+      original
+    })
+
+    mathSpy.mockRestore()
+  })
+})