@umituz/react-native-firebase 1.13.136 → 1.13.138

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-firebase",
-  "version": "1.13.136",
+  "version": "1.13.138",
   "description": "Unified Firebase package for React Native apps - Auth and Firestore services using Firebase JS SDK (no native modules).",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/auth/infrastructure/config/FirebaseAuthClient.ts

@@ -1,72 +1,68 @@
 /**
  * Firebase Auth Client - Infrastructure Layer
+ *
+ * Manages Firebase Authentication instance initialization
  */
 
 import type { Auth } from 'firebase/auth';
 import { getFirebaseApp } from '../../../infrastructure/config/FirebaseClient';
 import { FirebaseAuthInitializer } from './initializers/FirebaseAuthInitializer';
 import type { FirebaseAuthConfig } from '../../domain/value-objects/FirebaseAuthConfig';
+import { ServiceClientSingleton } from '../../../infrastructure/config/base/ServiceClientSingleton';
+
+/**
+ * Firebase Auth Client Singleton
+ */
+class FirebaseAuthClientSingleton extends ServiceClientSingleton<Auth, FirebaseAuthConfig> {
+  private constructor() {
+    super({
+      serviceName: 'FirebaseAuth',
+      initializer: (config?: FirebaseAuthConfig) => {
+        const app = getFirebaseApp();
+        if (!app) {
+          this.setError('Firebase App is not initialized');
+          return null;
+        }
+        const auth = FirebaseAuthInitializer.initialize(app, config);
+        if (!auth) {
+          this.setError('Auth initialization returned null');
+        }
+        return auth;
+      },
+    });
+  }
 
-class FirebaseAuthClientSingleton {
   private static instance: FirebaseAuthClientSingleton | null = null;
-  private auth: Auth | null = null;
-  private initializationError: string | null = null;
 
   static getInstance(): FirebaseAuthClientSingleton {
     if (!this.instance) this.instance = new FirebaseAuthClientSingleton();
     return this.instance;
   }
 
+  /**
+   * Initialize Auth with optional configuration
+   */
   initialize(config?: FirebaseAuthConfig): Auth | null {
-    if (this.auth) return this.auth;
-    if (this.initializationError) return null;
-
-    try {
-      const app = getFirebaseApp();
-      if (!app) return null;
-      this.auth = FirebaseAuthInitializer.initialize(app, config);
-      if (!this.auth) {
-        this.initializationError = "Auth initialization returned null";
-      }
-      return this.auth;
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : "Unknown error";
-      if (__DEV__) console.error('[FirebaseAuth] Init error:', message);
-      this.initializationError = message;
-      return null;
-    }
+    return super.initialize(config);
   }
 
+  /**
+   * Get Auth instance
+   */
   getAuth(): Auth | null {
-    // Don't retry if we already have an auth instance
-    if (this.auth) return this.auth;
-
-    // Don't retry if we already failed to initialize
-    if (this.initializationError) return null;
-
-    // Don't retry if Firebase app is not available
-    const app = getFirebaseApp();
-    if (!app) return null;
-
-    // Attempt initialization
-    this.initialize();
-    return this.auth;
-  }
-
-  getInitializationError(): string | null {
-    return this.initializationError;
-  }
-
-  reset(): void {
-    this.auth = null;
-    this.initializationError = null;
+    // Attempt initialization if not already initialized
+    if (!this.isInitialized() && !this.getInitializationError()) {
+      const app = getFirebaseApp();
+      if (app) this.initialize();
+    }
+    return this.getInstance();
   }
 }
 
 export const firebaseAuthClient = FirebaseAuthClientSingleton.getInstance();
 export const initializeFirebaseAuth = (c?: FirebaseAuthConfig) => firebaseAuthClient.initialize(c);
 export const getFirebaseAuth = () => firebaseAuthClient.getAuth();
-export const isFirebaseAuthInitialized = () => firebaseAuthClient.getAuth() !== null;
+export const isFirebaseAuthInitialized = () => firebaseAuthClient.isInitialized();
 export const getFirebaseAuthInitializationError = () => firebaseAuthClient.getInitializationError();
 export const resetFirebaseAuthClient = () => firebaseAuthClient.reset();
 

package/src/auth/infrastructure/services/apple-auth.service.ts

@@ -12,6 +12,12 @@ import * as AppleAuthentication from "expo-apple-authentication";
 import { Platform } from "react-native";
 import { generateNonce, hashNonce } from "./crypto.util";
 import type { AppleAuthResult } from "./apple-auth.types";
+import {
+  createSuccessResult,
+  createFailureResult,
+  logAuthError,
+  isCancellationError,
+} from "./base/base-auth.service";
 
 export class AppleAuthService {
   async isAvailable(): Promise<boolean> {
@@ -61,17 +67,9 @@ export class AppleAuthService {
       });
 
       const userCredential = await signInWithCredential(auth, credential);
-      const isNewUser =
-        userCredential.user.metadata.creationTime ===
-        userCredential.user.metadata.lastSignInTime;
-
-      return {
-        success: true,
-        userCredential,
-        isNewUser,
-      };
+      return createSuccessResult(userCredential);
     } catch (error) {
-      if (error instanceof Error && error.message.includes("ERR_CANCELED")) {
+      if (isCancellationError(error)) {
         return {
           success: false,
           error: "Apple Sign-In was cancelled",
@@ -79,16 +77,8 @@ export class AppleAuthService {
         };
       }
 
-      if (__DEV__) console.error('[Firebase Auth] Apple Sign-In failed:', error);
-
-      const errorCode = (error as { code?: string })?.code || 'unknown';
-      const errorMessage = error instanceof Error ? error.message : 'Apple sign-in failed';
-
-      return {
-        success: false,
-        error: errorMessage,
-        code: errorCode,
-      };
+      logAuthError('Apple Sign-In', error);
+      return createFailureResult(error);
     }
   }
 

package/src/auth/infrastructure/services/base/base-auth.service.ts

@@ -0,0 +1,104 @@
+/**
+ * Base Auth Service
+ *
+ * Provides common authentication service functionality
+ * Handles error processing, result formatting, and credential management
+ */
+
+import type { UserCredential } from 'firebase/auth';
+import { toAuthErrorInfo } from '../../../../domain/utils/error-handler.util';
+
+/**
+ * Base authentication result interface
+ */
+export interface BaseAuthResult {
+  readonly success: boolean;
+  readonly error?: string;
+  readonly code?: string;
+}
+
+/**
+ * Successful authentication result
+ */
+export interface AuthSuccessResult extends BaseAuthResult {
+  readonly success: true;
+  readonly userCredential: UserCredential;
+  readonly isNewUser: boolean;
+}
+
+/**
+ * Failed authentication result
+ */
+export interface AuthFailureResult extends BaseAuthResult {
+  readonly success: false;
+  readonly error: string;
+  readonly code: string;
+}
+
+/**
+ * Combined auth result type
+ */
+export type AuthResult = AuthSuccessResult | AuthFailureResult;
+
+/**
+ * Check if user is new based on metadata
+ */
+export function checkIsNewUser(userCredential: UserCredential): boolean {
+  return (
+    userCredential.user.metadata.creationTime ===
+    userCredential.user.metadata.lastSignInTime
+  );
+}
+
+/**
+ * Extract error information from unknown error
+ */
+export function extractAuthError(error: unknown): { code: string; message: string } {
+  const errorInfo = toAuthErrorInfo(error);
+  return {
+    code: errorInfo.code,
+    message: errorInfo.message,
+  };
+}
+
+/**
+ * Check if error is a cancellation error
+ */
+export function isCancellationError(error: unknown): boolean {
+  if (error instanceof Error) {
+    return error.message.includes('ERR_CANCELED');
+  }
+  return false;
+}
+
+/**
+ * Create failure result from error
+ */
+export function createFailureResult(error: unknown): AuthFailureResult {
+  const { code, message } = extractAuthError(error);
+  return {
+    success: false,
+    error: message,
+    code,
+  };
+}
+
+/**
+ * Create success result from user credential
+ */
+export function createSuccessResult(userCredential: UserCredential): AuthSuccessResult {
+  return {
+    success: true,
+    userCredential,
+    isNewUser: checkIsNewUser(userCredential),
+  };
+}
+
+/**
+ * Log auth error in development mode
+ */
+export function logAuthError(serviceName: string, error: unknown): void {
+  if (__DEV__) {
+    console.error(`[Firebase Auth] ${serviceName} failed:`, error);
+  }
+}

package/src/auth/infrastructure/services/google-auth.service.ts

@@ -9,6 +9,11 @@ import {
   type Auth,
 } from "firebase/auth";
 import type { GoogleAuthConfig, GoogleAuthResult } from "./google-auth.types";
+import {
+  createSuccessResult,
+  createFailureResult,
+  logAuthError,
+} from "./base/base-auth.service";
 
 /**
  * Google Auth Service
@@ -41,30 +46,10 @@ export class GoogleAuthService {
     try {
       const credential = GoogleAuthProvider.credential(idToken);
       const userCredential = await signInWithCredential(auth, credential);
-
-      const isNewUser =
-        userCredential.user.metadata.creationTime ===
-        userCredential.user.metadata.lastSignInTime;
-
-      return {
-        success: true,
-        userCredential,
-        isNewUser,
-      };
+      return createSuccessResult(userCredential);
     } catch (error) {
-      if (__DEV__) {
-        console.error('[Firebase Auth] Google Sign-In failed:', error);
-      }
-
-      // Extract error code for better error handling
-      const errorCode = (error as { code?: string })?.code || 'unknown';
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-
-      return {
-        success: false,
-        error: errorMessage,
-        code: errorCode,
-      };
+      logAuthError('Google Sign-In', error);
+      return createFailureResult(error);
     }
   }
 }

package/src/domain/guards/firebase-error.guard.ts

@@ -8,6 +8,15 @@
 
 import type { FirestoreError } from 'firebase/firestore';
 import type { AuthError } from 'firebase/auth';
+import { hasCodeProperty } from '../utils/type-guards.util';
+
+/**
+ * Firebase error base interface
+ */
+interface FirebaseErrorBase {
+  code: string;
+  message: string;
+}
 
 /**
  * Check if error is a Firebase Firestore error
@@ -33,54 +42,54 @@ export function isAuthError(error: unknown): error is AuthError {
   );
 }
 
+/**
+ * Check if error is a Firebase error (either Firestore or Auth)
+ */
+export function isFirebaseError(error: unknown): error is FirebaseErrorBase {
+  return isFirestoreError(error) || isAuthError(error);
+}
+
+/**
+ * Check if error has a specific code
+ */
+export function hasErrorCode(error: unknown, code: string): boolean {
+  return hasCodeProperty(error) && error.code === code;
+}
+
+/**
+ * Check if error code matches any of the provided codes
+ */
+export function hasAnyErrorCode(error: unknown, codes: string[]): boolean {
+  if (!hasCodeProperty(error)) return false;
+  return codes.includes(error.code);
+}
+
 /**
  * Check if error is a network error
  */
 export function isNetworkError(error: unknown): boolean {
-  if (!isFirestoreError(error) && !isAuthError(error)) {
-    return false;
-  }
-
-  const code = (error as FirestoreError | AuthError).code;
-  return (
-    code === 'unavailable' ||
-    code === 'network-request-failed' ||
-    code === 'timeout'
-  );
+  return hasAnyErrorCode(error, ['unavailable', 'network-request-failed', 'timeout']);
 }
 
 /**
  * Check if error is a permission denied error
  */
 export function isPermissionDeniedError(error: unknown): boolean {
-  if (!isFirestoreError(error) && !isAuthError(error)) {
-    return false;
-  }
-
-  const code = (error as FirestoreError | AuthError).code;
-  return code === 'permission-denied' || code === 'unauthorized';
+  return hasAnyErrorCode(error, ['permission-denied', 'unauthorized']);
 }
 
 /**
  * Check if error is a not found error
  */
 export function isNotFoundError(error: unknown): boolean {
-  if (!isFirestoreError(error)) {
-    return false;
-  }
-
-  return (error as FirestoreError).code === 'not-found';
+  return hasErrorCode(error, 'not-found');
 }
 
 /**
  * Check if error is a quota exceeded error
  */
 export function isQuotaExceededError(error: unknown): boolean {
-  if (!isFirestoreError(error)) {
-    return false;
-  }
-
-  return (error as FirestoreError).code === 'resource-exhausted';
+  return hasErrorCode(error, 'resource-exhausted');
 }
 
 /**
@@ -88,7 +97,7 @@ export function isQuotaExceededError(error: unknown): boolean {
  * Returns error message or unknown error message
  */
 export function getSafeErrorMessage(error: unknown): string {
-  if (isFirestoreError(error) || isAuthError(error)) {
+  if (isFirebaseError(error)) {
     return error.message;
   }
 
@@ -108,7 +117,7 @@ export function getSafeErrorMessage(error: unknown): string {
  * Returns error code or unknown error code
  */
 export function getSafeErrorCode(error: unknown): string {
-  if (isFirestoreError(error) || isAuthError(error)) {
+  if (hasCodeProperty(error)) {
     return error.code;
   }
 

package/src/domain/utils/error-handler.util.ts

@@ -3,6 +3,8 @@
  * Centralized error handling utilities for Firebase operations
  */
 
+import { hasCodeProperty, hasMessageProperty, hasCodeAndMessageProperties } from './type-guards.util';
+
 /**
  * Standard error structure with code and message
  */
@@ -11,15 +13,39 @@ export interface ErrorInfo {
   message: string;
 }
 
+/**
+ * Quota error codes
+ */
+const QUOTA_ERROR_CODES = [
+  'resource-exhausted',
+  'quota-exceeded',
+  'RESOURCE_EXHAUSTED',
+];
+
+/**
+ * Quota error message patterns
+ */
+const QUOTA_ERROR_MESSAGES = [
+  'quota exceeded',
+  'quota limit',
+  'daily limit',
+  'resource exhausted',
+  'too many requests',
+];
+
+/**
+ * Retryable error codes
+ */
+const RETRYABLE_ERROR_CODES = ['unavailable', 'deadline-exceeded', 'aborted'];
+
 /**
  * Convert unknown error to standard error info
  * Handles Error objects, strings, and unknown types
  */
 export function toErrorInfo(error: unknown): ErrorInfo {
   if (error instanceof Error) {
-    const firebaseErr = error as { code?: string };
     return {
-      code: firebaseErr.code || 'unknown',
+      code: hasCodeProperty(error) ? error.code : 'unknown',
       message: error.message,
     };
   }
@@ -35,9 +61,8 @@ export function toErrorInfo(error: unknown): ErrorInfo {
  */
 export function toAuthErrorInfo(error: unknown): ErrorInfo {
   if (error instanceof Error) {
-    const firebaseErr = error as { code?: string };
     return {
-      code: firebaseErr.code || 'auth/failed',
+      code: hasCodeProperty(error) && error.code ? error.code : 'auth/failed',
       message: error.message,
     };
   }
@@ -58,13 +83,16 @@ export function hasErrorCode(error: ErrorInfo, code: string): boolean {
  * Check if error is a cancelled/auth cancelled error
  */
 export function isCancelledError(error: ErrorInfo): boolean {
-  return error.code === 'auth/cancelled' || error.message.includes('ERR_CANCELED');
+  return (
+    error.code === 'auth/cancelled' ||
+    error.message.includes('ERR_CANCELED')
+  );
 }
 
 /**
- * Check if error is a quota exceeded error
+ * Check if error info is a quota error
  */
-export function isQuotaError(error: ErrorInfo): boolean {
+export function isQuotaErrorInfo(error: ErrorInfo): boolean {
   return (
     error.code === 'quota-exceeded' ||
     error.code.includes('quota') ||
@@ -73,7 +101,7 @@ export function isQuotaError(error: ErrorInfo): boolean {
 }
 
 /**
- * Check if error is a network error
+ * Check if error info is a network error
  */
 export function isNetworkError(error: ErrorInfo): boolean {
   return (
@@ -83,8 +111,68 @@ export function isNetworkError(error: ErrorInfo): boolean {
 }
 
 /**
- * Check if error is an authentication error
+ * Check if error info is an authentication error
  */
 export function isAuthError(error: ErrorInfo): boolean {
   return error.code.startsWith('auth/');
 }
+
+/**
+ * Check if unknown error is a Firestore quota error
+ * Enhanced type guard with proper error checking
+ */
+export function isQuotaError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+
+  if (hasCodeProperty(error)) {
+    const code = error.code;
+    return QUOTA_ERROR_CODES.some(
+      (c) => code === c || code.endsWith(`/${c}`) || code.startsWith(`${c}/`)
+    );
+  }
+
+  if (hasMessageProperty(error)) {
+    const message = error.message.toLowerCase();
+    return QUOTA_ERROR_MESSAGES.some((m) => {
+      const pattern = m.toLowerCase();
+      return (
+        message.includes(` ${pattern} `) ||
+        message.startsWith(`${pattern} `) ||
+        message.endsWith(` ${pattern}`) ||
+        message === pattern
+      );
+    });
+  }
+
+  return false;
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+
+  if (hasCodeProperty(error)) {
+    return RETRYABLE_ERROR_CODES.some((code) => error.code.includes(code));
+  }
+
+  return false;
+}
+
+/**
+ * Get user-friendly quota error message
+ */
+export function getQuotaErrorMessage(): string {
+  return 'Daily quota exceeded. Please try again tomorrow or upgrade your plan.';
+}
+
+/**
+ * Get user-friendly retryable error message
+ */
+export function getRetryableErrorMessage(): string {
+  return 'Temporary error occurred. Please try again.';
+}
+
+// Re-export type guards for convenience
+export { hasCodeProperty, hasMessageProperty, hasCodeAndMessageProperties };

package/src/domain/utils/type-guards.util.ts

@@ -0,0 +1,66 @@
+/**
+ * Type Guard Utilities
+ *
+ * Common type guards for Firebase and JavaScript objects.
+ * Provides type-safe checking without using 'as' assertions.
+ */
+
+/**
+ * Type guard for objects with a 'code' property of type string
+ * Commonly used for Firebase errors and other error objects
+ */
+export function hasCodeProperty(error: unknown): error is { code: string } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof (error as { code: unknown }).code === 'string'
+  );
+}
+
+/**
+ * Type guard for objects with a 'message' property of type string
+ * Commonly used for Error objects
+ */
+export function hasMessageProperty(error: unknown): error is { message: string } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    typeof (error as { message: unknown }).message === 'string'
+  );
+}
+
+/**
+ * Type guard for objects with both 'code' and 'message' properties
+ * Commonly used for Firebase error objects
+ */
+export function hasCodeAndMessageProperties(error: unknown): error is { code: string; message: string } {
+  return hasCodeProperty(error) && hasMessageProperty(error);
+}
+
+/**
+ * Type guard for objects with a 'name' property of type string
+ * Commonly used for Error objects
+ */
+export function hasNameProperty(error: unknown): error is { name: string } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'name' in error &&
+    typeof (error as { name: unknown }).name === 'string'
+  );
+}
+
+/**
+ * Type guard for objects with a 'stack' property of type string
+ * Commonly used for Error objects
+ */
+export function hasStackProperty(error: unknown): error is { stack: string } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'stack' in error &&
+    typeof (error as { stack: unknown }).stack === 'string'
+  );
+}

package/src/firestore/infrastructure/config/FirestoreClient.ts

@@ -11,17 +11,33 @@
 import type { Firestore } from 'firebase/firestore';
 import { getFirebaseApp } from '../../../infrastructure/config/FirebaseClient';
 import { FirebaseFirestoreInitializer } from './initializers/FirebaseFirestoreInitializer';
+import { ServiceClientSingleton } from '../../../infrastructure/config/base/ServiceClientSingleton';
 
 /**
  * Firestore Client Singleton
  * Manages Firestore initialization
  */
-class FirestoreClientSingleton {
-  private static instance: FirestoreClientSingleton | null = null;
-  private firestore: Firestore | null = null;
-  private initializationError: string | null = null;
+class FirestoreClientSingleton extends ServiceClientSingleton<Firestore> {
+  private constructor() {
+    super({
+      serviceName: 'Firestore',
+      initializer: () => {
+        const app = getFirebaseApp();
+        if (!app) {
+          this.setError('Firebase App is not initialized');
+          return null;
+        }
+        return FirebaseFirestoreInitializer.initialize(app);
+      },
+      autoInitializer: () => {
+        const app = getFirebaseApp();
+        if (!app) return null;
+        return FirebaseFirestoreInitializer.initialize(app);
+      },
+    });
+  }
 
-  private constructor() {}
+  private static instance: FirestoreClientSingleton | null = null;
 
   static getInstance(): FirestoreClientSingleton {
     if (!FirestoreClientSingleton.instance) {
@@ -30,44 +46,18 @@ class FirestoreClientSingleton {
     return FirestoreClientSingleton.instance;
   }
 
+  /**
+   * Initialize Firestore
+   */
   initialize(): Firestore | null {
-    if (this.firestore) return this.firestore;
-    if (this.initializationError) return null;
-
-    try {
-      const app = getFirebaseApp();
-      if (!app) return null;
-
-      this.firestore = FirebaseFirestoreInitializer.initialize(app);
-      return this.firestore;
-    } catch (error) {
-      this.initializationError =
-        error instanceof Error
-          ? error.message
-          : 'Failed to initialize Firestore client';
-      return null;
-    }
+    return super.initialize();
   }
 
+  /**
+   * Get Firestore instance with auto-initialization
+   */
   getFirestore(): Firestore | null {
-    if (!this.firestore && !this.initializationError) {
-      const app = getFirebaseApp();
-      if (app) this.initialize();
-    }
-    return this.firestore || null;
-  }
-
-  isInitialized(): boolean {
-    return this.firestore !== null;
-  }
-
-  getInitializationError(): string | null {
-    return this.initializationError;
-  }
-
-  reset(): void {
-    this.firestore = null;
-    this.initializationError = null;
+    return this.getInstance(true);
   }
 }
 
@@ -94,4 +84,3 @@ export function resetFirestoreClient(): void {
 }
 
 export type { Firestore } from 'firebase/firestore';
-

package/src/firestore/infrastructure/middleware/QueryDeduplicationMiddleware.ts

@@ -33,7 +33,11 @@ export class QueryDeduplicationMiddleware {
     if (this.queryManager.isPending(key)) {
       const pendingPromise = this.queryManager.get(key);
       if (pendingPromise) {
-        return pendingPromise as Promise<T>;
+        // Type assertion is safe here because the same key was used to store the promise
+        return Promise.race([pendingPromise]).then(() => {
+          // Retry the original query after pending completes
+          return queryFn();
+        });
       }
     }
 
@@ -59,4 +63,3 @@ export class QueryDeduplicationMiddleware {
 
 export const queryDeduplicationMiddleware = new QueryDeduplicationMiddleware();
 export type { QueryKey };
-

package/src/firestore/utils/operation/operation-executor.util.ts

@@ -6,7 +6,7 @@
 import type { Firestore } from "../../infrastructure/config/FirestoreClient";
 import { getFirestore } from "../../infrastructure/config/FirestoreClient";
 import type { FirestoreResult } from "../result/result.util";
-import { NO_DB_ERROR } from "../result/result.util";
+import { createNoDbErrorResult } from "../result/result.util";
 
 /**
  * Execute a Firestore operation with automatic null check
@@ -17,7 +17,7 @@ export async function withFirestore<T>(
 ): Promise<FirestoreResult<T>> {
   const db = getFirestore();
   if (!db) {
-    return NO_DB_ERROR as FirestoreResult<T>;
+    return createNoDbErrorResult<T>();
   }
   return operation(db);
 }

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

@@ -1,82 +1,13 @@
 /**
  * Quota Error Detection Utilities
+ *
+ * Re-exports centralized quota error detection from error-handler.util.ts
+ * This maintains backwards compatibility while using a single source of truth.
  */
 
-const QUOTA_ERROR_CODES = [
-    'resource-exhausted',
-    'quota-exceeded',
-    'RESOURCE_EXHAUSTED',
-];
-
-const QUOTA_ERROR_MESSAGES = [
-    'quota exceeded',
-    'quota limit',
-    'daily limit',
-    'resource exhausted',
-    'too many requests',
-];
-
-/**
- * Type guard for error with code property
- */
-function hasCodeProperty(error: unknown): error is { code: string } {
-    return typeof error === 'object' && error !== null && 'code' in error && typeof (error as { code: unknown }).code === 'string';
-}
-
-/**
- * Type guard for error with message property
- */
-function hasMessageProperty(error: unknown): error is { message: string } {
-    return typeof error === 'object' && error !== null && 'message' in error && typeof (error as { message: unknown }).message === 'string';
-}
-
-/**
- * Check if error is a Firestore quota error
- */
-export function isQuotaError(error: unknown): boolean {
-    if (!error || typeof error !== 'object') return false;
-
-    if (hasCodeProperty(error)) {
-        const code = error.code;
-        // Use more specific matching - exact match or ends with pattern
-        return QUOTA_ERROR_CODES.some((c) =>
-            code === c || code.endsWith(`/${c}`) || code.startsWith(`${c}/`)
-        );
-    }
-
-    if (hasMessageProperty(error)) {
-        const message = error.message;
-        const lowerMessage = message.toLowerCase();
-        // Use word boundaries to avoid partial matches
-        return QUOTA_ERROR_MESSAGES.some((m) =>
-            lowerMessage.includes(` ${m} `) ||
-            lowerMessage.startsWith(`${m} `) ||
-            lowerMessage.endsWith(` ${m}`) ||
-            lowerMessage === m
-        );
-    }
-
-    return false;
-}
-
-/**
- * Check if error is retryable
- */
-export function isRetryableError(error: unknown): boolean {
-    if (!error || typeof error !== 'object') return false;
-
-    if (hasCodeProperty(error)) {
-        const code = error.code;
-        const retryableCodes = ['unavailable', 'deadline-exceeded', 'aborted'];
-        return retryableCodes.some((c) => code.includes(c));
-    }
-
-    return false;
-}
-
-/**
- * Get user-friendly quota error message
- */
-export function getQuotaErrorMessage(): string {
-    return 'Daily quota exceeded. Please try again tomorrow or upgrade your plan.';
-}
+export {
+  isQuotaError,
+  isRetryableError,
+  getQuotaErrorMessage,
+  getRetryableErrorMessage,
+} from '../../domain/utils/error-handler.util';

package/src/firestore/utils/result/result.util.ts

@@ -26,10 +26,17 @@ export function createErrorResult<T>(message: string, code: string): FirestoreRe
 /**
  * Create a standard success result
  */
-export function createSuccessResult<T>(data?: T): FirestoreResult<T> {
+export function createFirestoreSuccessResult<T>(data?: T): FirestoreResult<T> {
   return { success: true, data };
 }
 
+/**
+ * Create no-db error result with proper typing
+ */
+export function createNoDbErrorResult<T>(): FirestoreResult<T> {
+  return { success: false, error: NO_DB_ERROR.error };
+}
+
 /**
  * Check if result is successful
  */
@@ -43,3 +50,6 @@ export function isSuccess<T>(result: FirestoreResult<T>): result is FirestoreRes
 export function isError<T>(result: FirestoreResult<T>): result is FirestoreResult<T> & { success: false } {
   return !result.success;
 }
+
+// Keep old function name for backwards compatibility
+export const createSuccessResult = createFirestoreSuccessResult;

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

@@ -9,7 +9,7 @@ import {
   type Transaction,
 } from "firebase/firestore";
 import { getFirestore } from "../../infrastructure/config/FirestoreClient";
-import type { Firestore } from "../../infrastructure/config/FirestoreClient";
+import { hasCodeProperty } from "../../../domain/utils/type-guards.util";
 
 /**
  * Execute a transaction with automatic DB instance check.
@@ -23,10 +23,10 @@ export async function runTransaction<T>(
     throw new Error("[runTransaction] Firestore database is not initialized. Please ensure Firebase is properly initialized before running transactions.");
   }
   try {
-    return await fbRunTransaction(db as Firestore, updateFunction);
+    return await fbRunTransaction(db, updateFunction);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-    const errorCode = error instanceof Error ? (error as { code?: string }).code : 'unknown';
+    const errorCode = hasCodeProperty(error) ? error.code : 'unknown';
 
     if (__DEV__) {
       console.error(`[runTransaction] Transaction failed (Code: ${errorCode}):`, errorMessage);

package/src/infrastructure/config/base/ClientStateManager.ts

@@ -0,0 +1,82 @@
+/**
+ * Client State Manager
+ *
+ * Generic state management for Firebase service clients.
+ * Provides centralized state tracking for initialization status, errors, and instances.
+ *
+ * @template TInstance - The service instance type (e.g., FirebaseApp, Firestore, Auth)
+ */
+
+export interface ClientState<TInstance> {
+  instance: TInstance | null;
+  initializationError: string | null;
+  isInitialized: boolean;
+}
+
+/**
+ * Generic client state manager
+ * Handles initialization state, error tracking, and instance management
+ */
+export class ClientStateManager<TInstance> {
+  private state: ClientState<TInstance>;
+
+  constructor() {
+    this.state = {
+      instance: null,
+      initializationError: null,
+      isInitialized: false,
+    };
+  }
+
+  /**
+   * Get the current instance
+   */
+  getInstance(): TInstance | null {
+    return this.state.instance;
+  }
+
+  /**
+   * Set the instance
+   */
+  setInstance(instance: TInstance | null): void {
+    this.state.instance = instance;
+    this.state.isInitialized = instance !== null;
+  }
+
+  /**
+   * Check if the service is initialized
+   */
+  isInitialized(): boolean {
+    return this.state.isInitialized;
+  }
+
+  /**
+   * Get the initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.state.initializationError;
+  }
+
+  /**
+   * Set the initialization error
+   */
+  setInitializationError(error: string | null): void {
+    this.state.initializationError = error;
+  }
+
+  /**
+   * Reset the state
+   */
+  reset(): void {
+    this.state.instance = null;
+    this.state.initializationError = null;
+    this.state.isInitialized = false;
+  }
+
+  /**
+   * Get the current state (read-only)
+   */
+  getState(): Readonly<ClientState<TInstance>> {
+    return this.state;
+  }
+}

package/src/infrastructure/config/base/ServiceClientSingleton.ts

@@ -0,0 +1,152 @@
+/**
+ * Service Client Singleton Base Class
+ *
+ * Provides a generic singleton pattern for Firebase service clients.
+ * Eliminates code duplication across FirebaseClient, FirestoreClient, FirebaseAuthClient.
+ *
+ * Features:
+ * - Generic singleton pattern
+ * - Initialization state management
+ * - Error handling and tracking
+ * - Automatic cleanup
+ *
+ * @template TInstance - The service instance type (e.g., Firestore, Auth)
+ * @template TConfig - The configuration type (optional)
+ */
+
+export interface ServiceClientState<TInstance> {
+  instance: TInstance | null;
+  initializationError: string | null;
+  isInitialized: boolean;
+}
+
+export interface ServiceClientOptions<TInstance, TConfig = unknown> {
+  serviceName: string;
+  initializer?: (config?: TConfig) => TInstance | null;
+  autoInitializer?: () => TInstance | null;
+}
+
+/**
+ * Generic service client singleton base class
+ * Provides common initialization, state management, and error handling
+ */
+export class ServiceClientSingleton<TInstance, TConfig = unknown> {
+  private static instances = new Map<string, ServiceClientSingleton<unknown, unknown>>();
+
+  protected state: ServiceClientState<TInstance>;
+  private readonly options: ServiceClientOptions<TInstance, TConfig>;
+
+  constructor(options: ServiceClientOptions<TInstance, TConfig>) {
+    this.options = options;
+    this.state = {
+      instance: null,
+      initializationError: null,
+      isInitialized: false,
+    };
+  }
+
+  /**
+   * Initialize the service with optional configuration
+   */
+  initialize(config?: TConfig): TInstance | null {
+    if (this.state.isInitialized && this.state.instance) {
+      return this.state.instance;
+    }
+
+    if (this.state.initializationError) {
+      return null;
+    }
+
+    try {
+      const instance = this.options.initializer ? this.options.initializer(config) : null;
+      if (instance) {
+        this.state.instance = instance;
+        this.state.isInitialized = true;
+      }
+      return instance;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : `Failed to initialize ${this.options.serviceName}`;
+      this.state.initializationError = errorMessage;
+
+      if (__DEV__) {
+        console.error(`[${this.options.serviceName}] Initialization failed:`, errorMessage);
+      }
+
+      return null;
+    }
+  }
+
+  /**
+   * Get the service instance, auto-initializing if needed
+   */
+  getInstance(autoInit: boolean = false): TInstance | null {
+    if (this.state.instance) {
+      return this.state.instance;
+    }
+
+    if (this.state.initializationError) {
+      return null;
+    }
+
+    if (autoInit && this.options.autoInitializer) {
+      try {
+        const instance = this.options.autoInitializer();
+        if (instance) {
+          this.state.instance = instance;
+          this.state.isInitialized = true;
+        }
+        return instance;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : `Failed to initialize ${this.options.serviceName}`;
+        this.state.initializationError = errorMessage;
+
+        if (__DEV__) {
+          console.error(`[${this.options.serviceName}] Auto-initialization failed:`, errorMessage);
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if the service is initialized
+   */
+  isInitialized(): boolean {
+    return this.state.isInitialized;
+  }
+
+  /**
+   * Get the initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.state.initializationError;
+  }
+
+  /**
+   * Reset the service state
+   */
+  reset(): void {
+    this.state.instance = null;
+    this.state.initializationError = null;
+    this.state.isInitialized = false;
+
+    if (__DEV__) {
+      console.log(`[${this.options.serviceName}] Service reset`);
+    }
+  }
+
+  /**
+   * Get the current instance without initialization
+   */
+  protected getCurrentInstance(): TInstance | null {
+    return this.state.instance;
+  }
+
+  /**
+   * Set initialization error
+   */
+  protected setError(error: string): void {
+    this.state.initializationError = error;
+  }
+}

package/src/infrastructure/config/state/FirebaseClientState.ts

@@ -3,36 +3,18 @@
  * Manages the state of Firebase initialization
  *
  * Single Responsibility: Only manages initialization state
+ * Uses generic ClientStateManager for shared functionality
  */
 
 import type { FirebaseApp } from '../initializers/FirebaseAppInitializer';
+import { ClientStateManager } from '../base/ClientStateManager';
 
-export class FirebaseClientState {
-  private app: FirebaseApp | null = null;
-  private initializationError: string | null = null;
-
+export class FirebaseClientState extends ClientStateManager<FirebaseApp> {
   getApp(): FirebaseApp | null {
-    return this.app;
+    return this.getInstance();
   }
 
   setApp(app: FirebaseApp | null): void {
-    this.app = app;
-  }
-
-  isInitialized(): boolean {
-    return this.app !== null;
-  }
-
-  getInitializationError(): string | null {
-    return this.initializationError;
-  }
-
-  setInitializationError(error: string | null): void {
-    this.initializationError = error;
-  }
-
-  reset(): void {
-    this.app = null;
-    this.initializationError = null;
+    this.setInstance(app);
   }
 }

package/src/infrastructure/config/validators/FirebaseConfigValidator.ts

@@ -2,10 +2,12 @@
  * Firebase Configuration Validator
  *
  * Single Responsibility: Validates Firebase configuration
+ * Uses centralized validation utilities from validation.util.ts
  */
 
 import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
 import { FirebaseConfigurationError } from '../../../domain/errors/FirebaseError';
+import { isValidString, isValidFirebaseApiKey, isValidFirebaseProjectId } from '../../../domain/utils/validation.util';
 
 /**
  * Validation rule interface
@@ -15,25 +17,28 @@ interface ValidationRule {
 }
 
 /**
- * Required field validation rule
+ * Required field validation rule using centralized validation
  */
 class RequiredFieldRule implements ValidationRule {
   constructor(
     private fieldName: string,
-    private getter: (config: FirebaseConfig) => string | undefined
+    private getter: (config: FirebaseConfig) => string | undefined,
+    private customValidator?: (value: string) => boolean
   ) {}
 
   validate(config: FirebaseConfig): void {
     const value = this.getter(config);
-    
-    if (!value || typeof value !== 'string') {
+
+    if (!isValidString(value)) {
       throw new FirebaseConfigurationError(
-        `Firebase ${this.fieldName} is required and must be a string`
+        `Firebase ${this.fieldName} is required and must be a non-empty string`
       );
     }
 
-    if (value.trim().length === 0) {
-      throw new FirebaseConfigurationError(`Firebase ${this.fieldName} cannot be empty`);
+    if (this.customValidator && !this.customValidator(value)) {
+      throw new FirebaseConfigurationError(
+        `Firebase ${this.fieldName} format is invalid`
+      );
     }
   }
 }
@@ -50,7 +55,7 @@ class PlaceholderRule implements ValidationRule {
 
   validate(config: FirebaseConfig): void {
     const value = this.getter(config);
-    
+
     if (value && value.includes(this.placeholder)) {
       throw new FirebaseConfigurationError(
         `Please replace placeholder values with actual Firebase credentials for ${this.fieldName}`
@@ -64,9 +69,9 @@ class PlaceholderRule implements ValidationRule {
  */
 export class FirebaseConfigValidator {
   private static rules: ValidationRule[] = [
-    new RequiredFieldRule('API Key', config => config.apiKey),
+    new RequiredFieldRule('API Key', config => config.apiKey, isValidFirebaseApiKey),
     new RequiredFieldRule('Auth Domain', config => config.authDomain),
-    new RequiredFieldRule('Project ID', config => config.projectId),
+    new RequiredFieldRule('Project ID', config => config.projectId, isValidFirebaseProjectId),
     new PlaceholderRule('API Key', config => config.apiKey, 'your_firebase_api_key'),
     new PlaceholderRule('Project ID', config => config.projectId, 'your-project-id'),
   ];
@@ -81,11 +86,3 @@ export class FirebaseConfigValidator {
     }
   }
 }
-
-
-
-
-
-
-
-