@umituz/react-native-firebase 1.13.3 → 1.13.5

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

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

@@ -0,0 +1,147 @@
+/**
+ * Base Repository - Core Operations
+ *
+ * Provides essential Firestore operations with centralized database access.
+ * All Firestore repositories should extend this class.
+ *
+ * Architecture:
+ * - DRY: Centralized database access (getDb)
+ * - SOLID: Single Responsibility - Database access only
+ * - KISS: Simple base class with protected db property
+ * - App-agnostic: Works with any app, no app-specific code
+ *
+ * This class is designed to be used across hundreds of apps.
+ * It provides a consistent interface for Firestore operations.
+ */
+
+import type { Firestore } from "firebase/firestore";
+import { getFirestore } from "../config/FirestoreClient";
+import {
+  isQuotaError as checkQuotaError,
+  getQuotaErrorMessage,
+} from "../../utils/quota-error-detector.util";
+import { FirebaseFirestoreQuotaError } from "../../domain/errors/FirebaseFirestoreError";
+
+export class BaseRepository {
+  private isDestroyed = false;
+
+  /**
+   * Get Firestore database instance
+   * Returns null if Firestore is not initialized (offline mode)
+   * Use getDbOrThrow() if you need to throw an error instead
+   *
+   * @returns Firestore instance or null if not initialized
+   */
+  protected getDb(): Firestore | null {
+    if (this.isDestroyed) {
+      if (__DEV__) {
+        console.warn('[BaseRepository] Attempted to use destroyed repository');
+      }
+      return null;
+    }
+    return getFirestore();
+  }
+
+  /**
+   * Get Firestore database instance or throw error
+   * Throws error if Firestore is not initialized
+   * Use this method when Firestore is required for the operation
+   *
+   * @returns Firestore instance
+   * @throws Error if Firestore is not initialized
+   */
+  protected getDbOrThrow(): Firestore {
+    const db = getFirestore();
+    if (!db) {
+      throw new Error("Firestore is not initialized. Please initialize Firebase App first.");
+    }
+    return db;
+  }
+
+  /**
+   * Check if Firestore is initialized
+   * Useful for conditional operations
+   *
+   * @returns true if Firestore is initialized, false otherwise
+   */
+  protected isDbInitialized(): boolean {
+    try {
+      const db = getFirestore();
+      return db !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if error is a quota error
+   * Quota errors indicate daily read/write/delete limits are exceeded
+   *
+   * @param error - Error to check
+   * @returns true if error is a quota error
+   */
+  protected isQuotaError(error: unknown): boolean {
+    return checkQuotaError(error);
+  }
+
+  /**
+   * Handle quota error
+   * Throws FirebaseFirestoreQuotaError with user-friendly message
+   *
+   * @param error - Original error
+   * @throws FirebaseFirestoreQuotaError
+   */
+  protected handleQuotaError(error: unknown): never {
+    const message = getQuotaErrorMessage();
+    throw new FirebaseFirestoreQuotaError(message, error);
+  }
+
+  /**
+   * Wrap Firestore operation with quota error handling
+   * Automatically detects and handles quota errors
+   *
+   * @param operation - Firestore operation to execute
+   * @returns Result of the operation
+   * @throws FirebaseFirestoreQuotaError if quota error occurs
+   */
+  protected async executeWithQuotaHandling<T>(
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      if (this.isQuotaError(error)) {
+        this.handleQuotaError(error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Track read operations (stub for analytics)
+   * @param collection - Collection name
+   * @param count - Number of reads
+   * @param cached - Whether read was from cache
+   */
+  protected trackRead(_collection: string, _count: number, _cached: boolean): void {
+    // Stub for future analytics implementation
+  }
+
+  protected trackWrite(_collection: string, _docId: string, _count: number): void {
+    // Stub for future analytics implementation
+  }
+
+  protected trackDelete(_collection: string, _docId: string, _count: number): void {
+    // Stub for future analytics implementation
+  }
+
+  /**
+   * Destroy repository and cleanup resources
+   */
+  destroy(): void {
+    this.isDestroyed = true;
+    if (__DEV__) {
+      console.log('[BaseRepository] Repository destroyed');
+    }
+  }
+}

package/src/firestore/infrastructure/services/QuotaMonitorService.ts

@@ -0,0 +1,108 @@
+/**
+ * Quota Monitor Service
+ * Infrastructure service for monitoring Firestore quota usage
+ */
+
+import type { QuotaMetrics, QuotaLimits, QuotaStatus } from '../../domain/entities/QuotaMetrics';
+import { QuotaCalculator } from '../../domain/services/QuotaCalculator';
+
+export class QuotaMonitorService {
+  private metrics: QuotaMetrics = {
+    readCount: 0,
+    writeCount: 0,
+    deleteCount: 0,
+    timestamp: Date.now(),
+  };
+
+  private limits: QuotaLimits = QuotaCalculator.getDefaultLimits();
+  private listeners: Set<(status: QuotaStatus) => void> = new Set();
+
+  /**
+   * Set quota limits
+   */
+  setLimits(limits: Partial<QuotaLimits>): void {
+    this.limits = { ...this.limits, ...limits };
+  }
+
+  /**
+   * Increment read count
+   */
+  incrementRead(count: number = 1): void {
+    this.metrics.readCount += count;
+    this.notifyListeners();
+  }
+
+  /**
+   * Increment write count
+   */
+  incrementWrite(count: number = 1): void {
+    this.metrics.writeCount += count;
+    this.notifyListeners();
+  }
+
+  /**
+   * Increment delete count
+   */
+  incrementDelete(count: number = 1): void {
+    this.metrics.deleteCount += count;
+    this.notifyListeners();
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): QuotaMetrics {
+    return { ...this.metrics };
+  }
+
+  /**
+   * Get current status
+   */
+  getStatus(): QuotaStatus {
+    return QuotaCalculator.calculateStatus(this.metrics, this.limits);
+  }
+
+  /**
+   * Reset metrics
+   */
+  resetMetrics(): void {
+    this.metrics = {
+      readCount: 0,
+      writeCount: 0,
+      deleteCount: 0,
+      timestamp: Date.now(),
+    };
+    this.notifyListeners();
+  }
+
+  /**
+   * Add status change listener
+   */
+  addListener(listener: (status: QuotaStatus) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Notify all listeners
+   */
+  private notifyListeners(): void {
+    const status = this.getStatus();
+    this.listeners.forEach((listener) => {
+      try {
+        listener(status);
+      } catch (error) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          /* eslint-disable-next-line no-console */
+          console.error('[QuotaMonitor] Listener error:', error);
+        }
+      }
+    });
+  }
+}
+
+export const quotaMonitorService = new QuotaMonitorService();
+

package/src/firestore/infrastructure/services/RequestLoggerService.ts

@@ -0,0 +1,139 @@
+/**
+ * Request Logger Service
+ * Infrastructure service for logging Firestore requests
+ */
+
+import type { RequestLog, RequestStats, RequestType } from '../../domain/entities/RequestLog';
+
+export class RequestLoggerService {
+  private logs: RequestLog[] = [];
+  private readonly MAX_LOGS = 1000;
+  private listeners: Set<(log: RequestLog) => void> = new Set();
+
+  /**
+   * Log a request
+   */
+  logRequest(log: Omit<RequestLog, 'id' | 'timestamp'>): void {
+    const fullLog: RequestLog = {
+      ...log,
+      id: this.generateId(),
+      timestamp: Date.now(),
+    };
+
+    this.logs.push(fullLog);
+
+    if (this.logs.length > this.MAX_LOGS) {
+      this.logs.shift();
+    }
+
+    // Log Firestore operations in development mode
+    if (__DEV__) {
+      const prefix = fullLog.cached ? '[Firestore Cache]' : '[Firestore]';
+      const operation = fullLog.type.toUpperCase();
+      const status = fullLog.success ? '✓' : '✗';
+      const details = fullLog.documentId
+        ? `${fullLog.collection}/${fullLog.documentId}`
+        : fullLog.collection;
+
+      if (fullLog.success) {
+        // eslint-disable-next-line no-console
+        console.log(`${prefix} ${status} ${operation}: ${details}`);
+      } else {
+        // eslint-disable-next-line no-console
+        console.error(`${prefix} ${status} ${operation}: ${details}`, fullLog.error);
+      }
+    }
+
+    this.notifyListeners(fullLog);
+  }
+
+  /**
+   * Get all logs
+   */
+  getLogs(): RequestLog[] {
+    return [...this.logs];
+  }
+
+  /**
+   * Get logs by type
+   */
+  getLogsByType(type: RequestType): RequestLog[] {
+    return this.logs.filter((log) => log.type === type);
+  }
+
+  /**
+   * Get request statistics
+   */
+  getStats(): RequestStats {
+    const totalRequests = this.logs.length;
+    const readRequests = this.logs.filter((l) => l.type === 'read').length;
+    const writeRequests = this.logs.filter((l) => l.type === 'write').length;
+    const deleteRequests = this.logs.filter((l) => l.type === 'delete').length;
+    const listenerRequests = this.logs.filter((l) => l.type === 'listener').length;
+    const cachedRequests = this.logs.filter((l) => l.cached).length;
+    const failedRequests = this.logs.filter((l) => !l.success).length;
+
+    const durations = this.logs
+      .filter((l) => l.duration !== undefined)
+      .map((l) => l.duration!);
+    const averageDuration =
+      durations.length > 0
+        ? durations.reduce((sum, d) => sum + d, 0) / durations.length
+        : 0;
+
+    return {
+      totalRequests,
+      readRequests,
+      writeRequests,
+      deleteRequests,
+      listenerRequests,
+      cachedRequests,
+      failedRequests,
+      averageDuration,
+    };
+  }
+
+  /**
+   * Clear all logs
+   */
+  clearLogs(): void {
+    this.logs = [];
+  }
+
+  /**
+   * Add log listener
+   */
+  addListener(listener: (log: RequestLog) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Generate unique ID
+   */
+  private generateId(): string {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+  }
+
+  /**
+   * Notify all listeners
+   */
+  private notifyListeners(log: RequestLog): void {
+    this.listeners.forEach((listener) => {
+      try {
+        listener(log);
+      } catch (error) {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__) {
+          /* eslint-disable-next-line no-console */
+          console.error('[RequestLogger] Listener error:', error);
+        }
+      }
+    });
+  }
+}
+
+export const requestLoggerService = new RequestLoggerService();
+

package/src/firestore/types/pagination.types.ts

@@ -0,0 +1,60 @@
+/**
+ * Pagination Types
+ *
+ * Generic types for cursor-based pagination in Firestore.
+ * Used across hundreds of apps for consistent pagination interface.
+ *
+ * @example
+ * ```typescript
+ * const result: PaginatedResult<Post> = await repository.getPosts({ limit: 10 });
+ * console.log(result.items); // Post[]
+ * console.log(result.hasMore); // boolean
+ * console.log(result.nextCursor); // string | null
+ * ```
+ */
+
+/**
+ * Pagination parameters for queries
+ */
+export interface PaginationParams {
+  /**
+   * Maximum number of items to return
+   * @default 10
+   */
+  limit?: number;
+
+  /**
+   * Cursor for pagination (document ID)
+   * Use this to fetch next page
+   */
+  cursor?: string;
+}
+
+/**
+ * Paginated result structure
+ */
+export interface PaginatedResult<T> {
+  /**
+   * Array of items in current page
+   */
+  items: T[];
+
+  /**
+   * Cursor for next page (null if no more items)
+   */
+  nextCursor: string | null;
+
+  /**
+   * Whether there are more items to fetch
+   */
+  hasMore: boolean;
+}
+
+/**
+ * Empty paginated result
+ */
+export const EMPTY_PAGINATED_RESULT: PaginatedResult<never> = {
+  items: [],
+  nextCursor: null,
+  hasMore: false,
+};

package/src/firestore/utils/dateUtils.ts

@@ -0,0 +1,31 @@
+import { Timestamp } from 'firebase/firestore';
+
+/**
+ * Convert ISO string to Firestore Timestamp
+ */
+export function isoToTimestamp(isoString: string): Timestamp {
+    return Timestamp.fromDate(new Date(isoString));
+}
+
+/**
+ * Convert Firestore Timestamp to ISO string
+ */
+export function timestampToISO(timestamp: Timestamp): string {
+    if (!timestamp) return new Date().toISOString();
+    return timestamp.toDate().toISOString();
+}
+
+/**
+ * Convert Firestore Timestamp to Date
+ */
+export function timestampToDate(timestamp: Timestamp): Date {
+    if (!timestamp) return new Date();
+    return timestamp.toDate();
+}
+
+/**
+ * Get current date as ISO string
+ */
+export function getCurrentISOString(): string {
+    return new Date().toISOString();
+}