@umituz/react-native-firebase 2.4.100 → 2.5.1

package/src/domains/firestore/presentation/hooks/useSmartFirestoreSnapshot.ts

@@ -1,361 +0,0 @@
-/**
- * useSmartFirestoreSnapshot Hook (Enhanced)
- *
- * Smart real-time listener with automatic lifecycle management
- *
- * FEATURES:
- * - Automatic listener suspension when app backgrounds
- * - Resume listeners when app foregrounds
- * - Configurable background timeout (default: 30s)
- * - Memory leak prevention
- * - Battery and data savings
- *
- * COST SAVINGS: ~80% reduction in background listener reads
- */
-
-import { useEffect, useMemo, useRef, useState, useCallback } from 'react';
-import {
-  useQuery,
-  useQueryClient,
-  type UseQueryResult,
-  type QueryKey,
-} from '@tanstack/react-query';
-import { AppState, AppStateStatus } from 'react-native';
-
-/**
- * Background behavior strategy
- */
-export type BackgroundStrategy =
-  | 'suspend'  // Suspend listeners when app backgrounds
-  | 'keep'     // Keep listeners active (default behavior)
-  | 'timeout'; // Keep listeners for timeout, then suspend
-
-/**
- * Smart snapshot options with enhanced lifecycle management
- */
-export interface UseSmartFirestoreSnapshotOptions<TData> {
-  /** Unique query key for caching */
-  queryKey: QueryKey;
-
-  /** Sets up the onSnapshot listener. Must return the unsubscribe function. */
-  subscribe: (onData: (data: TData) => void) => () => void;
-
-  /** Whether the subscription should be active */
-  enabled?: boolean;
-
-  /** Initial data before first snapshot arrives */
-  initialData?: TData;
-
-  /** Background behavior strategy (default: 'suspend') */
-  backgroundStrategy?: BackgroundStrategy;
-
-  /** Timeout in ms before suspending background listeners (default: 30000) */
-  backgroundTimeout?: number;
-
-  /** Delay in ms before resuming after foreground (default: 0) */
-  resumeDelay?: number;
-
-  /** Callback when listener is suspended */
-  onSuspend?: () => void;
-
-  /** Callback when listener is resumed */
-  onResume?: () => void;
-}
-
-/**
- * Internal state for listener lifecycle
- */
-interface ListenerState {
-  isSuspended: boolean;
-  isBackgrounded: boolean;
-  suspendTimer: ReturnType<typeof setTimeout> | null;
-}
-
-/**
- * Smart Firestore snapshot hook with automatic lifecycle management
- *
- * @example
- * ```typescript
- * const { data: matches, isLoading } = useSmartFirestoreSnapshot<Match[]>({
- *   queryKey: ["matches", userId],
- *   subscribe: (onData) => {
- *     if (!userId) return () => {};
- *     return onSnapshot(matchesCol(userId), (snap) => {
- *       onData(snap.docs.map(d => d.data() as Match));
- *     });
- *   },
- *   enabled: !!userId,
- *   initialData: [],
- *   backgroundStrategy: 'suspend',  // Suspend when app backgrounds
- *   backgroundTimeout: 30000,       // 30s timeout
- * });
- * ```
- */
-export function useSmartFirestoreSnapshot<TData>(
-  options: UseSmartFirestoreSnapshotOptions<TData>
-): UseQueryResult<TData, Error> {
-  const {
-    queryKey,
-    subscribe,
-    enabled = true,
-    initialData,
-    backgroundStrategy = 'suspend',
-    backgroundTimeout = 30000,
-    resumeDelay = 0,
-    onSuspend,
-    onResume,
-  } = options;
-
-  const queryClient = useQueryClient();
-  const unsubscribeRef = useRef<(() => void) | null>(null);
-  const dataPromiseRef = useRef<{ resolve: (value: TData) => void; reject: (error: Error) => void } | null>(null);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Listener state management
-  const [listenerState, setListenerState] = useState<ListenerState>({
-    isSuspended: false,
-    isBackgrounded: false,
-    suspendTimer: null,
-  });
-
-  // Stabilize queryKey to prevent unnecessary listener re-subscriptions
-  const stableKeyString = JSON.stringify(queryKey);
-  const stableQueryKey = useMemo(() => queryKey, [stableKeyString]);
-
-  /**
-   * Suspend the listener (stop receiving updates)
-   */
-  const suspendListener = useCallback(() => {
-    if (unsubscribeRef.current && !listenerState.isSuspended) {
-      unsubscribeRef.current();
-      unsubscribeRef.current = null;
-
-      setListenerState(prev => ({ ...prev, isSuspended: true }));
-
-      // Clear pending promise to prevent memory leaks
-      if (dataPromiseRef.current) {
-        dataPromiseRef.current.reject(new Error('Listener suspended'));
-        dataPromiseRef.current = null;
-      }
-
-      // Clear timeout
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-        timeoutRef.current = null;
-      }
-
-      // Notify callback
-      onSuspend?.();
-
-      if (__DEV__) {
-        console.log(`[SmartSnapshot] Listener suspended for query:`, queryKey);
-      }
-    }
-  }, [queryKey, listenerState.isSuspended, onSuspend]);
-
-  /**
-   * Resume the listener (start receiving updates again)
-   */
-  const resumeListener = useCallback(() => {
-    if (!unsubscribeRef.current && enabled && !listenerState.isBackgrounded) {
-      setListenerState(prev => ({ ...prev, isSuspended: false }));
-
-      // Notify callback
-      onResume?.();
-
-      if (__DEV__) {
-        console.log(`[SmartSnapshot] Listener resumed for query:`, queryKey);
-      }
-    }
-  }, [enabled, listenerState.isBackgrounded, onResume, queryKey]);
-
-  /**
-   * Handle app state changes (foreground/background)
-   */
-  useEffect(() => {
-    const timers: ReturnType<typeof setTimeout>[] = [];
-
-    const handleAppStateChange = (nextAppState: AppStateStatus) => {
-      const isBackgrounded = nextAppState.match(/inactive|background/);
-
-      setListenerState(prev => {
-        // Clear existing suspend timer
-        if (prev.suspendTimer) {
-          clearTimeout(prev.suspendTimer);
-        }
-
-        // App entering background
-        if (isBackgrounded && !prev.isBackgrounded) {
-          if (__DEV__) {
-            console.log(`[SmartSnapshot] App entering background for query:`, queryKey);
-          }
-
-          switch (backgroundStrategy) {
-            case 'suspend':
-              // Suspend immediately - track timer for cleanup
-              const suspendTimer = setTimeout(() => suspendListener(), 0);
-              timers.push(suspendTimer);
-              break;
-
-            case 'timeout':
-              // Suspend after timeout - timer stored in state for cleanup
-              const timer = setTimeout(() => {
-                suspendListener();
-              }, backgroundTimeout);
-              return { ...prev, isBackgrounded: true, suspendTimer: timer };
-
-            case 'keep':
-              // Keep listener active
-              return { ...prev, isBackgrounded: true };
-          }
-
-          return { ...prev, isBackgrounded: true };
-        }
-
-        // App entering foreground
-        if (!isBackgrounded && prev.isBackgrounded) {
-          if (__DEV__) {
-            console.log(`[SmartSnapshot] App entering foreground for query:`, queryKey);
-          }
-
-          // Resume listener (with optional delay) - track timer for cleanup
-          const resumeTimer = setTimeout(() => {
-            resumeListener();
-          }, resumeDelay);
-          timers.push(resumeTimer);
-
-          return { ...prev, isBackgrounded: false, suspendTimer: null };
-        }
-
-        return prev;
-      });
-    };
-
-    const subscription = AppState.addEventListener('change', handleAppStateChange);
-
-    return () => {
-      subscription.remove();
-      // Clean up any pending timers
-      timers.forEach(timer => clearTimeout(timer));
-    };
-  }, [queryKey, backgroundStrategy, backgroundTimeout, resumeDelay, suspendListener, resumeListener]);
-
-  /**
-   * Setup the snapshot listener
-   * Automatically manages listener lifecycle based on app state
-   */
-  useEffect(() => {
-    // Don't subscribe if disabled, suspended, or backgrounded (unless 'keep' strategy)
-    if (!enabled || listenerState.isSuspended) {
-      return;
-    }
-
-    if (listenerState.isBackgrounded && backgroundStrategy !== 'keep') {
-      return;
-    }
-
-    // Setup listener
-    unsubscribeRef.current = subscribe((data) => {
-      queryClient.setQueryData(stableQueryKey, data);
-
-      // Resolve any pending promise from queryFn
-      if (dataPromiseRef.current) {
-        dataPromiseRef.current.resolve(data);
-        dataPromiseRef.current = null;
-        if (timeoutRef.current) {
-          clearTimeout(timeoutRef.current);
-          timeoutRef.current = null;
-        }
-      }
-    });
-
-    return () => {
-      if (unsubscribeRef.current) {
-        unsubscribeRef.current();
-        unsubscribeRef.current = null;
-      }
-
-      // Reject pending promise on cleanup to prevent memory leaks
-      if (dataPromiseRef.current) {
-        dataPromiseRef.current.reject(new Error('Snapshot listener cleanup'));
-        dataPromiseRef.current = null;
-      }
-
-      // Clear timeout on cleanup
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-        timeoutRef.current = null;
-      }
-    };
-  }, [
-    enabled,
-    listenerState.isSuspended,
-    listenerState.isBackgrounded,
-    backgroundStrategy,
-    queryClient,
-    stableQueryKey,
-    subscribe,
-  ]);
-
-  /**
-   * TanStack Query integration
-   * Data comes from the snapshot listener, not from a fetch
-   */
-  return useQuery<TData, Error>({
-    queryKey,
-    queryFn: () => {
-      const cached = queryClient.getQueryData<TData>(queryKey);
-      if (cached !== undefined) return cached;
-      if (initialData !== undefined) return initialData;
-
-      // Return a promise that resolves when snapshot provides data
-      // This prevents hanging promises and memory leaks
-      return new Promise<TData>((resolve, reject) => {
-        dataPromiseRef.current = { resolve, reject };
-
-        // Timeout to prevent infinite waiting (memory leak protection)
-        timeoutRef.current = setTimeout(() => {
-          if (dataPromiseRef.current) {
-            dataPromiseRef.current = null;
-            timeoutRef.current = null;
-            if (initialData !== undefined) {
-              resolve(initialData);
-            } else {
-              reject(new Error('Snapshot listener timeout'));
-            }
-          }
-        }, 30000); // 30 second timeout
-      });
-    },
-    enabled,
-    initialData,
-    // Never refetch — data comes from the real-time listener
-    staleTime: Infinity,
-    refetchOnMount: false,
-    refetchOnWindowFocus: false,
-    refetchOnReconnect: false,
-  });
-}
-
-/**
- * Hook to manually control listener lifecycle
- * Useful for complex scenarios with custom logic
- */
-export function useSmartListenerControl() {
-  const [appState, setAppState] = useState<AppStateStatus>(AppState.currentState);
-
-  useEffect(() => {
-    const subscription = AppState.addEventListener('change', setAppState);
-    return () => subscription.remove();
-  }, []);
-
-  // Compute background status once to avoid duplicate regex matching
-  const isBackgrounded = appState.match(/inactive|background/);
-  const isForegrounded = !isBackgrounded;
-
-  return {
-    isBackgrounded,
-    isForegrounded,
-    appState,
-  };
-}

package/src/domains/firestore/presentation/query-keys/createFirestoreKeys.ts

@@ -1,32 +0,0 @@
-/**
- * Firestore Query Key Factory
- *
- * Creates consistent, type-safe query keys for Firestore collections.
- * Keys follow the pattern: [resource, scope, ...args]
- *
- * @example
- * ```typescript
- * const conversationKeys = createFirestoreKeys("conversations");
- *
- * conversationKeys.all()                // ["conversations"]
- * conversationKeys.lists()              // ["conversations", "list"]
- * conversationKeys.list({ status: "active" }) // ["conversations", "list", { status: "active" }]
- * conversationKeys.detail("abc")        // ["conversations", "detail", "abc"]
- * conversationKeys.userScoped("uid123") // ["conversations", "user", "uid123"]
- * ```
- */
-
-export function createFirestoreKeys(resource: string) {
-  return {
-    all: () => [resource] as const,
-    lists: () => [resource, 'list'] as const,
-    list: (filters?: Record<string, unknown>) =>
-      filters
-        ? ([resource, 'list', filters] as const)
-        : ([resource, 'list'] as const),
-    details: () => [resource, 'detail'] as const,
-    detail: (id: string | number) => [resource, 'detail', id] as const,
-    userScoped: (userId: string) => [resource, 'user', userId] as const,
-    custom: (...args: unknown[]) => [resource, ...args] as const,
-  };
-}

package/src/domains/firestore/presentation/query-keys/index.ts

@@ -1 +0,0 @@
-export { createFirestoreKeys } from './createFirestoreKeys';

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

@@ -1,119 +0,0 @@
-/**
- * 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;
-
-    const age = Date.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 {
-    // 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);
-    });
-
-    this.pendingQueries.set(key, {
-      promise,
-      timestamp: Date.now(),
-    });
-  }
-
-  /**
-   * 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

@@ -1,34 +0,0 @@
-/**
- * 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
- */
-function escapeKeyComponent(component: string): string {
-  return component.replace(/%/g, '%25').replace(/\|/g, '%7C');
-}
-
-/**
- * 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

@@ -1,83 +0,0 @@
-/**
- * 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();
-  }
-}