@sohanemon/utils 5.1.0 → 5.1.1

package/dist/functions/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cookie';
 export * from './object';
 export * from './shield';
+export * from './poll';
 export * from './utils';

package/dist/functions/index.js

@@ -1,4 +1,5 @@
 export * from './cookie';
 export * from './object';
 export * from './shield';
+export * from './poll';
 export * from './utils';

package/dist/functions/poll.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
+ * or until the operation times out or is aborted.
+ *
+ * Designed for waiting on async jobs, external state, or delayed availability.
+ *
+ * @template T The type of the successful result.
+ *
+ * @param cond
+ * A function returning a Promise that resolves to:
+ *   - a truthy value `T` → stop polling and return it
+ *   - falsy/null/undefined → continue polling
+ *
+ * @param options
+ * Configuration options:
+ * - `interval` (number) — Time between polls in ms (default: 5000 ms)
+ * - `timeout` (number) — Max total duration before failing (default: 5 min)
+ * - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
+ * - `signal` (AbortSignal) — Optional abort signal to cancel polling
+ *
+ * @returns
+ * Resolves with the truthy value `T` when successful.
+ * Throws `AbortError` if aborted
+ *
+ * @example
+ * ```ts
+ * const job = await poll(async () => {
+ *   const status = await getJobStatus();
+ *   return status === 'done' ? status : null;
+ * }, { interval: 3000, timeout: 60000 });
+ * ```
+ */
+export declare function poll<T>(cond: () => Promise<T | null | false | undefined>, { interval, timeout, jitter, signal, }?: Partial<{
+    interval: number;
+    timeout: number;
+    signal: AbortSignal;
+    jitter: boolean;
+}>): Promise<T>;

package/dist/functions/poll.js

@@ -0,0 +1,66 @@
+import { sleep } from './utils';
+/**
+ * Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
+ * or until the operation times out or is aborted.
+ *
+ * Designed for waiting on async jobs, external state, or delayed availability.
+ *
+ * @template T The type of the successful result.
+ *
+ * @param cond
+ * A function returning a Promise that resolves to:
+ *   - a truthy value `T` → stop polling and return it
+ *   - falsy/null/undefined → continue polling
+ *
+ * @param options
+ * Configuration options:
+ * - `interval` (number) — Time between polls in ms (default: 5000 ms)
+ * - `timeout` (number) — Max total duration before failing (default: 5 min)
+ * - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
+ * - `signal` (AbortSignal) — Optional abort signal to cancel polling
+ *
+ * @returns
+ * Resolves with the truthy value `T` when successful.
+ * Throws `AbortError` if aborted
+ *
+ * @example
+ * ```ts
+ * const job = await poll(async () => {
+ *   const status = await getJobStatus();
+ *   return status === 'done' ? status : null;
+ * }, { interval: 3000, timeout: 60000 });
+ * ```
+ */
+export async function poll(cond, { interval = 5000, timeout = 5 * 60 * 1000, jitter = true, signal, } = {}) {
+    const start = Date.now();
+    let aborted = signal?.aborted ?? false;
+    // fast listener (avoids repeated property lookups)
+    const abortListener = () => {
+        aborted = true;
+    };
+    signal?.addEventListener('abort', abortListener, { once: true });
+    try {
+        for (let attempt = 0;; attempt++) {
+            // fast exit check
+            if (aborted)
+                throw new Error('Polling aborted');
+            const result = await cond();
+            if (result)
+                return result;
+            const elapsed = Date.now() - start;
+            if (elapsed >= timeout)
+                throw new Error('Polling timed out', {
+                    cause: `Polling timed out after ${timeout}ms`,
+                });
+            // add jitter (±10%) for anti-sync
+            const delay = jitter
+                ? interval + (Math.random() - 0.5) * interval * 0.2
+                : interval;
+            await sleep(delay, signal);
+        }
+    }
+    finally {
+        // cleanup to avoid leaks
+        signal?.removeEventListener('abort', abortListener);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",