@umituz/react-native-firebase 1.13.3 → 1.13.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-firebase",
-  "version": "1.13.3",
-  "description": "Unified Firebase package for React Native apps - Centralized initialization and core services (Auth, Analytics, Crashlytics).",
+  "version": "1.13.5",
+  "description": "Unified Firebase package for React Native apps - Centralized initialization and core services (Auth, Firestore, Analytics, Crashlytics).",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
@@ -17,6 +17,9 @@
     "firebase-core",
     "auth",
     "authentication",
+    "firestore",
+    "database",
+    "repository",
     "analytics",
     "crashlytics",
     "ddd",
@@ -29,18 +32,12 @@
     "url": "https://github.com/umituz/react-native-firebase"
   },
   "peerDependencies": {
-    "@react-native-firebase/analytics": ">=18.0.0",
-    "@react-native-firebase/app": ">=18.0.0",
-    "@react-native-firebase/crashlytics": ">=18.0.0",
     "expo-apple-authentication": ">=6.0.0",
     "firebase": ">=10.0.0",
     "react": ">=18.2.0",
     "react-native": ">=0.74.0"
   },
   "devDependencies": {
-    "@react-native-firebase/analytics": "^19.0.0",
-    "@react-native-firebase/app": "^19.0.0",
-    "@react-native-firebase/crashlytics": "^19.0.0",
     "@types/react": "~19.1.10",
     "firebase": "^12.6.0",
     "react": "19.1.0",

package/src/firestore/__tests__/BaseRepository.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tests for BaseRepository
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { BaseRepository } from '../infrastructure/repositories/BaseRepository';
+import { getFirestore, resetFirestoreClient } from '../infrastructure/config/FirestoreClient';
+
+// Mock Firestore client
+jest.mock('../infrastructure/config/FirestoreClient', () => ({
+  getFirestore: jest.fn(),
+  resetFirestoreClient: jest.fn(),
+}));
+
+const mockGetFirestore = getFirestore as jest.MockedFunction<typeof getFirestore>;
+const mockResetFirestoreClient = resetFirestoreClient as jest.MockedFunction<typeof resetFirestoreClient>;
+
+describe('BaseRepository', () => {
+  let repository: BaseRepository;
+
+  beforeEach(() => {
+    repository = new BaseRepository();
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    repository.destroy();
+  });
+
+  describe('getDb', () => {
+    it('should return Firestore instance when available', () => {
+      const mockFirestore = {} as any;
+      mockGetFirestore.mockReturnValue(mockFirestore);
+
+      const result = repository.getDb();
+      expect(result).toBe(mockFirestore);
+    });
+
+    it('should return null when Firestore is not available', () => {
+      mockGetFirestore.mockReturnValue(null);
+
+      const result = repository.getDb();
+      expect(result).toBeNull();
+    });
+
+    it('should return null when repository is destroyed', () => {
+      repository.destroy();
+      const result = repository.getDb();
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('getDbOrThrow', () => {
+    it('should return Firestore instance when available', () => {
+      const mockFirestore = {} as any;
+      mockGetFirestore.mockReturnValue(mockFirestore);
+
+      const result = repository.getDbOrThrow();
+      expect(result).toBe(mockFirestore);
+    });
+
+    it('should throw error when Firestore is not available', () => {
+      mockGetFirestore.mockReturnValue(null);
+
+      expect(() => repository.getDbOrThrow()).toThrow(
+        'Firestore is not initialized. Please initialize Firebase App first.'
+      );
+    });
+  });
+
+  describe('isDbInitialized', () => {
+    it('should return true when Firestore is available', () => {
+      mockGetFirestore.mockReturnValue({} as any);
+
+      const result = repository.isDbInitialized();
+      expect(result).toBe(true);
+    });
+
+    it('should return false when Firestore is not available', () => {
+      mockGetFirestore.mockReturnValue(null);
+
+      const result = repository.isDbInitialized();
+      expect(result).toBe(false);
+    });
+
+    it('should return false when getFirestore throws', () => {
+      mockGetFirestore.mockImplementation(() => {
+        throw new Error('Test error');
+      });
+
+      const result = repository.isDbInitialized();
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('executeWithQuotaHandling', () => {
+    it('should execute operation successfully', async () => {
+      const mockOperation = jest.fn().mockResolvedValue('success');
+      const result = await repository.executeWithQuotaHandling(mockOperation);
+      expect(result).toBe('success');
+      expect(mockOperation).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle quota errors', async () => {
+      const quotaError = new Error('Quota exceeded');
+      const mockOperation = jest.fn().mockRejectedValue(quotaError);
+      
+      // Mock quota error detection
+      jest.spyOn(repository, 'isQuotaError').mockReturnValue(true);
+      jest.spyOn(repository, 'handleQuotaError').mockImplementation(() => {
+        throw new Error('Quota error handled');
+      });
+
+      await expect(repository.executeWithQuotaHandling(mockOperation)).rejects.toThrow('Quota error handled');
+    });
+
+    it('should re-throw non-quota errors', async () => {
+      const regularError = new Error('Regular error');
+      const mockOperation = jest.fn().mockRejectedValue(regularError);
+      
+      jest.spyOn(repository, 'isQuotaError').mockReturnValue(false);
+
+      await expect(repository.executeWithQuotaHandling(mockOperation)).rejects.toThrow('Regular error');
+    });
+  });
+
+  describe('destroy', () => {
+    it('should mark repository as destroyed', () => {
+      repository.destroy();
+      expect(repository.getDb()).toBeNull();
+    });
+  });
+});

package/src/firestore/__tests__/QueryDeduplicationMiddleware.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for QueryDeduplicationMiddleware
+ */
+
+import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { QueryDeduplicationMiddleware } from '../infrastructure/middleware/QueryDeduplicationMiddleware';
+
+describe('QueryDeduplicationMiddleware', () => {
+  let middleware: QueryDeduplicationMiddleware;
+
+  beforeEach(() => {
+    middleware = new QueryDeduplicationMiddleware();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    middleware.destroy();
+    jest.useRealTimers();
+  });
+
+  describe('deduplicate', () => {
+    it('should execute query immediately if not pending', async () => {
+      const queryFn = jest.fn().mockResolvedValue('result');
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      const result = await middleware.deduplicate(queryKey, queryFn);
+      expect(result).toBe('result');
+      expect(queryFn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should deduplicate identical queries within window', async () => {
+      const queryFn = jest.fn().mockResolvedValue('result');
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      const promise1 = middleware.deduplicate(queryKey, queryFn);
+      const promise2 = middleware.deduplicate(queryKey, queryFn);
+
+      const [result1, result2] = await Promise.all([promise1, promise2]);
+      expect(result1).toBe('result');
+      expect(result2).toBe('result');
+      expect(queryFn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should execute new query after deduplication window', async () => {
+      const queryFn = jest.fn().mockResolvedValue('result');
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      await middleware.deduplicate(queryKey, queryFn);
+      expect(queryFn).toHaveBeenCalledTimes(1);
+
+      // Advance time beyond deduplication window
+      jest.advanceTimersByTime(1100);
+
+      await middleware.deduplicate(queryKey, queryFn);
+      expect(queryFn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should handle different query keys separately', async () => {
+      const queryFn = jest.fn().mockResolvedValue('result');
+      const queryKey1 = {
+        collection: 'test1',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+      const queryKey2 = {
+        collection: 'test2',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      await middleware.deduplicate(queryKey1, queryFn);
+      await middleware.deduplicate(queryKey2, queryFn);
+
+      expect(queryFn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should clean up expired queries automatically', async () => {
+      const queryFn = jest.fn().mockResolvedValue('result');
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      await middleware.deduplicate(queryKey, queryFn);
+      expect(middleware.getPendingCount()).toBe(0);
+
+      // Advance time to trigger cleanup
+      jest.advanceTimersByTime(6000);
+      expect(middleware.getPendingCount()).toBe(0);
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all pending queries', async () => {
+      const queryFn = jest.fn(() => new Promise(() => {})); // Never resolves
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      middleware.deduplicate(queryKey, queryFn);
+      expect(middleware.getPendingCount()).toBe(1);
+
+      middleware.clear();
+      expect(middleware.getPendingCount()).toBe(0);
+    });
+  });
+
+  describe('destroy', () => {
+    it('should cleanup resources and clear queries', () => {
+      const queryKey = {
+        collection: 'test',
+        filters: 'field == value',
+        limit: 10,
+        orderBy: 'createdAt',
+      };
+
+      middleware.deduplicate(queryKey, () => Promise.resolve('result'));
+      middleware.destroy();
+
+      expect(middleware.getPendingCount()).toBe(0);
+    });
+  });
+});

package/src/firestore/__tests__/mocks/react-native-firebase.ts

@@ -0,0 +1,23 @@
+/**
+ * Mock for @umituz/react-native-firebase
+ */
+
+export class FirebaseError extends Error {
+  code: string;
+  originalError?: unknown;
+
+  constructor(message: string, code?: string, originalError?: unknown) {
+    super(message);
+    this.name = 'FirebaseError';
+    this.code = code || 'UNKNOWN';
+    this.originalError = originalError;
+  }
+}
+
+export function getFirebaseApp(): any {
+  return null;
+}
+
+export function initializeFirebase(): any {
+  return null;
+}

package/src/firestore/__tests__/setup.ts

@@ -0,0 +1,36 @@
+/**
+ * Jest setup file
+ */
+
+// Mock __DEV__ for tests
+export {};
+
+declare global {
+  var __DEV__: boolean | undefined;
+}
+
+if (typeof (global as any).__DEV__ === 'undefined') {
+  (global as any).__DEV__ = true;
+}
+
+// Mock console methods to avoid noise in tests
+const originalConsole = { ...console };
+
+beforeEach(() => {
+  // Restore console methods before each test
+  Object.assign(console, originalConsole);
+});
+
+// Set up global test utilities
+global.mockFirestore = () => ({
+  collection: jest.fn(),
+  doc: jest.fn(),
+  runTransaction: jest.fn(),
+  batch: jest.fn(),
+});
+
+global.mockFirebaseError = (code: string, message: string) => {
+  const error = new Error(message) as any;
+  error.code = code;
+  return error;
+};

package/src/firestore/domain/constants/QuotaLimits.ts

@@ -0,0 +1,97 @@
+/**
+ * Quota Limit Constants
+ * Domain layer - Default Firestore quota limits
+ *
+ * General-purpose constants for any app using Firestore
+ * Based on Firestore free tier and pricing documentation
+ */
+
+/**
+ * Firestore free tier daily limits
+ * https://firebase.google.com/docs/firestore/quotas
+ */
+export const FREE_TIER_LIMITS = {
+  /**
+   * Daily read operations (documents)
+   * Free tier: 50,000 reads/day
+   */
+  DAILY_READS: 50_000,
+
+  /**
+   * Daily write operations (documents)
+   * Free tier: 20,000 writes/day
+   */
+  DAILY_WRITES: 20_000,
+
+  /**
+   * Daily delete operations (documents)
+   * Free tier: 20,000 deletes/day
+   */
+  DAILY_DELETES: 20_000,
+
+  /**
+   * Stored data (GB)
+   * Free tier: 1 GB
+   */
+  STORAGE_GB: 1,
+} as const;
+
+/**
+ * Quota warning thresholds (percentage of limit)
+ * Apps can use these to show warnings before hitting limits
+ */
+export const QUOTA_THRESHOLDS = {
+  /**
+   * Warning threshold (80% of limit)
+   * Show warning to user
+   */
+  WARNING: 0.8,
+
+  /**
+   * Critical threshold (95% of limit)
+   * Show critical alert, consider disabling features
+   */
+  CRITICAL: 0.95,
+
+  /**
+   * Emergency threshold (98% of limit)
+   * Disable non-essential features
+   */
+  EMERGENCY: 0.98,
+} as const;
+
+/**
+ * Calculate quota usage percentage
+ * @param current - Current usage count
+ * @param limit - Total limit
+ * @returns Percentage (0-1)
+ */
+export function calculateQuotaUsage(current: number, limit: number): number {
+  return Math.min(1, current / limit);
+}
+
+/**
+ * Check if quota threshold is reached
+ * @param current - Current usage count
+ * @param limit - Total limit
+ * @param threshold - Threshold to check (0-1)
+ * @returns true if threshold is reached
+ */
+export function isQuotaThresholdReached(
+  current: number,
+  limit: number,
+  threshold: number,
+): boolean {
+  const usage = calculateQuotaUsage(current, limit);
+  return usage >= threshold;
+}
+
+/**
+ * Get remaining quota
+ * @param current - Current usage count
+ * @param limit - Total limit
+ * @returns Remaining quota count
+ */
+export function getRemainingQuota(current: number, limit: number): number {
+  return Math.max(0, limit - current);
+}

package/src/firestore/domain/entities/QuotaMetrics.ts

@@ -0,0 +1,28 @@
+/**
+ * Quota Metrics Entity
+ * Domain entity for tracking Firestore quota usage
+ */
+
+export interface QuotaMetrics {
+  readCount: number;
+  writeCount: number;
+  deleteCount: number;
+  timestamp: number;
+}
+
+export interface QuotaLimits {
+  dailyReadLimit: number;
+  dailyWriteLimit: number;
+  dailyDeleteLimit: number;
+}
+
+export interface QuotaStatus {
+  metrics: QuotaMetrics;
+  limits: QuotaLimits;
+  readPercentage: number;
+  writePercentage: number;
+  deletePercentage: number;
+  isNearLimit: boolean;
+  isOverLimit: boolean;
+}
+

package/src/firestore/domain/entities/RequestLog.ts

@@ -0,0 +1,30 @@
+/**
+ * Request Log Entity
+ * Domain entity for tracking Firestore requests
+ */
+
+export type RequestType = 'read' | 'write' | 'delete' | 'listener';
+
+export interface RequestLog {
+  id: string;
+  type: RequestType;
+  collection: string;
+  documentId?: string;
+  timestamp: number;
+  duration?: number;
+  success: boolean;
+  error?: string;
+  cached: boolean;
+}
+
+export interface RequestStats {
+  totalRequests: number;
+  readRequests: number;
+  writeRequests: number;
+  deleteRequests: number;
+  listenerRequests: number;
+  cachedRequests: number;
+  failedRequests: number;
+  averageDuration: number;
+}
+

package/src/firestore/domain/errors/FirebaseFirestoreError.ts

@@ -0,0 +1,52 @@
+/**
+ * Firebase Firestore Domain Errors
+ *
+ * Domain-Driven Design: Error types for Firestore operations
+ */
+
+import { FirebaseError } from '../../../domain/errors/FirebaseError';
+
+/**
+ * Firestore Error
+ * Thrown when Firestore operations fail
+ */
+export class FirebaseFirestoreError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'FIRESTORE_ERROR', originalError);
+    this.name = 'FirebaseFirestoreError';
+    Object.setPrototypeOf(this, FirebaseFirestoreError.prototype);
+  }
+}
+
+/**
+ * Firestore Initialization Error
+ * Thrown when Firestore fails to initialize
+ */
+export class FirebaseFirestoreInitializationError extends FirebaseFirestoreError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, originalError);
+    this.name = 'FirebaseFirestoreInitializationError';
+    Object.setPrototypeOf(this, FirebaseFirestoreInitializationError.prototype);
+  }
+}
+
+/**
+ * Firestore Quota Error
+ * Thrown when Firebase quota limits are exceeded
+ *
+ * Firebase quota limits:
+ * - Free tier: 50K reads/day, 20K writes/day, 20K deletes/day
+ * - Blaze plan: Pay as you go, higher limits
+ *
+ * This error is NOT retryable - quota won't increase by retrying
+ */
+export class FirebaseFirestoreQuotaError extends FirebaseFirestoreError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, originalError);
+    this.name = 'FirebaseFirestoreQuotaError';
+    (this as any).isQuotaError = true;
+    (this as any).code = 'resource-exhausted';
+    Object.setPrototypeOf(this, FirebaseFirestoreQuotaError.prototype);
+  }
+}
+

package/src/firestore/domain/services/QuotaCalculator.ts

@@ -0,0 +1,70 @@
+/**
+ * Quota Calculator Service
+ * Domain service for calculating quota usage and status
+ */
+
+import type { QuotaMetrics, QuotaLimits, QuotaStatus } from '../entities/QuotaMetrics';
+import { FREE_TIER_LIMITS } from '../constants/QuotaLimits';
+
+/**
+ * Default quota limits (Firebase Spark Plan)
+ * Can be overridden via configuration
+ */
+const DEFAULT_QUOTA_LIMITS: QuotaLimits = {
+  dailyReadLimit: FREE_TIER_LIMITS.DAILY_READS,
+  dailyWriteLimit: FREE_TIER_LIMITS.DAILY_WRITES,
+  dailyDeleteLimit: FREE_TIER_LIMITS.DAILY_DELETES,
+};
+
+export class QuotaCalculator {
+  /**
+   * Calculate quota status from metrics and limits
+   */
+  static calculateStatus(
+    metrics: QuotaMetrics,
+    limits: QuotaLimits = DEFAULT_QUOTA_LIMITS,
+  ): QuotaStatus {
+    const readPercentage = (metrics.readCount / limits.dailyReadLimit) * 100;
+    const writePercentage = (metrics.writeCount / limits.dailyWriteLimit) * 100;
+    const deletePercentage = (metrics.deleteCount / limits.dailyDeleteLimit) * 100;
+
+    const isNearLimit =
+      readPercentage >= 80 ||
+      writePercentage >= 80 ||
+      deletePercentage >= 80;
+
+    const isOverLimit =
+      readPercentage >= 100 ||
+      writePercentage >= 100 ||
+      deletePercentage >= 100;
+
+    return {
+      metrics,
+      limits,
+      readPercentage,
+      writePercentage,
+      deletePercentage,
+      isNearLimit,
+      isOverLimit,
+    };
+  }
+
+  /**
+   * Get default quota limits
+   */
+  static getDefaultLimits(): QuotaLimits {
+    return { ...DEFAULT_QUOTA_LIMITS };
+  }
+
+  /**
+   * Check if metrics are within limits
+   */
+  static isWithinLimits(
+    metrics: QuotaMetrics,
+    limits: QuotaLimits = DEFAULT_QUOTA_LIMITS,
+  ): boolean {
+    const status = this.calculateStatus(metrics, limits);
+    return !status.isOverLimit;
+  }
+}
+