@umituz/react-native-firebase 3.0.3 → 3.0.6

package/src/domains/firestore/utils/deduplication/pending-query-manager.util.ts

@@ -0,0 +1,126 @@
+/**
+ * Pending Query Manager Utility
+ * Manages pending queries for deduplication
+ */
+
+interface PendingQuery {
+  promise: Promise<unknown>;
+  timestamp: number;
+}
+
+export class PendingQueryManager {
+  private pendingQueries = new Map<string, PendingQuery>();
+  private deduplicationWindowMs: number;
+
+  constructor(deduplicationWindowMs: number = 1000) {
+    this.deduplicationWindowMs = deduplicationWindowMs;
+  }
+
+  /**
+   * Update the deduplication window dynamically
+   * Used for quota-aware adaptive deduplication
+   */
+  setWindow(windowMs: number): void {
+    this.deduplicationWindowMs = windowMs;
+  }
+
+  /**
+   * Get current deduplication window
+   */
+  getWindow(): number {
+    return this.deduplicationWindowMs;
+  }
+
+  /**
+   * Check if query is pending and not expired
+   */
+  isPending(key: string): boolean {
+    const pending = this.pendingQueries.get(key);
+    if (!pending) return false;
+
+    // PERF: Cache Date.now() to avoid multiple calls in hot path
+    const now = Date.now();
+    const age = now - pending.timestamp;
+    if (age > this.deduplicationWindowMs) {
+      this.pendingQueries.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get pending query promise
+   */
+  get(key: string): Promise<unknown> | null {
+    const pending = this.pendingQueries.get(key);
+    return pending ? pending.promise : null;
+  }
+
+  /**
+   * Add query to pending list.
+   * Cleanup is handled by the caller's finally block in deduplicate().
+   * Also attaches cleanup handlers to prevent memory leaks.
+   */
+  add(key: string, promise: Promise<unknown>): void {
+    // PERF: Cache timestamp to avoid multiple Date.now() calls
+    const now = Date.now();
+
+    // Set first, then attach cleanup handler to prevent race condition
+    // where immediately-resolved promise triggers cleanup before set()
+    this.pendingQueries.set(key, {
+      promise,
+      timestamp: now,
+    });
+
+    // Attach cleanup handler to ensure query is removed from map
+    // even if caller's finally block doesn't execute (e.g., unhandled rejection)
+    promise.finally(() => {
+      // Immediate cleanup - no delay needed for better performance
+      this.pendingQueries.delete(key);
+    });
+  }
+
+  /**
+   * Remove a specific query from pending list
+   */
+  remove(key: string): void {
+    this.pendingQueries.delete(key);
+  }
+
+  /**
+   * Clean up expired queries
+   * Uses current deduplication window (may be adjusted dynamically)
+   */
+  cleanup(): void {
+    const now = Date.now();
+    const windowMs = this.deduplicationWindowMs; // Capture current window
+
+    for (const [key, query] of this.pendingQueries.entries()) {
+      if (now - query.timestamp > windowMs) {
+        this.pendingQueries.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all pending queries
+   */
+  clear(): void {
+    this.pendingQueries.clear();
+  }
+
+  /**
+   * Get pending queries count
+   */
+  size(): number {
+    return this.pendingQueries.size;
+  }
+
+  /**
+   * Check if there are any pending queries
+   */
+  isEmpty(): boolean {
+    return this.pendingQueries.size === 0;
+  }
+}

package/src/domains/firestore/utils/deduplication/query-key-generator.util.ts

@@ -0,0 +1,41 @@
+/**
+ * Query Key Generator Utility
+ * Generates unique keys for query deduplication
+ */
+
+export interface QueryKey {
+  collection: string;
+  filters: string;
+  limit?: number;
+  orderBy?: string;
+}
+
+/**
+ * Escape special characters in query key components
+ * Prevents key collisions when filter strings contain separator characters
+ * FIX: Escape ALL special characters that could cause issues, not just % and |
+ */
+function escapeKeyComponent(component: string): string {
+  return component
+    .replace(/%/g, '%25')
+    .replace(/\|/g, '%7C')
+    .replace(/\n/g, '%0A')
+    .replace(/\r/g, '%0D')
+    .replace(/\0/g, '%00')
+    .replace(/\//g, '%2F');
+}
+
+/**
+ * Generate a unique key from query parameters
+ * Uses URL encoding to prevent collisions from separator characters
+ */
+export function generateQueryKey(key: QueryKey): string {
+  const parts = [
+    escapeKeyComponent(key.collection),
+    escapeKeyComponent(key.filters),
+    key.limit?.toString() || '',
+    escapeKeyComponent(key.orderBy || ''),
+  ];
+  return parts.join('|');
+}
+

package/src/domains/firestore/utils/deduplication/timer-manager.util.ts

@@ -0,0 +1,83 @@
+/**
+ * Timer Manager Utility
+ * Manages cleanup timers for deduplication middleware
+ */
+
+interface TimerManagerOptions {
+  cleanupIntervalMs: number;
+  onCleanup: () => void;
+}
+
+export class TimerManager {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly options: TimerManagerOptions;
+  private destroyed = false;
+
+  constructor(options: TimerManagerOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Start the cleanup timer
+   * Idempotent: safe to call multiple times
+   */
+  start(): void {
+    if (this.destroyed) {
+      return; // Don't start if destroyed
+    }
+
+    // Clear existing timer if running (prevents duplicate timers)
+    if (this.timer) {
+      this.stop();
+    }
+
+    this.timer = setInterval(() => {
+      if (this.destroyed) {
+        this.stop();
+        return;
+      }
+
+      try {
+        this.options.onCleanup();
+      } catch (error) {
+        // Silently handle cleanup errors to prevent timer from causing issues
+        // Log error in development for debugging (use __DEV__ for React Native)
+        if (__DEV__) {
+          console.error('TimerManager cleanup error:', error);
+        }
+      }
+    }, this.options.cleanupIntervalMs);
+
+    // In React Native, timers may not run when app is backgrounded
+    // Unref the timer to allow the event loop to exit if this is the only active timer
+    if (typeof (this.timer as any).unref === 'function') {
+      (this.timer as any).unref();
+    }
+  }
+
+  /**
+   * Stop the cleanup timer
+   */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Check if timer is running
+   */
+  isRunning(): boolean {
+    return this.timer !== null && !this.destroyed;
+  }
+
+  /**
+   * Destroy the timer manager
+   * Prevents timer from restarting
+   */
+  destroy(): void {
+    this.destroyed = true;
+    this.stop();
+  }
+}

package/src/domains/firestore/utils/pagination.helper.ts

@@ -49,8 +49,11 @@ export class PaginationHelper<T> {
     let nextCursor: string | null = null;
     if (hasMoreValue && resultItems.length > 0) {
       // Access is safe because we checked length > 0
-      const lastItem = resultItems[resultItems.length - 1]!;
-      nextCursor = getCursor(lastItem);
+      const lastIndex = resultItems.length - 1;
+      const lastItem = resultItems[lastIndex];
+      if (lastItem) {
+        nextCursor = getCursor(lastItem);
+      }
     }
 
     return {

package/src/domains/firestore/utils/transaction/transaction.util.ts

@@ -31,10 +31,16 @@ export async function runTransaction<T>(
     const errorCode = hasCodeProperty(error) ? error.code : 'unknown';
 
     if (isQuotaError(error)) {
-      throw new Error(`[runTransaction] ${ERROR_MESSAGES.FIRESTORE.QUOTA_EXCEEDED}: ${errorMessage} (Code: ${errorCode})`);
+      // FIX: Preserve original error by adding it as a custom property
+      const quotaError = new Error(`[runTransaction] ${ERROR_MESSAGES.FIRESTORE.QUOTA_EXCEEDED}: ${errorMessage} (Code: ${errorCode})`);
+      (quotaError as any).originalError = error;
+      throw quotaError;
     }
 
-    throw new Error(`[runTransaction] Transaction failed: ${errorMessage} (Code: ${errorCode})`);
+    // FIX: Preserve original error for debugging
+    const transactionError = new Error(`[runTransaction] Transaction failed: ${errorMessage} (Code: ${errorCode})`);
+    (transactionError as any).originalError = error;
+    throw transactionError;
   }
 }
 

package/src/index.ts

@@ -2,11 +2,6 @@
  * React Native Firebase - Unified Package
  *
  * Domain-Driven Design (DDD) Architecture
- *
- * IMPORTANT: This package does NOT import from 'firebase/app' or other firebase packages.
- * Import firebase SDK directly in your app if you need those types.
- *
- * This package provides utilities and abstractions ONLY for React Native.
  */
 
 // Core Errors
@@ -37,6 +32,8 @@ export type {
   ServiceInitializationResult,
 } from "./shared/infrastructure/config/services/FirebaseInitializationService";
 
+export type { FirebaseApp } from "./shared/infrastructure/config/initializers/FirebaseAppInitializer";
+
 // Type Guards
 export {
   isFirestoreError,
@@ -49,37 +46,332 @@ export {
   getSafeErrorCode,
 } from "./shared/domain/guards/firebase-error.guard";
 
-// Shared Infrastructure Base Classes
-export {
-  ServiceBase,
-  ErrorHandler,
-  defaultErrorHandler,
-  hasCodeProperty,
-  hasMessageProperty,
-  isFirebaseErrorLike,
-  hasNameProperty,
-  isErrorLike,
-  hasUidProperty,
-  hasEmailProperty,
-  hasProviderIdProperty,
-  isArray,
-  isString,
-  isFunction,
-  hasProperty,
-  hasProperties,
-} from "./shared/infrastructure/base";
+// =============================================================================
+// AUTH DOMAIN EXPORTS
+// =============================================================================
+
+// Domain Layer
+export type { FirebaseAuthConfig } from './domains/auth/domain/value-objects/FirebaseAuthConfig';
+export {
+  isAnonymousUser,
+} from './domains/auth/domain/entities/AnonymousUser';
+export type { AnonymousUser } from './domains/auth/domain/entities/AnonymousUser';
+
+// Infrastructure Layer - Config
+export {
+  getFirebaseAuth,
+  isFirebaseAuthInitialized,
+  getFirebaseAuthInitializationError,
+  resetFirebaseAuthClient,
+  firebaseAuthClient,
+  initializeFirebaseAuth,
+} from './domains/auth/infrastructure/config/FirebaseAuthClient';
+export type { Auth } from './domains/auth/infrastructure/config/FirebaseAuthClient';
+
+// Infrastructure Layer - Services
+export {
+  checkAuthState,
+  isAuthenticated,
+  isAnonymous,
+  getCurrentUserId,
+  getCurrentUser,
+  getCurrentUserIdFromGlobal,
+  getCurrentUserFromGlobal,
+  isCurrentUserAuthenticated,
+  isCurrentUserAnonymous,
+  verifyUserId,
+  isValidUser,
+} from './domains/auth/infrastructure/services/auth-utils.service';
+export type { AuthCheckResult } from './domains/auth/infrastructure/services/auth-utils.service';
+
+export {
+  AnonymousAuthService,
+  anonymousAuthService,
+} from './domains/auth/infrastructure/services/anonymous-auth.service';
+export type {
+  AnonymousAuthResult,
+  AnonymousAuthServiceInterface,
+} from './domains/auth/infrastructure/services/anonymous-auth.service';
+
+export {
+  shouldSkipFirestoreQuery,
+  createFirestoreQueryOptions,
+} from './domains/auth/infrastructure/services/firestore-utils.service';
+export type {
+  FirestoreQueryOptions,
+  FirestoreQueryResult,
+  FirestoreQuerySkipReason,
+} from './domains/auth/infrastructure/services/firestore-utils.service';
+
+// Social Auth Services
+export {
+  GoogleAuthService,
+  googleAuthService,
+} from './domains/auth/infrastructure/services/google-auth.service';
+export type {
+  GoogleAuthConfig,
+  GoogleAuthResult,
+} from './domains/auth/infrastructure/services/google-auth.types';
+
+export {
+  GoogleOAuthService,
+  googleOAuthService,
+} from './domains/auth/infrastructure/services/google-oauth.service';
+export type { GoogleOAuthConfig } from './domains/auth/infrastructure/services/google-oauth.service';
+
+export {
+  AppleAuthService,
+  appleAuthService,
+} from './domains/auth/infrastructure/services/apple-auth.service';
+export type { AppleAuthResult } from './domains/auth/infrastructure/services/apple-auth.types';
+
+// Password & Email/Password Auth
+export {
+  updateUserPassword,
+} from './domains/auth/infrastructure/services/password.service';
+
+export {
+  signInWithEmail,
+  signUpWithEmail,
+  signOut,
+  linkAnonymousWithEmail,
+} from './domains/auth/infrastructure/services/email-auth.service';
+export type {
+  EmailCredentials,
+  EmailAuthResult,
+} from './domains/auth/infrastructure/services/email-auth.service';
+
+// Auth Listener
+export {
+  setupAuthListener,
+} from './domains/auth/infrastructure/services/auth-listener.service';
+export type {
+  AuthListenerConfig,
+  AuthListenerResult,
+} from './domains/auth/infrastructure/services/auth-listener.service';
+
+// User Document Service
+export {
+  ensureUserDocument,
+  markUserDeleted,
+  configureUserDocumentService,
+} from './domains/auth/infrastructure/services/user-document.service';
+export type {
+  UserDocumentUser,
+  UserDocumentConfig,
+  UserDocumentExtras,
+} from './domains/auth/infrastructure/services/user-document.types';
+
+// Presentation Layer - Hooks
+export { useFirebaseAuth } from './domains/auth/presentation/hooks/useFirebaseAuth';
+export type { UseFirebaseAuthResult } from './domains/auth/presentation/hooks/useFirebaseAuth';
+
+export { useAnonymousAuth } from './domains/auth/presentation/hooks/useAnonymousAuth';
+export type { UseAnonymousAuthResult } from './domains/auth/presentation/hooks/useAnonymousAuth';
+
+export { useSocialAuth } from './domains/auth/presentation/hooks/useSocialAuth';
+export type {
+  SocialAuthConfig,
+  SocialAuthResult,
+  UseSocialAuthResult,
+} from './domains/auth/presentation/hooks/useSocialAuth';
+
+export { useGoogleOAuth } from './domains/auth/presentation/hooks/useGoogleOAuth';
+export type { UseGoogleOAuthResult } from './domains/auth/presentation/hooks/useGoogleOAuth';
+
+// =============================================================================
+// ACCOUNT DELETION DOMAIN EXPORTS
+// =============================================================================
+
+export {
+  deleteCurrentUser,
+  deleteUserAccount,
+} from './domains/account-deletion/infrastructure/services/account-deletion.service';
+export type { AccountDeletionResult } from './domains/account-deletion/infrastructure/services/account-deletion.service';
+
+export type {
+  AccountDeletionOptions,
+  ReauthenticationResult,
+  AuthProviderType,
+  ReauthCredentialResult,
+} from './domains/account-deletion/application/ports/reauthentication.types';
+
+export {
+  getUserAuthProvider,
+  reauthenticateWithPassword,
+  reauthenticateWithGoogle,
+  reauthenticateWithApple,
+  getAppleReauthCredential,
+} from './domains/account-deletion/infrastructure/services/reauthentication.service';
+
+// =============================================================================
+// FIRESTORE DOMAIN EXPORTS
+// =============================================================================
 
+// Domain Errors
+export {
+  FirebaseFirestoreError,
+  FirebaseFirestoreInitializationError,
+  FirebaseFirestoreQuotaError,
+} from './domains/firestore/domain/errors/FirebaseFirestoreError';
+
+// Firestore Client
+export {
+  initializeFirestore,
+  getFirestore,
+  isFirestoreInitialized,
+  getFirestoreInitializationError,
+  resetFirestoreClient,
+  firestoreClient,
+} from './domains/firestore/infrastructure/config/FirestoreClient';
+export type { Firestore } from './domains/firestore/infrastructure/config/FirestoreClient';
+
+// Repositories
+export { BaseRepository } from './domains/firestore/infrastructure/repositories/BaseRepository';
+export type { IPathResolver } from './domains/firestore/infrastructure/repositories/BaseRepository';
+export { BaseQueryRepository } from './domains/firestore/infrastructure/repositories/BaseQueryRepository';
+export { BasePaginatedRepository } from './domains/firestore/infrastructure/repositories/BasePaginatedRepository';
+
+// Date Utilities
+export {
+  isoToTimestamp,
+  timestampToISO,
+  timestampToDate,
+  getCurrentISOString,
+  formatRelativeTime,
+} from './domains/firestore/utils/dateUtils';
+export type { RelativeTimeLabels } from './domains/firestore/utils/dateUtils';
+
+// Query Builder
+export {
+  buildQuery,
+  createInFilter,
+  createEqualFilter,
+} from './domains/firestore/utils/query-builder';
+export type {
+  QueryBuilderOptions,
+  FieldFilter,
+} from './domains/firestore/utils/query-builder';
+
+// Pagination
+export {
+  PaginationHelper,
+  createPaginationHelper,
+} from './domains/firestore/utils/pagination.helper';
+export type {
+  PaginatedResult,
+  PaginationParams,
+} from './domains/firestore/types/pagination.types';
+export { EMPTY_PAGINATED_RESULT } from './domains/firestore/types/pagination.types';
+
+// Domain Constants
+export {
+  FREE_TIER_LIMITS,
+  QUOTA_THRESHOLDS,
+  calculateQuotaUsage,
+  isQuotaThresholdReached,
+  getRemainingQuota,
+} from './domains/firestore/domain/constants/QuotaLimits';
+
+// Domain Entities
+export type {
+  QuotaMetrics,
+  QuotaLimits,
+  QuotaStatus,
+} from './domains/firestore/domain/entities/QuotaMetrics';
 export type {
-  ServiceBaseOptions,
-  ErrorHandlerOptions,
-} from "./shared/infrastructure/base";
+  RequestLog,
+  RequestStats,
+  RequestType,
+} from './domains/firestore/domain/entities/RequestLog';
 
-// Domain Exports
-export * from "./domains/auth";
-export * from "./domains/account-deletion";
+// Domain Services
+export { QuotaCalculator } from './domains/firestore/domain/services/QuotaCalculator';
 
-// Firestore Module Exports
-export * from "./domains/firestore";
+// Quota Error Detection
+export {
+  isQuotaError,
+  isRetryableError,
+} from './shared/domain/utils/error-handlers/error-checkers';
+export {
+  ERROR_MESSAGES,
+} from './shared/domain/utils/error-handlers/error-messages';
+
+// Middleware
+export {
+  QueryDeduplicationMiddleware,
+  queryDeduplicationMiddleware,
+  syncDeduplicationWithQuota,
+} from './domains/firestore/infrastructure/middleware/QueryDeduplicationMiddleware';
+export type {
+  QueryDeduplicationConfig,
+  DeduplicationStatistics,
+} from './domains/firestore/infrastructure/middleware/QueryDeduplicationMiddleware';
+export {
+  QuotaTrackingMiddleware,
+  quotaTrackingMiddleware,
+} from './domains/firestore/infrastructure/middleware/QuotaTrackingMiddleware';
+
+// Services
+export {
+  RequestLoggerService,
+  requestLoggerService,
+} from './domains/firestore/infrastructure/services/RequestLoggerService';
+
+// Firestore Helper Utilities
+export {
+  withFirestore,
+  withFirestoreVoid,
+  withFirestoreBool,
+} from './domains/firestore/utils/operation/operation-executor.util';
+export {
+  runTransaction,
+  serverTimestamp,
+} from './domains/firestore/utils/transaction/transaction.util';
+export {
+  createErrorResult,
+  createSuccessResult,
+} from './domains/firestore/utils/result/result.util';
+export type { NoDbResult } from './domains/firestore/utils/result/result.util';
+
+// Validation Utilities
+export {
+  isValidCursor,
+  validateCursorOrThrow,
+  CursorValidationError,
+} from './domains/firestore/utils/validation/cursor-validator.util';
+export {
+  isValidFieldName,
+} from './domains/firestore/utils/validation/field-validator.util';
+export {
+  isValidDateRange,
+  validateDateRangeOrThrow,
+} from './domains/firestore/utils/validation/date-validator.util';
+
+// Presentation — TanStack Query integration
+export { useFirestoreQuery } from './domains/firestore/presentation/hooks/useFirestoreQuery';
+export { useFirestoreMutation } from './domains/firestore/presentation/hooks/useFirestoreMutation';
+export { useFirestoreSnapshot } from './domains/firestore/presentation/hooks/useFirestoreSnapshot';
+export { useSmartFirestoreSnapshot, useSmartListenerControl } from './domains/firestore/presentation/hooks/useSmartFirestoreSnapshot';
+export { createFirestoreKeys } from './domains/firestore/presentation/query-keys/createFirestoreKeys';
+
+export type { UseFirestoreQueryOptions } from './domains/firestore/presentation/hooks/useFirestoreQuery';
+export type { UseFirestoreMutationOptions } from './domains/firestore/presentation/hooks/useFirestoreMutation';
+export type { UseFirestoreSnapshotOptions } from './domains/firestore/presentation/hooks/useFirestoreSnapshot';
+export type { UseSmartFirestoreSnapshotOptions, BackgroundStrategy } from './domains/firestore/presentation/hooks/useSmartFirestoreSnapshot';
+
+// Firebase Types
+export { Timestamp } from 'firebase/firestore';
+export type {
+  CollectionReference,
+  QueryDocumentSnapshot,
+  DocumentData,
+  Transaction,
+  DocumentReference,
+  WriteBatch,
+  DocumentSnapshot,
+  QuerySnapshot,
+} from 'firebase/firestore';
 
 // Init Module Factory
 export {