@umituz/react-native-firebase 1.13.58 → 1.13.60

package/src/firestore/infrastructure/services/README.md

@@ -0,0 +1,332 @@
+# Request Logger Service
+
+Service for logging and tracking Firestore requests with statistics and analytics.
+
+## Purpose
+
+Provides comprehensive logging capabilities for Firestore operations including request tracking, statistics calculation, query hashing, log export, and analytics.
+
+## For AI Agents
+
+### Before Using Request Logger
+
+1. **LOG** all Firestore operations for monitoring
+2. **TRACK** quota usage with request logs
+3. **CALCULATE** statistics from logs
+4. **EXPORT** logs for analysis
+5. **CLEANUP** old logs regularly
+
+### Required Practices
+
+1. **Log all operations** - Log every Firestore operation
+2. **Use RequestLog type** - Type-safe log entries
+3. **Calculate statistics** - Use getStats() method
+4. **Export logs** - Export for offline analysis
+5. **Clean up old logs** - Remove logs periodically
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Log sensitive user data in requests
+- Log request payloads or document content
+- Store logs indefinitely without cleanup
+- Log in production database (use external service)
+- Ignore logging for debugging
+
+## ⚠️ Avoid
+
+- Logging every single read operation (use sampling)
+- Not cleaning up old logs
+- Logging in production without monitoring
+- Complex logging logic in critical path
+- Storing logs in production database
+
+## Service Methods
+
+### logRequest
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**Purpose:** Log a Firestore operation
+
+**Parameters:** `RequestLog` object
+- `type: RequestType` - Operation type ('read', 'write', 'delete')
+- `collectionName: string` - Collection being accessed
+- `documentCount: number` - Number of documents affected
+- `timestamp: number` - Unix timestamp
+- `queryHash?: string` - Hash for duplicate detection
+
+**Returns:** `void`
+
+**Usage Strategy:**
+1. Create RequestLog before operation
+2. Call logRequest() with log data
+3. Include queryHash for duplicates
+4. Log after operation completes
+5. Handle errors appropriately
+
+**When to Use:**
+- All repository read operations
+- All repository write operations
+- All repository delete operations
+- Quota tracking
+- Performance monitoring
+
+### getLogs
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**Purpose:** Retrieve all logged requests
+
+**Returns:** `RequestLog[]` - Array of all log entries
+
+**Usage Strategy:**
+1. Call getLogs() to retrieve logs
+2. Analyze log patterns
+3. Calculate statistics
+4. Export for analysis
+5. Display to users if needed
+
+**When to Use:**
+- Analyzing usage patterns
+- Calculating statistics
+- Exporting logs
+- Debugging issues
+- Monitoring quota
+
+### getStats
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**Purpose:** Calculate usage statistics from logs
+
+**Returns:** `RequestStats` object
+- `totalReads: number` - Total read operations
+- `totalWrites: number` - Total write operations
+- `totalDeletes: number` - Total delete operations
+- `totalRequests: number` - Total all operations
+- `avgDocCount: number` - Average documents per request
+
+**Usage Strategy:**
+1. Call getStats() to calculate statistics
+2. Display statistics to users
+3. Check quota usage
+4. Monitor trends
+5. Generate reports
+
+**When to Use:**
+- Displaying quota usage
+- Monitoring performance
+- Cost analysis
+- Usage trends
+- Before large operations
+
+### clearLogs
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**Purpose:** Remove all logged requests
+
+**Returns:** `void`
+
+**Usage Strategy:**
+1. Export logs before clearing
+2. Call clearLogs() to reset
+3. Schedule periodic cleanup
+4. Clear after exporting
+5. Confirm before clearing
+
+**When to Use:**
+- Periodic log cleanup
+- After exporting logs
+- Free up memory
+- Start fresh tracking
+- Privacy requirements
+
+## Usage Strategies
+
+### For Quota Tracking
+
+**Strategy:** Use request logs to track Firestore quota usage.
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**When to Use:**
+- Monitoring quota consumption
+- Warning threshold detection
+- Usage analytics
+- Cost optimization
+
+**Tracking Metrics:**
+- Total read operations
+- Total write operations
+- Total delete operations
+- Average document count per request
+- Request rate over time
+
+**Implementation:**
+1. Log all Firestore operations
+2. Calculate statistics periodically
+3. Check quota thresholds
+4. Display usage to users
+5. Warn when approaching limits
+
+### For Analytics
+
+**Strategy:** Analyze request logs for performance insights.
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**When to Use:**
+- Performance monitoring
+- Query optimization
+- Usage patterns analysis
+- Cost optimization
+
+**Analytics Metrics:**
+- Most queried collections
+- Average document counts
+- Request frequency
+- Query patterns (via queryHash)
+
+**Implementation:**
+1. Collect logs over time period
+2. Analyze collection access patterns
+3. Identify heavy queries
+4. Optimize based on findings
+5. Generate reports
+
+### For Debugging
+
+**Strategy:** Use request logs to debug Firestore operations.
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**When to Use:**
+- Investigating performance issues
+- Debugging quota spikes
+- Identifying problematic queries
+- Tracking operation failures
+
+**Debugging Approach:**
+1. Enable request logging
+2. Reproduce issue
+3. Review logs for operations
+4. Identify problematic patterns
+5. Fix and verify
+
+## Common Mistakes to Avoid
+
+1. ❌ Logging sensitive user data
+   - ✅ Only log operation metadata
+
+2. ❌ Not logging all operations
+   - ✅ Log every Firestore operation
+
+3. ❌ Storing logs indefinitely
+   - ✅ Clean up old logs regularly
+
+4. ❌ Not using types
+   - ✅ Always use RequestLog type
+
+5. ❌ Logging in production database
+   - ✅ Use external logging service
+
+## AI Agent Instructions
+
+### When Logging Requests
+
+1. Create RequestLog before operation
+2. Populate all required fields
+3. Include queryHash for duplicates
+4. Call logRequest() method
+5. Handle errors appropriately
+
+### When Calculating Statistics
+
+1. Collect logs over time period
+2. Call getStats() method
+3. Display statistics appropriately
+4. Check quota thresholds
+5. Generate reports
+
+### When Exporting Logs
+
+1. Call getLogs() to retrieve
+2. Export to CSV/JSON
+3. Store externally (not in database)
+4. Clear logs after export
+5. Schedule regular exports
+
+## Code Quality Standards
+
+### TypeScript
+
+- Use RequestLog type for all logs
+- Use RequestType for operation types
+- Type all method parameters
+- Type all return values
+- Export types for use in other modules
+
+### Error Handling
+
+- Wrap logging in try-catch
+- Don't let logging break operations
+- Log logging failures
+- Handle edge cases
+- Test error scenarios
+
+## Performance Considerations
+
+### Logging Overhead
+
+- Minimal performance impact
+- In-memory logging (fast)
+- Type checking at compile time
+- No network calls
+- Acceptable for all operations
+
+### Storage Strategy
+
+**Don't Store in Production Database:**
+- Use external logging service
+- Export logs for analysis
+- Keep logs in memory temporarily
+- Aggregate before storage
+- Clean up regularly
+
+### Log Cleanup
+
+**Regular Cleanup:**
+- Remove logs older than retention period
+- Aggregate before deletion
+- Keep statistics for long-term
+- Compress old logs if needed
+- Schedule automatic cleanup
+
+## Related Documentation
+
+- [Firestore Module README](../../README.md)
+- [Request Log Types README](../../domain/entities/README.md)
+- [Quota Tracking README](../middleware/README.md)
+
+## API Reference
+
+### Main Service
+
+**Import Path:** `@umituz/react-native-firebase/firestore` or `src/firestore/infrastructure/services`
+
+**Service:** `requestLoggerService`
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `logRequest` | `RequestLog` | `void` | Log a Firestore operation |
+| `getLogs` | - | `RequestLog[]` | Get all logged requests |
+| `getStats` | - | `RequestStats` | Calculate usage statistics |
+| `clearLogs` | - | `void` | Clear all logged requests |
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Firestore Module Team

package/src/firestore/infrastructure/services/RequestLoggerService.ts

@@ -36,10 +36,10 @@ export class RequestLoggerService {
         : fullLog.collection;
 
       if (fullLog.success) {
-        // eslint-disable-next-line no-console
+         
         console.log(`${prefix} ${status} ${operation}: ${details}`);
       } else {
-        // eslint-disable-next-line no-console
+         
         console.error(`${prefix} ${status} ${operation}: ${details}`, fullLog.error);
       }
     }
@@ -125,9 +125,9 @@ export class RequestLoggerService {
       try {
         listener(log);
       } catch (error) {
-        /* eslint-disable-next-line no-console */
+         
         if (__DEV__) {
-          /* eslint-disable-next-line no-console */
+           
           console.error('[RequestLogger] Listener error:', error);
         }
       }

package/src/firestore/types/pagination/README.md

@@ -0,0 +1,332 @@
+# Pagination Types
+
+TypeScript types and interfaces for Firestore pagination operations.
+
+## Purpose
+
+Provides type-safe pagination structures for cursor-based pagination in Firestore queries, ensuring consistent pagination patterns across the application.
+
+## For AI Agents
+
+### Before Using Pagination Types
+
+1. **UNDERSTAND** cursor-based pagination (not offset-based)
+2. **USE** these types for all paginated queries
+3. **NEVER** mix with offset-based pagination
+4. **ALWAYS** fetch limit + 1 for hasMore detection
+5. **STORE** cursor for next page in UI state
+
+### Required Practices
+
+1. **Use PaginatedResult<T>** for all paginated query returns
+2. **Use PaginationParams** for all paginated query inputs
+3. **Fetch limit + 1** to detect if more pages exist
+4. **Store nextCursor** in UI state for subsequent requests
+5. **Handle empty results** with EMPTY_PAGINATED_RESULT
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Use offset-based pagination (skip/take) - not scalable
+- Fetch exactly limit items (can't detect hasMore)
+- Mix cursor and offset pagination
+- Ignore nextCursor (breaks pagination)
+- Use pagination for small datasets (< 100 items)
+
+## ⚠️ Avoid
+
+- Complex cursor extraction logic
+- Storing entire paginated result in state (only cursor needed)
+- Not handling last page correctly
+- Infinite loops in pagination
+- Inconsistent page sizes
+
+## Usage Strategies
+
+### For Repository Methods
+
+**Strategy:** Return PaginatedResult from repository query methods.
+
+**Import From:** `src/firestore/types/pagination`
+
+**When to Use:**
+- Large datasets (> 100 documents)
+- Infinite scroll implementations
+- Ordered result sets requiring pagination
+- Mobile applications (performance)
+
+**Repository Pattern:**
+1. Accept `PaginationParams` as parameter
+2. Fetch `limit + 1` documents
+3. Build PaginatedResult from fetched items
+4. Set `hasMore: true` if items.length > limit
+5. Set `nextCursor` from last visible item
+
+**Type Safety:**
+- Use generic type `PaginatedResult<EntityType>`
+- TypeScript ensures type consistency
+- Autocomplete for result properties
+
+### For UI Components
+
+**Strategy:** Store cursor in state, load next page on demand.
+
+**Import From:** `src/firestore/types/pagination`
+
+**State Management:**
+- Store `data: T[]` in state
+- Store `hasMore: boolean` in state
+- Store `nextCursor?: string` in state
+- Load more when user reaches end
+
+**Pagination Flow:**
+1. Initial load: Call with `{ pageSize: 20 }`
+2. Append results to state
+3. Store nextCursor if hasMore is true
+4. On scroll end: Call with `{ pageSize: 20, cursor }`
+5. Stop when hasMore is false
+
+### For React Hooks
+
+**Strategy:** Create custom hook for pagination state management.
+
+**Import From:** `src/firestore/types/pagination`
+
+**Hook Responsibilities:**
+- Manage pagination state
+- Provide loadMore function
+- Handle loading states
+- Reset pagination when needed
+
+**Hook State:**
+- `data` - Accumulated items across pages
+- `hasMore` - Whether more pages exist
+- `loading` - Current page loading state
+- `error` - Any error from last fetch
+
+**Hook Methods:**
+- `loadMore()` - Fetch next page
+- `refresh()` - Reset and reload
+- `hasNextPage()` - Check if can load more
+
+## Type Definitions
+
+### PaginationParams
+
+**Import From:** `src/firestore/types/pagination`
+
+**Properties:**
+- `pageSize?: number` - Items per page (default: 20)
+- `cursor?: string` - Cursor from previous page's last item
+
+**Usage:**
+- Pass to repository `paginate()` method
+- Include cursor for page 2+
+- Omit cursor for first page
+
+### PaginatedResult<T>
+
+**Import From:** `src/firestore/types/pagination`
+
+**Generic Type:** `<T>` - Type of items in data array
+
+**Properties:**
+- `data: T[]` - Items for current page
+- `hasMore: boolean` - Whether more pages exist
+- `nextCursor?: string` - Cursor for next page (null if no more)
+- `totalCount?: number` - Total count (optional, rarely used)
+
+**Usage:**
+- Return type for repository paginate methods
+- Type-safe with generic parameter
+- TypeScript knows item types
+
+### EMPTY_PAGINATED_RESULT
+
+**Import From:** `src/firestore/types/pagination`
+
+**Type:** `PaginatedResult<never>`
+
+**Value:**
+- `data: []` - Empty array
+- `hasMore: false` - No more pages
+
+**Usage:**
+- Default initial state
+- Error fallback
+- Empty dataset indication
+
+## Cursor-Based Pagination Strategy
+
+### Why Cursor-Based?
+
+**Benefits:**
+- Scalable (doesn't skip documents)
+- Consistent results (no duplicates)
+- Real-time friendly (new items appear naturally)
+- Better performance (no offset scanning)
+
+**Why Not Offset-Based:**
+- Offset scans all skipped documents
+- Slows down with page number
+- Can show duplicates if items added
+- Can miss items if items deleted
+
+### Cursor Extraction
+
+**Strategy:** Use sortable field value as cursor.
+
+**Common Cursor Fields:**
+- `createdAt` timestamp
+- Document ID (`__name__`)
+- Any unique, sortable field
+
+**Requirements:**
+- Field must be indexed in Firestore
+- Field must be sortable
+- Consistent across queries
+- Unique per document (preferably)
+
+### Page Size Strategy
+
+**Recommended Sizes:**
+- Mobile: 10-20 items per page
+- Desktop: 20-50 items per page
+- Infinite scroll: 20 items per page
+
+**Considerations:**
+- Larger pages = fewer requests but more data transfer
+- Smaller pages = faster initial load but more requests
+- Consider document size (images, large text)
+- Test with real user data
+
+## Common Mistakes to Avoid
+
+1. ❌ Using offset-based pagination
+   - ✅ Use cursor-based pagination
+
+2. ❌ Fetching exactly limit items
+   - ✅ Fetch limit + 1 to detect hasMore
+
+3. ❌ Not sorting consistently
+   - ✅ Always sort same field same direction
+
+4. ❌ Complex cursor logic
+   - ✅ Use simple field value as cursor
+
+5. ❌ Storing entire result in state
+   - ✅ Store only cursor, fetch data on demand
+
+6. ❌ Not handling last page
+   - ✅ Check hasMore before loading more
+
+## AI Agent Instructions
+
+### When Creating Paginated Repository
+
+1. Extend `BasePaginatedRepository<TEntity, TOptions>`
+2. Implement `buildQuery(options, cursor?)` method
+3. Use `PaginationHelper` for result building
+4. Return `PaginatedResult<TEntity>` type
+5. Document cursor field used
+
+### When Creating Paginated Hook
+
+1. Import types from `src/firestore/types/pagination`
+2. Manage state for data, hasMore, nextCursor
+3. Provide loadMore function
+4. Handle loading and error states
+5. Reset pagination when needed
+
+### When Adding Pagination to UI
+
+1. Use pagination hook or state
+2. Call loadMore on scroll end
+3. Show loading indicator
+4. Stop when hasMore is false
+5. Handle errors gracefully
+
+## Code Quality Standards
+
+### TypeScript
+
+- Always specify generic type `<T>`
+- Never use `any` type
+- Import types from correct path
+- Use strict type checking
+
+### File Organization
+
+- One paginated repository per entity
+- Types in separate types file
+- Hooks in presentation layer
+- Tests for pagination logic
+
+## Performance Considerations
+
+### Fetch Strategy
+
+**Always Fetch limit + 1:**
+- Fetch 21 items for pageSize of 20
+- If returned 21, hasMore = true
+- Return only 20 items
+- Use 21st item's cursor for next page
+
+**Why +1?**
+- Determines if more pages exist
+- Provides cursor for next page
+- Minimal performance impact
+- Standard pagination pattern
+
+### State Management
+
+**Store Minimal State:**
+- Cursor string only (not entire result)
+- hasMore boolean
+- Current data array
+- Don't store all pages in state
+
+**Why Minimal State?**
+- Reduces memory usage
+- Faster renders
+- Simpler logic
+- Better UX (can refresh)
+
+## Related Documentation
+
+- [Pagination Helper README](../../utils/pagination.helper/README.md)
+- [Base Paginated Repository README](../../infrastructure/repositories/base-paginated-repository/README.md)
+- [Firestore Module README](../README.md)
+
+## API Reference
+
+### Main Types
+
+**Import Path:** `src/firestore/types/pagination`
+
+| Type | Description | Generic |
+|------|-------------|---------|
+| `PaginationParams` | Input parameters for pagination | No |
+| `PaginatedResult<T>` | Result from paginated query | Yes |
+| `EMPTY_PAGINATED_RESULT` | Empty result constant | No |
+
+### Type Usage
+
+**For Repository Methods:**
+- Return type: `async paginate(params: PaginationParams): Promise<PaginatedResult<User>>`
+- Input type: `params: { pageSize: 20, cursor: 'abc123' }`
+- Specify generic type for type safety
+- TypeScript enforces type consistency
+
+**For UI State:**
+- State for data: `useState<User[]>([])`
+- State for hasMore: `useState<boolean>(false)`
+- State for cursor: `useState<string>()`
+- Store cursor for next page requests
+- Check hasMore before loading more
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Firestore Module Team