@futdevpro/fsm-dynamo 1.16.27 → 1.16.29

package/src/_collections/utils/async.util.ts

@@ -1,198 +1,198 @@
-import { Observable } from 'rxjs';
-import { second, hour, minute, week, day } from '../constants/times.const';
-import { DyFM_Time } from './time.util';
-import { DyFM_Log } from './log.util';
-
-
-export class DyFM_Async {
-    
-  /**
-   * delays the execution of a function
-   * @param ms 
-   * @returns 
-   * 
-   * @example
-   * ```ts
-   * await DyFM_Async.wait(1000);
-   * ```
-   */
-  static wait(ms: number): Promise<void> {
-    return new Promise((resolve): any => setTimeout(resolve, ms));
-  }
-  static readonly sleep: typeof this.wait = this.wait;
-  static readonly delay: typeof this.wait = this.wait;
-
-  /** 
-   * WARNING: This function is recommended to use ONLY for limited instances,
-   * because it can cause performance issues.
-   * 
-   * @example
-   * ```ts
-   * await DyFM_Async.waitUntil(() => check(), 100, 10000);
-   * ```
-   */
-  static waitUntil(
-    check: () => boolean, 
-    interval: number = 100,
-    timeout: number = 10_000
-  ): Promise<void> {
-    const timeoutError = new Error('waitUntil timeout');
-
-    return new Promise((resolve, reject): void => {
-      const startTime = Date.now();
-
-      const intervalId = setInterval((): void => {
-        if (check()) {
-          clearInterval(intervalId);
-          resolve();
-        } else if (Date.now() - startTime > timeout) {
-          clearInterval(intervalId);
-
-          reject(timeoutError);
-        }
-      }, interval);
-    });
-  }
-
-  /** 
-   * WARNING: This function is recommended to use ONLY for limited instances,
-   * because it can cause performance issues.
-   * 
-   * @example
-   * const result = await DyFM_Async.waitUntilAsync(
-   *   () => check(),
-   *   30 * second,
-   *   5 * minute,
-   * );
-   */
-  static waitUntilAsync(
-    check: () => Promise<boolean>, 
-    interval: number = 100,
-    timeout: number = 10000
-  ): Promise<void> {
-    const timeoutError = new Error('waitUntilAsync timeout');
-
-    return new Promise((resolve, reject): void => {
-      const startTime = Date.now();
-
-      const intervalId = setInterval(async (): Promise<void> => {
-        if (await check()) {
-          clearInterval(intervalId);
-          resolve();
-        } else if (Date.now() - startTime > timeout) {
-          clearInterval(intervalId);
-          
-          reject(timeoutError);
-        }
-      }, interval);
-    });
-  }
-
-  /**
-   * Creates a promise that resolves when the observable emits a value that passes the check function
-   * 
-   * @example
-   * ```ts
-   * const observable = new Observable<number>(observer => {
-   *   setInterval(() => observer.next(Math.random()), 100);
-   * });
-   * const result = await DyFM_Async.takeUntil(observable, (value?: number) => value && value > 0.5);
-   * ```
-   */
-  static takeUntil<T>(
-    observable: Observable<T>, 
-    check: (value?: T) => boolean
-  ): Promise<T> {
-    return new Promise((resolve): void => {
-      const sub = observable.subscribe(
-        (value?: T): void => {
-          if (check(value)) {
-            sub.unsubscribe();
-            resolve(value as T);
-          }
-        }
-      );
-    });
-  }
-
-  /**
-   * Waits for a given amount of time and logs the remaining time.
-   * @param totalWaitTimeMs - The total amount of time to wait.
-   * @param context - The context of the countdown.
-   * @returns A promise that resolves when the countdown is complete.
-   * 
-   * @example
-   * ```ts
-   * await DyFM_Async.waitWithCountdownLogging(1000, 'Countdown');
-   * ```
-   */
-  static async waitWithCountdownLogging(
-    totalWaitTimeMs: number,
-    context: string = 'Countdown'
-  ): Promise<void> {
-    const startTime = Date.now();
-    const endTime = startTime + totalWaitTimeMs;
-    
-    // Define logging intervals based on total duration
-    /**
-     * Gets the logging interval based on the total duration.
-     * @param totalMs - The total duration in milliseconds.
-     * @returns The logging interval in milliseconds.
-     * 
-     * @example
-     * ```ts
-     * const logInterval = getLogInterval(1000);
-     * console.log(logInterval); // 1000
-     * ```
-     */
-    const getLogInterval = (totalMs: number): number => {
-      const totalSeconds = totalMs / second;
-      const totalMinutes = totalSeconds / 60;
-      const totalHours = totalMinutes / 60;
-      const totalDays = totalHours / 24;
-      const totalWeeks = totalDays / 7;
-      
-      if (totalWeeks >= 4) return week; // Every week
-      if (totalDays >= 7) return day; // Every day
-      if (totalDays >= 3) return 12 * hour; // Every 12 hours
-      if (totalDays >= 1) return 6 * hour; // Every 6 hours
-      if (totalHours >= 12) return 3 * hour; // Every 3 hours
-      if (totalHours >= 6) return hour; // Every hour
-      if (totalHours >= 3) return 30 * minute; // Every 30 minutes
-      if (totalHours >= 1) return 10 * minute; // Every 10 minutes
-      if (totalMinutes >= 30) return 5 * minute; // Every 5 minutes
-      if (totalMinutes >= 10) return minute; // Every minute
-      if (totalMinutes >= 5) return 30 * second; // Every 30 seconds
-      if (totalMinutes >= 1) return 10 * second; // Every 10 seconds
-      if (totalSeconds >= 30) return 5 * second; // Every 5 seconds
-      return second; // Every second
-    };
-    
-    const logInterval = getLogInterval(totalWaitTimeMs);
-    let lastLogTime = startTime;
-    
-    // Format remaining time for display using DyFM_Time utility
-    const formatRemainingTime = (remainingMs: number): string => DyFM_Time.getTimeInShortestString(remainingMs) as string;
-    
-    // Log initial countdown start
-    DyFM_Log.info(`⏳ ${context} started - Total duration: ${formatRemainingTime(totalWaitTimeMs)}`);
-    
-    while (Date.now() < endTime) {
-      const now = Date.now();
-      const remainingMs = endTime - now;
-      
-      // Check if it's time to log
-      if (now - lastLogTime >= logInterval) {
-        const remainingTime = formatRemainingTime(remainingMs);
-        DyFM_Log.info(`⏳ ${context} - ${remainingTime} remaining`);
-        lastLogTime = now;
-      }
-      
-      // Wait for a short interval before checking again
-      await DyFM_Async.wait(Math.min(DyFM_Time.second, remainingMs));
-    }
-    
-    // Log completion
-    DyFM_Log.success(`✅ ${context} completed`);
-  }
+import { Observable } from 'rxjs';
+import { second, hour, minute, week, day } from '../constants/times.const';
+import { DyFM_Time } from './time.util';
+import { DyFM_Log } from './log.util';
+
+
+export class DyFM_Async {
+    
+  /**
+   * delays the execution of a function
+   * @param ms 
+   * @returns 
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.wait(1000);
+   * ```
+   */
+  static wait(ms: number): Promise<void> {
+    return new Promise((resolve): any => setTimeout(resolve, ms));
+  }
+  static readonly sleep: typeof this.wait = this.wait;
+  static readonly delay: typeof this.wait = this.wait;
+
+  /** 
+   * WARNING: This function is recommended to use ONLY for limited instances,
+   * because it can cause performance issues.
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.waitUntil(() => check(), 100, 10000);
+   * ```
+   */
+  static waitUntil(
+    check: () => boolean, 
+    interval: number = 100,
+    timeout: number = 10_000
+  ): Promise<void> {
+    const timeoutError = new Error('waitUntil timeout');
+
+    return new Promise((resolve, reject): void => {
+      const startTime = Date.now();
+
+      const intervalId = setInterval((): void => {
+        if (check()) {
+          clearInterval(intervalId);
+          resolve();
+        } else if (Date.now() - startTime > timeout) {
+          clearInterval(intervalId);
+
+          reject(timeoutError);
+        }
+      }, interval);
+    });
+  }
+
+  /** 
+   * WARNING: This function is recommended to use ONLY for limited instances,
+   * because it can cause performance issues.
+   * 
+   * @example
+   * const result = await DyFM_Async.waitUntilAsync(
+   *   () => check(),
+   *   30 * second,
+   *   5 * minute,
+   * );
+   */
+  static waitUntilAsync(
+    check: () => Promise<boolean>, 
+    interval: number = 100,
+    timeout: number = 10000
+  ): Promise<void> {
+    const timeoutError = new Error('waitUntilAsync timeout');
+
+    return new Promise((resolve, reject): void => {
+      const startTime = Date.now();
+
+      const intervalId = setInterval(async (): Promise<void> => {
+        if (await check()) {
+          clearInterval(intervalId);
+          resolve();
+        } else if (Date.now() - startTime > timeout) {
+          clearInterval(intervalId);
+          
+          reject(timeoutError);
+        }
+      }, interval);
+    });
+  }
+
+  /**
+   * Creates a promise that resolves when the observable emits a value that passes the check function
+   * 
+   * @example
+   * ```ts
+   * const observable = new Observable<number>(observer => {
+   *   setInterval(() => observer.next(Math.random()), 100);
+   * });
+   * const result = await DyFM_Async.takeUntil(observable, (value?: number) => value && value > 0.5);
+   * ```
+   */
+  static takeUntil<T>(
+    observable: Observable<T>, 
+    check: (value?: T) => boolean
+  ): Promise<T> {
+    return new Promise((resolve): void => {
+      const sub = observable.subscribe(
+        (value?: T): void => {
+          if (check(value)) {
+            sub.unsubscribe();
+            resolve(value as T);
+          }
+        }
+      );
+    });
+  }
+
+  /**
+   * Waits for a given amount of time and logs the remaining time.
+   * @param totalWaitTimeMs - The total amount of time to wait.
+   * @param context - The context of the countdown.
+   * @returns A promise that resolves when the countdown is complete.
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.waitWithCountdownLogging(1000, 'Countdown');
+   * ```
+   */
+  static async waitWithCountdownLogging(
+    totalWaitTimeMs: number,
+    context: string = 'Countdown'
+  ): Promise<void> {
+    const startTime = Date.now();
+    const endTime = startTime + totalWaitTimeMs;
+    
+    // Define logging intervals based on total duration
+    /**
+     * Gets the logging interval based on the total duration.
+     * @param totalMs - The total duration in milliseconds.
+     * @returns The logging interval in milliseconds.
+     * 
+     * @example
+     * ```ts
+     * const logInterval = getLogInterval(1000);
+     * console.log(logInterval); // 1000
+     * ```
+     */
+    const getLogInterval = (totalMs: number): number => {
+      const totalSeconds = totalMs / second;
+      const totalMinutes = totalSeconds / 60;
+      const totalHours = totalMinutes / 60;
+      const totalDays = totalHours / 24;
+      const totalWeeks = totalDays / 7;
+      
+      if (totalWeeks >= 4) return week; // Every week
+      if (totalDays >= 7) return day; // Every day
+      if (totalDays >= 3) return 12 * hour; // Every 12 hours
+      if (totalDays >= 1) return 6 * hour; // Every 6 hours
+      if (totalHours >= 12) return 3 * hour; // Every 3 hours
+      if (totalHours >= 6) return hour; // Every hour
+      if (totalHours >= 3) return 30 * minute; // Every 30 minutes
+      if (totalHours >= 1) return 10 * minute; // Every 10 minutes
+      if (totalMinutes >= 30) return 5 * minute; // Every 5 minutes
+      if (totalMinutes >= 10) return minute; // Every minute
+      if (totalMinutes >= 5) return 30 * second; // Every 30 seconds
+      if (totalMinutes >= 1) return 10 * second; // Every 10 seconds
+      if (totalSeconds >= 30) return 5 * second; // Every 5 seconds
+      return second; // Every second
+    };
+    
+    const logInterval = getLogInterval(totalWaitTimeMs);
+    let lastLogTime = startTime;
+    
+    // Format remaining time for display using DyFM_Time utility
+    const formatRemainingTime = (remainingMs: number): string => DyFM_Time.getTimeInShortestString(remainingMs) as string;
+    
+    // Log initial countdown start
+    DyFM_Log.info(`⏳ ${context} started - Total duration: ${formatRemainingTime(totalWaitTimeMs)}`);
+    
+    while (Date.now() < endTime) {
+      const now = Date.now();
+      const remainingMs = endTime - now;
+      
+      // Check if it's time to log
+      if (now - lastLogTime >= logInterval) {
+        const remainingTime = formatRemainingTime(remainingMs);
+        DyFM_Log.info(`⏳ ${context} - ${remainingTime} remaining`);
+        lastLogTime = now;
+      }
+      
+      // Wait for a short interval before checking again
+      await DyFM_Async.wait(Math.min(DyFM_Time.second, remainingMs));
+    }
+    
+    // Log completion
+    DyFM_Log.success(`✅ ${context} completed`);
+  }
 }