@umituz/react-native-firebase 3.0.3 → 3.0.5

package/src/domains/firestore/utils/deduplication/pending-query-manager.util.ts

@@ -0,0 +1,119 @@
+/**
+ * Pending Query Manager Utility
+ * Manages pending queries for deduplication
+ */
+
+interface PendingQuery {
+  promise: Promise<unknown>;
+  timestamp: number;
+}
+
+export class PendingQueryManager {
+  private pendingQueries = new Map<string, PendingQuery>();
+  private deduplicationWindowMs: number;
+
+  constructor(deduplicationWindowMs: number = 1000) {
+    this.deduplicationWindowMs = deduplicationWindowMs;
+  }
+
+  /**
+   * Update the deduplication window dynamically
+   * Used for quota-aware adaptive deduplication
+   */
+  setWindow(windowMs: number): void {
+    this.deduplicationWindowMs = windowMs;
+  }
+
+  /**
+   * Get current deduplication window
+   */
+  getWindow(): number {
+    return this.deduplicationWindowMs;
+  }
+
+  /**
+   * Check if query is pending and not expired
+   */
+  isPending(key: string): boolean {
+    const pending = this.pendingQueries.get(key);
+    if (!pending) return false;
+
+    const age = Date.now() - pending.timestamp;
+    if (age > this.deduplicationWindowMs) {
+      this.pendingQueries.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get pending query promise
+   */
+  get(key: string): Promise<unknown> | null {
+    const pending = this.pendingQueries.get(key);
+    return pending ? pending.promise : null;
+  }
+
+  /**
+   * Add query to pending list.
+   * Cleanup is handled by the caller's finally block in deduplicate().
+   * Also attaches cleanup handlers to prevent memory leaks.
+   */
+  add(key: string, promise: Promise<unknown>): void {
+    // Attach cleanup handler to ensure query is removed from map
+    // even if caller's finally block doesn't execute (e.g., unhandled rejection)
+    promise.finally(() => {
+      // Immediate cleanup - no delay needed for better performance
+      this.pendingQueries.delete(key);
+    });
+
+    this.pendingQueries.set(key, {
+      promise,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Remove a specific query from pending list
+   */
+  remove(key: string): void {
+    this.pendingQueries.delete(key);
+  }
+
+  /**
+   * Clean up expired queries
+   * Uses current deduplication window (may be adjusted dynamically)
+   */
+  cleanup(): void {
+    const now = Date.now();
+    const windowMs = this.deduplicationWindowMs; // Capture current window
+
+    for (const [key, query] of this.pendingQueries.entries()) {
+      if (now - query.timestamp > windowMs) {
+        this.pendingQueries.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all pending queries
+   */
+  clear(): void {
+    this.pendingQueries.clear();
+  }
+
+  /**
+   * Get pending queries count
+   */
+  size(): number {
+    return this.pendingQueries.size;
+  }
+
+  /**
+   * Check if there are any pending queries
+   */
+  isEmpty(): boolean {
+    return this.pendingQueries.size === 0;
+  }
+}

package/src/domains/firestore/utils/deduplication/query-key-generator.util.ts

@@ -0,0 +1,34 @@
+/**
+ * Query Key Generator Utility
+ * Generates unique keys for query deduplication
+ */
+
+export interface QueryKey {
+  collection: string;
+  filters: string;
+  limit?: number;
+  orderBy?: string;
+}
+
+/**
+ * Escape special characters in query key components
+ * Prevents key collisions when filter strings contain separator characters
+ */
+function escapeKeyComponent(component: string): string {
+  return component.replace(/%/g, '%25').replace(/\|/g, '%7C');
+}
+
+/**
+ * Generate a unique key from query parameters
+ * Uses URL encoding to prevent collisions from separator characters
+ */
+export function generateQueryKey(key: QueryKey): string {
+  const parts = [
+    escapeKeyComponent(key.collection),
+    escapeKeyComponent(key.filters),
+    key.limit?.toString() || '',
+    escapeKeyComponent(key.orderBy || ''),
+  ];
+  return parts.join('|');
+}
+

package/src/domains/firestore/utils/deduplication/timer-manager.util.ts

@@ -0,0 +1,83 @@
+/**
+ * Timer Manager Utility
+ * Manages cleanup timers for deduplication middleware
+ */
+
+interface TimerManagerOptions {
+  cleanupIntervalMs: number;
+  onCleanup: () => void;
+}
+
+export class TimerManager {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly options: TimerManagerOptions;
+  private destroyed = false;
+
+  constructor(options: TimerManagerOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Start the cleanup timer
+   * Idempotent: safe to call multiple times
+   */
+  start(): void {
+    if (this.destroyed) {
+      return; // Don't start if destroyed
+    }
+
+    // Clear existing timer if running (prevents duplicate timers)
+    if (this.timer) {
+      this.stop();
+    }
+
+    this.timer = setInterval(() => {
+      if (this.destroyed) {
+        this.stop();
+        return;
+      }
+
+      try {
+        this.options.onCleanup();
+      } catch (error) {
+        // Silently handle cleanup errors to prevent timer from causing issues
+        // Log error in development for debugging (use __DEV__ for React Native)
+        if (__DEV__) {
+          console.error('TimerManager cleanup error:', error);
+        }
+      }
+    }, this.options.cleanupIntervalMs);
+
+    // In React Native, timers may not run when app is backgrounded
+    // Unref the timer to allow the event loop to exit if this is the only active timer
+    if (typeof (this.timer as any).unref === 'function') {
+      (this.timer as any).unref();
+    }
+  }
+
+  /**
+   * Stop the cleanup timer
+   */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Check if timer is running
+   */
+  isRunning(): boolean {
+    return this.timer !== null && !this.destroyed;
+  }
+
+  /**
+   * Destroy the timer manager
+   * Prevents timer from restarting
+   */
+  destroy(): void {
+    this.destroyed = true;
+    this.stop();
+  }
+}

package/src/index.ts

@@ -2,11 +2,6 @@
  * React Native Firebase - Unified Package
  *
  * Domain-Driven Design (DDD) Architecture
- *
- * IMPORTANT: This package does NOT import from 'firebase/app' or other firebase packages.
- * Import firebase SDK directly in your app if you need those types.
- *
- * This package provides utilities and abstractions ONLY for React Native.
  */
 
 // Core Errors
@@ -37,6 +32,8 @@ export type {
   ServiceInitializationResult,
 } from "./shared/infrastructure/config/services/FirebaseInitializationService";
 
+export type { FirebaseApp } from "./shared/infrastructure/config/initializers/FirebaseAppInitializer";
+
 // Type Guards
 export {
   isFirestoreError,
@@ -49,31 +46,6 @@ export {
   getSafeErrorCode,
 } from "./shared/domain/guards/firebase-error.guard";
 
-// Shared Infrastructure Base Classes
-export {
-  ServiceBase,
-  ErrorHandler,
-  defaultErrorHandler,
-  hasCodeProperty,
-  hasMessageProperty,
-  isFirebaseErrorLike,
-  hasNameProperty,
-  isErrorLike,
-  hasUidProperty,
-  hasEmailProperty,
-  hasProviderIdProperty,
-  isArray,
-  isString,
-  isFunction,
-  hasProperty,
-  hasProperties,
-} from "./shared/infrastructure/base";
-
-export type {
-  ServiceBaseOptions,
-  ErrorHandlerOptions,
-} from "./shared/infrastructure/base";
-
 // Domain Exports
 export * from "./domains/auth";
 export * from "./domains/account-deletion";

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',

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';