@umituz/react-native-firebase 1.13.57 → 1.13.59

package/src/firestore/utils/query-builder/README.md

@@ -0,0 +1,291 @@
+# Query Builder
+
+Advanced Firestore query building utility with support for filtering, sorting, pagination, and date ranges.
+
+## Purpose
+
+Provides a fluent interface for building complex Firestore queries while handling Firestore limitations (e.g., IN operator 10-item limit).
+
+## For AI Agents
+
+### Before Using Query Builder
+
+1. **UNDERSTAND** Firestore query limitations
+2. **USE** builder instead of raw Firestore queries
+3. **RESPECT** compound query limitations
+4. **HANDLE** large arrays with chunking
+
+### Required Practices
+
+1. **Use query builder** for complex queries
+2. **Handle IN operator limits** (max 10 values)
+3. **Apply modifiers in correct order** (filters → date range → sort → cursor → limit)
+4. **Use pagination** for large datasets
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Build queries manually with Firestore SDK
+- Use IN operator with more than 10 values without chunking
+- Apply modifiers in wrong order
+- Create compound queries that violate Firestore rules
+- Ignore pagination for large result sets
+
+## ⚠️ Avoid
+
+- Multiple range filters on different fields
+- Sorting + filtering on different fields without composite index
+- Very large IN arrays (use pagination instead)
+- Complex OR queries (performance impact)
+
+## Usage Strategies
+
+### For Complex Filtering
+
+**Strategy:** Use FieldFilter array for multiple conditions.
+
+**When to Use:**
+- Filtering by multiple fields
+- Combining equality and range filters
+- Building dynamic queries based on user input
+
+**Approach:**
+1. Create FieldFilter objects for each condition
+2. Add to baseFilters array
+3. Pass to buildQuery with other options
+
+### For Date Range Queries
+
+**Strategy:** Use dateRange option for time-based filtering.
+
+**When to Use:**
+- Filtering by creation/update time
+- Date-based analytics queries
+- Time-series data retrieval
+
+**Approach:**
+1. Specify field name (e.g., 'createdAt')
+2. Provide startDate and/or endDate as timestamps
+3. Combine with sorting on same field
+
+### For Pagination
+
+**Strategy:** Use cursorValue with limit for cursor-based pagination.
+
+**When to Use:**
+- Infinite scroll implementations
+- Large dataset navigation
+- Ordered result sets
+
+**Approach:**
+1. Store cursor from last page
+2. Pass as cursorValue in next request
+3. Always use with sort and limit
+
+### For Large IN Arrays
+
+**Strategy:** Let builder handle chunking automatically.
+
+**When to Use:**
+- Filtering by list of IDs
+- Multiple category selection
+- Tag-based filtering
+
+**Approach:**
+1. Create filter with operator: 'in'
+2. Pass array (any size supported)
+3. Builder splits into chunks of 10 automatically
+
+## Configuration Options
+
+### QueryBuilderOptions
+
+**collectionName** (required)
+- Target collection path
+- Type: string
+
+**baseFilters** (optional)
+- Array of field filters
+- Type: FieldFilter[]
+- Applied first in query chain
+
+**dateRange** (optional)
+- Date range filter
+- Type: { field: string; startDate?: number; endDate?: number }
+- Use Timestamps for dates
+
+**sort** (optional)
+- Sort configuration
+- Type: { field: string; order?: 'asc' | 'desc' }
+- Defaults to 'desc' if not specified
+
+**limitValue** (optional)
+- Maximum documents to return
+- Type: number
+- Use for pagination and performance
+
+**cursorValue** (optional)
+- Pagination cursor (timestamp)
+- Type: number
+- Requires sort to be set
+
+### FieldFilter
+
+**field** (required)
+- Document field to filter on
+- Type: string
+
+**operator** (required)
+- Comparison operator
+- Type: WhereFilterOp (==, !=, >, >=, <, <=, in, array-contains)
+
+**value** (required)
+- Filter value
+- Type: string | number | boolean | string[] | number[]
+
+## Helper Functions
+
+**Import from:** `src/firestore/utils/query-builder`
+
+### `createInFilter(field, values)`
+
+Create filter for IN operator.
+
+**Use For:**
+- Filtering by multiple values
+- ID list queries
+- Category/tag filtering
+
+**Note:** Automatically chunks arrays larger than 10 values.
+
+### `createEqualFilter(field, value)`
+
+Create filter for equality comparison.
+
+**Use For:**
+- Single value matches
+- ID lookups
+- Status filtering
+
+## Query Building Order
+
+**REQUIRED ORDER:** Modifiers must be applied in this sequence:
+
+1. **Collection reference** (base)
+2. **Base filters** (where clauses)
+3. **Date range** (>= and <=)
+4. **Sort** (orderBy)
+5. **Cursor** (startAfter)
+6. **Limit** (limit)
+
+**Why this order?**
+- Firestore requires specific order for composite queries
+- Filters before sorts
+- Sorts before cursors
+- Cursors before limits
+
+## Common Mistakes to Avoid
+
+1. ❌ Manual query construction
+   - ✅ Use buildQuery utility
+
+2. ❌ IN operator with 11+ values without chunking
+   - ✅ Builder handles this automatically
+
+3. ❌ Wrong modifier order
+   - ✅ Follow prescribed order in buildQuery
+
+4. ❌ Pagination without sort
+   - ✅ Always include sort when using cursor
+
+5. ❌ Multiple range filters on different fields
+   - ✅ Use single range filter or create composite index
+
+## AI Agent Instructions
+
+### When Adding Query Features
+
+1. Check Firestore limitations first
+2. Handle edge cases (null, undefined, empty arrays)
+3. Document query capabilities
+4. Update this README
+
+### When Building Queries
+
+1. Use buildQuery, not raw Firestore SDK
+2. Handle IN operator limits (10 items max per clause)
+3. Respect composite query requirements
+4. Always paginate large result sets
+5. Create composite indexes in Firebase Console when needed
+
+### For Complex Queries
+
+1. Break into multiple queries if needed
+2. Consider client-side filtering for complex logic
+3. Use denormalization for better query patterns
+4. Document query requirements
+
+## Code Quality Standards
+
+### TypeScript
+
+- All options must have explicit types
+- Export types for consumer use
+- Use strict type checking
+- Document generic type parameters
+
+### Error Handling
+
+- Validate required options
+- Provide clear error messages
+- Handle Firestore limitations gracefully
+- Log warnings for anti-patterns
+
+## Performance Considerations
+
+### Query Optimization
+
+1. **Limit results** always use limitValue
+2. **Create indexes** for composite queries
+3. **Avoid large offsets** use cursor-based pagination
+4. **Select specific fields** when possible (future feature)
+
+### Quota Management
+
+1. Each query reads all matched documents
+2. Use limit to control reads
+3. Date range filters reduce scanned documents
+4. Monitor query performance in Firebase Console
+
+## Related Documentation
+
+- [Firestore Module README](../README.md)
+- [Repository README](../../infrastructure/repositories/README.md)
+- [Pagination Helper README](../pagination.helper/README.md)
+- [Date Utilities README](../dateUtils/README.md)
+
+## Firebase Query Limitations
+
+### Composite Queries
+
+- Maximum 1 range filter (<, <=, >, >=)
+- Range filter and sort must be on same field
+- Requires composite index for most combinations
+
+### IN Operator
+
+- Maximum 10 values per query
+- Builder auto-chunks larger arrays
+- Each chunk counts as separate query for quota
+
+### OR Queries
+
+- Maximum 30 disjunctions
+- Can impact performance
+- Use sparingly
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Firestore Module Team

package/src/firestore/utils/quota-error-detector/README.md

@@ -0,0 +1,355 @@
+# Quota Error Detector
+
+Utilities for detecting and handling Firestore quota errors and retryable errors.
+
+## Purpose
+
+Provides reliable detection of Firestore quota errors (resource-exhausted, quota-exceeded) and retryable transient errors (unavailable, deadline-exceeded) for proper error handling and user communication.
+
+## For AI Agents
+
+### Before Using Error Detection
+
+1. **ALWAYS** wrap Firestore operations in try-catch
+2. **CHECK** error type before handling
+3. **PROVIDE** user-friendly messages for quota errors
+4. **IMPLEMENT** retry logic for retryable errors
+5. **LOG** errors appropriately
+
+### Required Practices
+
+1. **Use isQuotaError()** for quota detection
+2. **Use getQuotaErrorMessage()** for user-facing messages
+3. **Use isRetryableError()** for retry logic
+4. **Handle quota errors gracefully** (stop operations, inform user)
+5. **Implement exponential backoff** for retryable errors
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Ignore quota errors (continue operations)
+- Show raw error messages to users
+- Retry quota errors (won't succeed)
+- Assume all errors are quota errors
+- Log sensitive error data
+
+## ⚠️ Avoid
+
+- Too many retries (implement max retry limit)
+- No delay between retries (use backoff)
+- Confusing retryable with quota errors
+- Not tracking quota usage
+- Blocking UI for retryable errors
+
+## Usage Strategies
+
+### For Quota Error Handling
+
+**Strategy:** Detect quota errors and stop operations immediately.
+
+**When to Use:**
+- After Firestore write operations
+- After Firestore read operations (if quota-limited)
+- In error boundaries
+- In background sync operations
+
+**Approach:**
+1. Catch errors from Firestore operations
+2. Check with isQuotaError()
+3. Show user-friendly message
+4. Disable operations that consume quota
+5. Track quota exceeded state
+
+**User Message Strategy:**
+- Inform user clearly about quota limit
+- Suggest upgrade plan or waiting
+- Provide action buttons (upgrade, contact support)
+- Don't show technical details
+
+### For Retryable Error Handling
+
+**Strategy:** Implement retry logic with exponential backoff.
+
+**When to Use:**
+- Network timeout errors
+- Temporary service unavailability
+- Deadline exceeded errors
+- Automatic retry operations
+
+**Approach:**
+1. Check with isRetryableError()
+2. Wait with exponential backoff (1s, 2s, 4s, 8s...)
+3. Retry operation
+4. Max retries: 3-5
+5. Give up after max retries
+
+**Exponential Backoff:**
+- Retry 1: Wait 1 second
+- Retry 2: Wait 2 seconds
+- Retry 3: Wait 4 seconds
+- Retry 4: Wait 8 seconds
+- Max: 5 retries
+
+### For Error Logging
+
+**Strategy:** Log errors appropriately based on type.
+
+**When to Use:**
+- Monitoring error rates
+- Debugging issues
+- Analytics and alerting
+
+**Approach:**
+1. Log retryable errors as warnings
+2. Log quota errors as errors
+3. Include error context (operation, collection)
+4. Don't log sensitive data (user data, tokens)
+5. Aggregate error metrics
+
+## Error Detection Logic
+
+### Quota Error Detection
+
+**isQuotaError(error)** checks for:
+
+**Error Codes:**
+- `resource-exhausted`
+- `quota-exceeded`
+- `RESOURCE_EXHAUSTED`
+
+**Error Messages:**
+- "quota"
+- "exceeded"
+- "limit"
+- "too many requests"
+
+**Detection Strategy:**
+1. Check error.code for known quota codes
+2. Check error.message for quota-related keywords
+3. Case-insensitive message matching
+
+### Retryable Error Detection
+
+**isRetryableError(error)** checks for:
+
+**Error Codes:**
+- `unavailable` - Service temporarily unavailable
+- `deadline-exceeded` - Request timeout
+- `aborted` - Operation cancelled (can retry)
+
+**Detection Strategy:**
+1. Check error.code for retryable codes
+2. Only code-based detection (more reliable)
+3. Conservative (only retry if safe)
+
+## API Reference
+
+### `isQuotaError(error: unknown): boolean`
+
+Check if error is a Firestore quota error.
+
+**Parameters:**
+- **error**: unknown - Error object from Firestore operation
+
+**Returns:** boolean - True if quota error detected
+
+**Use For:**
+- Detecting quota exceeded
+- Stopping operations
+- Showing user messages
+
+### `isRetryableError(error: unknown): boolean`
+
+Check if error is retryable (transient).
+
+**Parameters:**
+- **error**: unknown - Error object from Firestore operation
+
+**Returns:** boolean - True if error is retryable
+
+**Use For:**
+- Implementing retry logic
+- Background sync operations
+- Automatic recovery
+
+### `getQuotaErrorMessage(): string`
+
+Get user-friendly quota error message.
+
+**Returns:** string - User-facing error message
+
+**Use For:**
+- Displaying to users
+- Error notifications
+- In-app messaging
+
+**Message:** "Daily quota exceeded. Please try again tomorrow or upgrade your plan."
+
+## Error Handling Patterns
+
+### Pattern 1: Quota-Aware Operations
+
+**Strategy:** Check for quota errors and handle gracefully
+
+**Implementation Steps:**
+1. Wrap Firestore operations in try-catch
+2. Check if error is quota error with isQuotaError()
+3. Show user-friendly message with getQuotaErrorMessage()
+4. Disable further operations when quota exceeded
+5. Log quota errors for monitoring
+
+**Error Handling Flow:**
+- Detect quota errors immediately
+- Show clear user message
+- Set quota exceeded flag in UI
+- Prevent further quota-consuming operations
+- Allow retry after quota reset
+
+### Pattern 2: Retry with Backoff
+
+**Strategy:** Retry only retryable errors with exponential backoff
+
+**Implementation Steps:**
+1. Define max retry attempts (typically 3)
+2. Wrap operation in retry loop
+3. Check if error is retryable with isRetryableError()
+4. Calculate exponential delay: 2^attempt * 1000ms
+5. Continue or throw based on retry count
+
+**Retry Rules:**
+- Retry retryable errors (resource exhaustion, rate limits)
+- Never retry quota errors (will not succeed)
+- Use exponential backoff between retries
+- Set max retry limit to prevent infinite loops
+- Return last error after max retries
+
+### Pattern 3: Error Boundary
+
+**Strategy:** Create React hook for error handling
+
+**State Management:**
+- Track quota exceeded status
+- Track current error
+- Provide execute function for operations
+
+**Error Handling Logic:**
+1. Check if error is quota error
+2. Set quota exceeded flag if true
+3. Check if error is retryable
+4. Retry operation once if retryable
+5. Set error state for other errors
+
+**Hook Return Values:**
+- execute function for operations
+- quotaExceeded boolean flag
+- error object with details
+
+## Common Mistakes to Avoid
+
+1. ❌ Retrying quota errors
+   - ✅ Quota errors will not succeed on retry
+
+2. ❌ Showing raw error messages
+   - ✅ Use getQuotaErrorMessage() for user-friendly text
+
+3. ❌ No retry limit for retryable errors
+   - ✅ Always implement max retry limit (3-5)
+
+4. ❌ Ignoring error types
+   - ✅ Check error type before handling
+
+5. ❌ Blocking UI for retryable errors
+   - ✅ Retry in background, show loading indicator
+
+## AI Agent Instructions
+
+### When Handling Firestore Errors
+
+1. Always check error type before handling
+2. Use isQuotaError() for quota detection
+3. Use isRetryableError() for retry logic
+4. Implement proper handling for each type
+5. Provide user feedback for quota errors
+
+### When Implementing Retry Logic
+
+1. Only retry if isRetryableError() returns true
+2. Implement exponential backoff (2^n * 1000ms)
+3. Set max retry limit (3-5 retries)
+4. Don't retry quota errors
+5. Log retry attempts for monitoring
+
+### For User Experience
+
+1. Show clear messages for quota errors
+2. Provide action buttons (upgrade, contact)
+3. Use loading states for retryable errors
+4. Don't block UI for transient errors
+5. Track quota state globally
+
+## Code Quality Standards
+
+### TypeScript
+
+- Use unknown type for error parameter
+- Type guard functions properly
+- Narrow error type before accessing properties
+- Export for use across modules
+
+### Error Handling
+
+- Always handle quota errors explicitly
+- Never swallow errors silently
+- Log errors appropriately
+- Provide context in logs
+
+## Performance Considerations
+
+### Retry Strategy
+
+- Exponential backoff prevents hammering service
+- Max retries prevent infinite loops
+- Short delays for user-facing operations
+- Longer delays for background operations
+
+### Quota Monitoring
+
+- Track quota usage proactively
+- Show warnings before hitting limit
+- Implement graceful degradation
+- Cache data to reduce quota usage
+
+## Related Documentation
+
+- [Firestore Module README](../README.md)
+- [Firestore Error Codes](https://firebase.google.com/docs/firestore/manage-rest/errors)
+- [Quota Management](../../infrastructure/services/quota-tracker-service/README.md)
+
+## Firebase Quota Best Practices
+
+### Quota Types
+
+**Daily Quota:**
+- Reads: 50,000/day (free tier)
+- Writes: 20,000/day (free tier)
+- Deletes: 20,000/day (free tier)
+
+**Strategies:**
+- Monitor usage before hitting limits
+- Implement caching to reduce reads
+- Batch writes to reduce write count
+- Use pagination to limit result size
+
+### Quota Exceeded Handling
+
+1. **Stop operations** - Don't waste quota on failed operations
+2. **Inform user** - Clear message about what happened
+3. **Provide options** - Upgrade plan, wait, contact support
+4. **Track state** - Remember quota exceeded across app
+5. **Retry later** - Allow retry when quota resets
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Firestore Module Team