@umituz/react-native-subscription 3.1.9 → 3.1.11

package/src/shared/presentation/hooks/useFirestoreRealTime.ts

@@ -0,0 +1,230 @@
+/**
+ * Generic real-time sync hook for Firestore.
+ *
+ * Eliminates 90% duplication from real-time hooks:
+ * - useCreditsRealTime: 116 → ~35 lines
+ * - useTransactionHistory: 98 → ~30 lines
+ *
+ * Features:
+ * - Generic type support for any document/collection
+ * - Automatic cleanup with unsubscribe
+ * - Consistent error handling
+ * - Loading state management
+ * - Type-safe mapper function
+ * - Support for both document and collection queries
+ */
+
+import { useEffect, useState, useCallback, useRef } from "react";
+import {
+  onSnapshot,
+  type Query,
+  type DocumentReference,
+} from "firebase/firestore";
+import type { HookState, HookStateWithEmpty } from "../types/hookState.types";
+import { logError, logWarn } from "../../utils/logger";
+
+/**
+ * Configuration for building a Firestore document reference.
+ */
+export interface DocumentConfig {
+  /** Collection name */
+  collectionName: string;
+
+  /** Whether to use a user subcollection (users/{userId}/{collectionName}) */
+  useUserSubcollection: boolean;
+
+  /** Document ID (fixed string or function that takes userId) */
+  docId: string | ((userId: string) => string);
+}
+
+/**
+ * Configuration for building a Firestore collection query.
+ */
+export interface CollectionConfig {
+  /** Collection name */
+  collectionName: string;
+
+  /** Whether to use a user subcollection (users/{userId}/{collectionName}) */
+  useUserSubcollection: boolean;
+}
+
+/**
+ * Query builder for collection queries.
+ * Takes a Firestore collection reference and returns a Query with constraints.
+ */
+export type QueryBuilder<T> = (collection: any) => Query<T>;
+
+/**
+ * Mapper function to convert Firestore document data to domain entity.
+ */
+export type Mapper<TDocument, TEntity> = (
+  doc: TDocument,
+  docId: string
+) => TEntity;
+
+/**
+ * Generic hook for real-time document sync via Firestore onSnapshot.
+ *
+ * PERFORMANCE: Uses useRef to stabilize mapper and prevent unnecessary re-subscriptions
+ *
+ * @template TDocument - Firestore document type
+ * @template TEntity - Domain entity type
+ *
+ * @param userId - User ID to fetch document for
+ * @param docRef - Document reference from Firestore
+ * @param mapper - Function to map document data to entity
+ * @param tag - Logging tag for debugging
+ *
+ * @returns Hook state with data, loading, error, and refetch
+ */
+export function useFirestoreDocumentRealTime<TDocument, TEntity>(
+  userId: string | null | undefined,
+  docRef: DocumentReference<TDocument> | null,
+  mapper: Mapper<TDocument, TEntity>,
+  tag: string
+): HookState<TEntity> {
+  const [data, setData] = useState<TEntity | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Stabilize mapper to prevent re-subscriptions when parent re-renders
+  const mapperRef = useRef(mapper);
+  mapperRef.current = mapper;
+
+  useEffect(() => {
+    // Reset state when userId changes
+    if (!userId) {
+      setData(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    if (!docRef) {
+      setIsLoading(false);
+      return;
+    }
+
+    const unsubscribe = onSnapshot(
+      docRef,
+      (snapshot) => {
+        if (snapshot.exists()) {
+          const entity = mapperRef.current(snapshot.data() as TDocument, snapshot.id);
+          setData(entity);
+        } else {
+          setData(null);
+        }
+        setIsLoading(false);
+      },
+      (err: Error) => {
+        logError(tag, "Snapshot error", err, { userId });
+        setError(err);
+        setIsLoading(false);
+      }
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [userId, docRef, tag]); // Removed mapper from deps
+
+  const refetch = useCallback(() => {
+    // Real-time sync doesn't need refetch, but keep for API compatibility
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      logWarn(tag, "Refetch called - not needed for real-time sync");
+    }
+  }, [tag]);
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch,
+  };
+}
+
+/**
+ * Generic hook for real-time collection sync via Firestore onSnapshot.
+ *
+ * PERFORMANCE: Uses useRef to stabilize mapper and optimize snapshot processing
+ *
+ * @template TDocument - Firestore document type
+ * @template TEntity - Domain entity type
+ *
+ * @param userId - User ID to fetch collection for
+ * @param query - Firestore query to listen to
+ * @param mapper - Function to map document data to entity
+ * @param tag - Logging tag for debugging
+ *
+ * @returns Hook state with array data, loading, error, refetch, and isEmpty
+ */
+export function useFirestoreCollectionRealTime<TDocument, TEntity>(
+  userId: string | null | undefined,
+  query: Query<TDocument>,
+  mapper: Mapper<TDocument, TEntity>,
+  tag: string
+): HookStateWithEmpty<TEntity> {
+  const [data, setData] = useState<TEntity[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Stabilize mapper to prevent re-subscriptions when parent re-renders
+  const mapperRef = useRef(mapper);
+  mapperRef.current = mapper;
+
+  useEffect(() => {
+    // Reset state when userId changes
+    if (!userId) {
+      setData([]);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    const unsubscribe = onSnapshot(
+      query,
+      (snapshot) => {
+        // PERFORMANCE: Pre-allocate array with known size for better memory efficiency
+        const entities: TEntity[] = new Array(snapshot.size);
+        let index = 0;
+
+        snapshot.forEach((doc) => {
+          entities[index++] = mapperRef.current(doc.data() as TDocument, doc.id);
+        });
+
+        setData(entities);
+        setIsLoading(false);
+      },
+      (err: Error) => {
+        logError(tag, "Snapshot error", err, { userId });
+        setError(err);
+        setIsLoading(false);
+      }
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [userId, query, tag]); // Removed mapper from deps
+
+  const refetch = useCallback(() => {
+    // Real-time sync doesn't need refetch, but keep for API compatibility
+    if (typeof __DEV__ !== "undefined" && __DEV__) {
+      logWarn(tag, "Refetch called - not needed for real-time sync");
+    }
+  }, [tag]);
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch,
+    isEmpty: data.length === 0,
+  };
+}

package/src/shared/presentation/types/hookState.types.ts

@@ -0,0 +1,97 @@
+/**
+ * Standardized hook state types for consistent return values across all hooks.
+ *
+ * Benefits:
+ * - Type consistency across 25+ hooks
+ * - Easier to understand and maintain
+ * - Better IDE autocomplete
+ * - Predictable API surface
+ */
+
+/**
+ * Standard hook state returned by data-fetching hooks.
+ * Provides consistent interface for loading, error, and data states.
+ *
+ * @template T - The type of data returned by the hook
+ */
+export interface HookState<T> {
+  /** The fetched data, or null if not yet loaded or on error */
+  data: T | null;
+
+  /** Whether the hook is currently fetching data */
+  isLoading: boolean;
+
+  /** Any error that occurred during fetching, or null if no error */
+  error: Error | null;
+
+  /** Function to manually refetch data (no-op for real-time sync hooks) */
+  refetch: () => void;
+}
+
+/**
+ * Extended hook state that includes isEmpty for collection queries.
+ * Useful when you need to distinguish between "no data" and "loading".
+ *
+ * @template T - The type of data in the array (typically a document type)
+ */
+export interface HookStateWithEmpty<T> extends HookState<T[]> {
+  /** Whether the data array is empty (only meaningful when isLoading is false) */
+  isEmpty: boolean;
+}
+
+/**
+ * Extended hook state that includes metadata.
+ * Useful for hooks that need to return additional computed values.
+ *
+ * @template T - The type of data returned by the hook
+ * @template M - The type of metadata
+ */
+export interface HookStateWithMeta<T, M> extends HookState<T> {
+  /** Additional computed or derived metadata */
+  meta: M;
+}
+
+/**
+ * Factory function to create a standard HookState.
+ * Useful for testing or when you need to construct state objects.
+ */
+export function createHookState<T>(
+  data: T | null,
+  isLoading: boolean,
+  error: Error | null,
+  refetch: () => void = () => {}
+): HookState<T> {
+  return { data, isLoading, error, refetch };
+}
+
+/**
+ * Factory function to create a HookStateWithEmpty.
+ * Automatically computes isEmpty from the data array.
+ */
+export function createHookStateWithEmpty<T>(
+  data: T[] | null,
+  isLoading: boolean,
+  error: Error | null,
+  refetch: () => void = () => {}
+): HookStateWithEmpty<T> {
+  return {
+    data,
+    isLoading,
+    error,
+    refetch,
+    isEmpty: data === null ? false : data.length === 0,
+  };
+}
+
+/**
+ * Factory function to create a HookStateWithMeta.
+ */
+export function createHookStateWithMeta<T, M>(
+  data: T | null,
+  isLoading: boolean,
+  error: Error | null,
+  meta: M,
+  refetch: () => void = () => {}
+): HookStateWithMeta<T, M> {
+  return { data, isLoading, error, refetch, meta };
+}

package/src/shared/utils/errors/errorAssertions.ts

@@ -0,0 +1,35 @@
+/**
+ * Error Assertion Functions
+ *
+ * Runtime validation and type narrowing utilities.
+ * Throws errors with consistent formatting.
+ */
+
+import { createError } from "./errorConversion";
+
+/**
+ * Assert that a condition is true, throw error otherwise.
+ * Useful for validation and runtime checks.
+ */
+export function assert(
+  condition: boolean,
+  message: string,
+  code: string = "ASSERTION_ERROR"
+): asserts condition {
+  if (!condition) {
+    throw createError(message, code);
+  }
+}
+
+/**
+ * Assert that a value is not null/undefined.
+ * Throws error if value is null/undefined, returns value otherwise.
+ * Useful for type narrowing.
+ */
+export function assertNotNil<T>(
+  value: T | null | undefined,
+  message: string = "Value should not be null or undefined"
+): T {
+  assert(value !== null && value !== undefined, message, "NOT_NIL_ERROR");
+  return value;
+}

package/src/shared/utils/errors/errorConversion.ts

@@ -0,0 +1,73 @@
+/**
+ * Error Conversion Utilities
+ *
+ * Functions to normalize and convert unknown errors to Error objects.
+ * Separated for better modularity and testability.
+ */
+
+import { logError } from "../logger";
+
+/**
+ * Safely convert unknown error to Error object.
+ * Useful when catching errors from external APIs.
+ */
+export function toError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+
+  if (error === null || error === undefined) {
+    return new Error("Unknown error occurred");
+  }
+
+  try {
+    return new Error(JSON.stringify(error));
+  } catch {
+    return new Error(String(error));
+  }
+}
+
+/**
+ * Create an error with a code and optional cause.
+ */
+export function createError(
+  message: string,
+  code: string,
+  cause?: Error
+): Error {
+  const error = new Error(message);
+  error.name = code;
+
+  if (cause) {
+    // @ts-ignore - adding cause property
+    error.cause = cause;
+  }
+
+  return error;
+}
+
+/**
+ * Log an error with consistent formatting.
+ * Only logs in __DEV__ mode.
+ */
+export function logAndReturnError(
+  tag: string,
+  message: string,
+  error: unknown,
+  context?: Record<string, unknown>
+): Error {
+  const normalizedError = toError(error);
+
+  if (typeof __DEV__ !== "undefined" && __DEV__) {
+    logError(tag, message, normalizedError, {
+      ...context,
+      originalError: error,
+    });
+  }
+
+  return normalizedError;
+}

package/src/shared/utils/errors/errorTypeGuards.ts

@@ -0,0 +1,27 @@
+/**
+ * Error Type Guards
+ *
+ * Type-safe error checking utilities.
+ * Provides type narrowing for error objects.
+ */
+
+/**
+ * Type guard to check if value is an Error.
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}
+
+/**
+ * Type guard to check if error has a code property.
+ */
+export function isErrorWithCode(error: Error): error is Error & { code: string } {
+  return "code" in error && typeof error.code === "string";
+}
+
+/**
+ * Type guard to check if error has a cause property.
+ */
+export function isErrorWithCause(error: Error): error is Error & { cause: Error } {
+  return "cause" in error && error.cause instanceof Error;
+}

package/src/shared/utils/errors/errorWrappers.ts

@@ -0,0 +1,54 @@
+/**
+ * Error Wrapper Functions
+ *
+ * Wrap functions with error handling and return Result types.
+ * Provides consistent error handling patterns.
+ */
+
+import { logAndReturnError } from "./errorConversion";
+
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: Error };
+
+/**
+ * Wrap an async function with error handling.
+ * Returns a Result type with success/error states.
+ */
+export async function tryAsync<T>(
+  fn: () => Promise<T>,
+  context: { tag: string; operation: string }
+): Promise<Result<T>> {
+  try {
+    const data = await fn();
+    return { success: true, data };
+  } catch (error) {
+    const normalizedError = logAndReturnError(
+      context.tag,
+      `Failed to ${context.operation}`,
+      error
+    );
+    return { success: false, error: normalizedError };
+  }
+}
+
+/**
+ * Wrap a synchronous function with error handling.
+ * Returns a Result type with success/error states.
+ */
+export function trySync<T>(
+  fn: () => T,
+  context: { tag: string; operation: string }
+): Result<T> {
+  try {
+    const data = fn();
+    return { success: true, data };
+  } catch (error) {
+    const normalizedError = logAndReturnError(
+      context.tag,
+      `Failed to ${context.operation}`,
+      error
+    );
+    return { success: false, error: normalizedError };
+  }
+}

package/src/shared/utils/errors/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Error Utilities Module
+ *
+ * Centralized error handling utilities split into focused modules.
+ * Original 195-line file split into 5 files for better maintainability.
+ *
+ * Modules:
+ * - errorConversion: Error normalization and creation
+ * - errorTypeGuards: Type-safe error checking
+ * - errorWrappers: Function wrapping with error handling
+ * - errorAssertions: Runtime validation and type narrowing
+ * - serviceErrors: Service-specific error creation
+ */
+
+export * from './errorConversion';
+export * from './errorTypeGuards';
+export * from './errorWrappers';
+export * from './errorAssertions';
+export * from './serviceErrors';

package/src/shared/utils/errors/serviceErrors.ts

@@ -0,0 +1,36 @@
+/**
+ * Service-Specific Error Creators
+ *
+ * Consistent error creation for external services.
+ * Provides clear error codes and messages.
+ */
+
+import { createError, toError } from "./errorConversion";
+
+/**
+ * Create a Firestore-specific error with consistent formatting.
+ */
+export function createFirestoreError(
+  operation: string,
+  error: unknown
+): Error {
+  return createError(
+    `Firestore ${operation} failed`,
+    "FIRESTORE_ERROR",
+    toError(error)
+  );
+}
+
+/**
+ * Create a RevenueCat-specific error with consistent formatting.
+ */
+export function createRevenueCatError(
+  operation: string,
+  error: unknown
+): Error {
+  return createError(
+    `RevenueCat ${operation} failed`,
+    "REVENUECAT_ERROR",
+    toError(error)
+  );
+}