@umituz/react-native-firebase 3.0.3 → 3.0.6

package/src/shared/domain/utils/calculation.util.ts

@@ -1,7 +1,24 @@
 /**
  * Calculation Utilities
+ * Common mathematical operations used across the codebase
+ * Optimized for performance with minimal allocations
  */
 
+/**
+ * Safely calculates percentage (0-1 range)
+ * Optimized: Guards against division by zero
+ *
+ * @param current - Current value
+ * @param limit - Maximum value
+ * @returns Percentage between 0 and 1
+ *
+ * @example
+ * ```typescript
+ * const percentage = calculatePercentage(750, 1000); // 0.75
+ * const percentage = calculatePercentage(1200, 1000); // 1.0 (capped)
+ * const percentage = calculatePercentage(0, 1000); // 0.0
+ * ```
+ */
 export function calculatePercentage(current: number, limit: number): number {
   if (limit <= 0) return 0;
   if (current <= 0) return 0;
@@ -9,56 +26,327 @@ export function calculatePercentage(current: number, limit: number): number {
   return current / limit;
 }
 
+/**
+ * Calculates remaining quota
+ * Optimized: Single Math.max call
+ *
+ * @param current - Current usage
+ * @param limit - Maximum limit
+ * @returns Remaining amount (minimum 0)
+ *
+ * @example
+ * ```typescript
+ * const remaining = calculateRemaining(250, 1000); // 750
+ * const remaining = calculateRemaining(1200, 1000); // 0 (capped)
+ * ```
+ */
 export function calculateRemaining(current: number, limit: number): number {
   return Math.max(0, limit - current);
 }
 
+/**
+ * Safe floor with minimum value
+ * Optimized: Single comparison
+ *
+ * @param value - Value to floor
+ * @param min - Minimum allowed value
+ * @returns Floored value, at least min
+ *
+ * @example
+ * ```typescript
+ * const result = safeFloor(5.7, 1); // 5
+ * const result = safeFloor(0.3, 1); // 1 (min enforced)
+ * const result = safeFloor(-2.5, 0); // 0 (min enforced)
+ * ```
+ */
 export function safeFloor(value: number, min: number): number {
   const floored = Math.floor(value);
   return floored < min ? min : floored;
 }
 
+/**
+ * Safe ceil with maximum value
+ * Optimized: Single comparison
+ *
+ * @param value - Value to ceil
+ * @param max - Maximum allowed value
+ * @returns Ceiled value, at most max
+ *
+ * @example
+ * ```typescript
+ * const result = safeCeil(5.2, 10); // 6
+ * const result = safeCeil(9.8, 10); // 10 (max enforced)
+ * const result = safeCeil(12.1, 10); // 10 (max enforced)
+ * ```
+ */
+export function safeCeil(value: number, max: number): number {
+  const ceiled = Math.ceil(value);
+  return ceiled > max ? max : ceiled;
+}
+
+/**
+ * Clamp value between min and max
+ * Optimized: Efficient without branching
+ *
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ *
+ * @example
+ * ```typescript
+ * const result = clamp(5, 0, 10); // 5
+ * const result = clamp(-5, 0, 10); // 0
+ * const result = clamp(15, 0, 10); // 10
+ * ```
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+/**
+ * Calculate milliseconds between two dates
+ * Optimized: Direct subtraction without Date object creation
+ *
+ * @param date1 - First date (timestamp or Date)
+ * @param date2 - Second date (timestamp or Date)
+ * @returns Difference in milliseconds (date1 - date2)
+ *
+ * @example
+ * ```typescript
+ * const diff = diffMs(Date.now(), Date.now() - 3600000); // 3600000
+ * ```
+ */
 export function diffMs(date1: number | Date, date2: number | Date): number {
-  const d1 = typeof date1 === 'number' ? date1 : date1.getTime();
-  const d2 = typeof date2 === 'number' ? date2 : date2.getTime();
-  return Math.abs(d1 - d2);
+  const ms1 = typeof date1 === 'number' ? date1 : date1.getTime();
+  const ms2 = typeof date2 === 'number' ? date2 : date2.getTime();
+  return ms1 - ms2;
 }
 
+/**
+ * Calculate minutes difference between two dates
+ * Optimized: Single Math.floor call
+ *
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @returns Difference in minutes (floored)
+ *
+ * @example
+ * ```typescript
+ * const diff = diffMinutes(Date.now(), Date.now() - 180000); // 3
+ * ```
+ */
 export function diffMinutes(date1: number | Date, date2: number | Date): number {
-  return Math.floor(diffMs(date1, date2) / 60000);
+  const msDiff = diffMs(date1, date2);
+  return Math.floor(msDiff / 60_000);
 }
 
+/**
+ * Calculate hours difference between two dates
+ * Optimized: Single Math.floor call
+ *
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @returns Difference in hours (floored)
+ *
+ * @example
+ * ```typescript
+ * const diff = diffHours(Date.now(), Date.now() - 7200000); // 2
+ * ```
+ */
 export function diffHours(date1: number | Date, date2: number | Date): number {
-  return Math.floor(diffMs(date1, date2) / 3600000);
+  const minsDiff = diffMinutes(date1, date2);
+  return Math.floor(minsDiff / 60);
 }
 
+/**
+ * Calculate days difference between two dates
+ * Optimized: Single Math.floor call
+ *
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @returns Difference in days (floored)
+ *
+ * @example
+ * ```typescript
+ * const diff = diffDays(Date.now(), Date.now() - 172800000); // 2
+ * ```
+ */
 export function diffDays(date1: number | Date, date2: number | Date): number {
-  return Math.floor(diffMs(date1, date2) / 86400000);
+  const hoursDiff = diffHours(date1, date2);
+  return Math.floor(hoursDiff / 24);
 }
 
-export function chunkArray<T>(array: readonly T[], chunkSize: number): T[][] {
-  if (chunkSize <= 0) return [];
-  const result: T[][] = [];
-  for (let i = 0; i < array.length; i += chunkSize) {
-    result.push(array.slice(i, i + chunkSize) as T[]);
+/**
+ * Safe array slice with bounds checking
+ * Optimized: Prevents negative indices and out-of-bounds
+ *
+ * @param array - Array to slice
+ * @param start - Start index (inclusive)
+ * @param end - End index (exclusive)
+ * @returns Sliced array
+ *
+ * @example
+ * ```typescript
+ * const items = [1, 2, 3, 4, 5];
+ * const sliced = safeSlice(items, 1, 3); // [2, 3]
+ * const sliced = safeSlice(items, -5, 10); // [1, 2, 3, 4, 5] (bounds checked)
+ * ```
+ */
+export function safeSlice<T>(array: T[], start: number, end?: number): T[] {
+  const len = array.length;
+
+  // Clamp start index
+  const safeStart = start < 0 ? 0 : (start >= len ? len : start);
+
+  // Clamp end index
+  const safeEnd = end === undefined
+    ? len
+    : (end < 0 ? 0 : (end >= len ? len : end));
+
+  // Only slice if valid range
+  if (safeStart >= safeEnd) {
+    return [];
   }
-  return result;
-}
 
-export function safeSlice<T>(array: T[], start: number, end?: number): T[] {
-  if (start < 0) return array.slice(0, end);
-  if (start >= array.length) return [];
-  return array.slice(start, end);
+  return array.slice(safeStart, safeEnd);
 }
 
+/**
+ * Calculate fetch limit for pagination (pageLimit + 1)
+ * Optimized: Simple addition
+ *
+ * @param pageLimit - Requested page size
+ * @returns Fetch limit (pageLimit + 1 for hasMore detection)
+ *
+ * @example
+ * ```typescript
+ * const fetchLimit = getFetchLimit(10); // 11
+ * ```
+ */
 export function getFetchLimit(pageLimit: number): number {
   return pageLimit + 1;
 }
 
+/**
+ * Calculate if hasMore based on items length and page limit
+ * Optimized: Direct comparison
+ *
+ * @param itemsLength - Total items fetched
+ * @param pageLimit - Requested page size
+ * @returns true if there are more items
+ *
+ * @example
+ * ```typescript
+ * const hasMore = hasMore(11, 10); // true
+ * const hasMore = hasMore(10, 10); // false
+ * ```
+ */
 export function hasMore(itemsLength: number, pageLimit: number): boolean {
   return itemsLength > pageLimit;
 }
 
+/**
+ * Calculate result items count (min of itemsLength and pageLimit)
+ * Optimized: Single Math.min call
+ *
+ * @param itemsLength - Total items fetched
+ * @param pageLimit - Requested page size
+ * @returns Number of items to return
+ *
+ * @example
+ * ```typescript
+ * const count = getResultCount(11, 10); // 10
+ * const count = getResultCount(8, 10); // 8
+ * ```
+ */
 export function getResultCount(itemsLength: number, pageLimit: number): number {
   return Math.min(itemsLength, pageLimit);
 }
+
+/**
+ * Chunk array into smaller arrays
+ * Optimized: Pre-allocated chunks when size is known
+ *
+ * @param array - Array to chunk
+ * @param chunkSize - Size of each chunk
+ * @returns Array of chunks
+ *
+ * @example
+ * ```typescript
+ * const chunks = chunkArray([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * ```
+ */
+export function chunkArray<T>(array: readonly T[], chunkSize: number): T[][] {
+  if (chunkSize <= 0) {
+    throw new Error('chunkSize must be greater than 0');
+  }
+
+  const chunks: T[][] = [];
+  const len = array.length;
+
+  for (let i = 0; i < len; i += chunkSize) {
+    const end = Math.min(i + chunkSize, len);
+    chunks.push(array.slice(i, end) as T[]);
+  }
+
+  return chunks;
+}
+
+/**
+ * Sum array of numbers
+ * Optimized: Direct for-loop (faster than reduce)
+ *
+ * @param numbers - Array of numbers to sum
+ * @returns Sum of all numbers
+ *
+ * @example
+ * ```typescript
+ * const sum = sumArray([1, 2, 3, 4, 5]); // 15
+ * ```
+ */
+export function sumArray(numbers: number[]): number {
+  let sum = 0;
+  for (let i = 0; i < numbers.length; i++) {
+    const num = numbers[i];
+    if (num !== undefined && num !== null) {
+      sum += num;
+    }
+  }
+  return sum;
+}
+
+/**
+ * Average of array of numbers
+ * Optimized: Single-pass calculation
+ *
+ * @param numbers - Array of numbers
+ * @returns Average value
+ *
+ * @example
+ * ```typescript
+ * const avg = averageArray([1, 2, 3, 4, 5]); // 3
+ * ```
+ */
+export function averageArray(numbers: number[]): number {
+  if (numbers.length === 0) return 0;
+  return sumArray(numbers) / numbers.length;
+}
+
+/**
+ * Round to decimal places
+ * Optimized: Efficient rounding without string conversion
+ *
+ * @param value - Value to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded value
+ *
+ * @example
+ * ```typescript
+ * const rounded = roundToDecimals(3.14159, 2); // 3.14
+ * ```
+ */
+export function roundToDecimals(value: number, decimals: number): number {
+  const multiplier = Math.pow(10, decimals);
+  return Math.round(value * multiplier) / multiplier;
+}

package/src/shared/domain/utils/error-handlers/error-messages.ts

@@ -13,11 +13,6 @@ export const ERROR_MESSAGES = {
     INVALID_CREDENTIALS: 'Invalid credentials provided',
     USER_CHANGED: 'User changed during operation',
     OPERATION_IN_PROGRESS: 'Operation already in progress',
-    USER_NOT_FOUND: 'User not found',
-    EMAIL_ALREADY_IN_USE: 'Email is already in use',
-    TOO_MANY_REQUESTS: 'Too many requests. Please try again later',
-    USER_DISABLED: 'This account has been disabled',
-    GENERIC_ERROR: 'Authentication error occurred',
   },
   FIRESTORE: {
     NOT_INITIALIZED: 'Firestore is not initialized',
@@ -30,12 +25,6 @@ export const ERROR_MESSAGES = {
     PERMISSION_DENIED: 'Permission denied',
     TRANSACTION_FAILED: 'Transaction failed',
     NETWORK_ERROR: 'Network error occurred',
-    NOT_FOUND: 'Document not found',
-    UNAVAILABLE: 'Firestore service is unavailable',
-    GENERIC_ERROR: 'Firestore error occurred',
-  },
-  STORAGE: {
-    GENERIC_ERROR: 'Storage error occurred',
   },
   REPOSITORY: {
     DESTROYED: 'Repository has been destroyed',
@@ -54,7 +43,3 @@ export const ERROR_MESSAGES = {
   },
 } as const;
 
-export function getQuotaErrorMessage(): string {
-  return ERROR_MESSAGES.FIRESTORE.QUOTA_EXCEEDED;
-}
-

package/src/shared/domain/utils/index.ts

@@ -37,6 +37,8 @@ export {
   calculatePercentage,
   calculateRemaining,
   safeFloor,
+  safeCeil,
+  clamp,
   diffMs,
   diffMinutes,
   diffHours,
@@ -46,4 +48,7 @@ export {
   hasMore,
   getResultCount,
   chunkArray,
+  sumArray,
+  averageArray,
+  roundToDecimals,
 } from './calculation.util';

package/src/shared/infrastructure/config/base/ClientStateManager.ts

@@ -0,0 +1,82 @@
+/**
+ * Client State Manager
+ *
+ * Generic state management for Firebase service clients.
+ * Provides centralized state tracking for initialization status, errors, and instances.
+ *
+ * @template TInstance - The service instance type (e.g., FirebaseApp, Firestore, Auth)
+ */
+
+interface ClientState<TInstance> {
+  instance: TInstance | null;
+  initializationError: string | null;
+  isInitialized: boolean;
+}
+
+/**
+ * Generic client state manager
+ * Handles initialization state, error tracking, and instance management
+ */
+export class ClientStateManager<TInstance> {
+  private state: ClientState<TInstance>;
+
+  constructor() {
+    this.state = {
+      instance: null,
+      initializationError: null,
+      isInitialized: false,
+    };
+  }
+
+  /**
+   * Get the current instance
+   */
+  getInstance(): TInstance | null {
+    return this.state.instance;
+  }
+
+  /**
+   * Set the instance
+   */
+  setInstance(instance: TInstance | null): void {
+    this.state.instance = instance;
+    this.state.isInitialized = instance !== null;
+  }
+
+  /**
+   * Check if the service is initialized
+   */
+  isInitialized(): boolean {
+    return this.state.isInitialized;
+  }
+
+  /**
+   * Get the initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.state.initializationError;
+  }
+
+  /**
+   * Set the initialization error
+   */
+  setInitializationError(error: string | null): void {
+    this.state.initializationError = error;
+  }
+
+  /**
+   * Reset the state
+   */
+  reset(): void {
+    this.state.instance = null;
+    this.state.initializationError = null;
+    this.state.isInitialized = false;
+  }
+
+  /**
+   * Get the current state (read-only)
+   */
+  getState(): Readonly<ClientState<TInstance>> {
+    return this.state;
+  }
+}

package/src/shared/infrastructure/config/base/ServiceClientSingleton.ts

@@ -1,39 +1,155 @@
 /**
- * Service Client Singleton Base
- * Base singleton pattern for service clients
+ * Service Client Singleton Base Class
  *
- * Max lines: 150 (enforced for maintainability)
+ * Provides a generic singleton pattern for Firebase service clients.
+ * Eliminates code duplication across FirebaseClient, FirestoreClient, FirebaseAuthClient.
+ *
+ * Features:
+ * - Generic singleton pattern
+ * - Initialization state management
+ * - Error handling and tracking
+ * - Automatic cleanup
+ *
+ * @template TInstance - The service instance type (e.g., Firestore, Auth)
+ * @template TConfig - The configuration type (optional)
+ */
+
+interface ServiceClientState<TInstance> {
+  instance: TInstance | null;
+  initializationError: string | null;
+  isInitialized: boolean;
+}
+
+interface ServiceClientOptions<TInstance, TConfig = unknown> {
+  serviceName: string;
+  initializer?: (config?: TConfig) => TInstance | null;
+  autoInitializer?: () => TInstance | null;
+}
+
+/**
+ * Generic service client singleton base class
+ * Provides common initialization, state management, and error handling
  */
+export class ServiceClientSingleton<TInstance, TConfig = unknown> {
+  protected state: ServiceClientState<TInstance>;
+  private readonly options: ServiceClientOptions<TInstance, TConfig>;
+  private initInProgress = false;
+
+  constructor(options: ServiceClientOptions<TInstance, TConfig>) {
+    this.options = options;
+    this.state = {
+      instance: null,
+      initializationError: null,
+      isInitialized: false,
+    };
+  }
+
+  /**
+   * Initialize the service with optional configuration
+   */
+  initialize(config?: TConfig): TInstance | null {
+    if (this.state.isInitialized && this.state.instance) {
+      return this.state.instance;
+    }
+
+    if (this.state.initializationError) {
+      return null;
+    }
+
+    // Prevent concurrent initialization attempts
+    if (this.initInProgress) {
+      return null;
+    }
 
-export abstract class ServiceClientSingleton<TInstance, TConfig = unknown> {
-  protected instance: TInstance | null = null;
-  protected initializationError: Error | null = null;
+    this.initInProgress = true;
+    try {
+      const instance = this.options.initializer ? this.options.initializer(config) : null;
+      if (instance) {
+        this.state.instance = instance;
+        this.state.isInitialized = true;
+      }
+      return instance;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : `Failed to initialize ${this.options.serviceName}`;
+      this.state.initializationError = errorMessage;
+      return null;
+    } finally {
+      this.initInProgress = false;
+    }
+  }
+
+  /**
+   * Get the service instance, auto-initializing if needed
+   */
+  getInstance(autoInit: boolean = false): TInstance | null {
+    if (this.state.instance) {
+      return this.state.instance;
+    }
 
-  protected constructor() {}
+    if (this.state.initializationError) {
+      return null;
+    }
 
-  abstract initialize(config?: TConfig): Promise<TInstance> | TInstance;
+    // Prevent concurrent auto-initialization attempts
+    if (this.initInProgress) {
+      return null;
+    }
 
-  getInstance(): TInstance {
-    if (!this.instance) {
-      throw new Error('Service not initialized. Call initialize() first.');
+    if (autoInit && this.options.autoInitializer) {
+      this.initInProgress = true;
+      try {
+        const instance = this.options.autoInitializer();
+        if (instance) {
+          this.state.instance = instance;
+          this.state.isInitialized = true;
+        }
+        return instance;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : `Failed to initialize ${this.options.serviceName}`;
+        this.state.initializationError = errorMessage;
+      } finally {
+        this.initInProgress = false;
+      }
     }
-    return this.instance;
+
+    return null;
   }
 
+  /**
+   * Check if the service is initialized
+   */
   isInitialized(): boolean {
-    return this.instance !== null;
+    return this.state.isInitialized;
   }
 
-  getInitializationError(): Error | null {
-    return this.initializationError;
+  /**
+   * Get the initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.state.initializationError;
   }
 
-  setError(message: string): void {
-    this.initializationError = new Error(message);
+  /**
+   * Reset the service state
+   */
+  reset(): void {
+    this.state.instance = null;
+    this.state.initializationError = null;
+    this.state.isInitialized = false;
+    this.initInProgress = false;
   }
 
-  reset(): void {
-    this.instance = null;
-    this.initializationError = null;
+  /**
+   * Get the current instance without initialization
+   */
+  protected getCurrentInstance(): TInstance | null {
+    return this.state.instance;
+  }
+
+  /**
+   * Set initialization error
+   */
+  protected setError(error: string): void {
+    this.state.initializationError = error;
   }
 }

package/src/shared/infrastructure/config/clients/FirebaseClientSingleton.ts

@@ -5,7 +5,7 @@
 
 import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
 import type { IFirebaseClient } from '../../../../application/ports/IFirebaseClient';
-import type { FirebaseApp } from 'firebase/app';
+import type { FirebaseApp } from '../initializers/FirebaseAppInitializer';
 import { FirebaseClientState } from '../state/FirebaseClientState';
 import { FirebaseInitializationOrchestrator } from '../orchestrators/FirebaseInitializationOrchestrator';
 

package/src/shared/infrastructure/config/initializers/FirebaseAppInitializer.ts

@@ -0,0 +1,9 @@
+/**
+ * Firebase App Initializer
+ *
+ * Single Responsibility: Expose Firebase App type
+ */
+
+import type { FirebaseApp as FirebaseAppType } from 'firebase/app';
+
+export type FirebaseApp = FirebaseAppType;

package/src/shared/infrastructure/config/services/FirebaseInitializationService.ts

@@ -4,7 +4,7 @@
  */
 
 import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
-import type { FirebaseApp } from 'firebase/app';
+import type { FirebaseApp } from '../initializers/FirebaseAppInitializer';
 import { FirebaseClientSingleton } from '../clients/FirebaseClientSingleton';
 import { loadFirebaseConfig } from '../FirebaseConfigLoader';