@umituz/react-native-firebase 1.13.2 → 1.13.4

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

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';