@umituz/react-native-ai-fal-provider 2.0.20 → 2.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-fal-provider",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "FAL AI provider for React Native - implements IAIProvider interface for unified AI generation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -28,8 +28,8 @@
   },
   "peerDependencies": {
     "@fal-ai/client": ">=0.6.0",
-    "react": ">=18.2.0",
-    "react-native": ">=0.74.0"
+    "react": ">=19.0.0",
+    "react-native": ">=0.81.0"
   },
   "dependencies": {
     "@fal-ai/client": ">=0.6.0"
@@ -46,7 +46,7 @@
     "@tanstack/query-async-storage-persister": "^5.66.7",
     "@tanstack/react-query": "^5.66.7",
     "@tanstack/react-query-persist-client": "^5.66.7",
-    "@types/react": "~18.3.12",
+    "@types/react": "~19.1.0",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
     "@umituz/react-native-auth": "*",
@@ -77,8 +77,8 @@
     "expo-video": "^3.0.15",
     "expo-web-browser": "^12.0.0",
     "firebase": "^12.7.0",
-    "react": "18.3.1",
-    "react-native": "0.76.1",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
     "react-native-gesture-handler": "^2.30.0",
     "react-native-purchases": "^9.7.5",
     "react-native-reanimated": "^4.2.1",

package/src/exports/infrastructure.ts

@@ -15,6 +15,7 @@ export type { FalProviderType } from "../infrastructure/services";
 export {
   categorizeFalError,
   mapFalError,
+  parseFalError,
   isFalErrorRetryable,
   buildSingleImageInput,
   buildDualImageInput,
@@ -41,12 +42,21 @@ export {
   isImageDataUri,
   uploadToFalStorage,
   uploadMultipleToFalStorage,
-  formatCreditCost,
+  formatNumber,
+  formatCurrency,
+  formatBytes,
+  formatDuration,
+  truncateText,
   truncatePrompt,
   sanitizePrompt,
   buildErrorMessage,
   isDefined,
   removeNullish,
+  generateUniqueId,
+  debounce,
+  throttle,
+  sleep,
+  retry,
 } from "../infrastructure/utils";
 
 export {

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

@@ -10,42 +10,7 @@ import { DEFAULT_FAL_CONFIG } from "./fal-provider.constants";
 import { mapFalStatusToJobStatus } from "./fal-status-mapper";
 import { validateNSFWContent } from "../validators/nsfw-validator";
 import { NSFWContentError } from "./nsfw-content-error";
-
-interface FalApiErrorDetail {
-  msg?: string;
-  type?: string;
-  loc?: string[];
-}
-
-interface FalApiError {
-  body?: { detail?: FalApiErrorDetail[] } | string;
-  message?: string;
-}
-
-/**
- * Parse FAL API error and extract user-friendly message
- */
-function parseFalError(error: unknown): string {
-  const fallback = error instanceof Error ? error.message : String(error);
-
-  const falError = error as FalApiError;
-  if (!falError?.body) return fallback;
-
-  const body = typeof falError.body === "string"
-    ? safeJsonParse(falError.body)
-    : falError.body;
-
-  const detail = body?.detail?.[0];
-  return detail?.msg ?? falError.message ?? fallback;
-}
-
-function safeJsonParse(str: string): { detail?: FalApiErrorDetail[] } | null {
-  try {
-    return JSON.parse(str) as { detail?: FalApiErrorDetail[] };
-  } catch {
-    return null;
-  }
-}
+import { parseFalError } from "../utils/error-mapper";
 
 /**
  * Handle FAL subscription with timeout and cancellation

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

@@ -135,7 +135,7 @@ export class FalProvider implements IAIProvider {
     }).then((res) => res.result).finally(() => removeRequest(key));
 
     // Store promise immediately to prevent race condition
-    storeRequest(key, { promise, abortController });
+    storeRequest(key, { promise, abortController, createdAt: Date.now() });
     return promise;
   }
 

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

@@ -6,6 +6,7 @@
 export interface ActiveRequest<T = unknown> {
   promise: Promise<T>;
   abortController: AbortController;
+  createdAt: number;
 }
 
 const STORE_KEY = "__FAL_PROVIDER_REQUESTS__";
@@ -40,7 +41,11 @@ export function getExistingRequest<T>(key: string): ActiveRequest<T> | undefined
 }
 
 export function storeRequest<T>(key: string, request: ActiveRequest<T>): void {
-  getRequestStore().set(key, request);
+  const requestWithTimestamp = {
+    ...request,
+    createdAt: request.createdAt ?? Date.now(),
+  };
+  getRequestStore().set(key, requestWithTimestamp);
 }
 
 export function removeRequest(key: string): void {
@@ -63,15 +68,41 @@ export function hasActiveRequests(): boolean {
  * Clean up completed/stale requests from the store
  * Should be called periodically to prevent memory leaks
  *
- * Note: This is a placeholder for future implementation.
- * Currently, requests are cleaned up automatically when they complete.
+ * @param maxAge - Maximum age in milliseconds (default: 5 minutes)
+ * @returns Number of requests cleaned up
  */
-export function cleanupRequestStore(_maxAge: number = 300000): void {
+export function cleanupRequestStore(maxAge: number = 300000): number {
   const store = getRequestStore();
+  const now = Date.now();
+  let cleanedCount = 0;
 
-  // Requests are automatically removed when they complete (via finally block)
-  // This function exists for future enhancements like time-based cleanup
+  // Track stale requests
+  const staleKeys: string[] = [];
+
+  for (const [key, request] of store.entries()) {
+    const requestAge = now - request.createdAt;
+
+    // Clean up stale requests that exceed max age
+    if (requestAge > maxAge) {
+      staleKeys.push(key);
+    }
+  }
+
+  // Remove stale requests
+  for (const key of staleKeys) {
+    const request = store.get(key);
+    if (request) {
+      request.abortController.abort();
+      store.delete(key);
+      cleanedCount++;
+    }
+  }
+
+  // Log warning if store size is still large after cleanup
   if (store.size > 50) {
-    // Store size exceeds threshold - indicates potential memory leak
+    // eslint-disable-next-line no-console
+    console.warn(`Request store size (${store.size}) exceeds threshold, potential memory leak detected`);
   }
+
+  return cleanedCount;
 }

package/src/infrastructure/utils/collection-filters.util.ts

@@ -0,0 +1,171 @@
+/**
+ * Collection Filter Utilities
+ * Common filter operations for arrays of objects
+ */
+
+/**
+ * Filter array by property value
+ */
+export function filterByProperty<T>(
+  items: readonly T[],
+  property: keyof T,
+  value: unknown
+): T[] {
+  return items.filter((item) => item[property] === value);
+}
+
+/**
+ * Filter array by predicate function
+ */
+export function filterByPredicate<T>(
+  items: readonly T[],
+  predicate: (item: T) => boolean
+): T[] {
+  return items.filter(predicate);
+}
+
+/**
+ * Filter array by time range (timestamp property)
+ */
+export function filterByTimeRange<T>(
+  items: readonly T[],
+  timestampProperty: keyof T,
+  startTime: number,
+  endTime: number
+): T[] {
+  return items.filter((item) => {
+    const timestamp = item[timestampProperty] as unknown as number;
+    return timestamp >= startTime && timestamp <= endTime;
+  });
+}
+
+/**
+ * Filter array by multiple property values (OR logic)
+ */
+export function filterByAnyProperty<T>(
+  items: readonly T[],
+  property: keyof T,
+  values: readonly unknown[]
+): T[] {
+  const valueSet = new Set(values);
+  return items.filter((item) => valueSet.has(item[property]));
+}
+
+/**
+ * Sort array by date property (descending - newest first)
+ */
+export function sortByDateDescending<T>(
+  items: readonly T[],
+  dateProperty: keyof T
+): T[] {
+  return [...items].sort((a, b) => {
+    const timeA = new Date(a[dateProperty] as unknown as string).getTime();
+    const timeB = new Date(b[dateProperty] as unknown as string).getTime();
+    return timeB - timeA;
+  });
+}
+
+/**
+ * Sort array by date property (ascending - oldest first)
+ */
+export function sortByDateAscending<T>(
+  items: readonly T[],
+  dateProperty: keyof T
+): T[] {
+  return [...items].sort((a, b) => {
+    const timeA = new Date(a[dateProperty] as unknown as string).getTime();
+    const timeB = new Date(b[dateProperty] as unknown as string).getTime();
+    return timeA - timeB;
+  });
+}
+
+/**
+ * Sort array by number property (descending)
+ */
+export function sortByNumberDescending<T>(
+  items: readonly T[],
+  numberProperty: keyof T
+): T[] {
+  return [...items].sort((a, b) => {
+    const numA = a[numberProperty] as unknown as number;
+    const numB = b[numberProperty] as unknown as number;
+    return numB - numA;
+  });
+}
+
+/**
+ * Sort array by number property (ascending)
+ */
+export function sortByNumberAscending<T>(
+  items: readonly T[],
+  numberProperty: keyof T
+): T[] {
+  return [...items].sort((a, b) => {
+    const numA = a[numberProperty] as unknown as number;
+    const numB = b[numberProperty] as unknown as number;
+    return numA - numB;
+  });
+}
+
+/**
+ * Reduce array to sum of number property
+ */
+export function sumByProperty<T>(
+  items: readonly T[],
+  numberProperty: keyof T
+): number {
+  return items.reduce((sum, item) => {
+    const value = item[numberProperty] as unknown as number;
+    return sum + (typeof value === "number" ? value : 0);
+  }, 0);
+}
+
+/**
+ * Group array by property value
+ */
+export function groupByProperty<T>(
+  items: readonly T[],
+  property: keyof T
+): Map<unknown, T[]> {
+  const groups = new Map<unknown, T[]>();
+  for (const item of items) {
+    const key = item[property];
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+
+/**
+ * Chunk array into smaller arrays of specified size
+ */
+export function chunkArray<T>(items: readonly T[], chunkSize: number): T[][] {
+  const result: T[][] = [];
+  for (let i = 0; i < items.length; i += chunkSize) {
+    result.push([...items.slice(i, i + chunkSize)]);
+  }
+  return result;
+}
+
+/**
+ * Get distinct values of a property from array
+ */
+export function distinctByProperty<T>(
+  items: readonly T[],
+  property: keyof T
+): unknown[] {
+  const seen = new Set<unknown>();
+  const result: unknown[] = [];
+  for (const item of items) {
+    const value = item[property];
+    if (!seen.has(value)) {
+      seen.add(value);
+      result.push(value);
+    }
+  }
+  return result;
+}

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

@@ -9,6 +9,7 @@ import type {
   ModelCostInfo,
 } from "../../domain/entities/cost-tracking.types";
 import { findModelById } from "../../domain/constants/default-models.constants";
+import { filterByProperty, filterByTimeRange } from "./collection-filters.util";
 
 interface CostSummary {
   totalEstimatedCost: number;
@@ -29,18 +30,6 @@ function calculateCostSummary(costs: GenerationCost[], currency: string): CostSu
   );
 }
 
-function filterCostsByModel(costs: GenerationCost[], modelId: string): GenerationCost[] {
-  return costs.filter((cost) => cost.model === modelId);
-}
-
-function filterCostsByOperation(costs: GenerationCost[], operation: string): GenerationCost[] {
-  return costs.filter((cost) => cost.operation === operation);
-}
-
-function filterCostsByTimeRange(costs: GenerationCost[], startTime: number, endTime: number): GenerationCost[] {
-  return costs.filter((cost) => cost.timestamp >= startTime && cost.timestamp <= endTime);
-}
-
 export class CostTracker {
   private config: Required<CostTrackerConfig>;
   private costHistory: GenerationCost[] = [];
@@ -161,14 +150,14 @@ export class CostTracker {
   }
 
   getCostsByModel(modelId: string): GenerationCost[] {
-    return filterCostsByModel(this.costHistory, modelId);
+    return filterByProperty(this.costHistory, "model", modelId);
   }
 
   getCostsByOperation(operation: string): GenerationCost[] {
-    return filterCostsByOperation(this.costHistory, operation);
+    return filterByProperty(this.costHistory, "operation", operation);
   }
 
   getCostsByTimeRange(startTime: number, endTime: number): GenerationCost[] {
-    return filterCostsByTimeRange(this.costHistory, startTime, endTime);
+    return filterByTimeRange(this.costHistory, "timestamp", startTime, endTime);
   }
 }

package/src/infrastructure/utils/data-parsers.util.ts

@@ -0,0 +1,191 @@
+/**
+ * Data Parser Utilities
+ * Common patterns for parsing, validating, and transforming data
+ */
+
+/**
+ * Safely parse JSON with fallback
+ */
+export function safeJsonParse<T = unknown>(
+  data: string,
+  fallback: T
+): T {
+  try {
+    return JSON.parse(data) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Safely parse JSON with null fallback
+ */
+export function safeJsonParseOrNull<T = unknown>(data: string): T | null {
+  try {
+    return JSON.parse(data) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safely stringify object with fallback
+ */
+export function safeJsonStringify(
+  data: unknown,
+  fallback: string
+): string {
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Check if string is valid JSON
+ */
+export function isValidJson(data: string): boolean {
+  try {
+    JSON.parse(data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate object structure
+ */
+export function validateObjectStructure<T extends Record<string, unknown>>(
+  data: unknown,
+  requiredKeys: readonly (keyof T)[]
+): data is T {
+  if (!data || typeof data !== "object") {
+    return false;
+  }
+
+  for (const key of requiredKeys) {
+    if (!(key in data)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate array of objects
+ */
+export function validateObjectArray<T>(
+  data: unknown,
+  validator: (item: unknown) => item is T
+): data is T[] {
+  if (!Array.isArray(data)) {
+    return false;
+  }
+
+  return data.every(validator);
+}
+
+/**
+ * Parse number with fallback
+ */
+export function parseNumber(value: unknown, fallback: number): number {
+  if (typeof value === "number") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+
+  return fallback;
+}
+
+/**
+ * Parse boolean with fallback
+ */
+export function parseBoolean(value: unknown, fallback: boolean): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const lower = value.toLowerCase().trim();
+    if (lower === "true" || lower === "yes" || lower === "1") {
+      return true;
+    }
+    if (lower === "false" || lower === "no" || lower === "0") {
+      return false;
+    }
+  }
+
+  if (typeof value === "number") {
+    return value !== 0;
+  }
+
+  return fallback;
+}
+
+/**
+ * Clamp number between min and max
+ */
+export function clampNumber(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Round to decimal places
+ */
+export function roundToDecimals(value: number, decimals: number): number {
+  const multiplier = Math.pow(10, decimals);
+  return Math.round(value * multiplier) / multiplier;
+}
+
+/**
+ * Deep clone object using JSON
+ */
+export function deepClone<T>(data: T): T {
+  return safeJsonParse(safeJsonStringify(data, "{}"), data);
+}
+
+/**
+ * Merge objects with later objects overriding earlier ones
+ */
+export function mergeObjects<T extends Record<string, unknown>>(
+  ...objects: Partial<T>[]
+): T {
+  return Object.assign({}, ...objects) as T;
+}
+
+/**
+ * Pick specified properties from object
+ */
+export function pickProperties<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: readonly K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Omit specified properties from object
+ */
+export function omitProperties<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: readonly K[]
+): Omit<T, K> {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result as Omit<T, K>;
+}

package/src/infrastructure/utils/error-mapper.ts

@@ -4,14 +4,43 @@
 
 import type { FalErrorInfo } from "../../domain/entities/error.types";
 import { categorizeFalError } from "./error-categorizer";
+import { safeJsonParseOrNull } from "./data-parsers.util";
 
 const STATUS_CODES = ["400", "401", "402", "403", "404", "422", "429", "500", "502", "503", "504"];
 
+interface FalApiErrorDetail {
+  msg?: string;
+  type?: string;
+  loc?: string[];
+}
+
+interface FalApiError {
+  body?: { detail?: FalApiErrorDetail[] } | string;
+  message?: string;
+}
+
 function extractStatusCode(errorString: string): number | undefined {
   const code = STATUS_CODES.find((c) => errorString.includes(c));
   return code ? parseInt(code, 10) : undefined;
 }
 
+/**
+ * Parse FAL API error and extract user-friendly message
+ */
+export function parseFalError(error: unknown): string {
+  const fallback = error instanceof Error ? error.message : String(error);
+
+  const falError = error as FalApiError;
+  if (!falError?.body) return fallback;
+
+  const body = typeof falError.body === "string"
+    ? safeJsonParseOrNull<{ detail?: FalApiErrorDetail[] }>(falError.body)
+    : falError.body;
+
+  const detail = body?.detail?.[0];
+  return detail?.msg ?? falError.message ?? fallback;
+}
+
 export function mapFalError(error: unknown): FalErrorInfo {
   const category = categorizeFalError(error);
 

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

@@ -0,0 +1,208 @@
+/**
+ * Formatting Utilities
+ * Common formatting functions for display and data presentation
+ */
+
+/**
+ * Format number with decimal places
+ */
+export function formatNumber(value: number, decimals: number = 2): string {
+  if (Number.isNaN(value) || !Number.isFinite(value)) {
+    return "0";
+  }
+
+  // Return integer if no decimal part
+  if (value % 1 === 0) {
+    return value.toString();
+  }
+
+  return value.toFixed(decimals);
+}
+
+/**
+ * Format currency amount
+ */
+export function formatCurrency(amount: number, currency: string = "USD"): string {
+  const formatted = formatNumber(amount, 2);
+  return `${currency} ${formatted}`;
+}
+
+/**
+ * Format bytes to human-readable size
+ */
+export function formatBytes(bytes: number, decimals: number = 2): string {
+  if (bytes === 0) return "0 Bytes";
+
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string
+ */
+export function formatDuration(milliseconds: number): string {
+  if (milliseconds < 1000) {
+    return `${milliseconds}ms`;
+  }
+
+  const seconds = Math.floor(milliseconds / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return remainingSeconds > 0
+      ? `${minutes}m ${remainingSeconds}s`
+      : `${minutes}m`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes > 0
+    ? `${hours}h ${remainingMinutes}m`
+    : `${hours}h`;
+}
+
+/**
+ * Format percentage
+ */
+export function formatPercentage(value: number, decimals: number = 1): string {
+  if (value < 0) return "0%";
+  if (value > 100) return "100%";
+  return `${formatNumber(value, decimals)}%`;
+}
+
+/**
+ * Format date to locale string
+ */
+export function formatDate(date: Date | string, locale: string = "en-US"): string {
+  const dateObj = typeof date === "string" ? new Date(date) : date;
+  return dateObj.toLocaleDateString(locale, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Format date and time to locale string
+ */
+export function formatDateTime(date: Date | string, locale: string = "en-US"): string {
+  const dateObj = typeof date === "string" ? new Date(date) : date;
+  return dateObj.toLocaleString(locale, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * Format relative time (e.g., "2 hours ago")
+ */
+export function formatRelativeTime(date: Date | string, locale: string = "en-US"): string {
+  const dateObj = typeof date === "string" ? new Date(date) : date;
+  const now = new Date();
+  const diffMs = now.getTime() - dateObj.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+
+  if (diffSec < 60) {
+    return rtf.format(-diffSec, "second");
+  }
+  if (diffMin < 60) {
+    return rtf.format(-diffMin, "minute");
+  }
+  if (diffHour < 24) {
+    return rtf.format(-diffHour, "hour");
+  }
+  if (diffDay < 30) {
+    return rtf.format(-diffDay, "day");
+  }
+  if (diffDay < 365) {
+    const months = Math.floor(diffDay / 30);
+    return rtf.format(-months, "month");
+  }
+  const years = Math.floor(diffDay / 365);
+  return rtf.format(-years, "year");
+}
+
+/**
+ * Truncate text with ellipsis
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Capitalize first letter of string
+ */
+export function capitalize(text: string): string {
+  if (!text) return text;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+/**
+ * Convert string to title case
+ */
+export function toTitleCase(text: string): string {
+  return text
+    .toLowerCase()
+    .split(" ")
+    .map((word) => capitalize(word))
+    .join(" ");
+}
+
+/**
+ * Convert string to slug
+ */
+export function toSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/[\s_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Format list of items with conjunction
+ */
+export function formatList(items: readonly string[], conjunction: string = "and"): string {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0] ?? "";
+  if (items.length === 2) return items.join(` ${conjunction} `);
+
+  const allButLast = items.slice(0, -1);
+  const last = items[items.length - 1];
+  return `${allButLast.join(", ")}, ${conjunction} ${last}`;
+}
+
+/**
+ * Pluralize word based on count
+ */
+export function pluralize(word: string, count: number): string {
+  if (count === 1) return word;
+  return `${word}s`;
+}
+
+/**
+ * Format count with plural word
+ */
+export function formatCount(word: string, count: number): string {
+  return `${count} ${pluralize(word, count)}`;
+}

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

@@ -3,16 +3,6 @@
  * 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
  */
@@ -43,3 +33,118 @@ export function removeNullish<T extends Record<string, unknown>>(
     Object.entries(obj).filter(([_, value]) => isDefined(value))
   ) as Partial<T>;
 }
+
+/**
+ * Generate unique ID
+ */
+export function generateUniqueId(prefix: string = ""): string {
+  const timestamp = Date.now().toString(36);
+  const randomStr = Math.random().toString(36).substring(2, 9);
+  return prefix ? `${prefix}_${timestamp}${randomStr}` : `${timestamp}${randomStr}`;
+}
+
+/**
+ * Create debounced function
+ */
+export function debounce<T extends (...args: never[]) => void>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  return function debounced(...args: Parameters<T>) {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      func(...args);
+    }, wait);
+  };
+}
+
+/**
+ * Create throttled function
+ */
+export function throttle<T extends (...args: never[]) => void>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle = false;
+
+  return function throttled(...args: Parameters<T>) {
+    if (!inThrottle) {
+      func(...args);
+      inThrottle = true;
+      setTimeout(() => {
+        inThrottle = false;
+      }, limit);
+    }
+  };
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry function with exponential backoff
+ */
+export async function retry<T>(
+  func: () => Promise<T>,
+  options: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown) => boolean;
+  } = {}
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    maxDelay = 10000,
+    shouldRetry = () => true,
+  } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await func();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxRetries || !shouldRetry(error)) {
+        throw error;
+      }
+
+      const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * No-op function
+ */
+export function noop(): void {
+  // Intentionally empty
+}
+
+/**
+ * Identity function
+ */
+export function identity<T>(value: T): T {
+  return value;
+}
+
+/**
+ * Constant function (returns same value regardless of input)
+ */
+export function constant<T>(value: T): () => T {
+  return () => value;
+}

package/src/infrastructure/utils/index.ts

@@ -2,12 +2,63 @@
  * Utils Index
  */
 
+export {
+  filterByProperty,
+  filterByPredicate,
+  filterByTimeRange,
+  filterByAnyProperty,
+  sortByDateDescending,
+  sortByDateAscending,
+  sortByNumberDescending,
+  sortByNumberAscending,
+  sumByProperty,
+  groupByProperty,
+  chunkArray,
+  distinctByProperty,
+} from "./collection-filters.util";
+
+export {
+  safeJsonParse,
+  safeJsonParseOrNull,
+  safeJsonStringify,
+  isValidJson,
+  validateObjectStructure,
+  validateObjectArray,
+  parseNumber,
+  parseBoolean,
+  clampNumber,
+  roundToDecimals,
+  deepClone,
+  mergeObjects,
+  pickProperties,
+  omitProperties,
+} from "./data-parsers.util";
+
 export { categorizeFalError } from "./error-categorizer";
 export {
   mapFalError,
+  parseFalError,
   isFalErrorRetryable,
 } from "./error-mapper";
 
+export {
+  formatNumber,
+  formatCurrency,
+  formatBytes,
+  formatDuration,
+  formatPercentage,
+  formatDate,
+  formatDateTime,
+  formatRelativeTime,
+  truncateText,
+  capitalize,
+  toTitleCase,
+  toSlug,
+  formatList,
+  pluralize,
+  formatCount,
+} from "./formatting.util";
+
 export {
   buildSingleImageInput,
   buildDualImageInput,
@@ -43,10 +94,17 @@ export {
 } from "./prompt-helpers.util";
 
 export {
-  formatCreditCost,
   buildErrorMessage,
   isDefined,
   removeNullish,
+  generateUniqueId,
+  debounce,
+  throttle,
+  sleep,
+  retry,
+  noop,
+  identity,
+  constant,
 } from "./general-helpers.util";
 
 export {

package/src/infrastructure/utils/job-metadata/job-metadata-queries.util.ts

@@ -5,6 +5,8 @@
 
 import type { FalJobMetadata } from "./job-metadata.types";
 import { isJobStale, isJobRunning, isJobCompleted } from "./job-metadata-lifecycle.util";
+import { sortByDateDescending, filterByPredicate } from "../collection-filters.util";
+import { safeJsonParseOrNull, validateObjectStructure } from "../data-parsers.util";
 
 /**
  * Serialize job metadata for storage
@@ -17,55 +19,39 @@ export function serializeJobMetadata(metadata: FalJobMetadata): string {
  * Deserialize job metadata from storage
  */
 export function deserializeJobMetadata(data: string): FalJobMetadata | null {
-  try {
-    const parsed = JSON.parse(data) as Record<string, unknown>;
-    // Validate structure
-    if (!parsed || typeof parsed !== 'object') {
-      // eslint-disable-next-line no-console
-      console.warn('Invalid job metadata: not an object', data);
-      return null;
-    }
-    if (!parsed.requestId || !parsed.model || !parsed.status) {
-      // eslint-disable-next-line no-console
-      console.warn('Invalid job metadata: missing required fields', data);
-      return null;
-    }
-    return parsed as unknown as FalJobMetadata;
-  } catch (error) {
-    // eslint-disable-next-line no-console
-    console.error('Failed to deserialize job metadata:', error, 'Data:', data);
+  const parsed = safeJsonParseOrNull<Record<string, unknown>>(data);
+
+  if (!parsed || !validateObjectStructure<Partial<FalJobMetadata>>(parsed, ["requestId", "model", "status"] as const)) {
     return null;
   }
+
+  return parsed as FalJobMetadata;
 }
 
 /**
  * Filter valid job metadata from array
  */
 export function filterValidJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
-  return jobs.filter((job) => !isJobStale(job));
+  return filterByPredicate(jobs, (job) => !isJobStale(job));
 }
 
 /**
  * Sort jobs by creation time (newest first)
  */
 export function sortJobsByCreation(jobs: FalJobMetadata[]): FalJobMetadata[] {
-  return [...jobs].sort((a, b) => {
-    const timeA = new Date(a.createdAt).getTime();
-    const timeB = new Date(b.createdAt).getTime();
-    return timeB - timeA;
-  });
+  return sortByDateDescending(jobs, "createdAt");
 }
 
 /**
  * Get active jobs (not completed and not stale)
  */
 export function getActiveJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
-  return jobs.filter((job) => isJobRunning(job) && !isJobStale(job));
+  return filterByPredicate(jobs, (job) => isJobRunning(job) && !isJobStale(job));
 }
 
 /**
  * Get completed jobs
  */
 export function getCompletedJobs(jobs: FalJobMetadata[]): FalJobMetadata[] {
-  return jobs.filter((job) => isJobCompleted(job));
+  return filterByPredicate(jobs, isJobCompleted);
 }

package/src/infrastructure/utils/job-storage/job-storage-crud.util.ts

@@ -6,6 +6,7 @@
 import type { FalJobMetadata } from "../job-metadata";
 import { updateJobMetadata } from "../job-metadata";
 import type { IJobStorage } from "./job-storage-interface";
+import { safeJsonParseOrNull, safeJsonStringify } from "../data-parsers.util";
 
 /**
  * Save job metadata to storage
@@ -15,7 +16,7 @@ export async function saveJobMetadata(
   metadata: FalJobMetadata
 ): Promise<void> {
   const key = `fal_job:${metadata.requestId}`;
-  const value = JSON.stringify(metadata);
+  const value = safeJsonStringify(metadata, "{}");
   await storage.setItem(key, value);
 }
 
@@ -30,11 +31,7 @@ export async function loadJobMetadata(
   const value = await storage.getItem(key);
   if (!value) return null;
 
-  try {
-    return JSON.parse(value) as FalJobMetadata;
-  } catch {
-    return null;
-  }
+  return safeJsonParseOrNull<FalJobMetadata>(value);
 }
 
 /**

package/src/infrastructure/utils/job-storage/job-storage-queries.util.ts

@@ -6,6 +6,7 @@
 import type { FalJobMetadata } from "../job-metadata";
 import type { IJobStorage } from "./job-storage-interface";
 import { deleteJobMetadata } from "./job-storage-crud.util";
+import { safeJsonParseOrNull } from "../data-parsers.util";
 
 /**
  * Load all jobs from storage
@@ -24,12 +25,9 @@ export async function loadAllJobs(
   for (const key of jobKeys) {
     const value = await storage.getItem(key);
     if (value) {
-      try {
-        const metadata = JSON.parse(value) as FalJobMetadata;
+      const metadata = safeJsonParseOrNull<FalJobMetadata>(value);
+      if (metadata) {
         jobs.push(metadata);
-      } catch {
-        // Skip invalid entries
-        continue;
       }
     }
   }