@talex-touch/utils 1.0.30 → 1.0.32

package/common/utils/task-queue.ts

@@ -36,8 +36,9 @@ export interface AdaptiveTaskQueueOptions {
 const DEFAULT_YIELD_INTERVAL_MS = 17
 
 async function delay(ms: number): Promise<void> {
-  if (ms <= 0) return
-  await new Promise<void>((resolve) => setTimeout(resolve, ms))
+  if (ms <= 0)
+    return
+  await new Promise<void>(resolve => setTimeout(resolve, ms))
 }
 
 /**
@@ -50,10 +51,11 @@ async function delay(ms: number): Promise<void> {
 export async function runAdaptiveTaskQueue<T>(
   items: readonly T[],
   handler: (item: T, index: number) => Promise<void> | void,
-  options: AdaptiveTaskQueueOptions = {}
+  options: AdaptiveTaskQueueOptions = {},
 ): Promise<void> {
   const total = items.length
-  if (total === 0) return
+  if (total === 0)
+    return
 
   const {
     estimatedTaskTimeMs = 1,
@@ -61,7 +63,7 @@ export async function runAdaptiveTaskQueue<T>(
     maxBatchSize,
     logger = console,
     label = 'AdaptiveTaskQueue',
-    onYield
+    onYield,
   } = options
 
   const safeTaskMs = Math.max(estimatedTaskTimeMs, 0.1)
@@ -71,11 +73,10 @@ export async function runAdaptiveTaskQueue<T>(
   const currentPerformance = typeof globalThis !== 'undefined' ? (globalThis as any)?.performance : undefined
   const now = () => (currentPerformance ? currentPerformance.now() : Date.now())
 
-
   const startTime = now()
 
   logger.debug?.(
-    `[${label}] Starting queue for ${total} item(s). batchSize=${batchSize}, estimated=${safeTaskMs.toFixed(2)}ms`
+    `[${label}] Starting queue for ${total} item(s). batchSize=${batchSize}, estimated=${safeTaskMs.toFixed(2)}ms`,
   )
 
   for (let index = 0; index < total; index++) {
@@ -90,19 +91,19 @@ export async function runAdaptiveTaskQueue<T>(
       logger.debug?.(
         `[${label}] Yielded after ${processed}/${total} item(s); wait ${(
           afterYield - beforeYield
-        ).toFixed(1)}ms`
+        ).toFixed(1)}ms`,
       )
       onYield?.({
         processed,
         total,
         batchSize,
-        elapsedMs
+        elapsedMs,
       })
     }
   }
 
   const endTime = now()
   logger.debug?.(
-    `[${label}] Completed ${total} item(s) in ${((endTime - startTime) / 1000).toFixed(2)}s`
+    `[${label}] Completed ${total} item(s) in ${((endTime - startTime) / 1000).toFixed(2)}s`,
   )
 }

package/common/utils/time.ts

@@ -19,11 +19,11 @@ export class TimeoutError extends Error {
    * @param message - An optional message describing the timeout error. Defaults to 'Operation timed out'.
    */
   constructor(message: string = 'Operation timed out') {
-    super(message);
-    this.name = 'TimeoutError';
+    super(message)
+    this.name = 'TimeoutError'
     // Maintain proper stack trace for the error.
     if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, TimeoutError);
+      Error.captureStackTrace(this, TimeoutError)
     }
   }
 }
@@ -62,19 +62,19 @@ export class TimeoutError extends Error {
 export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
   if (ms <= 0) {
     // If timeout is 0 or negative, return the original Promise without a timeout mechanism.
-    return promise;
+    return promise
   }
 
   // Create a promise that rejects in <ms> milliseconds
   const timeout = new Promise<never>((_, reject) => {
     const id = setTimeout(() => {
-      clearTimeout(id);
-      reject(new TimeoutError(`Promise timed out after ${ms} ms`));
-    }, ms);
-  });
+      clearTimeout(id)
+      reject(new TimeoutError(`Promise timed out after ${ms} ms`))
+    }, ms)
+  })
 
   // Race the input promise against the timeout promise
-  return Promise.race([promise, timeout]);
+  return Promise.race([promise, timeout])
 }
 
 /**
@@ -82,13 +82,13 @@ export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  * computes `T` based on the current attempt number.
  * @template T The type of the value.
  */
-type DynamicValue<T> = T | ((attempt: number) => T);
+type DynamicValue<T> = T | ((attempt: number) => T)
 
 /**
  * Defines a generic asynchronous function type that returns a Promise.
  * @template T The type of the Promise's resolution value.
  */
-type AsyncFunction<T> = (...args: any[]) => Promise<T>;
+type AsyncFunction<T> = (...args: any[]) => Promise<T>
 
 /**
  * Defines the options for configuring the retrier behavior.
@@ -100,45 +100,45 @@ export interface RetrierOptions {
    * - If a `function`, it dynamically calculates the maximum retries based on the current attempt number (starting from 1).
    * @defaultValue 2 (meaning 1 initial attempt + 2 retries, total 3 attempts)
    */
-  maxRetries?: DynamicValue<number>;
+  maxRetries?: DynamicValue<number>
   /**
    * The timeout duration for each individual attempt in milliseconds.
    * - If a `number`, it represents a fixed timeout for each attempt.
    * - If a `function`, it dynamically calculates the timeout based on the current attempt number.
    * @defaultValue 5000 (5 seconds)
    */
-  timeoutMs?: DynamicValue<number>;
+  timeoutMs?: DynamicValue<number>
   /**
    * Callback invoked at the beginning of each attempt.
    * @param attempt - The current attempt number (starts from 1).
    * @param error - The error from the previous attempt, if any (undefined for the first attempt).
    */
-  onAttempt?: (attempt: number, error?: Error) => void;
+  onAttempt?: (attempt: number, error?: Error) => void
   /**
    * Callback invoked upon successful completion of the operation.
    * @template T The type of the successful result.
    * @param result - The successful result of the operation.
    * @param attempt - The attempt number on which the operation succeeded.
    */
-  onSuccess?: <T>(result: T, attempt: number) => void;
+  onSuccess?: <T>(result: T, attempt: number) => void
   /**
    * Callback invoked when all retries have been exhausted and the operation ultimately fails.
    * @param error - The final error that caused the operation to fail.
    * @param attempt - The total number of attempts made before final failure.
    */
-  onFailure?: (error: Error, attempt: number) => void;
+  onFailure?: (error: Error, attempt: number) => void
   /**
    * Callback invoked before initiating a retry, indicating that a retry will occur.
    * @param attempt - The attempt number that just failed and will lead to the next retry.
    * @param error - The error that caused the current attempt to fail.
    */
-  onRetry?: (attempt: number, error: Error) => void;
+  onRetry?: (attempt: number, error: Error) => void
   /**
    * Callback invoked when a single attempt times out. Note that this is a specific type of failure that leads to a retry.
    * @param attempt - The attempt number that timed out.
    * @param ms - The timeout duration (in milliseconds) that was set for this specific attempt.
    */
-  onTimeout?: (attempt: number, ms: number) => void;
+  onTimeout?: (attempt: number, ms: number) => void
   /**
    * A predicate function that determines whether a given error should trigger a retry.
    * If this function returns `false`, the retrier will immediately stop and throw the error.
@@ -147,7 +147,7 @@ export interface RetrierOptions {
    * @param attempt - The current attempt number.
    * @returns `true` if a retry should occur, `false` otherwise.
    */
-  shouldRetry?: (error: Error, attempt: number) => boolean;
+  shouldRetry?: (error: Error, attempt: number) => boolean
 }
 
 /**
@@ -218,7 +218,7 @@ export function createRetrier(options: RetrierOptions = {}) {
     onRetry,
     onTimeout,
     shouldRetry = () => true, // Default: retry on all errors
-  } = options;
+  } = options
 
   /**
    * Resolves a DynamicValue to its concrete value for the given attempt.
@@ -228,8 +228,8 @@ export function createRetrier(options: RetrierOptions = {}) {
    * @returns The concrete value.
    */
   const resolveDynamicValue = <T_Val>(value: DynamicValue<T_Val>, attempt: number): T_Val => {
-    return typeof value === 'function' ? (value as (attempt: number) => T_Val)(attempt) : value;
-  };
+    return typeof value === 'function' ? (value as (attempt: number) => T_Val)(attempt) : value
+  }
 
   /**
    * A higher-order function that takes an asynchronous function and returns a new function
@@ -243,53 +243,55 @@ export function createRetrier(options: RetrierOptions = {}) {
    */
   return function <T, Func extends AsyncFunction<T>>(func: Func): ((...args: Parameters<Func>) => Promise<T>) {
     return async function (this: ThisParameterType<Func>, ...args: Parameters<Func>): Promise<T> {
-      let currentAttempt = 0;
-      let lastError: Error | undefined;
+      let currentAttempt = 0
+      let lastError: Error | undefined
 
       // Resolve maxRetries once or dynamically per attempt based on DynamicValue type
-      const calculatedMaxRetries = resolveDynamicValue(maxRetries, 1); // Calculate for the first attempt as starting point
+      const calculatedMaxRetries = resolveDynamicValue(maxRetries, 1) // Calculate for the first attempt as starting point
 
       // Loop through attempts up to the maximum allowed retries
       while (currentAttempt <= calculatedMaxRetries) {
-        currentAttempt++;
-        onAttempt?.(currentAttempt, lastError); // Notify about current attempt, including previous error if any
+        currentAttempt++
+        onAttempt?.(currentAttempt, lastError) // Notify about current attempt, including previous error if any
 
         // Resolve timeoutMs dynamically for the current attempt
-        const currentTimeoutMs = resolveDynamicValue(timeoutMs, currentAttempt);
+        const currentTimeoutMs = resolveDynamicValue(timeoutMs, currentAttempt)
 
         try {
           // Execute the original function with its original `this` context and arguments,
           // wrapped by the `withTimeout` utility.
-          const result = await withTimeout(func.apply(this, args), currentTimeoutMs);
-          onSuccess?.(result, currentAttempt); // Notify success
-          return result; // Return the successful result
-        } catch (error: any) {
-          lastError = error; // Store the error for the next attempt's `onAttempt` callback
+          const result = await withTimeout(func.apply(this, args), currentTimeoutMs)
+          onSuccess?.(result, currentAttempt) // Notify success
+          return result // Return the successful result
+        }
+        catch (error: any) {
+          lastError = error // Store the error for the next attempt's `onAttempt` callback
 
           // Notify if the specific error was a timeout
           if (error instanceof TimeoutError) {
-            onTimeout?.(currentAttempt, currentTimeoutMs);
-          } else {
+            onTimeout?.(currentAttempt, currentTimeoutMs)
+          }
+          else {
             // console.warn(`Attempt ${currentAttempt} failed with error:`, error.message); // Example internal logging
           }
 
           // Determine if a retry should proceed based on the `shouldRetry` predicate and max attempts
-          const shouldProceedRetry = shouldRetry(error, currentAttempt);
+          const shouldProceedRetry = shouldRetry(error, currentAttempt)
 
           if (!shouldProceedRetry || currentAttempt > calculatedMaxRetries) {
-            onFailure?.(error, currentAttempt); // Notify final failure
-            throw error; // Throw the error if no more retries or `shouldRetry` returns false
+            onFailure?.(error, currentAttempt) // Notify final failure
+            throw error // Throw the error if no more retries or `shouldRetry` returns false
           }
 
-          onRetry?.(currentAttempt, error); // Notify that a retry will occur
+          onRetry?.(currentAttempt, error) // Notify that a retry will occur
           // Optional: Add a delay here for exponential backoff or other retry strategies.
           // e.g., `await new Promise(resolve => setTimeout(resolve, Math.pow(2, currentAttempt) * 100));`
         }
       }
       // This line should ideally not be reached if the loop's conditions are correct and errors are always thrown.
-      throw new Error('Retrier exhausted all attempts without success. This is an unexpected state.');
-    };
-  };
+      throw new Error('Retrier exhausted all attempts without success. This is an unexpected state.')
+    }
+  }
 }
 
 /**
@@ -359,16 +361,17 @@ export function useRetrier<T, Func extends AsyncFunction<T>>(func: Func): ((...a
     timeoutMs: 5000, // Default: 5 seconds timeout
     onAttempt: (attempt, error) => {
       if (attempt > 1) {
-        console.log(`[UseRetrier Default] Attempt ${attempt} (after previous error: ${error?.message || 'None'})...`);
-      } else {
-        console.log(`[UseRetrier Default] Starting initial attempt ${attempt}...`);
+        console.log(`[UseRetrier Default] Attempt ${attempt} (after previous error: ${error?.message || 'None'})...`)
+      }
+      else {
+        console.log(`[UseRetrier Default] Starting initial attempt ${attempt}...`)
       }
     },
     onSuccess: (result, attempt) => console.log(`[UseRetrier Default] ✅ Succeeded on attempt ${attempt}. Result:`, result),
     onFailure: (error, attempt) => console.error(`[UseRetrier Default] ❌ Failed after ${attempt} attempts. Final Error:`, error.message),
     onRetry: (attempt, error) => console.warn(`[UseRetrier Default] 🔄 Will retry. Attempt ${attempt} failed with: ${error.message}`),
     onTimeout: (attempt, ms) => console.warn(`[UseRetrier Default] ⏰ Attempt ${attempt} timed out after ${ms}ms.`),
-  });
+  })
   // Use the created default retrier to wrap the provided function.
-  return defaultRetrier(func);
+  return defaultRetrier(func)
 }

package/common/utils/timing.ts

@@ -24,7 +24,7 @@ const DEFAULT_HISTORY_LIMIT = 50
 export const DEFAULT_TIMING_LOG_THRESHOLDS: Readonly<ResolvedTimingLogThresholds> = Object.freeze({
   none: 16.7,
   info: 200,
-  warn: 500
+  warn: 500,
 })
 
 export const DEFAULT_TIMING_OPTIONS: Readonly<Required<Pick<TimingOptions, 'autoLog' | 'storeHistory'>> & {
@@ -32,7 +32,7 @@ export const DEFAULT_TIMING_OPTIONS: Readonly<Required<Pick<TimingOptions, 'auto
 }> = Object.freeze({
   autoLog: DEFAULT_AUTO_LOG,
   storeHistory: DEFAULT_STORE_HISTORY,
-  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS
+  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS,
 })
 
 export const DEFAULT_TIMING_MANAGER_CONFIG: Readonly<
@@ -43,7 +43,7 @@ export const DEFAULT_TIMING_MANAGER_CONFIG: Readonly<
   autoLog: DEFAULT_AUTO_LOG,
   storeHistory: DEFAULT_STORE_HISTORY,
   historyLimit: DEFAULT_HISTORY_LIMIT,
-  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS
+  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS,
 })
 
 export interface TimingStats {
@@ -83,7 +83,7 @@ export interface TimingOptions {
   logThresholds?: TimingLogThresholdOverrides
 }
 
-type ResolvedTimingOptions = {
+interface ResolvedTimingOptions {
   autoLog: boolean
   storeHistory: boolean
   historyLimit: number
@@ -101,13 +101,13 @@ export class TimingManager {
   constructor(config: TimingManagerConfig = {}) {
     const mergedThresholds: ResolvedTimingLogThresholds = {
       ...DEFAULT_TIMING_LOG_THRESHOLDS,
-      ...(config.logThresholds ?? {})
+      ...(config.logThresholds ?? {}),
     }
 
     this.config = {
       ...DEFAULT_TIMING_MANAGER_CONFIG,
       ...config,
-      logThresholds: mergedThresholds
+      logThresholds: mergedThresholds,
     }
   }
 
@@ -142,12 +142,13 @@ export class TimingManager {
 
   getStats(label: string): TimingStats | undefined {
     const stats = this.stats.get(label)
-    if (!stats) return undefined
+    if (!stats)
+      return undefined
     return { ...stats }
   }
 
   getAllStats(): TimingStats[] {
-    return Array.from(this.stats.values()).map((s) => ({ ...s }))
+    return Array.from(this.stats.values()).map(s => ({ ...s }))
   }
 
   getHistory(label: string): TimingRecord[] {
@@ -159,7 +160,7 @@ export class TimingManager {
       const stats = this.moduleStats.get(moduleKey)
       return stats ? { ...stats } : undefined
     }
-    return Array.from(this.moduleStats.values()).map((s) => ({ ...s }))
+    return Array.from(this.moduleStats.values()).map(s => ({ ...s }))
   }
 
   reset(label?: string): void {
@@ -183,7 +184,7 @@ export class TimingManager {
       maxMs: Number.NEGATIVE_INFINITY,
       minMs: Number.POSITIVE_INFINITY,
       lastMs: 0,
-      errorCount: 0
+      errorCount: 0,
     }
 
     next.count += 1
@@ -214,7 +215,7 @@ export class TimingManager {
     const logThresholds: ResolvedTimingLogThresholds = {
       ...DEFAULT_TIMING_LOG_THRESHOLDS,
       ...(this.config.logThresholds ?? {}),
-      ...(options.logThresholds ?? {})
+      ...(options.logThresholds ?? {}),
     }
 
     return {
@@ -223,7 +224,7 @@ export class TimingManager {
       historyLimit: options.historyLimit ?? this.config.historyLimit ?? DEFAULT_HISTORY_LIMIT,
       logThresholds,
       formatter: options.formatter ?? this.config.formatter ?? defaultFormatter,
-      logger: options.logger ?? this.config.logger ?? defaultLogger
+      logger: options.logger ?? this.config.logger ?? defaultLogger,
     }
   }
 }
@@ -232,7 +233,7 @@ export class TimingScope {
   constructor(
     private readonly manager: TimingManager,
     private readonly label: string,
-    private readonly options: TimingOptions
+    private readonly options: TimingOptions,
   ) {}
 
   async cost<T>(fn: () => Promise<T> | T, meta: TimingMeta = {}, overrides: TimingOptions = {}): Promise<T> {
@@ -241,7 +242,8 @@ export class TimingScope {
       const result = await fn()
       this.finish(startedAt, meta, undefined, overrides)
       return result
-    } catch (error) {
+    }
+    catch (error) {
       this.finish(startedAt, meta, error, overrides)
       throw error
     }
@@ -256,7 +258,8 @@ export class TimingScope {
         const value = await fn(index)
         this.finish(startedAt, { ...iterationMeta, iteration: index }, undefined, overrides)
         results.push(value)
-      } catch (error) {
+      }
+      catch (error) {
         this.finish(startedAt, { ...iterationMeta, iteration: index }, error, overrides)
         throw error
       }
@@ -274,9 +277,9 @@ export class TimingScope {
         durationMs,
         startedAt,
         endedAt,
-        meta
+        meta,
       },
-      { ...this.options, ...overrides }
+      { ...this.options, ...overrides },
     )
   }
 
@@ -296,7 +299,7 @@ export class TimingScope {
       startedAt,
       endedAt,
       meta,
-      error
+      error,
     }
 
     this.manager.record(this.label, record, { ...this.options, ...overrides })
@@ -305,10 +308,10 @@ export class TimingScope {
 
 function defaultFormatter(record: TimingRecord, stats: TimingStats): string {
   const duration = record.durationMs.toFixed(2)
-  const levelTag =
-    record.logLevel && record.logLevel !== 'info' ? ` [${record.logLevel.toUpperCase()}]` : ''
+  const levelTag
+    = record.logLevel && record.logLevel !== 'info' ? ` [${record.logLevel.toUpperCase()}]` : ''
   return `⏱  [${record.label}] ${duration} ms${levelTag} (avg: ${stats.avgMs.toFixed(
-    2
+    2,
   )} ms, max: ${stats.maxMs.toFixed(2)} ms, count: ${stats.count})`
 }
 
@@ -370,7 +373,7 @@ export function completeTiming(
   label: string,
   startedAt: number,
   meta: TimingMeta = {},
-  options: TimingOptions = {}
+  options: TimingOptions = {},
 ): number {
   const endedAt = now()
   const durationMs = endedAt - startedAt
@@ -381,9 +384,9 @@ export function completeTiming(
       durationMs,
       startedAt,
       endedAt,
-      meta
+      meta,
     },
-    options
+    options,
   )
   return durationMs
 }
@@ -392,7 +395,7 @@ export function logTiming(
   label: string,
   durationMs: number,
   meta: TimingMeta = {},
-  options: TimingOptions = {}
+  options: TimingOptions = {},
 ): void {
   const endedAt = now()
   const startedAt = endedAt - durationMs
@@ -403,9 +406,9 @@ export function logTiming(
       durationMs,
       startedAt,
       endedAt,
-      meta
+      meta,
     },
-    options
+    options,
   )
 }
 
@@ -422,14 +425,14 @@ export const timingLogger = {
       label,
       startedAt: startTiming(),
       meta,
-      options
+      options,
     }
   },
 
   finish(
     token: TimingLoggerToken,
     meta: TimingMeta = {},
-    overrides: TimingOptions = {}
+    overrides: TimingOptions = {},
   ): number {
     const mergedMeta = { ...token.meta, ...meta }
     const mergedOptions = mergeTimingOptions(token.options, overrides)
@@ -440,7 +443,7 @@ export const timingLogger = {
     label: string,
     durationMs: number,
     meta: TimingMeta = {},
-    options: TimingOptions = {}
+    options: TimingOptions = {},
   ): number {
     logTiming(label, durationMs, meta, options)
     return durationMs
@@ -450,7 +453,7 @@ export const timingLogger = {
     label: string,
     fn: () => Promise<T> | T,
     meta: TimingMeta = {},
-    options: TimingOptions = {}
+    options: TimingOptions = {},
   ): Promise<T> {
     const scope = createTiming(label, options)
     return scope.cost(fn, meta)
@@ -460,11 +463,11 @@ export const timingLogger = {
     label: string,
     durationMs: number,
     meta: TimingMeta = {},
-    options: TimingOptions = {}
+    options: TimingOptions = {},
   ): number {
     logTiming(label, durationMs, meta, options)
     return durationMs
-  }
+  },
 }
 
 export function createTiming(label: string, options: TimingOptions = {}): TimingScope {
@@ -473,9 +476,10 @@ export function createTiming(label: string, options: TimingOptions = {}): Timing
 
 function mergeTimingOptions(
   base: TimingOptions = {},
-  override: TimingOptions = {}
+  override: TimingOptions = {},
 ): TimingOptions {
-  if (!base && !override) return {}
+  if (!base && !override)
+    return {}
   if (!override || Object.keys(override).length === 0) {
     return { ...base }
   }
@@ -488,7 +492,7 @@ function mergeTimingOptions(
     ...override,
     logThresholds: {
       ...(base.logThresholds ?? {}),
-      ...(override.logThresholds ?? {})
-    }
+      ...(override.logThresholds ?? {}),
+    },
   }
 }

package/core-box/builder/index.ts

@@ -3,4 +3,4 @@
  * 提供 TuffItem 构建工具和实用函数
  */
 
-export * from './tuff-builder';
+export * from './tuff-builder'