@umituz/react-native-ai-fal-provider 2.1.8 → 2.1.10

package/package.json

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

package/src/exports/infrastructure.ts

@@ -21,6 +21,35 @@ export {
   buildDualImageInput,
 } from "../infrastructure/utils";
 
+// Error handling utilities
+export {
+  getErrorMessage,
+  getErrorMessageOr,
+  formatErrorMessage,
+} from "../infrastructure/utils/helpers/error-helpers.util";
+
+// Image field constants
+export {
+  IMAGE_URL_FIELDS,
+  isImageField,
+} from "../infrastructure/utils/constants/image-fields.constants";
+export type {
+  ImageUrlField,
+} from "../infrastructure/utils/constants/image-fields.constants";
+
+// Validators
+export {
+  isDataUri,
+  isBase64DataUri,
+  extractMimeType,
+  extractBase64Content,
+} from "../infrastructure/utils/validators/data-uri-validator.util";
+export {
+  isEmptyString,
+  isNonEmptyString,
+  isString,
+} from "../infrastructure/utils/validators/string-validator.util";
+
 export { CostTracker } from "../infrastructure/utils/cost-tracker";
 
 export {
@@ -39,7 +68,6 @@ export {
   formatImageDataUri,
   extractBase64,
   getDataUriExtension,
-  isImageDataUri,
   uploadToFalStorage,
   uploadMultipleToFalStorage,
   formatNumber,

package/src/infrastructure/utils/constants/image-fields.constants.ts

@@ -0,0 +1,59 @@
+/**
+ * Image Field Constants
+ * Single source of truth for all image-related field names
+ *
+ * CRITICAL: This file consolidates image field names that were previously
+ * duplicated and inconsistent across the codebase:
+ * - input-validator.util.ts had 5 fields
+ * - input-preprocessor.util.ts had 9 fields
+ *
+ * All image field definitions must be maintained here to prevent future inconsistencies.
+ */
+
+/**
+ * All supported image URL field names across the FAL AI API
+ * Used for preprocessing (base64 to URL conversion) and validation
+ *
+ * @example
+ * ```typescript
+ * for (const field of IMAGE_URL_FIELDS) {
+ *   if (field in input && isBase64(input[field])) {
+ *     input[field] = await uploadToStorage(input[field]);
+ *   }
+ * }
+ * ```
+ */
+export const IMAGE_URL_FIELDS = [
+  "image_url",
+  "second_image_url",
+  "third_image_url",
+  "fourth_image_url",
+  "base_image_url",
+  "swap_image_url",
+  "driver_image_url",
+  "mask_url",
+  "input_image_url",
+] as const;
+
+/**
+ * Type-safe image URL field names
+ */
+export type ImageUrlField = typeof IMAGE_URL_FIELDS[number];
+
+/**
+ * Check if a field name is a known image field
+ *
+ * @param fieldName - The field name to check
+ * @returns Type guard indicating if the field is an ImageUrlField
+ *
+ * @example
+ * ```typescript
+ * if (isImageField(fieldName)) {
+ *   // TypeScript knows fieldName is ImageUrlField here
+ *   console.log(`Processing image field: ${fieldName}`);
+ * }
+ * ```
+ */
+export function isImageField(fieldName: string): fieldName is ImageUrlField {
+  return IMAGE_URL_FIELDS.includes(fieldName as ImageUrlField);
+}

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

@@ -10,6 +10,7 @@ import type {
 } from "../../domain/entities/cost-tracking.types";
 import { findModelById } from "../../domain/constants/default-models.constants";
 import { filterByProperty, filterByTimeRange } from "./collections";
+import { getErrorMessage } from './helpers/error-helpers.util';
 
 export type { GenerationCost } from "../../domain/entities/cost-tracking.types";
 
@@ -61,7 +62,7 @@ export class CostTracker {
       // Log error but continue with default cost info
       console.warn(
         `[cost-tracker] Failed to get model cost info for ${modelId}:`,
-        error instanceof Error ? error.message : String(error)
+        getErrorMessage(error)
       );
     }
 

package/src/infrastructure/utils/cost-tracking-executor.util.ts

@@ -4,6 +4,7 @@
  */
 
 import type { CostTracker } from "./cost-tracker";
+import { getErrorMessage } from './helpers/error-helpers.util';
 
 interface ExecuteWithCostTrackingOptions<T> {
   tracker: CostTracker | null;
@@ -39,7 +40,7 @@ export async function executeWithCostTracking<T>(
       // Log for debugging and audit trail
       console.error(
         `[cost-tracking] Failed to complete cost tracking for ${operation} on ${model}:`,
-        costError instanceof Error ? costError.message : String(costError),
+        getErrorMessage(costError),
         { operationId, model, operation }
       );
     }
@@ -53,7 +54,7 @@ export async function executeWithCostTracking<T>(
       // Log for debugging and audit trail
       console.error(
         `[cost-tracking] Failed to mark operation as failed for ${operation} on ${model}:`,
-        failError instanceof Error ? failError.message : String(failError),
+        getErrorMessage(failError),
         { operationId, model, operation }
       );
     }

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

@@ -6,6 +6,7 @@
 import type { FalErrorInfo, FalErrorCategory, FalErrorType } from "../../domain/entities/error.types";
 import { FalErrorType as ErrorTypeEnum } from "../../domain/entities/error.types";
 import { safeJsonParseOrNull } from "./parsers";
+import { isNonEmptyString } from './validators/string-validator.util';
 
 const STATUS_CODES = ["400", "401", "402", "403", "404", "422", "429", "500", "502", "503", "504"];
 
@@ -130,7 +131,7 @@ export function mapFalError(error: unknown): FalErrorInfo {
  */
 export function parseFalError(error: unknown): string {
   const userMessage = parseFalApiError(error);
-  if (!userMessage || userMessage.trim().length === 0) {
+  if (!isNonEmptyString(userMessage)) {
     return "An unknown error occurred. Please try again.";
   }
   return userMessage;

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

@@ -8,6 +8,7 @@ import {
   base64ToTempFile,
   deleteTempFile,
 } from "@umituz/react-native-design-system/filesystem";
+import { getErrorMessage } from './helpers/error-helpers.util';
 
 /**
  * Upload base64 image to FAL storage
@@ -34,7 +35,7 @@ export async function uploadToFalStorage(base64: string): Promise<string> {
       // 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)
+        getErrorMessage(cleanupError)
       );
       // Don't throw - cleanup errors shouldn't fail the upload
     }
@@ -68,7 +69,7 @@ export async function uploadMultipleToFalStorage(
   if (failures.length > 0) {
     const errorMessage = failures
       .map(({ index, error }) =>
-        `Image ${index}: ${error instanceof Error ? error.message : String(error)}`
+        `Image ${index}: ${getErrorMessage(error)}`
       )
       .join('; ');
 

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

@@ -0,0 +1,86 @@
+/**
+ * Error Helper Utilities
+ * Centralized error message extraction and formatting
+ *
+ * This utility eliminates the repeated pattern:
+ * `error instanceof Error ? error.message : String(error)`
+ * which appeared 8 times across 6 files in the codebase.
+ */
+
+/**
+ * Extract error message from any error type
+ * Handles Error instances, strings, and unknown types
+ *
+ * @param error - The error to extract message from
+ * @returns The error message as a string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   console.error('Operation failed:', getErrorMessage(error));
+ * }
+ * ```
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Extract error message with fallback
+ * Returns fallback if error message is empty or whitespace-only
+ *
+ * @param error - The error to extract message from
+ * @param fallback - Fallback message if error message is empty
+ * @returns The error message or fallback
+ *
+ * @example
+ * ```typescript
+ * const message = getErrorMessageOr(error, 'An unknown error occurred');
+ * ```
+ */
+export function getErrorMessageOr(error: unknown, fallback: string): string {
+  const message = getErrorMessage(error);
+  return message && message.trim().length > 0 ? message : fallback;
+}
+
+/**
+ * Create error message with context prefix
+ * Useful for adding operation context to error messages
+ *
+ * @param error - The error to extract message from
+ * @param context - Context to prepend to the error message
+ * @returns Formatted error message with context
+ *
+ * @example
+ * ```typescript
+ * throw new Error(formatErrorMessage(error, 'Failed to upload image'));
+ * // Output: "Failed to upload image: Network timeout"
+ * ```
+ */
+export function formatErrorMessage(error: unknown, context: string): string {
+  return `${context}: ${getErrorMessage(error)}`;
+}
+
+/**
+ * Extract error name (for Error instances)
+ * Returns undefined for non-Error types
+ *
+ * @param error - The error to extract name from
+ * @returns The error name or undefined
+ */
+export function getErrorName(error: unknown): string | undefined {
+  return error instanceof Error ? error.name : undefined;
+}
+
+/**
+ * Extract error stack trace
+ * Returns undefined for non-Error types
+ *
+ * @param error - The error to extract stack from
+ * @returns The error stack trace or undefined
+ */
+export function getErrorStack(error: unknown): string | undefined {
+  return error instanceof Error ? error.stack : undefined;
+}

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

@@ -45,10 +45,3 @@ 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/index.ts

@@ -31,7 +31,7 @@ export {
 
 export { formatDate } from "./date-format.util";
 export { formatNumber, formatBytes, formatDuration } from "./number-format.util";
-export { truncateText } from "./string-format.util";
+export { truncateText, truncatePrompt, sanitizePrompt } from "./string-format.util";
 
 export {
   buildSingleImageInput,
@@ -54,7 +54,6 @@ export {
   formatImageDataUri,
   extractBase64,
   getDataUriExtension,
-  isImageDataUri,
 } from "./image-helpers.util";
 
 export {
@@ -62,11 +61,6 @@ export {
   uploadMultipleToFalStorage,
 } from "./fal-storage.util";
 
-export {
-  truncatePrompt,
-  sanitizePrompt,
-} from "./prompt-helpers.util";
-
 export {
   buildErrorMessage,
   isDefined,

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

@@ -4,22 +4,9 @@
  */
 
 import { uploadToFalStorage } from "./fal-storage.util";
-
-const IMAGE_URL_KEYS = [
-  "image_url",
-  "second_image_url",
-  "third_image_url",
-  "fourth_image_url",
-  "driver_image_url",
-  "base_image_url",
-  "swap_image_url",
-  "mask_url",
-  "input_image_url",
-];
-
-function isBase64DataUri(value: unknown): value is string {
-  return typeof value === "string" && value.startsWith("data:image/");
-}
+import { getErrorMessage } from './helpers/error-helpers.util';
+import { IMAGE_URL_FIELDS } from './constants/image-fields.constants';
+import { isImageDataUri as isBase64DataUri } from './validators/data-uri-validator.util';
 
 /**
  * Preprocess input by uploading base64 images to FAL storage
@@ -32,7 +19,7 @@ export async function preprocessInput(
   const uploadPromises: Promise<unknown>[] = [];
 
   // Handle individual image URL keys
-  for (const key of IMAGE_URL_KEYS) {
+  for (const key of IMAGE_URL_FIELDS) {
     const value = result[key];
     if (isBase64DataUri(value)) {
       const uploadPromise = uploadToFalStorage(value)
@@ -41,7 +28,7 @@ export async function preprocessInput(
           return url;
         })
         .catch((error) => {
-          const errorMessage = `Failed to upload ${key}: ${error instanceof Error ? error.message : "Unknown error"}`;
+          const errorMessage = `Failed to upload ${key}: ${getErrorMessage(error)}`;
           console.error(`[preprocessInput] ${errorMessage}`);
           throw new Error(errorMessage);
         });
@@ -68,7 +55,7 @@ export async function preprocessInput(
         const uploadPromise = uploadToFalStorage(imageUrl)
           .then((url) => url)
           .catch((error) => {
-            const errorMessage = `Failed to upload image_urls[${i}]: ${error instanceof Error ? error.message : "Unknown error"}`;
+            const errorMessage = `Failed to upload image_urls[${i}]: ${getErrorMessage(error)}`;
             console.error(`[preprocessInput] ${errorMessage}`);
             errors.push(errorMessage);
             throw new Error(errorMessage);
@@ -104,7 +91,7 @@ export async function preprocessInput(
         processedUrls.push(result.value);
       } else {
         uploadErrors.push(
-          `Upload ${index} failed: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`
+          `Upload ${index} failed: ${getErrorMessage(result.reason)}`
         );
       }
     });
@@ -139,7 +126,7 @@ export async function preprocessInput(
 
       const errorMessages = failedUploads.map((result) =>
         result.status === 'rejected'
-          ? (result.reason instanceof Error ? result.reason.message : String(result.reason))
+          ? (getErrorMessage(result.reason))
           : 'Unknown error'
       );
 

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

@@ -4,6 +4,9 @@
  */
 
 import { isValidModelId, isValidPrompt } from "./type-guards";
+import { IMAGE_URL_FIELDS } from './constants/image-fields.constants';
+import { isImageDataUri } from './validators/data-uri-validator.util';
+import { isNonEmptyString } from './validators/string-validator.util';
 
 /**
  * Detect potentially malicious content in strings
@@ -49,7 +52,7 @@ function isValidAndSafeUrl(value: string): boolean {
   }
 
   // Allow base64 image data URIs only
-  if (value.startsWith('data:image/')) {
+  if (isImageDataUri(value)) {
     // Check for suspicious content in data URI
     const dataContent = value.substring(0, 200); // Check first 200 chars
     if (hasSuspiciousContent(dataContent)) {
@@ -134,16 +137,8 @@ export function validateInput(
     }
   }
 
-  // Validate image_url fields if present
-  const imageFields = [
-    "image_url",
-    "second_image_url",
-    "base_image_url",
-    "swap_image_url",
-    "mask_url",
-  ];
-
-  for (const field of imageFields) {
+  // Validate all image_url fields
+  for (const field of IMAGE_URL_FIELDS) {
     const value = input[field];
     if (value !== undefined) {
       if (typeof value !== "string") {
@@ -151,7 +146,7 @@ export function validateInput(
           field,
           message: `${field} must be a string`,
         });
-      } else if (!value || value.trim().length === 0) {
+      } else if (!isNonEmptyString(value)) {
         // Explicitly check for empty/whitespace-only strings
         errors.push({
           field,

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

@@ -3,6 +3,8 @@
  * Safe JSON parsing and validation operations
  */
 
+import { getErrorMessage } from '../helpers/error-helpers.util';
+
 /**
  * Safely parse JSON with fallback
  */
@@ -15,7 +17,7 @@ export function safeJsonParse<T = unknown>(
   } catch (error) {
     console.warn(
       '[json-parsers] Failed to parse JSON, using fallback:',
-      error instanceof Error ? error.message : String(error),
+      getErrorMessage(error),
       { dataPreview: data.substring(0, 100) }
     );
     return fallback;
@@ -31,7 +33,7 @@ export function safeJsonParseOrNull<T = unknown>(data: string): T | null {
   } catch (error) {
     console.warn(
       '[json-parsers] Failed to parse JSON, returning null:',
-      error instanceof Error ? error.message : String(error),
+      getErrorMessage(error),
       { dataPreview: data.substring(0, 100) }
     );
     return null;
@@ -50,7 +52,7 @@ export function safeJsonStringify(
   } catch (error) {
     console.warn(
       '[json-parsers] Failed to stringify object, using fallback:',
-      error instanceof Error ? error.message : String(error),
+      getErrorMessage(error),
       { dataType: typeof data }
     );
     return fallback;

package/src/infrastructure/utils/parsers/object-transformers.util.ts

@@ -3,6 +3,8 @@
  * Clone, merge, pick, and omit operations
  */
 
+import { getErrorMessage } from '../helpers/error-helpers.util';
+
 /**
  * Deep clone object using JSON serialization
  * NOTE: This has limitations:
@@ -20,7 +22,7 @@ export function deepClone<T>(data: T): T {
     // Fallback for circular references or other JSON errors
     console.warn(
       '[object-transformers] deepClone failed, returning original:',
-      error instanceof Error ? error.message : String(error)
+      getErrorMessage(error)
     );
     // Return original data if cloning fails
     return data;

package/src/infrastructure/utils/string-format.util.ts

@@ -1,14 +1,72 @@
 /**
  * String Formatting Utilities
  * Functions for formatting and manipulating strings
+ *
+ * Consolidates text truncation and prompt sanitization utilities.
+ * Previously duplicated across string-format.util.ts and prompt-helpers.util.ts.
  */
 
 /**
- * Truncate text with ellipsis
+ * Truncate text with customizable ellipsis
+ *
+ * @param text - The text to truncate
+ * @param maxLength - Maximum length including ellipsis
+ * @param ellipsis - String to append when truncating (default: "...")
+ * @returns Truncated text with ellipsis or original if under max length
+ *
+ * @example
+ * ```typescript
+ * truncateText("Hello World", 8); // "Hello..."
+ * truncateText("Hello World", 8, "…"); // "Hello W…"
+ * ```
  */
-export function truncateText(text: string, maxLength: number): string {
+export function truncateText(
+  text: string,
+  maxLength: number,
+  ellipsis: string = "..."
+): string {
   if (text.length <= maxLength) {
     return text;
   }
-  return text.slice(0, maxLength - 3) + "...";
+  return text.slice(0, maxLength - ellipsis.length) + ellipsis;
+}
+
+/**
+ * Truncate prompt to maximum length
+ * Specialized wrapper for prompt truncation with 5000 char default
+ *
+ * @param prompt - The prompt text to truncate
+ * @param maxLength - Maximum length (default: 5000)
+ * @returns Truncated prompt
+ *
+ * @example
+ * ```typescript
+ * truncatePrompt(longPrompt); // Truncates to 5000 chars
+ * truncatePrompt(longPrompt, 1000); // Truncates to 1000 chars
+ * ```
+ */
+export function truncatePrompt(prompt: string, maxLength: number = 5000): string {
+  return truncateText(prompt, maxLength);
+}
+
+/**
+ * Sanitize prompt by removing excessive whitespace and control characters
+ * Also enforces maximum length of 5000 characters
+ *
+ * @param prompt - The prompt text to sanitize
+ * @returns Sanitized prompt
+ *
+ * @example
+ * ```typescript
+ * sanitizePrompt("Hello  \n\n  World\x00"); // "Hello World"
+ * ```
+ */
+export function sanitizePrompt(prompt: string): string {
+  return prompt
+    .trim()
+    .replace(/\s+/g, " ")
+    // Remove control characters except tab, newline, carriage return
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, '')
+    .slice(0, 5000);
 }

package/src/infrastructure/utils/type-guards/validation-guards.util.ts

@@ -10,6 +10,7 @@ import {
   MAX_TIMEOUT_MS,
   MAX_RETRY_COUNT,
 } from './constants';
+import { isNonEmptyString } from '../validators/string-validator.util';
 
 /**
  * Validate base64 image string
@@ -19,7 +20,7 @@ export function isValidBase64Image(value: unknown): boolean {
     return false;
   }
 
-  // Check data URI prefix
+  // Check data URI prefix - use direct check instead of type guard to avoid type narrowing issues
   if (value.startsWith("data:image/")) {
     const base64Part = value.split("base64,")[1];
     if (!base64Part) return false;
@@ -67,7 +68,9 @@ export function isValidModelId(value: unknown): boolean {
  * Validate prompt string
  */
 export function isValidPrompt(value: unknown): boolean {
-  return typeof value === "string" && value.trim().length > 0 && value.length <= MAX_PROMPT_LENGTH;
+  // Use type guard first, then check length
+  if (!isNonEmptyString(value)) return false;
+  return value.length <= MAX_PROMPT_LENGTH;
 }
 
 /**

package/src/infrastructure/utils/validators/data-uri-validator.util.ts

@@ -0,0 +1,91 @@
+/**
+ * Data URI Validation Utilities
+ * Centralized data URI format checking and validation
+ *
+ * Eliminates the duplicated pattern:
+ * `value.startsWith("data:image/")`
+ * which appeared in 4 different files.
+ */
+
+/**
+ * Check if value is a data URI (any type)
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a data URI string
+ *
+ * @example
+ * ```typescript
+ * isDataUri("data:text/plain;base64,SGVsbG8="); // true
+ * isDataUri("https://example.com/image.png"); // false
+ * ```
+ */
+export function isDataUri(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("data:");
+}
+
+/**
+ * Check if value is an image data URI
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is an image data URI string
+ *
+ * @example
+ * ```typescript
+ * isImageDataUri("data:image/png;base64,iVBOR..."); // true
+ * isImageDataUri("data:text/plain;base64,SGVsbG8="); // false
+ * isImageDataUri("https://example.com/image.png"); // false
+ * ```
+ */
+export function isImageDataUri(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("data:image/");
+}
+
+/**
+ * Check if value is a base64-encoded data URI
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value contains base64 encoding
+ *
+ * @example
+ * ```typescript
+ * isBase64DataUri("data:image/png;base64,iVBOR..."); // true
+ * isBase64DataUri("data:image/svg+xml,<svg>...</svg>"); // false
+ * ```
+ */
+export function isBase64DataUri(value: unknown): value is string {
+  return isDataUri(value) && value.includes("base64,");
+}
+
+/**
+ * Extract MIME type from data URI
+ *
+ * @param dataUri - Data URI string
+ * @returns MIME type or null if not found
+ *
+ * @example
+ * ```typescript
+ * extractMimeType("data:image/png;base64,iVBOR..."); // "image/png"
+ * extractMimeType("data:text/plain;charset=utf-8,Hello"); // "text/plain"
+ * ```
+ */
+export function extractMimeType(dataUri: string): string | null {
+  const match = dataUri.match(/^data:([^;,]+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract base64 content from data URI
+ *
+ * @param dataUri - Data URI string
+ * @returns Base64 content or null if not base64-encoded
+ *
+ * @example
+ * ```typescript
+ * extractBase64Content("data:image/png;base64,iVBOR..."); // "iVBOR..."
+ * extractBase64Content("data:text/plain,Hello"); // null
+ * ```
+ */
+export function extractBase64Content(dataUri: string): string | null {
+  const parts = dataUri.split("base64,");
+  return parts.length === 2 ? parts[1] : null;
+}

package/src/infrastructure/utils/validators/string-validator.util.ts

@@ -0,0 +1,64 @@
+/**
+ * String Validation Utilities
+ * Common string validation patterns
+ *
+ * Eliminates the duplicated pattern:
+ * `value.trim().length === 0`
+ * which appeared in 3+ files.
+ */
+
+/**
+ * Check if string is empty or whitespace-only
+ *
+ * @param value - Value to check
+ * @returns True if the value is an empty string or contains only whitespace
+ *
+ * @example
+ * ```typescript
+ * isEmptyString(""); // true
+ * isEmptyString("   "); // true
+ * isEmptyString("Hello"); // false
+ * isEmptyString(null); // false
+ * ```
+ */
+export function isEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length === 0;
+}
+
+/**
+ * Check if value is a non-empty string
+ * Type guard version for better TypeScript inference
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a non-empty string
+ *
+ * @example
+ * ```typescript
+ * if (isNonEmptyString(input)) {
+ *   // TypeScript knows input is a string here
+ *   console.log(input.toUpperCase());
+ * }
+ * ```
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Check if value is a string (empty or non-empty)
+ * Basic type guard for string validation
+ *
+ * @param value - Value to check
+ * @returns Type guard indicating if the value is a string
+ *
+ * @example
+ * ```typescript
+ * if (isString(value)) {
+ *   // TypeScript knows value is a string here
+ *   console.log(value.length);
+ * }
+ * ```
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === "string";
+}

package/src/presentation/hooks/use-models.ts

@@ -43,8 +43,8 @@ export function useModels(props: UseModelsProps): UseModelsReturn {
     config?.defaultModelId,
   ]);
 
-  // Direct effect - no intermediate callback needed
-  useEffect(() => {
+  // Unified load function - eliminates duplication between effect and manual reload
+  const performLoad = useCallback(() => {
     setIsLoading(true);
     setError(null);
 
@@ -59,21 +59,13 @@ export function useModels(props: UseModelsProps): UseModelsReturn {
     }
   }, [type, memoizedConfig]);
 
-  // Separate refresh callback for manual reloads
-  const loadModels = useCallback(() => {
-    setIsLoading(true);
-    setError(null);
+  // Auto-load on mount and when dependencies change
+  useEffect(() => {
+    performLoad();
+  }, [performLoad]);
 
-    try {
-      const selectionData = falModelsService.getModelSelectionData(type, memoizedConfig);
-      setModels(selectionData.models);
-      setSelectedModel(selectionData.selectedModel);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to load models');
-    } finally {
-      setIsLoading(false);
-    }
-  }, [type, memoizedConfig]);
+  // Alias for manual reloads (same function, clearer name for external API)
+  const loadModels = performLoad;
 
   const selectModel = useCallback(
     (modelId: string) => {

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

@@ -1,27 +0,0 @@
-/**
- * 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 and control characters
- */
-export function sanitizePrompt(prompt: string): string {
-  return prompt
-    .trim()
-    .replace(/\s+/g, " ")
-    // Remove control characters except tab, newline, carriage return
-    // eslint-disable-next-line no-control-regex
-    .replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, '')
-    .slice(0, 5000);
-}