@umituz/react-native-firebase 2.0.0 → 2.0.2

package/src/domains/firestore/utils/pagination.helper/README.md

@@ -1,298 +0,0 @@
-# Pagination Helper
-
-Cursor-based pagination utilities for Firestore queries with type-safe result handling.
-
-## Purpose
-
-Provides consistent pagination logic across all Firestore queries using cursor-based pagination (not offset-based). Handles hasMore detection and cursor extraction for any document type.
-
-## For AI Agents
-
-### Before Using Pagination Helper
-
-1. **UNDERSTAND** cursor-based vs offset-based pagination
-2. **ALWAYS** fetch limit + 1 documents for hasMore detection
-3. **USE** generic type parameter for type safety
-4. **EXTRACT** cursor from appropriate field
-
-### Required Practices
-
-1. **Fetch limit + 1** documents to detect if more pages exist
-2. **Use cursor from last visible document** for next page
-3. **Sort consistently** for stable pagination
-4. **Handle edge cases** (empty results, last page)
-5. **Use generic type parameter** for type safety
-
-### Forbidden Practices
-
-## ❌ NEVER
-
-- Use offset-based pagination (skip/take) - not scalable
-- Fetch exactly limit documents (can't detect hasMore)
-- Use document ID as cursor unless sorted by ID
-- Assume pagination state in frontend (always from backend)
-- Paginate without sorting
-
-## ⚠️ Avoid
-
-- Large page sizes (use 10-50)
-- Inconsistent sort orders between pages
-- Complex cursor extraction logic
-- Not handling last page correctly
-
-## Usage Strategies
-
-### For Cursor-Based Pagination
-
-**Strategy:** Use last document's field as cursor for next page.
-
-**When to Use:**
-- Infinite scroll implementations
-- Large dataset navigation
-- Ordered result sets
-- Real-time data streams
-
-**Why Cursor-Based:**
-- Scalable (doesn't skip documents)
-- Consistent results (no missing/duplicate items)
-- Performance (doesn't scan skipped documents)
-- Real-time friendly (new items appear naturally)
-
-**Approach:**
-1. Fetch limit + 1 documents
-2. If returned > limit, hasMore = true
-3. Use last item's cursor for next page
-4. Store cursor in frontend state
-
-### For Different Cursor Types
-
-**By Timestamp:**
-- Use creation time field
-- Requires sorting by timestamp
-- Most common for chronological feeds
-
-**By ID:**
-- Use document ID
-- Requires sorting by __name__
-- Good for lexicographic ordering
-
-**By Custom Field:**
-- Use any sortable field
-- Requires consistent sorting
-- Must be unique and stable
-
-### For Type Safety
-
-**Strategy:** Use generic type parameter <T>.
-
-**When to Use:**
-- Strongly typed document entities
-- Type-safe cursor extraction
-- Compile-time type checking
-
-**Approach:**
-1. Define document type
-2. Create helper with type parameter
-3. Type-safe access to fields
-4. Type-safe cursor extraction
-
-## API Reference
-
-### PaginationHelper<T>
-
-Generic helper class for pagination logic.
-
-Constructor: No parameters required
-
-Methods:
-
-#### `buildResult(items: T[], pageLimit: number, getCursor: (item: T) => string)`
-
-Build paginated result from fetched items.
-
-**Parameters:**
-- **items**: All fetched items (should be limit + 1)
-- **pageLimit**: Requested page size
-- **getCursor**: Function to extract cursor from item
-
-**Returns:** PaginatedResult<T>
-
-**Behavior:**
-- If items.length > limit: hasMore = true, trims to limit
-- If items.length <= limit: hasMore = false, returns all items
-- Extracts cursor from last item for next page
-
-#### `getLimit(params?: PaginationParams, defaultLimit?: number)`
-
-Extract limit from pagination params or use default.
-
-**Parameters:**
-- **params**: Optional pagination parameters
-- **defaultLimit**: Default limit (default: 10)
-
-**Returns:** number - Page limit to use
-
-#### `getFetchLimit(pageLimit: number)`
-
-Calculate fetch limit (page limit + 1 for hasMore detection).
-
-**Parameters:**
-- **pageLimit**: Requested page size
-
-**Returns:** number - Fetch limit (pageLimit + 1)
-
-**Why:** Fetch one extra to detect if more pages exist.
-
-#### `hasCursor(params?: PaginationParams)`
-
-Check if pagination params has a cursor.
-
-**Parameters:**
-- **params**: Optional pagination parameters
-
-**Returns:** boolean - True if cursor exists
-
-**Use For:** Determining if this is a first page or subsequent page
-
-### Helper Functions
-
-#### `createPaginationHelper<T>()`
-
-Factory function to create typed pagination helper.
-
-**Returns:** PaginationHelper<T>
-
-**Use For:** Cleaner API, type inference
-
-## Result Types
-
-### PaginatedResult<T>
-
-- **items**: T[] - Paginated items (trimmed to limit)
-- **nextCursor**: string | null - Cursor for next page (null if no more)
-- **hasMore**: boolean - Whether more pages exist
-
-### PaginationParams
-
-- **cursor**: string | null - Current page cursor
-- **limit**: number | null - Page size limit
-
-## Common Mistakes to Avoid
-
-1. ❌ Fetching exactly limit documents
-   - ✅ Fetch limit + 1 to detect hasMore
-
-2. ❌ Using offset-based pagination
-   - ✅ Use cursor-based pagination
-
-3. ❌ Not sorting consistently
-   - ✅ Always sort same field in same direction
-
-4. ❌ Complex cursor logic
-   - ✅ Use simple field-based cursor extraction
-
-5. ❌ Not handling last page
-   - ✅ Return hasMore: false when items <= limit
-
-## AI Agent Instructions
-
-### When Implementing Pagination
-
-1. Always fetch limit + 1 documents
-2. Use buildResult to handle hasMore logic
-3. Extract cursor from sorted field
-4. Store nextCursor for subsequent requests
-5. Handle null cursor (first page)
-
-### When Creating Paginated Repository
-
-1. Extend BasePaginatedRepository
-2. Use PaginationHelper in implementation
-3. Accept PaginationParams in query methods
-4. Return PaginatedResult type
-5. Document cursor field used
-
-### For Custom Cursor Logic
-
-1. Keep getCursor function simple
-2. Extract from sorted field
-3. Return string representation
-4. Handle null/undefined gracefully
-5. Document cursor extraction logic
-
-## Integration with Repositories
-
-**Strategy:** Use PaginationHelper in BasePaginatedRepository.
-
-**Repository Implementation:**
-1. Extract limit from params using getLimit()
-2. Calculate fetch limit using getFetchLimit()
-3. Build query with cursor if hasCursor() is true
-4. Fetch fetchLimit documents
-5. Build result using buildResult()
-
-## Performance Considerations
-
-### Page Size Guidelines
-
-- **Small pages (10-20)**: Better for mobile, less data transfer
-- **Medium pages (20-50)**: Good balance
-- **Large pages (50-100)**: Fewer requests, more data
-
-**Recommendation:** Start with 20, adjust based on:
-
-- Document size
-- Network conditions
-- UI requirements
-- User behavior
-
-### Query Performance
-
-- Cursor-based queries are efficient
-- No document scanning for offsets
-- Index usage for sorting
-- Consistent performance regardless of page number
-
-## Code Quality Standards
-
-### TypeScript
-
-- Always use generic type parameter <T>
-- Define proper return types
-- Export pagination types
-- Use strict type checking
-
-### Error Handling
-
-- Handle empty item arrays
-- Handle null cursor
-- Validate page limit > 0
-- Handle invalid cursor values
-
-## Related Documentation
-
-- [Pagination Types README](../../types/pagination/README.md)
-- [Base Paginated Repository README](../../infrastructure/repositories/base-paginated-repository/README.md)
-- [Query Builder README](../query-builder/README.md)
-
-## Migration Guide
-
-### From Offset-Based Pagination
-
-**Don't Do (Offset-Based - Not Scalable):**
-- Parameter: `skip: (page - 1) * limit`
-- Parameter: `limit: limit`
-- Problem: Scans all skipped documents
-- Problem: Doesn't scale (slows with page number)
-
-**Do Instead (Cursor-Based - Scalable):**
-- Parameter: `cursor: lastDocumentCursor`
-- Parameter: `limit: limit`
-- Benefit: Starts from specific position
-- Benefit: Performs consistently
-- Benefit: Scales to large datasets
-
----
-
-**Last Updated:** 2025-01-08
-**Maintainer:** Firestore Module Team

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

@@ -1,291 +0,0 @@
-# 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