@umituz/react-native-firebase 1.13.2 → 1.13.4

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

package/src/firestore/utils/document-mapper.helper.ts

@@ -0,0 +1,145 @@
+/**
+ * Document Mapper Helper
+ *
+ * Utilities for batch document processing with enrichment.
+ * Handles document extraction, validation, and enrichment with related data.
+ *
+ * App-agnostic: Works with any document type and any enrichment logic.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentMapperHelper } from '@umituz/react-native-firestore';
+ *
+ * const mapper = new DocumentMapperHelper<Post, User, EnrichedPost>();
+ * const enriched = await mapper.mapWithEnrichment(
+ *   postDocs,
+ *   post => extractPost(post),
+ *   post => post.userId,
+ *   userId => userRepo.getById(userId),
+ *   (post, user) => ({ ...post, user })
+ * );
+ * ```
+ */
+
+import type { QueryDocumentSnapshot, DocumentData } from 'firebase/firestore';
+
+export class DocumentMapperHelper<TSource, TEnrichment, TResult> {
+  /**
+   * Map documents with enrichment from related data
+   *
+   * Process flow:
+   * 1. Extract source data from document
+   * 2. Skip if extraction fails or source is invalid
+   * 3. Get enrichment key from source
+   * 4. Fetch enrichment data using the key
+   * 5. Skip if enrichment data not found
+   * 6. Combine source and enrichment into result
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractSource - Extract source data from document
+   * @param getEnrichmentKey - Get enrichment key from source
+   * @param fetchEnrichment - Fetch enrichment data by key
+   * @param combineData - Combine source and enrichment into result
+   * @returns Array of enriched results
+   */
+  async mapWithEnrichment(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractSource: (doc: QueryDocumentSnapshot<DocumentData>) => TSource | null,
+    getEnrichmentKey: (source: TSource) => string,
+    fetchEnrichment: (key: string) => Promise<TEnrichment | null>,
+    combineData: (source: TSource, enrichment: TEnrichment) => TResult,
+  ): Promise<TResult[]> {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const source = extractSource(doc);
+      if (!source) continue;
+
+      const enrichmentKey = getEnrichmentKey(source);
+      const enrichment = await fetchEnrichment(enrichmentKey);
+      if (!enrichment) continue;
+
+      results.push(combineData(source, enrichment));
+    }
+
+    return results;
+  }
+
+  /**
+   * Map documents with multiple enrichments
+   *
+   * Similar to mapWithEnrichment but supports multiple enrichment sources.
+   * Useful when result needs data from multiple related collections.
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractSource - Extract source data from document
+   * @param getEnrichmentKeys - Get all enrichment keys from source
+   * @param fetchEnrichments - Fetch all enrichment data by keys
+   * @param combineData - Combine source and enrichments into result
+   * @returns Array of enriched results
+   */
+  async mapWithMultipleEnrichments<TEnrichments extends Record<string, unknown>>(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractSource: (doc: QueryDocumentSnapshot<DocumentData>) => TSource | null,
+    getEnrichmentKeys: (source: TSource) => Record<string, string>,
+    fetchEnrichments: (keys: Record<string, string>) => Promise<TEnrichments | null>,
+    combineData: (source: TSource, enrichments: TEnrichments) => TResult,
+  ): Promise<TResult[]> {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const source = extractSource(doc);
+      if (!source) continue;
+
+      const enrichmentKeys = getEnrichmentKeys(source);
+      const enrichments = await fetchEnrichments(enrichmentKeys);
+      if (!enrichments) continue;
+
+      results.push(combineData(source, enrichments));
+    }
+
+    return results;
+  }
+
+  /**
+   * Simple document mapping without enrichment
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractData - Extract data from document
+   * @returns Array of extracted data (nulls filtered out)
+   */
+  map(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractData: (doc: QueryDocumentSnapshot<DocumentData>) => TResult | null,
+  ): TResult[] {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const data = extractData(doc);
+      if (data) {
+        results.push(data);
+      }
+    }
+
+    return results;
+  }
+}
+
+/**
+ * Create document mapper helper
+ *
+ * @returns DocumentMapperHelper instance
+ *
+ * @example
+ * ```typescript
+ * const mapper = createDocumentMapper<Post, User, EnrichedPost>();
+ * const enriched = await mapper.mapWithEnrichment(...);
+ * ```
+ */
+export function createDocumentMapper<
+  TSource,
+  TEnrichment,
+  TResult,
+>(): DocumentMapperHelper<TSource, TEnrichment, TResult> {
+  return new DocumentMapperHelper<TSource, TEnrichment, TResult>();
+}