@umituz/react-native-firebase 2.4.86 → 2.4.87

package/.agents/workflows/setup-firebase.md

@@ -2,43 +2,177 @@
 description: Sets up or updates the @umituz/react-native-firebase package in a React Native app.
 ---
 
-# Firebase Infrastructure Setup Skill
+# Firebase Infrastructure Setup Workflow
 
-When this workflow/skill is invoked, follow these explicit instructions to configure `@umituz/react-native-firebase`.
+This workflow provides automated setup for `@umituz/react-native-firebase` integration.
+
+## Quick Start
+
+Just invoke this workflow when you want to:
+- Install @umituz/react-native-firebase in a new project
+- Update existing installation to latest version
+- Configure Firebase credentials and initialization
+- Set up optimal cost-saving configurations
 
 ## Step 1: Check and Update `package.json`
-- Analyze the project's `package.json`.
-- Check if `@umituz/react-native-firebase` exists.
-  - If missing: Install with `npm install @umituz/react-native-firebase`.
-  - If outdated: Update it to the latest version.
+
+Analyze the project's `package.json`:
+- Check if `@umituz/react-native-firebase` exists in dependencies
+- Check version (current: 2.4.86)
+- If missing: Run `npm install @umituz/react-native-firebase`
+- If outdated: Run `npm install @umituz/react-native-firebase@latest`
 
 ## Step 2: Install Peer Dependencies
-Check and install any missing peer dependencies (use `npx expo install` for Expo packages to ensure compatibility):
-- `firebase`
-- `@gorhom/portal`
-- `@tanstack/react-query`
-- `@umituz/react-native-design-system`
-- `expo-apple-authentication`, `expo-auth-session`, `expo-crypto`, `expo-web-browser`
+
+Install required peer dependencies:
+
+### Core Dependencies
+```bash
+# Firebase SDK
+npm install firebase
+
+# State Management
+npm install @umituz/react-native-design-system
+
+# Query Library
+npm install @tanstack/react-query
+```
+
+### React Navigation (if using)
+```bash
+npm install @gorhom/portal
+```
+
+### Authentication Dependencies (if using social auth)
+```bash
+# For Expo projects
+npx expo install expo-apple-authentication expo-auth-session expo-crypto expo-web-browser
+
+# For bare React Native
+npm install @react-native-firebase/app @react-native-firebase/auth
+```
 
 ## Step 3: Check Environment Variables
-- Ensure that Firebase credentials (like `FIREBASE_API_KEY`, `FIREBASE_PROJECT_ID`, etc.) are defined in the project's `.env.example` and `.env` files. If they are missing, prompt the user to add them or scaffold the keys.
+
+Verify Firebase credentials are configured. Check for these environment variables:
+
+**Required:**
+- `EXPO_PUBLIC_FIREBASE_API_KEY`
+- `EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN`
+- `EXPO_PUBLIC_FIREBASE_PROJECT_ID`
+
+**Optional:**
+- `EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET`
+- `EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID`
+- `EXPO_PUBLIC_FIREBASE_APP_ID`
+
+Check if `.env` or `.env.example` exists. If not, create `.env.example`:
+```env
+# Firebase Configuration
+EXPO_PUBLIC_FIREBASE_API_KEY=your_api_key_here
+EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
+EXPO_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
+EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
+EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
+EXPO_PUBLIC_FIREBASE_APP_ID=your_app_id
+```
 
 ## Step 4: Setup Initialization Logic
-- Locate the main entry point (e.g. `App.tsx`, `index.js`, or a dedicated config file).
-- Check if Firebase is initialized.
-- If not, import and implement the initialization boilerplate from `@umituz/react-native-firebase`:
-  ```typescript
-  import { autoInitializeFirebase } from '@umituz/react-native-firebase';
-  
-  // Call initialization logic early in the app lifecycle
-  ```
-
-// turbo
-## Step 5: Native Setup (If bare React Native)
-If the project structure indicates an iOS build folder is present, run:
+
+Locate the main entry point (usually `App.tsx`, `index.js`, `app/_layout.tsx` for Expo Router).
+
+Check if Firebase is initialized. If not, add initialization:
+
+```typescript
+import { autoInitializeFirebase } from '@umituz/react-native-firebase';
+
+// Call initialization early in app lifecycle
+useEffect(() => {
+  autoInitializeFirebase();
+}, []);
+```
+
+For Expo Router (app/_layout.tsx):
+```typescript
+import { autoInitializeFirebase } from '@umituz/react-native-firebase';
+
+export default function RootLayout() {
+  // Initialize Firebase when app starts
+  autoInitializeFirebase();
+
+  return (
+    <Stack>
+      <Stack.Screen name="(tabs)" options={{ headerShown: false }}>
+        {/* your screens */}
+      </Stack.Screen>
+    </Stack>
+  );
+}
+```
+
+## Step 5: Native Setup (Bare React Native Only)
+
+If the project has an `ios/` folder (bare React Native):
 ```bash
 cd ios && pod install
+cd ..
+```
+
+For Android, no additional setup needed beyond Step 4.
+
+## Step 6: Verify Setup
+
+Run the app and verify:
+- No Firebase initialization errors
+- Firestore queries work
+- Authentication works (if configured)
+- Quota tracking is active (check __DEV__ logs)
+
+## Step 7: Enable Cost Optimizations (Recommended)
+
+For production apps, enable smart cost-saving features:
+
+```typescript
+import { useSmartFirestoreSnapshot } from '@umituz/react-native-firebase';
+
+// Instead of useFirestoreSnapshot, use the smart version
+const { data } = useSmartFirestoreSnapshot({
+  queryKey: ['my-data'],
+  subscribe: (onData) => onSnapshot(collection(db, 'data'), (snap) => {
+    onData(snap.docs.map(d => d.data()));
+  }),
+  backgroundStrategy: 'suspend', // Saves battery and data when app backgrounds
+});
 ```
 
-## Step 6: Summary
-Output what was done: the packages that were updated, the environment keys that were checked/added, and the files modified to include initialization logic.
+## Troubleshooting
+
+**Issue:** "Firebase not initialized"
+- **Solution:** Make sure `autoInitializeFirebase()` is called in app entry point
+- **Solution:** Verify environment variables are set correctly
+
+**Issue:** "Module not found: @umituz/react-native-design-system"
+- **Solution:** Run `npm install @umituz/react-native-design-system`
+
+**Issue:** "Expo router not found"
+- **Solution:** This package works with any navigation, adjust import paths as needed
+
+## Step 8: Summary
+
+After setup, provide user with:
+1. ✅ Packages installed/updated: [list versions]
+2. ✅ Environment variables configured: [list keys]
+3. ✅ Initialization added to: [file path]
+4. ✅ Cost optimizations enabled: [smart snapshot, persistent cache, etc.]
+5. ✅ Next steps: [initialize auth, setup Firestore, etc.]
+
+## Additional Resources
+
+- Documentation: See README.md for detailed API reference
+- Examples: Check `/examples` folder (if exists)
+- Support: Report issues on GitHub
+
+---
+**Last Updated:** 2025-03-18
+**Package Version:** 2.4.86
+**Platform:** React Native (Expo & Bare)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-firebase",
-  "version": "2.4.86",
+  "version": "2.4.87",
   "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/domains/firestore/index.ts

@@ -96,6 +96,7 @@ export {
 export {
   QueryDeduplicationMiddleware,
   queryDeduplicationMiddleware,
+  syncDeduplicationWithQuota,
   useDeduplicationWithQuota,
 } from './infrastructure/middleware/QueryDeduplicationMiddleware';
 export type {

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

@@ -30,9 +30,9 @@ const DEFAULT_CLEANUP_INTERVAL_MS = 15000;       // 15s (was 3s)
  * Quota-based window adjustment thresholds
  */
 const QUOTA_THRESHOLDS = {
-  HIGH_USAGE: 0.80,   // 80% - extend window to 30s
+  HIGH_USAGE: 0.80,   // 80% - extend window to 60s (1 min)
   MEDIUM_USAGE: 0.60, // 60% - extend window to 20s
-  NORMAL: 0.60,       // < 60% - use default 10s
+  NORMAL: 0.50,       // < 50% - use default 10s
 } as const;
 
 /**
@@ -280,15 +280,21 @@ export const queryDeduplicationMiddleware = new QueryDeduplicationMiddleware({
 });
 
 /**
- * Hook to integrate deduplication with quota tracking
+ * Helper function to integrate deduplication with quota tracking
  * Automatically adjusts window based on quota usage
  *
+ * Note: This is NOT a React hook, but a helper function.
+ * Call this from your own hook or effect as needed.
+ *
  * @example
  * ```typescript
- * useDeduplicationWithQuota(queryDeduplicationMiddleware, quotaMiddleware);
+ * // In your own hook or component:
+ * useEffect(() => {
+ *   syncDeduplicationWithQuota(queryDeduplicationMiddleware, quotaMiddleware, quotaLimits);
+ * }, [quotaMiddleware.getCounts().reads]);
  * ```
  */
-export function useDeduplicationWithQuota(
+export function syncDeduplicationWithQuota(
   deduplication: QueryDeduplicationMiddleware,
   quotaMiddleware: { getCounts: () => { reads: number; writes: number; deletes: number } },
   quotaLimits: { dailyReadLimit: number }
@@ -298,3 +304,9 @@ export function useDeduplicationWithQuota(
   const quotaPercentage = counts.reads / quotaLimits.dailyReadLimit;
   deduplication.adjustWindowForQuota(quotaPercentage);
 }
+
+/**
+ * @deprecated Use syncDeduplicationWithQuota instead (not a hook)
+ * This will be removed in a future version
+ */
+export const useDeduplicationWithQuota = syncDeduplicationWithQuota;

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

@@ -173,6 +173,8 @@ export function useSmartFirestoreSnapshot<TData>(
    * Handle app state changes (foreground/background)
    */
   useEffect(() => {
+    const timers: ReturnType<typeof setTimeout>[] = [];
+
     const handleAppStateChange = (nextAppState: AppStateStatus) => {
       const isBackgrounded = nextAppState.match(/inactive|background/);
 
@@ -190,12 +192,13 @@ export function useSmartFirestoreSnapshot<TData>(
 
           switch (backgroundStrategy) {
             case 'suspend':
-              // Suspend immediately
-              setTimeout(() => suspendListener(), 0);
+              // Suspend immediately - track timer for cleanup
+              const suspendTimer = setTimeout(() => suspendListener(), 0);
+              timers.push(suspendTimer);
               break;
 
             case 'timeout':
-              // Suspend after timeout
+              // Suspend after timeout - timer stored in state for cleanup
               const timer = setTimeout(() => {
                 suspendListener();
               }, backgroundTimeout);
@@ -215,10 +218,11 @@ export function useSmartFirestoreSnapshot<TData>(
             console.log(`[SmartSnapshot] App entering foreground for query:`, queryKey);
           }
 
-          // Resume listener (with optional delay)
-          setTimeout(() => {
+          // Resume listener (with optional delay) - track timer for cleanup
+          const resumeTimer = setTimeout(() => {
             resumeListener();
           }, resumeDelay);
+          timers.push(resumeTimer);
 
           return { ...prev, isBackgrounded: false, suspendTimer: null };
         }
@@ -231,6 +235,8 @@ export function useSmartFirestoreSnapshot<TData>(
 
     return () => {
       subscription.remove();
+      // Clean up any pending timers
+      timers.forEach(timer => clearTimeout(timer));
     };
   }, [queryKey, backgroundStrategy, backgroundTimeout, resumeDelay, suspendListener, resumeListener]);
 
@@ -343,9 +349,13 @@ export function useSmartListenerControl() {
     return () => subscription.remove();
   }, []);
 
+  // Compute background status once to avoid duplicate regex matching
+  const isBackgrounded = appState.match(/inactive|background/);
+  const isForegrounded = !isBackgrounded;
+
   return {
-    isBackgrounded: appState.match(/inactive|background/),
-    isForegrounded: !appState.match(/inactive|background/),
+    isBackgrounded,
+    isForegrounded,
     appState,
   };
 }