@umituz/react-native-ai-fal-provider 2.0.37 → 2.0.39

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

@@ -1,191 +1,9 @@
 /**
  * Data Parser Utilities
- * Common patterns for parsing, validating, and transforming data
+ * @deprecated This file is now split into smaller modules for better maintainability.
+ * Import from './parsers' submodules instead.
+ *
+ * This file re-exports all functions for backward compatibility.
  */
 
-/**
- * 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>;
-}
+export * from './parsers';

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

@@ -1,8 +1,18 @@
 /**
  * FAL Error Mapper - Maps errors to user-friendly info
  *
+ * @deprecated This module is a re-export for backward compatibility.
+ * Import directly from './fal-error-handler.util' instead.
+ *
  * This module re-exports error handling functions from the unified
  * fal-error-handler.util module for backward compatibility.
+ *
+ * @example
+ * // Instead of:
+ * import { mapFalError } from './error-mapper';
+ *
+ * // Use:
+ * import { mapFalError } from './fal-error-handler.util';
  */
 
 export {

package/src/infrastructure/utils/fal-error-handler.util.ts

@@ -94,34 +94,37 @@ function categorizeError(error: unknown): FalErrorCategory {
 }
 
 /**
- * Map error to FalErrorInfo with full error details
+ * Build FalErrorInfo from error string and category
  */
-export function mapFalError(error: unknown): FalErrorInfo {
-  const category = categorizeError(error);
-
-  if (error instanceof Error) {
-    return {
-      type: category.type,
-      messageKey: `fal.errors.${category.messageKey}`,
-      retryable: category.retryable,
-      originalError: error.message,
-      originalErrorName: error.name,
-      stack: error.stack,
-      statusCode: extractStatusCode(error.message),
-    };
-  }
-
-  const errorString = String(error);
-
+function buildErrorInfo(
+  category: FalErrorCategory,
+  errorString: string,
+  errorInstance?: Error
+): FalErrorInfo {
   return {
     type: category.type,
     messageKey: `fal.errors.${category.messageKey}`,
     retryable: category.retryable,
     originalError: errorString,
+    originalErrorName: errorInstance?.name,
+    stack: errorInstance?.stack,
     statusCode: extractStatusCode(errorString),
   };
 }
 
+/**
+ * Map error to FalErrorInfo with full error details
+ */
+export function mapFalError(error: unknown): FalErrorInfo {
+  const category = categorizeError(error);
+
+  if (error instanceof Error) {
+    return buildErrorInfo(category, error.message, error);
+  }
+
+  return buildErrorInfo(category, String(error));
+}
+
 /**
  * Parse FAL error and return user-friendly message
  */

package/src/infrastructure/utils/fal-generation-state-manager.util.ts

@@ -25,6 +25,7 @@ export class FalGenerationStateManager<T> {
   private isMounted = true;
   private currentRequestId: string | null = null;
   private lastRequest: { endpoint: string; input: FalJobInput } | null = null;
+  private lastNotifiedStatus: string | null = null; // Track last status to prevent duplicate callbacks
 
   constructor(
     private options?: GenerationStateOptions<T>
@@ -57,6 +58,7 @@ export class FalGenerationStateManager<T> {
   clearLastRequest(): void {
     this.lastRequest = null;
     this.currentRequestId = null;
+    this.lastNotifiedStatus = null;
   }
 
   handleQueueUpdate(status: FalQueueStatus): void {
@@ -77,8 +79,13 @@ export class FalGenerationStateManager<T> {
       queuePosition: status.queuePosition,
     };
 
-    this.options?.onQueueUpdate?.(normalizedStatus);
-    this.options?.onProgress?.(normalizedStatus);
+    // Only notify if status actually changed (idempotent callbacks)
+    const statusKey = `${normalizedStatus.status}-${normalizedStatus.requestId}`;
+    if (this.lastNotifiedStatus !== statusKey) {
+      this.lastNotifiedStatus = statusKey;
+      this.options?.onQueueUpdate?.(normalizedStatus);
+      this.options?.onProgress?.(normalizedStatus);
+    }
   }
 
   handleResult(result: T): void {

package/src/infrastructure/utils/fal-storage.util.ts

@@ -30,8 +30,13 @@ export async function uploadToFalStorage(base64: string): Promise<string> {
     try {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-call
       await deleteTempFile(tempUri);
-    } catch {
-      // Silently ignore cleanup errors
+    } catch (cleanupError) {
+      // Log cleanup errors to prevent disk space leaks
+      console.warn(
+        `[fal-storage] Failed to delete temp file: ${tempUri}`,
+        cleanupError instanceof Error ? cleanupError.message : String(cleanupError)
+      );
+      // Don't throw - cleanup errors shouldn't fail the upload
     }
   }
 }

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

@@ -1,150 +1,9 @@
 /**
  * General Helper Utilities
- * Common utility functions
+ * @deprecated This file is now split into smaller modules for better maintainability.
+ * Import from './helpers' submodules instead.
+ *
+ * This file re-exports all functions for backward compatibility.
  */
 
-/**
- * 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>;
-}
-
-/**
- * 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;
-}
+export * from './helpers';

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

@@ -0,0 +1,25 @@
+/**
+ * Function Helper Utilities
+ * Common functional programming helpers
+ */
+
+/**
+ * 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/helpers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Helper Utilities - Centralized Exports
+ * Re-exports all helper utilities from submodules
+ */
+
+export * from './timing-helpers.util';
+export * from './object-helpers.util';
+export * from './function-helpers.util';

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

@@ -0,0 +1,44 @@
+/**
+ * Object Helper Utilities
+ * Object manipulation and validation helpers
+ */
+
+/**
+ * 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>;
+}
+
+/**
+ * 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}`;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Timing Helper Utilities
+ * Debounce, throttle, sleep, and retry operations
+ */
+
+/**
+ * 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;
+}

package/src/infrastructure/utils/input-preprocessor.util.ts

@@ -38,9 +38,12 @@ export async function preprocessInput(
       const uploadPromise = uploadToFalStorage(value)
         .then((url) => {
           result[key] = url;
+          return url;
         })
         .catch((error) => {
-          throw new Error(`Failed to upload ${key}: ${error instanceof Error ? error.message : "Unknown error"}`);
+          const errorMessage = `Failed to upload ${key}: ${error instanceof Error ? error.message : "Unknown error"}`;
+          console.error(`[preprocessInput] ${errorMessage}`);
+          throw new Error(errorMessage);
         });
 
       uploadPromises.push(uploadPromise);
@@ -62,11 +65,14 @@ export async function preprocessInput(
       }
 
       if (isBase64DataUri(imageUrl)) {
-        const uploadPromise = uploadToFalStorage(imageUrl).catch((error) => {
-          const errorMessage = `Failed to upload image_urls[${i}]: ${error instanceof Error ? error.message : "Unknown error"}`;
-          errors.push(errorMessage);
-          throw new Error(errorMessage);
-        });
+        const uploadPromise = uploadToFalStorage(imageUrl)
+          .then((url) => url)
+          .catch((error) => {
+            const errorMessage = `Failed to upload image_urls[${i}]: ${error instanceof Error ? error.message : "Unknown error"}`;
+            console.error(`[preprocessInput] ${errorMessage}`);
+            errors.push(errorMessage);
+            throw new Error(errorMessage);
+          });
         uploadTasks.push({ index: i, url: uploadPromise });
       } else if (typeof imageUrl === "string") {
         uploadTasks.push({ index: i, url: imageUrl });