@umituz/react-native-ai-fal-provider 1.0.94 → 1.0.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-fal-provider",
-  "version": "1.0.94",
+  "version": "1.0.98",
   "description": "FAL AI provider for React Native - implements IAIProvider interface for unified AI generation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/infrastructure/services/fal-feature-models.ts

@@ -0,0 +1,46 @@
+/**
+ * FAL Feature Models - Model resolution and input building
+ */
+
+import type {
+  ImageFeatureType,
+  VideoFeatureType,
+  ImageFeatureInputData,
+  VideoFeatureInputData,
+} from "@umituz/react-native-ai-generation-content";
+import {
+  buildImageFeatureInput as buildImageFeatureInputImpl,
+  buildVideoFeatureInput as buildVideoFeatureInputImpl,
+} from "../builders";
+
+export function getImageFeatureModel(
+  imageFeatureModels: Record<string, string>,
+  feature: ImageFeatureType,
+): string {
+  const model = imageFeatureModels[feature];
+  if (!model) throw new Error(`No model for image feature: ${feature}`);
+  return model;
+}
+
+export function getVideoFeatureModel(
+  videoFeatureModels: Record<string, string>,
+  feature: VideoFeatureType,
+): string {
+  const model = videoFeatureModels[feature];
+  if (!model) throw new Error(`No model for video feature: ${feature}`);
+  return model;
+}
+
+export function buildImageFeatureInput(
+  feature: ImageFeatureType,
+  data: ImageFeatureInputData,
+): Record<string, unknown> {
+  return buildImageFeatureInputImpl(feature, data);
+}
+
+export function buildVideoFeatureInput(
+  feature: VideoFeatureType,
+  data: VideoFeatureInputData,
+): Record<string, unknown> {
+  return buildVideoFeatureInputImpl(feature, data);
+}

package/src/infrastructure/services/fal-provider.ts

@@ -1,6 +1,6 @@
 /**
  * FAL Provider - Implements IAIProvider interface
- * Uses Promise Deduplication Pattern with globalThis for hot reload persistence
+ * Orchestrates FAL AI operations with Promise Deduplication
  */
 
 import { fal } from "@fal-ai/client";
@@ -9,40 +9,28 @@ import type {
   RunOptions, ImageFeatureType, VideoFeatureType, ImageFeatureInputData,
   VideoFeatureInputData, ProviderCapabilities,
 } from "@umituz/react-native-ai-generation-content";
-import type { FalQueueStatus } from "../../domain/entities/fal.types";
 import type { CostTrackerConfig } from "../../domain/entities/cost-tracking.types";
 import { DEFAULT_FAL_CONFIG, FAL_CAPABILITIES } from "./fal-provider.constants";
-import { mapFalStatusToJobStatus } from "./fal-status-mapper";
+import { handleFalSubscription, handleFalRun } from "./fal-provider-subscription";
+import { CostTracker } from "../utils/cost-tracker";
+import {
+  createRequestKey, getExistingRequest, storeRequest,
+  removeRequest, cancelAllRequests, hasActiveRequests,
+} from "./request-store";
 import {
+  submitJob as submitJobImpl,
+  getJobStatus as getJobStatusImpl,
+  getJobResult as getJobResultImpl,
+} from "./fal-queue-operations";
+import {
+  getImageFeatureModel as getImageFeatureModelImpl,
+  getVideoFeatureModel as getVideoFeatureModelImpl,
   buildImageFeatureInput as buildImageFeatureInputImpl,
   buildVideoFeatureInput as buildVideoFeatureInputImpl,
-} from "../builders";
-import { handleFalSubscription, handleFalRun } from "./fal-provider-subscription";
-import { CostTracker } from "../utils/cost-tracker";
+} from "./fal-feature-models";
 
 declare const __DEV__: boolean | undefined;
 
-interface ActiveRequest<T = unknown> {
-  promise: Promise<T>;
-  abortController: AbortController;
-}
-
-// Global request store - survives hot reloads via globalThis
-const STORE_KEY = "__FAL_PROVIDER_REQUESTS__";
-type RequestStore = Map<string, ActiveRequest>;
-
-function getRequestStore(): RequestStore {
-  if (!(globalThis as Record<string, unknown>)[STORE_KEY]) {
-    (globalThis as Record<string, unknown>)[STORE_KEY] = new Map();
-  }
-  return (globalThis as Record<string, unknown>)[STORE_KEY] as RequestStore;
-}
-
-function createRequestKey(model: string, input: Record<string, unknown>): string {
-  const inputStr = JSON.stringify(input, Object.keys(input).sort());
-  return `${model}:${inputStr.slice(0, 100)}`; // Limit key length
-}
-
 export class FalProvider implements IAIProvider {
   readonly providerId = "fal";
   readonly providerName = "FAL AI";
@@ -107,20 +95,17 @@ export class FalProvider implements IAIProvider {
 
   async submitJob(model: string, input: Record<string, unknown>): Promise<JobSubmission> {
     this.validateInit();
-    const result = await fal.queue.submit(model, { input });
-    return { requestId: result.request_id, statusUrl: result.status_url, responseUrl: result.response_url };
+    return submitJobImpl(model, input);
   }
 
   async getJobStatus(model: string, requestId: string): Promise<JobStatus> {
     this.validateInit();
-    const status = await fal.queue.status(model, { requestId, logs: true });
-    return mapFalStatusToJobStatus(status as unknown as FalQueueStatus);
+    return getJobStatusImpl(model, requestId);
   }
 
   async getJobResult<T = unknown>(model: string, requestId: string): Promise<T> {
     this.validateInit();
-    const result = await fal.queue.result(model, { requestId });
-    return result.data as T;
+    return getJobResultImpl<T>(model, requestId);
   }
 
   async subscribe<T = unknown>(
@@ -129,16 +114,14 @@ export class FalProvider implements IAIProvider {
     options?: SubscribeOptions<T>,
   ): Promise<T> {
     this.validateInit();
-    const store = getRequestStore();
     const key = createRequestKey(model, input);
 
-    // Return existing promise if same request is in progress
-    const existing = store.get(key);
+    const existing = getExistingRequest<T>(key);
     if (existing) {
       if (typeof __DEV__ !== "undefined" && __DEV__) {
         console.log(`[FalProvider] Dedup: returning existing promise for ${model}`);
       }
-      return existing.promise as Promise<T>;
+      return existing.promise;
     }
 
     const abortController = new AbortController();
@@ -151,9 +134,9 @@ export class FalProvider implements IAIProvider {
         }
         return result;
       })
-      .finally(() => store.delete(key));
+      .finally(() => removeRequest(key));
 
-    store.set(key, { promise, abortController });
+    storeRequest(key, { promise, abortController });
     return promise;
   }
 
@@ -174,24 +157,15 @@ export class FalProvider implements IAIProvider {
   }
 
   cancelCurrentRequest(): void {
-    const store = getRequestStore();
-    store.forEach((req, key) => {
-      if (typeof __DEV__ !== "undefined" && __DEV__) {
-        console.log(`[FalProvider] Cancelling request: ${key}`);
-      }
-      req.abortController.abort();
-    });
-    store.clear();
+    cancelAllRequests();
   }
 
   hasRunningRequest(): boolean {
-    return getRequestStore().size > 0;
+    return hasActiveRequests();
   }
 
   getImageFeatureModel(feature: ImageFeatureType): string {
-    const model = this.imageFeatureModels[feature];
-    if (!model) throw new Error(`No model for image feature: ${feature}`);
-    return model;
+    return getImageFeatureModelImpl(this.imageFeatureModels, feature);
   }
 
   buildImageFeatureInput(feature: ImageFeatureType, data: ImageFeatureInputData): Record<string, unknown> {
@@ -199,9 +173,7 @@ export class FalProvider implements IAIProvider {
   }
 
   getVideoFeatureModel(feature: VideoFeatureType): string {
-    const model = this.videoFeatureModels[feature];
-    if (!model) throw new Error(`No model for video feature: ${feature}`);
-    return model;
+    return getVideoFeatureModelImpl(this.videoFeatureModels, feature);
   }
 
   buildVideoFeatureInput(feature: VideoFeatureType, data: VideoFeatureInputData): Record<string, unknown> {

package/src/infrastructure/services/fal-queue-operations.ts

@@ -0,0 +1,27 @@
+/**
+ * FAL Queue Operations - Direct FAL API queue interactions
+ */
+
+import { fal } from "@fal-ai/client";
+import type { JobSubmission, JobStatus } from "@umituz/react-native-ai-generation-content";
+import type { FalQueueStatus } from "../../domain/entities/fal.types";
+import { mapFalStatusToJobStatus } from "./fal-status-mapper";
+
+export async function submitJob(model: string, input: Record<string, unknown>): Promise<JobSubmission> {
+  const result = await fal.queue.submit(model, { input });
+  return {
+    requestId: result.request_id,
+    statusUrl: result.status_url,
+    responseUrl: result.response_url,
+  };
+}
+
+export async function getJobStatus(model: string, requestId: string): Promise<JobStatus> {
+  const status = await fal.queue.status(model, { requestId, logs: true });
+  return mapFalStatusToJobStatus(status as unknown as FalQueueStatus);
+}
+
+export async function getJobResult<T = unknown>(model: string, requestId: string): Promise<T> {
+  const result = await fal.queue.result(model, { requestId });
+  return result.data as T;
+}

package/src/infrastructure/services/request-store.ts

@@ -0,0 +1,53 @@
+/**
+ * Request Store - Promise Deduplication with globalThis
+ * Survives hot reloads for React Native development
+ */
+
+declare const __DEV__: boolean | undefined;
+
+export interface ActiveRequest<T = unknown> {
+  promise: Promise<T>;
+  abortController: AbortController;
+}
+
+const STORE_KEY = "__FAL_PROVIDER_REQUESTS__";
+type RequestStore = Map<string, ActiveRequest>;
+
+export function getRequestStore(): RequestStore {
+  if (!(globalThis as Record<string, unknown>)[STORE_KEY]) {
+    (globalThis as Record<string, unknown>)[STORE_KEY] = new Map();
+  }
+  return (globalThis as Record<string, unknown>)[STORE_KEY] as RequestStore;
+}
+
+export function createRequestKey(model: string, input: Record<string, unknown>): string {
+  const inputStr = JSON.stringify(input, Object.keys(input).sort());
+  return `${model}:${inputStr.slice(0, 100)}`;
+}
+
+export function getExistingRequest<T>(key: string): ActiveRequest<T> | undefined {
+  return getRequestStore().get(key) as ActiveRequest<T> | undefined;
+}
+
+export function storeRequest<T>(key: string, request: ActiveRequest<T>): void {
+  getRequestStore().set(key, request);
+}
+
+export function removeRequest(key: string): void {
+  getRequestStore().delete(key);
+}
+
+export function cancelAllRequests(): void {
+  const store = getRequestStore();
+  store.forEach((req, key) => {
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      console.log(`[RequestStore] Cancelling: ${key}`);
+    }
+    req.abortController.abort();
+  });
+  store.clear();
+}
+
+export function hasActiveRequests(): boolean {
+  return getRequestStore().size > 0;
+}

package/src/infrastructure/utils/cost-tracker-queries.ts

@@ -0,0 +1,67 @@
+/**
+ * Cost Tracker Queries
+ * Query functions for cost history analysis
+ */
+
+import type { GenerationCost, CostSummary } from "../../domain/entities/cost-tracking.types";
+
+/**
+ * Calculate cost summary from history
+ */
+export function calculateCostSummary(
+  costHistory: readonly GenerationCost[],
+  currency: string
+): CostSummary {
+  const completedCosts = costHistory.filter((c) => c.actualCost > 0);
+  const totalCost = completedCosts.reduce((sum, c) => sum + c.actualCost, 0);
+  const totalGenerations = completedCosts.length;
+  const averageCost = totalGenerations > 0 ? totalCost / totalGenerations : 0;
+
+  const modelBreakdown: Record<string, number> = {};
+  const operationBreakdown: Record<string, number> = {};
+
+  for (const cost of completedCosts) {
+    modelBreakdown[cost.model] = (modelBreakdown[cost.model] ?? 0) + cost.actualCost;
+    operationBreakdown[cost.operation] = (operationBreakdown[cost.operation] ?? 0) + cost.actualCost;
+  }
+
+  return {
+    totalCost,
+    totalGenerations,
+    averageCost,
+    currency,
+    modelBreakdown,
+    operationBreakdown,
+  };
+}
+
+/**
+ * Filter costs by model
+ */
+export function filterCostsByModel(
+  costHistory: readonly GenerationCost[],
+  modelId: string
+): GenerationCost[] {
+  return costHistory.filter((c) => c.model === modelId);
+}
+
+/**
+ * Filter costs by operation type
+ */
+export function filterCostsByOperation(
+  costHistory: readonly GenerationCost[],
+  operation: string
+): GenerationCost[] {
+  return costHistory.filter((c) => c.operation === operation);
+}
+
+/**
+ * Filter costs by time range
+ */
+export function filterCostsByTimeRange(
+  costHistory: readonly GenerationCost[],
+  startTime: number,
+  endTime: number
+): GenerationCost[] {
+  return costHistory.filter((c) => c.timestamp >= startTime && c.timestamp <= endTime);
+}

package/src/infrastructure/utils/cost-tracker.ts

@@ -10,6 +10,12 @@ import type {
   ModelCostInfo,
 } from "../../domain/entities/cost-tracking.types";
 import { findModelById } from "../../domain/constants/default-models.constants";
+import {
+  calculateCostSummary,
+  filterCostsByModel,
+  filterCostsByOperation,
+  filterCostsByTimeRange,
+} from "./cost-tracker-queries";
 
 declare const __DEV__: boolean | undefined;
 
@@ -27,9 +33,6 @@ export class CostTracker {
     };
   }
 
-  /**
-   * Get cost information for a model
-   */
   getModelCostInfo(modelId: string): ModelCostInfo {
     const model = findModelById(modelId);
 
@@ -52,17 +55,11 @@ export class CostTracker {
     };
   }
 
-  /**
-   * Calculate estimated cost for a generation
-   */
   calculateEstimatedCost(modelId: string): number {
     const costInfo = this.getModelCostInfo(modelId);
     return costInfo.costPerRequest;
   }
 
-  /**
-   * Start tracking a generation operation
-   */
   startOperation(modelId: string, operation: string): string {
     const operationId = `${Date.now()}-${operation}`;
     const estimatedCost = this.calculateEstimatedCost(modelId);
@@ -86,9 +83,6 @@ export class CostTracker {
     return operationId;
   }
 
-  /**
-   * Complete tracking for a generation operation
-   */
   completeOperation(
     operationId: string,
     modelId: string,
@@ -120,70 +114,28 @@ export class CostTracker {
     return cost;
   }
 
-  /**
-   * Get cost summary for all tracked operations
-   */
   getCostSummary(): CostSummary {
-    const completedCosts = this.costHistory.filter((c) => c.actualCost > 0);
-    const totalCost = completedCosts.reduce((sum, c) => sum + c.actualCost, 0);
-    const totalGenerations = completedCosts.length;
-    const averageCost = totalGenerations > 0 ? totalCost / totalGenerations : 0;
-
-    const modelBreakdown: Record<string, number> = {};
-    const operationBreakdown: Record<string, number> = {};
-
-    for (const cost of completedCosts) {
-      modelBreakdown[cost.model] =
-        (modelBreakdown[cost.model] ?? 0) + cost.actualCost;
-      operationBreakdown[cost.operation] =
-        (operationBreakdown[cost.operation] ?? 0) + cost.actualCost;
-    }
-
-    return {
-      totalCost,
-      totalGenerations,
-      averageCost,
-      currency: this.config.currency,
-      modelBreakdown,
-      operationBreakdown,
-    };
+    return calculateCostSummary(this.costHistory, this.config.currency);
   }
 
-  /**
-   * Get cost history
-   */
   getCostHistory(): readonly GenerationCost[] {
     return this.costHistory;
   }
 
-  /**
-   * Clear cost history
-   */
   clearHistory(): void {
     this.costHistory = [];
     this.currentOperationCosts.clear();
   }
 
-  /**
-   * Get costs for a specific model
-   */
   getCostsByModel(modelId: string): GenerationCost[] {
-    return this.costHistory.filter((c) => c.model === modelId);
+    return filterCostsByModel(this.costHistory, modelId);
   }
 
-  /**
-   * Get costs for a specific operation type
-   */
   getCostsByOperation(operation: string): GenerationCost[] {
-    return this.costHistory.filter((c) => c.operation === operation);
+    return filterCostsByOperation(this.costHistory, operation);
   }
 
-  /**
-   * Get costs for a specific time range
-   */
   getCostsByTimeRange(startTime: number, endTime: number): GenerationCost[] {
-    return this.costHistory.filter(
-      (c) => c.timestamp >= startTime && c.timestamp <= endTime,
-    );
+    return filterCostsByTimeRange(this.costHistory, startTime, endTime);
   }
 }

package/src/infrastructure/utils/general-helpers.util.ts

@@ -0,0 +1,45 @@
+/**
+ * General Helper Utilities
+ * Common utility functions
+ */
+
+/**
+ * Format credit cost for display
+ */
+export function formatCreditCost(cost: number): string {
+  if (cost % 1 === 0) {
+    return cost.toString();
+  }
+  return cost.toFixed(2);
+}
+
+/**
+ * Build error message with context
+ */
+export function buildErrorMessage(
+  type: string,
+  context: Record<string, unknown>
+): string {
+  const contextStr = Object.entries(context)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(", ");
+  return `${type}${contextStr ? ` (${contextStr})` : ""}`;
+}
+
+/**
+ * Check if value is defined (not null or undefined)
+ */
+export function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Filter out null and undefined values from object
+ */
+export function removeNullish<T extends Record<string, unknown>>(
+  obj: T
+): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([_, value]) => isDefined(value))
+  ) as Partial<T>;
+}

package/src/infrastructure/utils/helpers.util.ts

@@ -1,151 +1,29 @@
 /**
- * Helper Utilities
- * Common helper functions for FAL operations
- */
-
-/**
- * Format image as data URI if not already formatted
- */
-export function formatImageDataUri(base64: string): string {
-  if (base64.startsWith("data:")) {
-    return base64;
-  }
-  return `data:image/jpeg;base64,${base64}`;
-}
-
-/**
- * Extract base64 from data URI
- */
-export function extractBase64(dataUri: string): string {
-  if (!dataUri.startsWith("data:")) {
-    return dataUri;
-  }
-
-  const parts = dataUri.split(",");
-  return parts.length > 1 ? parts[1] : dataUri;
-}
-
-/**
- * Get file extension from data URI
- */
-export function getDataUriExtension(dataUri: string): string | null {
-  const match = dataUri.match(/^data:image\/(\w+);base64/);
-  return match ? match[1] : null;
-}
-
-/**
- * Check if data URI is an image
- */
-export function isImageDataUri(value: string): boolean {
-  return value.startsWith("data:image/");
-}
-
-/**
- * Calculate timeout with jitter to avoid thundering herd
- */
-export function calculateTimeoutWithJitter(
-  baseTimeout: number,
-  jitterPercent: number = 0.1
-): number {
-  const jitter = baseTimeout * jitterPercent;
-  const randomJitter = Math.random() * jitter - jitter / 2;
-  return Math.max(1000, baseTimeout + randomJitter);
-}
-
-/**
- * Format credit cost for display
- */
-export function formatCreditCost(cost: number): string {
-  if (cost % 1 === 0) {
-    return cost.toString();
-  }
-  return cost.toFixed(2);
-}
-
-/**
- * Truncate prompt to maximum length
- */
-export function truncatePrompt(prompt: string, maxLength: number = 5000): string {
-  if (prompt.length <= maxLength) {
-    return prompt;
-  }
-  return prompt.slice(0, maxLength - 3) + "...";
-}
-
-/**
- * Sanitize prompt by removing excessive whitespace
- */
-export function sanitizePrompt(prompt: string): string {
-  return prompt.trim().replace(/\s+/g, " ");
-}
-
-/**
- * Build error message with context
- */
-export function buildErrorMessage(
-  type: string,
-  context: Record<string, unknown>
-): string {
-  const contextStr = Object.entries(context)
-    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
-    .join(", ");
-  return `${type}${contextStr ? ` (${contextStr})` : ""}`;
-}
-
-/**
- * Check if value is defined (not null or undefined)
- */
-export function isDefined<T>(value: T | null | undefined): value is T {
-  return value !== null && value !== undefined;
-}
-
-/**
- * Filter out null and undefined values from object
- */
-export function removeNullish<T extends Record<string, unknown>>(
-  obj: T
-): Partial<T> {
-  return Object.fromEntries(
-    Object.entries(obj).filter(([_, value]) => isDefined(value))
-  ) as Partial<T>;
-}
-
-/**
- * Debounce function (for rate limiting)
- */
-export function debounce<T extends (...args: never[]) => unknown>(
-  func: T,
-  wait: number
-): (...args: Parameters<T>) => void {
-  let timeout: ReturnType<typeof setTimeout> | null = null;
-
-  return function executedFunction(...args: Parameters<T>) {
-    const later = () => {
-      timeout = null;
-      func(...args);
-    };
-
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-    timeout = setTimeout(later, wait);
-  };
-}
-
-/**
- * Simple throttle function
- */
-export function throttle<T extends (...args: never[]) => unknown>(
-  func: T,
-  limit: number
-): (...args: Parameters<T>) => void {
-  let inThrottle = false;
-
-  return function executedFunction(...args: Parameters<T>) {
-    if (!inThrottle) {
-      func(...args);
-      inThrottle = true;
-      setTimeout(() => (inThrottle = false), limit);
-    }
-  };
-}
+ * Helper Utilities - Re-exports
+ * Backward compatibility barrel file
+ */
+
+export {
+  formatImageDataUri,
+  extractBase64,
+  getDataUriExtension,
+  isImageDataUri,
+} from "./image-helpers.util";
+
+export {
+  truncatePrompt,
+  sanitizePrompt,
+} from "./prompt-helpers.util";
+
+export {
+  calculateTimeoutWithJitter,
+  debounce,
+  throttle,
+} from "./timing-helpers.util";
+
+export {
+  formatCreditCost,
+  buildErrorMessage,
+  isDefined,
+  removeNullish,
+} from "./general-helpers.util";

package/src/infrastructure/utils/image-helpers.util.ts

@@ -0,0 +1,40 @@
+/**
+ * Image Helper Utilities
+ * Functions for image data URI manipulation
+ */
+
+/**
+ * Format image as data URI if not already formatted
+ */
+export function formatImageDataUri(base64: string): string {
+  if (base64.startsWith("data:")) {
+    return base64;
+  }
+  return `data:image/jpeg;base64,${base64}`;
+}
+
+/**
+ * Extract base64 from data URI
+ */
+export function extractBase64(dataUri: string): string {
+  if (!dataUri.startsWith("data:")) {
+    return dataUri;
+  }
+  const parts = dataUri.split(",");
+  return parts.length > 1 ? parts[1] : dataUri;
+}
+
+/**
+ * Get file extension from data URI
+ */
+export function getDataUriExtension(dataUri: string): string | null {
+  const match = dataUri.match(/^data:image\/(\w+);base64/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if data URI is an image
+ */
+export function isImageDataUri(value: string): boolean {
+  return value.startsWith("data:image/");
+}

package/src/infrastructure/utils/prompt-helpers.util.ts

@@ -0,0 +1,21 @@
+/**
+ * Prompt Helper Utilities
+ * Functions for prompt manipulation and sanitization
+ */
+
+/**
+ * Truncate prompt to maximum length
+ */
+export function truncatePrompt(prompt: string, maxLength: number = 5000): string {
+  if (prompt.length <= maxLength) {
+    return prompt;
+  }
+  return prompt.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Sanitize prompt by removing excessive whitespace
+ */
+export function sanitizePrompt(prompt: string): string {
+  return prompt.trim().replace(/\s+/g, " ");
+}

package/src/infrastructure/utils/timing-helpers.util.ts

@@ -0,0 +1,56 @@
+/**
+ * Timing Helper Utilities
+ * Functions for timing, debouncing, and throttling
+ */
+
+/**
+ * Calculate timeout with jitter to avoid thundering herd
+ */
+export function calculateTimeoutWithJitter(
+  baseTimeout: number,
+  jitterPercent: number = 0.1
+): number {
+  const jitter = baseTimeout * jitterPercent;
+  const randomJitter = Math.random() * jitter - jitter / 2;
+  return Math.max(1000, baseTimeout + randomJitter);
+}
+
+/**
+ * Debounce function (for rate limiting)
+ */
+export function debounce<T extends (...args: never[]) => unknown>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  return function executedFunction(...args: Parameters<T>) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait);
+  };
+}
+
+/**
+ * Simple throttle function
+ */
+export function throttle<T extends (...args: never[]) => unknown>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+
+  return function executedFunction(...args: Parameters<T>) {
+    if (!inThrottle) {
+      func(...args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}