@umituz/react-native-firebase 1.13.3 → 1.13.4

package/src/firestore/index.ts

@@ -0,0 +1,174 @@
+/**
+ * React Native Firestore Module
+ * Domain-Driven Design (DDD) Architecture
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all Firestore operations.
+ * ALL imports from the Firestore module MUST go through this file.
+ *
+ * Architecture:
+ * - domain: Errors, Constants, Entities, Services
+ * - infrastructure: Firestore client, BaseRepository, utilities
+ * - utils: Date utilities, timestamp conversion, query builders
+ *
+ * This module is designed to be used across hundreds of apps.
+ * It provides a consistent interface for Firestore operations.
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Errors
+// =============================================================================
+
+export {
+  FirebaseFirestoreError,
+  FirebaseFirestoreInitializationError,
+  FirebaseFirestoreQuotaError,
+} from './domain/errors/FirebaseFirestoreError';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Firestore Client
+// =============================================================================
+
+export {
+  initializeFirestore,
+  getFirestore,
+  isFirestoreInitialized,
+  getFirestoreInitializationError,
+  resetFirestoreClient,
+  firestoreClient,
+} from './infrastructure/config/FirestoreClient';
+
+export type { Firestore } from './infrastructure/config/FirestoreClient';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - BaseRepository
+// =============================================================================
+
+export { BaseRepository } from './infrastructure/repositories/BaseRepository';
+export { BaseQueryRepository } from './infrastructure/repositories/BaseQueryRepository';
+export { BasePaginatedRepository } from './infrastructure/repositories/BasePaginatedRepository';
+
+// =============================================================================
+// UTILS - Date Utilities
+// =============================================================================
+
+export {
+  isoToTimestamp,
+  timestampToISO,
+  timestampToDate,
+  getCurrentISOString,
+} from './utils/dateUtils';
+
+// =============================================================================
+// UTILS - Query Builder
+// =============================================================================
+
+export {
+  buildQuery,
+  createInFilter,
+  createEqualFilter,
+} from './utils/query-builder';
+
+export type {
+  QueryBuilderOptions,
+  FieldFilter,
+} from './utils/query-builder';
+
+// =============================================================================
+// UTILS - Pagination
+// =============================================================================
+
+export {
+  PaginationHelper,
+  createPaginationHelper,
+} from './utils/pagination.helper';
+
+export type {
+  PaginatedResult,
+  PaginationParams,
+} from './types/pagination.types';
+
+export { EMPTY_PAGINATED_RESULT } from './types/pagination.types';
+
+// =============================================================================
+// UTILS - Document Mapper
+// =============================================================================
+
+export {
+  DocumentMapperHelper,
+  createDocumentMapper,
+} from './utils/document-mapper.helper';
+
+// =============================================================================
+// UTILS - Quota Error Detection
+// =============================================================================
+
+export {
+  isQuotaError,
+  isRetryableError,
+  getQuotaErrorMessage,
+} from './utils/quota-error-detector.util';
+
+// =============================================================================
+// DOMAIN LAYER - Constants
+// =============================================================================
+
+export {
+  FREE_TIER_LIMITS,
+  QUOTA_THRESHOLDS,
+  calculateQuotaUsage,
+  isQuotaThresholdReached,
+  getRemainingQuota,
+} from './domain/constants/QuotaLimits';
+
+// =============================================================================
+// DOMAIN LAYER - Entities
+// =============================================================================
+
+export type {
+  QuotaMetrics,
+  QuotaLimits,
+  QuotaStatus,
+} from './domain/entities/QuotaMetrics';
+
+export type {
+  RequestLog,
+  RequestStats,
+  RequestType,
+} from './domain/entities/RequestLog';
+
+// =============================================================================
+// DOMAIN LAYER - Services
+// =============================================================================
+
+export { QuotaCalculator } from './domain/services/QuotaCalculator';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Middleware
+// =============================================================================
+
+export {
+  QueryDeduplicationMiddleware,
+  queryDeduplicationMiddleware,
+} from './infrastructure/middleware/QueryDeduplicationMiddleware';
+
+export {
+  QuotaTrackingMiddleware,
+  quotaTrackingMiddleware,
+} from './infrastructure/middleware/QuotaTrackingMiddleware';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Services
+// =============================================================================
+
+export {
+  QuotaMonitorService,
+  quotaMonitorService,
+} from './infrastructure/services/QuotaMonitorService';
+
+export {
+  RequestLoggerService,
+  requestLoggerService,
+} from './infrastructure/services/RequestLoggerService';
+
+// Re-export Firestore types for convenience
+export type { Timestamp } from 'firebase/firestore';

package/src/firestore/infrastructure/config/FirestoreClient.ts

@@ -0,0 +1,181 @@
+/**
+ * Firestore Client - Infrastructure Layer
+ *
+ * Domain-Driven Design: Infrastructure implementation of Firestore client
+ * Singleton pattern for managing Firestore instance
+ *
+ * IMPORTANT: This package requires Firebase App to be initialized first.
+ * Use @umituz/react-native-firebase to initialize Firebase App.
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Only manages Firestore initialization
+ * - Open/Closed: Extensible through configuration, closed for modification
+ * - Dependency Inversion: Depends on Firebase App from @umituz/react-native-firebase
+ */
+
+import type { Firestore } from 'firebase/firestore';
+import { getFirebaseApp } from '../../../infrastructure/config/FirebaseClient';
+import { FirebaseFirestoreInitializer } from './initializers/FirebaseFirestoreInitializer';
+
+/**
+ * Firestore Client Singleton
+ * Manages Firestore initialization
+ */
+class FirestoreClientSingleton {
+  private static instance: FirestoreClientSingleton | null = null;
+  private firestore: Firestore | null = null;
+  private initializationError: string | null = null;
+
+  private constructor() {
+    // Private constructor to enforce singleton pattern
+  }
+
+  /**
+   * Get singleton instance
+   */
+  static getInstance(): FirestoreClientSingleton {
+    if (!FirestoreClientSingleton.instance) {
+      FirestoreClientSingleton.instance = new FirestoreClientSingleton();
+    }
+    return FirestoreClientSingleton.instance;
+  }
+
+  /**
+   * Initialize Firestore
+   * Requires Firebase App to be initialized first via @umituz/react-native-firebase
+   *
+   * @returns Firestore instance or null if initialization fails
+   */
+  initialize(): Firestore | null {
+    if (this.firestore) {
+      return this.firestore;
+    }
+    if (this.initializationError) {
+      return null;
+    }
+    try {
+      const app = getFirebaseApp(); // Get the core Firebase App
+
+      // Return null if Firebase App is not available (offline mode)
+      if (!app) {
+        return null;
+      }
+
+      this.firestore = FirebaseFirestoreInitializer.initialize(app);
+      return this.firestore;
+    } catch (error) {
+      this.initializationError =
+        error instanceof Error
+          ? error.message
+          : 'Failed to initialize Firestore client';
+      return null;
+    }
+  }
+
+  /**
+   * Get Firestore instance
+   * Auto-initializes if Firebase App is available
+   * Returns null if config is not available (offline mode - no error)
+   * @returns Firestore instance or null if not initialized
+   */
+  getFirestore(): Firestore | null {
+    // Auto-initialize if not already initialized
+    if (!this.firestore && !this.initializationError) {
+      try {
+        // Try to get Firebase App (will auto-initialize if config is available)
+        const app = getFirebaseApp();
+        if (app) {
+          this.initialize();
+        }
+      } catch {
+        // Firebase App not available, return null (offline mode)
+        return null;
+      }
+    }
+
+    // Return null if not initialized (offline mode - no error)
+    return this.firestore || null;
+  }
+
+  /**
+   * Check if Firestore is initialized
+   */
+  isInitialized(): boolean {
+    return this.firestore !== null;
+  }
+
+  /**
+   * Get initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.initializationError;
+  }
+
+  /**
+   * Reset Firestore client instance
+   * Useful for testing
+   */
+  reset(): void {
+    this.firestore = null;
+    this.initializationError = null;
+  }
+}
+
+export const firestoreClient = FirestoreClientSingleton.getInstance();
+
+/**
+ * Initialize Firestore
+ * Requires Firebase App to be initialized first via @umituz/react-native-firebase
+ *
+ * @returns Firestore instance or null if initialization fails
+ *
+ * @example
+ * ```typescript
+ * import { initializeFirebase } from '@umituz/react-native-firebase';
+ * import { initializeFirestore } from '@umituz/react-native-firestore';
+ *
+ * // Initialize Firebase App first
+ * const app = initializeFirebase(config);
+ *
+ * // Then initialize Firestore
+ * const db = initializeFirestore();
+ * ```
+ */
+export function initializeFirestore(): Firestore | null {
+  return firestoreClient.initialize();
+}
+
+/**
+ * Get Firestore instance
+ * Auto-initializes if Firebase App is available
+ * Returns null if config is not available (offline mode - no error)
+ * @returns Firestore instance or null if not initialized
+ */
+export function getFirestore(): Firestore | null {
+  return firestoreClient.getFirestore();
+}
+
+/**
+ * Check if Firestore is initialized
+ */
+export function isFirestoreInitialized(): boolean {
+  return firestoreClient.isInitialized();
+}
+
+/**
+ * Get Firestore initialization error if any
+ */
+export function getFirestoreInitializationError(): string | null {
+  return firestoreClient.getInitializationError();
+}
+
+/**
+ * Reset Firestore client instance
+ * Useful for testing
+ */
+export function resetFirestoreClient(): void {
+  firestoreClient.reset();
+}
+
+export type { Firestore } from 'firebase/firestore';
+

package/src/firestore/infrastructure/config/initializers/FirebaseFirestoreInitializer.ts

@@ -0,0 +1,46 @@
+/**
+ * Firebase Firestore Initializer
+ *
+ * Single Responsibility: Initialize Firestore instance
+ *
+ * NOTE: React Native does not support IndexedDB (browser API), so we use
+ * memoryLocalCache instead of persistentLocalCache. For client-side caching,
+ * use TanStack Query which works on all platforms.
+ */
+
+import {
+  getFirestore,
+  initializeFirestore,
+  memoryLocalCache,
+} from 'firebase/firestore';
+import type { Firestore } from 'firebase/firestore';
+import type { FirebaseApp } from 'firebase/app';
+
+/**
+ * Initializes Firestore
+ * Platform-agnostic: Works on all platforms (Web, iOS, Android)
+ */
+export class FirebaseFirestoreInitializer {
+  /**
+   * Initialize Firestore with memory cache configuration
+   * React Native does not support IndexedDB, so we use memory cache
+   * For offline persistence, use TanStack Query with AsyncStorage
+   */
+  static initialize(app: FirebaseApp): Firestore {
+    try {
+      // Use memory cache for React Native compatibility
+      // IndexedDB (persistentLocalCache) is not available in React Native
+      return initializeFirestore(app, {
+        localCache: memoryLocalCache(),
+      });
+    } catch (error: any) {
+      // If already initialized, get existing instance
+      if (error.code === 'failed-precondition') {
+        return getFirestore(app);
+      }
+
+      return getFirestore(app);
+    }
+  }
+}
+

package/src/firestore/infrastructure/middleware/QueryDeduplicationMiddleware.ts

@@ -0,0 +1,153 @@
+/**
+ * Query Deduplication Middleware
+ * Prevents duplicate Firestore queries within a short time window
+ */
+
+interface PendingQuery {
+  promise: Promise<unknown>;
+  timestamp: number;
+}
+
+interface QueryKey {
+  collection: string;
+  filters: string;
+  limit?: number;
+  orderBy?: string;
+}
+
+export class QueryDeduplicationMiddleware {
+  private pendingQueries = new Map<string, PendingQuery>();
+  private readonly DEDUPLICATION_WINDOW_MS = 1000; // 1 second
+  private readonly CLEANUP_INTERVAL_MS = 5000; // 5 seconds
+  private cleanupTimer: NodeJS.Timeout | null = null;
+
+  constructor() {
+    this.startCleanupTimer();
+  }
+
+  /**
+   * Start cleanup timer to prevent memory leaks
+   */
+  private startCleanupTimer(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+    
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupExpiredQueries();
+    }, this.CLEANUP_INTERVAL_MS);
+  }
+
+  /**
+   * Clean up expired queries to prevent memory leaks
+   */
+  private cleanupExpiredQueries(): void {
+    const now = Date.now();
+    for (const [key, query] of this.pendingQueries.entries()) {
+      if (now - query.timestamp > this.DEDUPLICATION_WINDOW_MS) {
+        this.pendingQueries.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Generate query key from query parameters
+   */
+  private generateQueryKey(key: QueryKey): string {
+    const parts = [
+      key.collection,
+      key.filters,
+      key.limit?.toString() || '',
+      key.orderBy || '',
+    ];
+    return parts.join('|');
+  }
+
+  /**
+   * Check if query is already pending
+   */
+  private isQueryPending(key: string): boolean {
+    const pending = this.pendingQueries.get(key);
+    if (!pending) return false;
+
+    const age = Date.now() - pending.timestamp;
+    if (age > this.DEDUPLICATION_WINDOW_MS) {
+      this.pendingQueries.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get pending query promise
+   */
+  private getPendingQuery(key: string): Promise<unknown> | null {
+    const pending = this.pendingQueries.get(key);
+    return pending ? pending.promise : null;
+  }
+
+  /**
+   * Add query to pending list
+   */
+  private addPendingQuery(key: string, promise: Promise<unknown>): void {
+    this.pendingQueries.set(key, {
+      promise,
+      timestamp: Date.now(),
+    });
+
+    promise.finally(() => {
+      this.pendingQueries.delete(key);
+    });
+  }
+
+  /**
+   * Deduplicate a query
+   */
+  async deduplicate<T>(
+    queryKey: QueryKey,
+    queryFn: () => Promise<T>,
+  ): Promise<T> {
+    const key = this.generateQueryKey(queryKey);
+
+    if (this.isQueryPending(key)) {
+      const pendingPromise = this.getPendingQuery(key);
+      if (pendingPromise) {
+        return pendingPromise as Promise<T>;
+      }
+    }
+
+    const promise = queryFn();
+    this.addPendingQuery(key, promise);
+
+    return promise;
+  }
+
+  /**
+   * Clear all pending queries
+   */
+  clear(): void {
+    this.pendingQueries.clear();
+  }
+
+  /**
+   * Destroy middleware and cleanup resources
+   */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.pendingQueries.clear();
+  }
+
+  /**
+   * Get pending queries count
+   */
+  getPendingCount(): number {
+    return this.pendingQueries.size;
+  }
+}
+
+export const queryDeduplicationMiddleware = new QueryDeduplicationMiddleware();
+

package/src/firestore/infrastructure/middleware/QuotaTrackingMiddleware.ts

@@ -0,0 +1,165 @@
+/**
+ * Quota Tracking Middleware
+ * Tracks Firestore operations for quota monitoring
+ */
+
+import { quotaMonitorService } from '../services/QuotaMonitorService';
+import { requestLoggerService } from '../services/RequestLoggerService';
+import type { RequestType } from '../../domain/entities/RequestLog';
+
+interface TrackedOperation {
+  type: RequestType;
+  collection: string;
+  documentId?: string;
+  count: number;
+  cached?: boolean;
+}
+
+export class QuotaTrackingMiddleware {
+  /**
+   * Track a read operation
+   */
+  trackRead(collection: string, count: number = 1, cached: boolean = false): void {
+    quotaMonitorService.incrementRead(count);
+    requestLoggerService.logRequest({
+      type: 'read',
+      collection,
+      success: true,
+      cached,
+    });
+  }
+
+  /**
+   * Track a write operation
+   */
+  trackWrite(
+    collection: string,
+    documentId?: string,
+    count: number = 1,
+  ): void {
+    quotaMonitorService.incrementWrite(count);
+    requestLoggerService.logRequest({
+      type: 'write',
+      collection,
+      documentId,
+      success: true,
+      cached: false,
+    });
+  }
+
+  /**
+   * Track a delete operation
+   */
+  trackDelete(
+    collection: string,
+    documentId?: string,
+    count: number = 1,
+  ): void {
+    quotaMonitorService.incrementDelete(count);
+    requestLoggerService.logRequest({
+      type: 'delete',
+      collection,
+      documentId,
+      success: true,
+      cached: false,
+    });
+  }
+
+  /**
+   * Track a listener operation
+   */
+  trackListener(collection: string, documentId?: string): void {
+    requestLoggerService.logRequest({
+      type: 'listener',
+      collection,
+      documentId,
+      success: true,
+      cached: false,
+    });
+  }
+
+  /**
+   * Track a failed operation
+   */
+  trackError(
+    type: RequestType,
+    collection: string,
+    error: string,
+    documentId?: string,
+  ): void {
+    requestLoggerService.logRequest({
+      type,
+      collection,
+      documentId,
+      success: false,
+      error,
+      cached: false,
+    });
+  }
+
+  /**
+   * Track operation with timing
+   */
+  async trackOperation<T>(
+    operation: TrackedOperation,
+    operationFn: () => Promise<T>,
+  ): Promise<T> {
+    const startTime = Date.now();
+
+    try {
+      const result = await operationFn();
+      const duration = Date.now() - startTime;
+
+      if (operation.type === 'read') {
+        quotaMonitorService.incrementRead(operation.count);
+        requestLoggerService.logRequest({
+          type: 'read',
+          collection: operation.collection,
+          documentId: operation.documentId,
+          success: true,
+          cached: operation.cached || false,
+          duration,
+        });
+      } else if (operation.type === 'write') {
+        quotaMonitorService.incrementWrite(operation.count);
+        requestLoggerService.logRequest({
+          type: 'write',
+          collection: operation.collection,
+          documentId: operation.documentId,
+          success: true,
+          cached: false,
+          duration,
+        });
+      } else if (operation.type === 'delete') {
+        quotaMonitorService.incrementDelete(operation.count);
+        requestLoggerService.logRequest({
+          type: 'delete',
+          collection: operation.collection,
+          documentId: operation.documentId,
+          success: true,
+          cached: false,
+          duration,
+        });
+      }
+
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      requestLoggerService.logRequest({
+        type: operation.type,
+        collection: operation.collection,
+        documentId: operation.documentId,
+        success: false,
+        error: errorMessage,
+        cached: false,
+        duration,
+      });
+
+      throw error;
+    }
+  }
+}
+
+export const quotaTrackingMiddleware = new QuotaTrackingMiddleware();
+