@sohanemon/utils 5.0.9 → 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/dist/functions/shield.js

@@ -1,4 +1,3 @@
-import { isSSR } from './utils';
 export function shield(operation) {
     if (operation instanceof Promise) {
         return operation
@@ -10,12 +9,7 @@ export function shield(operation) {
         return [null, data];
     }
     catch (error) {
-        if (isSSR) {
-            console.info(`🛡 [shield] ${operation.name} failed →`, error);
-        }
-        else {
-            console.info(`%c🛡 [shield] %c${operation.name}`, 'color:#f87171;font-weight:bold;', 'color:#aaa;', error);
-        }
+        console.log(`\x1b[31m🛡 [shield]\x1b[0m ${operation.name} failed →`, error);
         return [error, null];
     }
 }

package/dist/functions/utils.d.ts

@@ -86,10 +86,13 @@ export declare const svgToBase64: (str: string) => string;
 /**
  * Pauses execution for the specified time.
  *
+ * `signal` allows cancelling the sleep via AbortSignal.
+ *
  * @param time - Time in milliseconds to sleep (default is 1000ms)
- * @returns - A Promise that resolves after the specified time
+ * @param signal - Optional AbortSignal to cancel the sleep early
+ * @returns - A Promise that resolves after the specified time or when aborted
  */
-export declare const sleep: (time?: number) => Promise<unknown>;
+export declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
 type DebouncedFunction<F extends (...args: any[]) => any> = {
     (...args: Parameters<F>): ReturnType<F> | undefined;
     readonly isPending: boolean;

package/dist/functions/utils.js

@@ -158,10 +158,32 @@ export const svgToBase64 = (str) => isSSR ? Buffer.from(str).toString('base64')
 /**
  * Pauses execution for the specified time.
  *
+ * `signal` allows cancelling the sleep via AbortSignal.
+ *
  * @param time - Time in milliseconds to sleep (default is 1000ms)
- * @returns - A Promise that resolves after the specified time
+ * @param signal - Optional AbortSignal to cancel the sleep early
+ * @returns - A Promise that resolves after the specified time or when aborted
  */
-export const sleep = (time = 1000) => new Promise((resolve) => setTimeout(resolve, time));
+export const sleep = (time = 1000, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const id = setTimeout(() => {
+        cleanup();
+        resolve();
+    }, time);
+    function onAbort() {
+        clearTimeout(id);
+        cleanup();
+        resolve();
+    }
+    function cleanup() {
+        signal?.removeEventListener('abort', onAbort);
+    }
+    // only add listener if a signal was supplied
+    if (signal) {
+        signal.addEventListener('abort', onAbort, { once: true });
+    }
+});
 /**
  * Creates a debounced function that delays invoking the provided function until
  * after the specified `wait` time has elapsed since the last invocation.

package/package.json

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