@umituz/react-native-firebase 2.0.0 → 2.0.2

package/src/domains/firestore/domain/constants/README.md

@@ -1,332 +0,0 @@
-# Firestore Constants
-
-Firestore quota limits, thresholds, and constants for Firebase operations.
-
-## Purpose
-
-Provides constants and configuration values for Firestore quota management including free tier limits, warning thresholds, and utility functions for quota calculations.
-
-## For AI Agents
-
-### Before Using Firestore Constants
-
-1. **USE** constants for all quota values
-2. **CHECK** quota thresholds before operations
-3. **CALCULATE** quota usage with utility functions
-4. **WARN** users when approaching limits
-5. **NEVER** hardcode quota values
-
-### Required Practices
-
-1. **Use constants** - Import FREE_TIER_LIMITS and QUOTA_THRESHOLDS
-2. **Calculate usage** - Use calculateQuotaUsage() function
-3. **Check thresholds** - Use isQuotaThresholdReached()
-4. **Monitor quota** - Track usage throughout the day
-5. **Warn appropriately** - Show warnings at thresholds
-
-### Forbidden Practices
-
-## ❌ NEVER
-
-- Hardcode quota values (50,000, 20,000, etc.)
-- Ignore quota limits
-- Skip quota monitoring
-- Calculate quota manually
-- Exceed free tier without warning
-
-## ⚠️ Avoid
-
-- Not checking quota before operations
-- Hardcoding threshold percentages
-- Not warning users at thresholds
-- Calculating quota incorrectly
-- Ignoring delete quota (monthly vs daily)
-
-## Constants
-
-### FREE_TIER_LIMITS
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**Purpose:** Firebase free tier daily/monthly quota limits
-
-**Properties:**
-- `dailyReads: number` - Daily read limit (50,000)
-- `dailyWrites: number` - Daily write limit (20,000)
-- `monthlyDeletes: number` - Monthly delete limit (20,000)
-
-**Usage:**
-- Use for quota calculations
-- Display limits to users
-- Calculate remaining quota
-- Set up monitoring
-
-**When to Use:**
-- Calculating quota usage
-- Displaying quota information
-- Checking remaining quota
-- Setting up alerts
-
-**Important Notes:**
-- Reads reset daily
-- Writes reset daily
-- Deletes reset monthly
-- Different reset periods
-
-### QUOTA_THRESHOLDS
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**Purpose:** Warning and critical threshold percentages
-
-**Properties:**
-- `warning: number` - Warning threshold (80%)
-- `critical: number` - Critical threshold (90%)
-
-**Usage:**
-- Trigger warnings at 80%
-- Trigger critical alerts at 90%
-- Display warnings to users
-- Implement throttling
-
-**When to Use:**
-- Checking if quota exceeded
-- Showing warnings to users
-- Implementing usage alerts
-- Throttling operations
-
-**Threshold Strategy:**
-- Warning at 80% - Inform user
-- Critical at 90% - Strong warning
-- Limit at 100% - Block operations
-- Consider upgrade prompts
-
-## Utility Functions
-
-### calculateQuotaUsage
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**Purpose:** Calculate quota usage percentages from raw numbers
-
-**Parameters:**
-- Object with `reads`, `writes`, `deletes` counts
-
-**Returns:** `QuotaMetrics` object with:
-- `totalReads`, `totalWrites`, `totalDeletes`
-- `reads: QuotaStatus` - { used, limit, percentage }
-- `writes: QuotaStatus` - { used, limit, percentage }
-- `deletes: QuotaStatus` - { used, limit, percentage }
-
-**QuotaStatus Properties:**
-- `used: number` - Amount used
-- `limit: number` - Total limit
-- `percentage: number` - Usage percentage (0-100)
-
-**Usage Strategy:**
-1. Collect operation counts
-2. Call calculateQuotaUsage()
-3. Check percentages for each type
-4. Display to user if needed
-5. Implement throttling
-
-**When to Use:**
-- After batch operations
-- Displaying quota status
-- Checking before large operations
-- Monitoring usage trends
-
-### isQuotaThresholdReached
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**Purpose:** Check if quota usage has reached a specific threshold
-
-**Parameters:**
-- `metrics: QuotaMetrics` - From calculateQuotaUsage()
-- `threshold: number` - Threshold percentage (80 or 90)
-
-**Returns:** `boolean` - Whether threshold reached
-
-**Usage Strategy:**
-1. Calculate quota usage
-2. Check if warning threshold reached
-3. Check if critical threshold reached
-4. Display appropriate warning
-5. Throttle operations if needed
-
-**When to Use:**
-- After quota calculations
-- Before large operations
-- Displaying warnings
-- Implementing throttling
-
-## Quota Management Strategy
-
-### Monitoring Quota
-
-**Strategy:** Track quota usage throughout the day.
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**When to Monitor:**
-- After write operations
-- After read operations
-- Periodically (every hour)
-- Before large batch operations
-
-**Monitoring Approach:**
-1. Count operations by type
-2. Use calculateQuotaUsage()
-3. Check thresholds
-4. Warn if approaching limit
-5. Throttle if critical
-
-### Warning Strategy
-
-**Strategy:** Warn users at appropriate thresholds.
-
-**Warning Threshold (80%):**
-- Inform user of usage
-- Suggest quota conservation
-- Show remaining quota
-- Optional: upgrade prompt
-
-**Critical Threshold (90%):**
-- Strong warning
-- Block non-essential operations
-- Require confirmation for operations
-- Strong upgrade suggestion
-
-**Limit Reached (100%):**
-- Block all operations
-- Show upgrade prompt
-- Provide clear guidance
-- Offer upgrade option
-
-### Quota Reset Times
-
-**Reads and Writes:**
-- Reset daily at midnight Pacific Time
-- 50,000 reads per day
-- 20,000 writes per day
-
-**Deletes:**
-- Reset monthly on billing date
-- 20,000 deletes per month
-- Different reset period than reads/writes
-
-**Strategy:**
-1. Track reset times
-2. Display reset time to users
-3. Plan operations accordingly
-4. Consider time zones
-
-## Common Mistakes to Avoid
-
-1. ❌ Hardcoding quota values
-   - ✅ Use FREE_TIER_LIMITS constant
-
-2. ❌ Not calculating quota correctly
-   - ✅ Use calculateQuotaUsage()
-
-3. ❌ Ignoring monthly delete quota
-   - ✅ Remember deletes are monthly
-
-4. ❌ Not warning at thresholds
-   - ✅ Use isQuotaThresholdReached()
-
-5. ❌ Mixing daily and monthly quotas
-   - ✅ Track separately
-
-## AI Agent Instructions
-
-### When Calculating Quota
-
-1. Collect operation counts (reads, writes, deletes)
-2. Call calculateQuotaUsage()
-3. Check returned percentages
-4. Compare with thresholds
-5. Display to user if needed
-
-### When Checking Thresholds
-
-1. Calculate quota usage first
-2. Call isQuotaThresholdReached(metrics, 80) for warning
-3. Call isQuotaThresholdReached(metrics, 90) for critical
-4. Display appropriate warning
-5. Throttle operations if critical
-
-### When Displaying Quota Info
-
-1. Calculate current usage
-2. Show used/limit for each type
-3. Show percentage used
-4. Display reset time
-5. Suggest upgrade if near limit
-
-## Code Quality Standards
-
-### Constants
-
-- Export all constants
-- Use descriptive names
-- Document reset periods
-- Group related constants
-- No magic numbers
-
-### Utility Functions
-
-- Type all parameters
-- Type all returns
-- Handle edge cases
-- Document behavior
-- Include examples in comments
-
-## Performance Considerations
-
-### Calculation Overhead
-
-- Minimal overhead for calculations
-- Simple arithmetic operations
-- No network calls
-- Safe for frequent use
-- Cache results if needed
-
-### Monitoring Frequency
-
-- Don't calculate on every operation
-- Calculate periodically (hourly)
-- Calculate after batches
-- Cache results
-- Update UI efficiently
-
-## Related Documentation
-
-- [Firestore Module README](../../README.md)
-- [Firestore Errors README](../errors/README.md)
-- [Quota Error Detector README](../../utils/quota-error-detector/README.md)
-- [Request Log Types README](../../entities/README.md)
-
-## API Reference
-
-### Constants
-
-**Import Path:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-| Constant | Type | Values |
-|----------|------|--------|
-| `FREE_TIER_LIMITS` | Object | { dailyReads: 50000, dailyWrites: 20000, monthlyDeletes: 20000 } |
-| `QUOTA_THRESHOLDS` | Object | { warning: 80, critical: 90 } |
-
-### Utility Functions
-
-| Function | Parameters | Returns | Description |
-|----------|-----------|---------|-------------|
-| `calculateQuotaUsage` | `{ reads, writes, deletes }` | `QuotaMetrics` | Calculate usage percentages |
-| `isQuotaThresholdReached` | `metrics, threshold` | `boolean` | Check if threshold reached |
-
----
-
-**Last Updated:** 2025-01-08
-**Maintainer:** Firestore Module Team

package/src/domains/firestore/domain/entities/README.md

@@ -1,286 +0,0 @@
-# Request Log Types
-
-TypeScript types for Firestore request logging and tracking.
-
-## Purpose
-
-Provides type definitions for logging Firestore requests including request types, logs, and statistics. Used for monitoring, analytics, and quota tracking.
-
-## For AI Agents
-
-### Before Using Request Log Types
-
-1. **USE** types for type-safe request logging
-2. **LOG** all Firestore operations for monitoring
-3. **TRACK** quota usage with request logs
-4. **ANALYZE** logs for performance optimization
-5. **NEVER** log sensitive user data in requests
-
-### Required Practices
-
-1. **Log all Firestore operations** with RequestLog
-2. **Use RequestType** for operation categorization
-3. **Calculate statistics** with RequestStats
-4. **Import types from correct path**
-5. **Use queryHash for duplicate detection**
-
-### Forbidden Practices
-
-## ❌ NEVER
-
-- Log sensitive user data in request logs
-- Log request payloads or document content
-- Ignore logging for Firestore operations
-- Use request logs for debugging only (also for analytics)
-- Store logs indefinitely (cleanup old logs)
-
-## ⚠️ Avoid
-
-- Logging every single read operation (use sampling)
-- Not cleaning up old logs
-- Logging in production without monitoring
-- Storing logs in production database
-- Complex logging logic in critical path
-
-## Usage Strategies
-
-### For Request Logging
-
-**Strategy:** Log every Firestore operation for monitoring and quota tracking.
-
-**Import From:** `src/firestore/domain/entities`
-
-**When to Use:**
-- Repository operations (read, write, delete)
-- Quota tracking middleware
-- Performance monitoring
-- Analytics and reporting
-
-**Logging Strategy:**
-1. Create RequestLog before operation
-2. Set operation type (read/write/delete)
-3. Record collection name
-4. Count affected documents
-5. Add timestamp and query hash
-6. Log operation completion
-
-### For Quota Tracking
-
-**Strategy:** Use request logs to track Firestore quota usage.
-
-**Import From:** `src/firestore/domain/entities`
-
-**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
-
-### For Analytics
-
-**Strategy:** Analyze request logs for performance insights.
-
-**Import From:** `src/firestore/domain/entities`
-
-**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)
-
-## Type Definitions
-
-### RequestLog
-
-**Import From:** `src/firestore/domain/entities`
-
-**Purpose:** Log entry for a Firestore request
-
-**Properties:**
-- `type: RequestType` - Type of operation (read/write/delete)
-- `collectionName: string` - Collection being accessed
-- `documentCount: number` - Number of documents affected
-- `timestamp: number` - Unix timestamp of request
-- `queryHash?: string` - Hash of query for duplicate detection
-
-**Usage:**
-- Create log entry before Firestore operation
-- Populate with operation details
-- Store for analytics and monitoring
-- Use queryHash for deduplication
-
-### RequestType
-
-**Import From:** `src/firestore/domain/entities`
-
-**Purpose:** Type of Firestore request
-
-**Values:**
-- `'read'` - Query/get operations
-- `'write'` - Create/update operations
-- `'delete'` - Delete operations
-
-**Usage:**
-- Categorize operations for quota tracking
-- Separate read/write/delete costs
-- Filter logs by operation type
-- Generate statistics by type
-
-### RequestStats
-
-**Import From:** `src/firestore/domain/entities`
-
-**Purpose:** Statistics summary for Firestore requests
-
-**Properties:**
-- `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:**
-- Calculate from array of RequestLog
-- Display usage statistics
-- Monitor quota consumption
-- Generate reports
-
-## Helper Functions
-
-### Creating Request Logs
-
-**Strategy:** Create log entry before each Firestore operation.
-
-**Properties to Set:**
-1. `type` - Operation type (read/write/delete)
-2. `collectionName` - Target collection
-3. `documentCount` - Affected document count
-4. `timestamp` - Current timestamp
-5. `queryHash` - Optional query identifier
-
-**When to Create:**
-- Before repository query execution
-- In middleware before operation
-- After operation completes
-- On operation errors (log failed attempt)
-
-### Calculating Statistics
-
-**Strategy:** Aggregate RequestLog array into RequestStats.
-
-**Calculation:**
-1. Filter logs by type for each count
-2. Sum document counts
-3. Calculate average document count
-4. Return statistics object
-
-**When to Calculate:**
-- On-demand statistics display
-- Periodic reporting (daily/weekly)
-- After quota threshold warning
-- Performance monitoring
-
-## Common Mistakes to Avoid
-
-1. ❌ Logging sensitive data in request logs
-   - ✅ 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 logging service or external tool
-
-## AI Agent Instructions
-
-### When Adding Request Logging
-
-1. Import types from `src/firestore/domain/entities`
-2. Create RequestLog before each operation
-3. Populate all required fields
-4. Include queryHash for duplicates
-5. Log operation completion
-
-### When Calculating Statistics
-
-1. Collect all RequestLog entries
-2. Filter by type for counts
-3. Calculate aggregates
-4. Return RequestStats object
-5. Handle empty log array
-
-### When Using for Analytics
-
-1. Export logs periodically
-2. Analyze query patterns
-3. Identify most accessed collections
-4. Detect performance issues
-5. Generate usage reports
-
-## Performance Considerations
-
-### Logging Overhead
-
-**Minimal Impact:**
-- Type checking at compile time (not runtime)
-- Simple object creation
-- No complex transformations
-- 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
-
-### Log Cleanup
-
-**Regular Cleanup:**
-- Remove logs older than retention period
-- Aggregate before deletion
-- Keep statistics for long-term
-- Compress old logs if needed
-
-## Related Documentation
-
-- [Firestore Module README](../../README.md)
-- [Request Logger Service README](../../infrastructure/services/request-logger-service/README.md)
-- [Quota Tracking README](../../infrastructure/middleware/quota-tracking/README.md)
-
-## API Reference
-
-### Main Types
-
-**Import Path:** `src/firestore/domain/entities`
-
-| Type | Purpose | Properties |
-|------|---------|------------|
-| `RequestLog` | Single request log | type, collectionName, documentCount, timestamp, queryHash |
-| `RequestType` | Operation type | 'read' \| 'write' \| 'delete' |
-| `RequestStats` | Usage statistics | totalReads, totalWrites, totalDeletes, totalRequests, avgDocCount |
-
----
-
-**Last Updated:** 2025-01-08
-**Maintainer:** Firestore Module Team