@umituz/react-native-firebase 1.13.2 → 1.13.4

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();
+

package/src/firestore/infrastructure/repositories/BasePaginatedRepository.ts

@@ -0,0 +1,90 @@
+/**
+ * Base Repository - Pagination Operations
+ *
+ * Provides pagination operations for Firestore repositories.
+ * Extends BaseQueryRepository with pagination-specific functionality.
+ */
+
+import type { QueryDocumentSnapshot, DocumentData } from "firebase/firestore";
+import { collection, query, orderBy, limit, startAfter, getDoc, doc, getDocs } from "firebase/firestore";
+import { PaginationHelper } from "../../utils/pagination.helper";
+import type { PaginatedResult, PaginationParams } from "../../types/pagination.types";
+import { BaseQueryRepository } from "./BaseQueryRepository";
+
+export abstract class BasePaginatedRepository extends BaseQueryRepository {
+  /**
+   * Execute paginated query with cursor support
+   *
+   * Generic helper for cursor-based pagination queries.
+   * Automatically handles cursor document fetching and result building.
+   *
+   * @param collectionName - Firestore collection name
+   * @param params - Pagination parameters
+   * @param orderByField - Field to order by (default: "createdAt")
+   * @param orderDirection - Sort direction (default: "desc")
+   * @returns QueryDocumentSnapshot array (limit + 1 for hasMore detection)
+   */
+  protected async executePaginatedQuery(
+    collectionName: string,
+    params?: PaginationParams,
+    orderByField: string = "createdAt",
+    orderDirection: "asc" | "desc" = "desc",
+  ): Promise<QueryDocumentSnapshot<DocumentData>[]> {
+    const db = this.getDbOrThrow();
+    const helper = new PaginationHelper();
+    const pageLimit = helper.getLimit(params);
+    const fetchLimit = helper.getFetchLimit(pageLimit);
+
+    const collectionRef = collection(db, collectionName);
+    let q = query(
+      collectionRef,
+      orderBy(orderByField, orderDirection),
+      limit(fetchLimit),
+    );
+
+    if (helper.hasCursor(params)) {
+      const cursorDoc = await getDoc(doc(db, collectionName, params!.cursor!));
+      if (cursorDoc.exists()) {
+        q = query(
+          collectionRef,
+          orderBy(orderByField, orderDirection),
+          startAfter(cursorDoc),
+          limit(fetchLimit),
+        );
+      }
+    }
+
+    const snapshot = await getDocs(q);
+    this.trackRead(collectionName, snapshot.docs.length, snapshot.metadata.fromCache);
+    return snapshot.docs;
+  }
+
+  /**
+   * Build paginated result from documents
+   *
+   * Helper to convert raw Firestore documents to paginated result.
+   * Works with any document type and cursor extraction logic.
+   *
+   * @param docs - Firestore document snapshots
+   * @param params - Pagination parameters
+   * @param extractData - Function to extract data from document
+   * @param getCursor - Function to extract cursor from data
+   * @returns Paginated result
+   */
+  protected buildPaginatedResult<T>(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    params: PaginationParams | undefined,
+    extractData: (doc: QueryDocumentSnapshot<DocumentData>) => T | null,
+    getCursor: (item: T) => string,
+  ): PaginatedResult<T> {
+    const items: T[] = [];
+    for (const doc of docs) {
+      const data = extractData(doc);
+      if (data) items.push(data);
+    }
+
+    const helper = new PaginationHelper<T>();
+    const pageLimit = helper.getLimit(params);
+    return helper.buildResult(items, pageLimit, getCursor);
+  }
+}

package/src/firestore/infrastructure/repositories/BaseQueryRepository.ts

@@ -0,0 +1,80 @@
+/**
+ * Base Repository - Query Operations
+ *
+ * Provides query and tracking operations for Firestore repositories.
+ * Extends BaseRepository with query-specific functionality.
+ */
+
+import type { Query } from "firebase/firestore";
+import { quotaTrackingMiddleware } from "../middleware/QuotaTrackingMiddleware";
+import { queryDeduplicationMiddleware } from "../middleware/QueryDeduplicationMiddleware";
+import { BaseRepository } from "./BaseRepository";
+
+export abstract class BaseQueryRepository extends BaseRepository {
+  /**
+   * Execute query with deduplication and quota tracking
+   * Prevents duplicate queries and tracks quota usage
+   *
+   * @param collection - Collection name
+   * @param query - Firestore query
+   * @param queryFn - Function to execute the query
+   * @param cached - Whether the result is from cache
+   * @returns Query result
+   */
+  protected async executeQuery<T>(
+    collection: string,
+    query: Query,
+    queryFn: () => Promise<T>,
+    cached: boolean = false,
+  ): Promise<T> {
+    const queryKey = {
+      collection,
+      filters: query.toString(),
+      limit: undefined,
+      orderBy: undefined,
+    };
+
+    return queryDeduplicationMiddleware.deduplicate(queryKey, async () => {
+      return quotaTrackingMiddleware.trackOperation(
+        {
+          type: 'read',
+          collection,
+          count: 1,
+          cached,
+        },
+        queryFn,
+      );
+    });
+  }
+
+  /**
+   * Track read operation
+   *
+   * @param collection - Collection name
+   * @param count - Number of documents read
+   * @param cached - Whether the result is from cache
+   */
+  protected override trackRead(
+    collection: string,
+    count: number = 1,
+    cached: boolean = false,
+  ): void {
+    quotaTrackingMiddleware.trackRead(collection, count, cached);
+  }
+
+  protected override trackWrite(
+    collection: string,
+    documentId?: string,
+    count: number = 1,
+  ): void {
+    quotaTrackingMiddleware.trackWrite(collection, documentId, count);
+  }
+
+  protected override trackDelete(
+    collection: string,
+    documentId?: string,
+    count: number = 1,
+  ): void {
+    quotaTrackingMiddleware.trackDelete(collection, documentId, count);
+  }
+}