@umituz/react-native-firebase 1.13.3 → 1.13.4

package/src/firestore/utils/document-mapper.helper.ts

@@ -0,0 +1,145 @@
+/**
+ * Document Mapper Helper
+ *
+ * Utilities for batch document processing with enrichment.
+ * Handles document extraction, validation, and enrichment with related data.
+ *
+ * App-agnostic: Works with any document type and any enrichment logic.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentMapperHelper } from '@umituz/react-native-firestore';
+ *
+ * const mapper = new DocumentMapperHelper<Post, User, EnrichedPost>();
+ * const enriched = await mapper.mapWithEnrichment(
+ *   postDocs,
+ *   post => extractPost(post),
+ *   post => post.userId,
+ *   userId => userRepo.getById(userId),
+ *   (post, user) => ({ ...post, user })
+ * );
+ * ```
+ */
+
+import type { QueryDocumentSnapshot, DocumentData } from 'firebase/firestore';
+
+export class DocumentMapperHelper<TSource, TEnrichment, TResult> {
+  /**
+   * Map documents with enrichment from related data
+   *
+   * Process flow:
+   * 1. Extract source data from document
+   * 2. Skip if extraction fails or source is invalid
+   * 3. Get enrichment key from source
+   * 4. Fetch enrichment data using the key
+   * 5. Skip if enrichment data not found
+   * 6. Combine source and enrichment into result
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractSource - Extract source data from document
+   * @param getEnrichmentKey - Get enrichment key from source
+   * @param fetchEnrichment - Fetch enrichment data by key
+   * @param combineData - Combine source and enrichment into result
+   * @returns Array of enriched results
+   */
+  async mapWithEnrichment(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractSource: (doc: QueryDocumentSnapshot<DocumentData>) => TSource | null,
+    getEnrichmentKey: (source: TSource) => string,
+    fetchEnrichment: (key: string) => Promise<TEnrichment | null>,
+    combineData: (source: TSource, enrichment: TEnrichment) => TResult,
+  ): Promise<TResult[]> {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const source = extractSource(doc);
+      if (!source) continue;
+
+      const enrichmentKey = getEnrichmentKey(source);
+      const enrichment = await fetchEnrichment(enrichmentKey);
+      if (!enrichment) continue;
+
+      results.push(combineData(source, enrichment));
+    }
+
+    return results;
+  }
+
+  /**
+   * Map documents with multiple enrichments
+   *
+   * Similar to mapWithEnrichment but supports multiple enrichment sources.
+   * Useful when result needs data from multiple related collections.
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractSource - Extract source data from document
+   * @param getEnrichmentKeys - Get all enrichment keys from source
+   * @param fetchEnrichments - Fetch all enrichment data by keys
+   * @param combineData - Combine source and enrichments into result
+   * @returns Array of enriched results
+   */
+  async mapWithMultipleEnrichments<TEnrichments extends Record<string, unknown>>(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractSource: (doc: QueryDocumentSnapshot<DocumentData>) => TSource | null,
+    getEnrichmentKeys: (source: TSource) => Record<string, string>,
+    fetchEnrichments: (keys: Record<string, string>) => Promise<TEnrichments | null>,
+    combineData: (source: TSource, enrichments: TEnrichments) => TResult,
+  ): Promise<TResult[]> {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const source = extractSource(doc);
+      if (!source) continue;
+
+      const enrichmentKeys = getEnrichmentKeys(source);
+      const enrichments = await fetchEnrichments(enrichmentKeys);
+      if (!enrichments) continue;
+
+      results.push(combineData(source, enrichments));
+    }
+
+    return results;
+  }
+
+  /**
+   * Simple document mapping without enrichment
+   *
+   * @param docs - Firestore document snapshots
+   * @param extractData - Extract data from document
+   * @returns Array of extracted data (nulls filtered out)
+   */
+  map(
+    docs: QueryDocumentSnapshot<DocumentData>[],
+    extractData: (doc: QueryDocumentSnapshot<DocumentData>) => TResult | null,
+  ): TResult[] {
+    const results: TResult[] = [];
+
+    for (const doc of docs) {
+      const data = extractData(doc);
+      if (data) {
+        results.push(data);
+      }
+    }
+
+    return results;
+  }
+}
+
+/**
+ * Create document mapper helper
+ *
+ * @returns DocumentMapperHelper instance
+ *
+ * @example
+ * ```typescript
+ * const mapper = createDocumentMapper<Post, User, EnrichedPost>();
+ * const enriched = await mapper.mapWithEnrichment(...);
+ * ```
+ */
+export function createDocumentMapper<
+  TSource,
+  TEnrichment,
+  TResult,
+>(): DocumentMapperHelper<TSource, TEnrichment, TResult> {
+  return new DocumentMapperHelper<TSource, TEnrichment, TResult>();
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Pagination Helper
+ *
+ * Utilities for cursor-based pagination in Firestore.
+ * Handles pagination logic, cursor management, and hasMore detection.
+ *
+ * App-agnostic: Works with any document type and any collection.
+ *
+ * @example
+ * ```typescript
+ * import { PaginationHelper } from '@umituz/react-native-firestore';
+ *
+ * const helper = new PaginationHelper<Post>();
+ * const result = helper.buildResult(posts, 10, post => post.id);
+ * ```
+ */
+
+import type { PaginatedResult, PaginationParams } from '../types/pagination.types';
+
+export class PaginationHelper<T> {
+  /**
+   * Build paginated result from items
+   *
+   * @param items - All items fetched (should be limit + 1)
+   * @param pageLimit - Requested page size
+   * @param getCursor - Function to extract cursor from item
+   * @returns Paginated result with hasMore and nextCursor
+   */
+  buildResult(
+    items: T[],
+    pageLimit: number,
+    getCursor: (item: T) => string,
+  ): PaginatedResult<T> {
+    const hasMore = items.length > pageLimit;
+    const resultItems = hasMore ? items.slice(0, pageLimit) : items;
+    const lastItem = resultItems[resultItems.length - 1];
+    const nextCursor = hasMore && lastItem
+      ? getCursor(lastItem)
+      : null;
+
+    return {
+      items: resultItems,
+      nextCursor,
+      hasMore,
+    };
+  }
+
+  /**
+   * Get default limit from params or use default
+   *
+   * @param params - Pagination params
+   * @param defaultLimit - Default limit if not specified
+   * @returns Page limit
+   */
+  getLimit(params?: PaginationParams, defaultLimit: number = 10): number {
+    return params?.limit || defaultLimit;
+  }
+
+  /**
+   * Calculate fetch limit (page limit + 1 for hasMore detection)
+   *
+   * @param pageLimit - Requested page size
+   * @returns Fetch limit (pageLimit + 1)
+   */
+  getFetchLimit(pageLimit: number): number {
+    return pageLimit + 1;
+  }
+
+  /**
+   * Check if params has cursor
+   *
+   * @param params - Pagination params
+   * @returns true if cursor exists
+   */
+  hasCursor(params?: PaginationParams): boolean {
+    return !!params?.cursor;
+  }
+}
+
+/**
+ * Create pagination helper for a specific type
+ *
+ * @returns PaginationHelper instance
+ *
+ * @example
+ * ```typescript
+ * const helper = createPaginationHelper<Post>();
+ * const result = helper.buildResult(posts, 10, post => post.id);
+ * ```
+ */
+export function createPaginationHelper<T>(): PaginationHelper<T> {
+  return new PaginationHelper<T>();
+}

package/src/firestore/utils/query-builder.ts

@@ -0,0 +1,188 @@
+/**
+ * Query Builder Utility
+ * Single Responsibility: Build Firestore queries with advanced filtering
+ *
+ * App-agnostic utility for building Firestore queries.
+ * Supports:
+ * - Firestore 'in' operator (up to 10 values)
+ * - Firestore 'or' operator (for >10 values via chunking)
+ * - Single value filtering
+ * - Multiple field filtering
+ * - Date range filtering
+ * - Sorting
+ * - Limiting
+ *
+ * This utility is designed to be used across hundreds of apps.
+ * It provides a consistent interface for Firestore query building.
+ */
+
+import {
+  collection,
+  query,
+  where,
+  orderBy,
+  limit as limitQuery,
+  startAfter,
+  or,
+  type Firestore,
+  type Query,
+  Timestamp,
+  type WhereFilterOp,
+} from "firebase/firestore";
+
+export interface FieldFilter {
+  field: string;
+  operator: WhereFilterOp;
+  value: string | number | boolean | string[] | number[];
+}
+
+export interface QueryBuilderOptions {
+  collectionName: string;
+  baseFilters?: FieldFilter[];
+  dateRange?: {
+    field: string;
+    startDate?: number;
+    endDate?: number;
+  };
+  sort?: {
+    field: string;
+    order?: "asc" | "desc";
+  };
+  limitValue?: number;
+  /**
+   * Cursor value for pagination (timestamp in milliseconds)
+   * Used with startAfter for cursor-based pagination
+   */
+  cursorValue?: number;
+}
+
+const MAX_IN_OPERATOR_VALUES = 10;
+
+/**
+ * Build Firestore query with advanced filtering support
+ *
+ * @param db - Firestore database instance
+ * @param options - Query builder options
+ * @returns Firestore Query object
+ */
+export function buildQuery(
+  db: Firestore,
+  options: QueryBuilderOptions,
+): Query {
+  const {
+    collectionName,
+    baseFilters = [],
+    dateRange,
+    sort,
+    limitValue,
+    cursorValue,
+  } = options;
+
+  const collectionRef = collection(db, collectionName);
+  let q: Query = collectionRef;
+
+  // Apply base filters
+  for (const filter of baseFilters) {
+    q = applyFieldFilter(q, filter);
+  }
+
+  // Apply date range filters
+  if (dateRange) {
+    if (dateRange.startDate) {
+      q = query(
+        q,
+        where(
+          dateRange.field,
+          ">=",
+          Timestamp.fromMillis(dateRange.startDate),
+        ),
+      );
+    }
+    if (dateRange.endDate) {
+      q = query(
+        q,
+        where(
+          dateRange.field,
+          "<=",
+          Timestamp.fromMillis(dateRange.endDate),
+        ),
+      );
+    }
+  }
+
+  // Apply sorting
+  if (sort) {
+    const sortOrder = sort.order || "desc";
+    q = query(q, orderBy(sort.field, sortOrder));
+  }
+
+  // Apply cursor for pagination (must come after orderBy)
+  if (cursorValue !== undefined) {
+    q = query(q, startAfter(Timestamp.fromMillis(cursorValue)));
+  }
+
+  // Apply limit
+  if (limitValue !== undefined) {
+    q = query(q, limitQuery(limitValue));
+  }
+
+  return q;
+}
+
+/**
+ * Apply field filter with support for 'in' operator and chunking
+ * Handles arrays by using 'in' operator (up to 10 values)
+ * For arrays >10 values, splits into chunks and uses 'or' operator
+ */
+function applyFieldFilter(q: Query, filter: FieldFilter): Query {
+  const { field, operator, value } = filter;
+
+  // Handle 'in' operator with array values
+  if (operator === "in" && Array.isArray(value)) {
+    // Firestore 'in' operator supports up to 10 values
+    if (value.length <= MAX_IN_OPERATOR_VALUES) {
+      return query(q, where(field, "in", value));
+    }
+
+    // Split into chunks of 10 and use 'or' operator
+    const chunks: (string[] | number[])[] = [];
+    for (let i = 0; i < value.length; i += MAX_IN_OPERATOR_VALUES) {
+      chunks.push(value.slice(i, i + MAX_IN_OPERATOR_VALUES));
+    }
+
+    const orConditions = chunks.map((chunk) => where(field, "in", chunk));
+    return query(q, or(...orConditions));
+  }
+
+  // Standard filter
+  return query(q, where(field, operator, value));
+}
+
+/**
+ * Helper: Create a field filter for 'in' operator
+ * Automatically handles chunking if array >10 values
+ */
+export function createInFilter(
+  field: string,
+  values: string[] | number[],
+): FieldFilter {
+  return {
+    field,
+    operator: "in",
+    value: values,
+  };
+}
+
+/**
+ * Helper: Create a field filter for equality
+ */
+export function createEqualFilter(
+  field: string,
+  value: string | number | boolean,
+): FieldFilter {
+  return {
+    field,
+    operator: "==",
+    value,
+  };
+}

package/src/firestore/utils/quota-error-detector.util.ts

@@ -0,0 +1,100 @@
+/**
+ * Quota Error Detector Utility
+ * Single Responsibility: Detect Firebase quota errors
+ *
+ * Firebase quota limits:
+ * - Free tier: 50K reads/day, 20K writes/day, 20K deletes/day
+ * - Blaze plan: Pay as you go, higher limits
+ *
+ * Quota errors are NOT retryable - quota won't increase by retrying
+ */
+
+/**
+ * Check if error is a Firebase quota error
+ * Quota errors indicate daily read/write/delete limits are exceeded
+ *
+ * @param error - Error object to check
+ * @returns true if error is a quota error
+ */
+export function isQuotaError(error: unknown): boolean {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+
+  const firebaseError = error as { code?: string; message?: string; name?: string };
+
+  // Check error code
+  if (firebaseError.code === "resource-exhausted") {
+    return true;
+  }
+
+  // Check error message
+  const errorMessage = firebaseError.message?.toLowerCase() || "";
+  if (
+    errorMessage.includes("quota") ||
+    errorMessage.includes("quota exceeded") ||
+    errorMessage.includes("resource-exhausted") ||
+    errorMessage.includes("daily limit")
+  ) {
+    return true;
+  }
+
+  // Check error name
+  const errorName = firebaseError.name?.toLowerCase() || "";
+  if (errorName.includes("quota") || errorName.includes("resource-exhausted")) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if error is retryable
+ * Quota errors are NOT retryable
+ *
+ * @param error - Error object to check
+ * @returns true if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  // Quota errors are NOT retryable
+  if (isQuotaError(error)) {
+    return false;
+  }
+
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+
+  const firebaseError = error as { code?: string; message?: string };
+
+  // Firestore transaction conflicts are retryable
+  if (firebaseError.code === "failed-precondition") {
+    return true;
+  }
+
+  // Network errors are retryable
+  if (
+    firebaseError.code === "unavailable" ||
+    firebaseError.code === "deadline-exceeded"
+  ) {
+    return true;
+  }
+
+  // Timeout errors are retryable
+  const errorMessage = firebaseError.message?.toLowerCase() || "";
+  if (errorMessage.includes("timeout")) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get user-friendly quota error message
+ *
+ * @returns User-friendly error message
+ */
+export function getQuotaErrorMessage(): string {
+  return "Firebase quota exceeded. Please try again later or upgrade your Firebase plan.";
+}
+

package/src/index.ts

@@ -5,12 +5,14 @@
  *
  * This package provides Firebase App initialization and core services:
  * - Auth
+ * - Firestore
  * - Analytics
  * - Crashlytics
  *
  * Usage:
  *   import { initializeFirebase, getFirebaseApp } from '@umituz/react-native-firebase';
  *   import { useFirebaseAuth } from '@umituz/react-native-firebase';
+ *   import { getFirestore, BaseRepository } from '@umituz/react-native-firebase';
  *   import { firebaseAnalyticsService } from '@umituz/react-native-firebase';
  */
 
@@ -51,6 +53,12 @@ export type {
 
 export * from './auth';
 
+// =============================================================================
+// FIRESTORE MODULE
+// =============================================================================
+
+export * from './firestore';
+
 // =============================================================================
 // ANALYTICS MODULE
 // =============================================================================