@umituz/react-native-firebase 1.13.58 → 1.13.60

package/src/firestore/domain/README.md

@@ -0,0 +1,325 @@
+# Firestore Domain
+
+Domain layer for Firestore module containing business logic, entities, value objects, errors, and domain services.
+
+## Purpose
+
+Implements Domain-Driven Design (DDD) principles for Firestore, separating business logic from infrastructure concerns and providing a clean architecture.
+
+## For AI Agents
+
+### Before Using Firestore Domain
+
+1. **UNDERSTAND** DDD architecture (domain → infrastructure → presentation)
+2. **USE** domain entities (not infrastructure)
+3. **NEVER** import Firebase SDK in domain layer
+4. **DEFINE** business logic in domain
+5. **KEEP** domain layer Firebase-free
+
+### Required Practices
+
+1. **Keep domain Firebase-free** - No Firebase imports in domain
+2. **Define entities** - Business entities with behavior
+3. **Create value objects** - Immutable value types
+4. **Define domain errors** - Custom error classes
+5. **Write domain services** - Business logic services
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Import Firebase SDK in domain layer
+- Mix infrastructure concerns in domain
+- Create anemic domain models (data without behavior)
+- Skip domain validation
+- Put business logic in infrastructure
+
+## ⚠️ Avoid
+
+- Leaking domain logic to infrastructure
+- Not validating business rules
+- Missing domain entities
+- Complex domain services
+- Unclear domain boundaries
+
+## Domain Layer Structure
+
+### Organization
+
+**Import From:** `src/firestore/domain`
+
+**Structure:**
+- `entities/` - Business entities (QuotaMetrics, RequestLog)
+- `services/` - Domain services (QuotaCalculator)
+- `constants/` - Domain constants (QuotaLimits)
+- `errors/` - Domain errors (FirebaseFirestoreError)
+
+**Principles:**
+- No external dependencies (Firebase-free)
+- Pure business logic
+- Type-safe entities
+- Clear boundaries
+- Testable in isolation
+
+## Entities
+
+### QuotaMetrics
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
+
+**Purpose:** Represents Firestore quota usage metrics
+
+**Properties:**
+- `totalReads: number` - Total read operations
+- `totalWrites: number` - Total write operations
+- `totalDeletes: number` - Total delete operations
+- `reads: QuotaStatus` - Read quota details
+- `writes: QuotaStatus` - Write quota details
+- `deletes: QuotaStatus` - Delete quota details
+
+**QuotaStatus Properties:**
+- `used: number` - Amount used
+- `limit: number` - Total limit
+- `percentage: number` - Usage percentage (0-100)
+
+**Usage:**
+- Track quota usage
+- Display usage to users
+- Check thresholds
+- Calculate remaining quota
+- Monitor trends
+
+**When to Use:**
+- After quota calculations
+- Displaying quota status
+- Checking thresholds
+- Monitoring usage
+- Cost analysis
+
+### RequestLog
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
+
+**Purpose:** Log entry for a Firestore request
+
+**Properties:**
+- `type: RequestType` - Operation type ('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 operation
+- Populate with operation details
+- Store for analytics and monitoring
+- Use queryHash for deduplication
+
+**When to Use:**
+- Repository operations (read, write, delete)
+- Quota tracking middleware
+- Performance monitoring
+- Analytics and reporting
+
+## Value Objects
+
+### QuotaStatus
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
+
+**Purpose:** Represents quota usage status for a single operation type
+
+**Properties:**
+- `used: number` - Amount used
+- `limit: number` - Total limit
+- `percentage: number` - Usage percentage
+
+**Characteristics:**
+- Immutable value object
+- Used in QuotaMetrics
+- Calculated from raw counts
+- Used for threshold checking
+
+**When to Use:**
+- Calculating quota usage
+- Checking thresholds
+- Displaying quota status
+- Monitoring limits
+
+## Domain Services
+
+### QuotaCalculator
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/services`
+
+**Purpose:** Business logic for quota calculations
+
+**Responsibilities:**
+- Calculate quota usage percentages
+- Check quota thresholds
+- Calculate remaining quota
+- Validate quota limits
+
+**Methods:**
+- Calculate usage from operation counts
+- Compare against thresholds
+- Return QuotaMetrics object
+
+**When to Use:**
+- After batch operations
+- Displaying quota status
+- Checking before large operations
+- Monitoring usage trends
+
+## Domain Constants
+
+### QuotaLimits
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
+
+**Purpose:** Firebase free tier quota limits
+
+**Constants:**
+- Daily read limit (50,000)
+- Daily write limit (20,000)
+- Monthly delete limit (20,000)
+
+**Usage:**
+- Quota calculations
+- Display limits to users
+- Calculate remaining quota
+- Set up monitoring
+
+**When to Use:**
+- Calculating quota usage
+- Displaying quota information
+- Setting up alerts
+- Checking remaining quota
+
+## Domain Errors
+
+### FirebaseFirestoreError
+
+**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/errors`
+
+**Purpose:** Base error class for all Firestore errors
+
+**Properties:**
+- `code: string` - Error code
+- `message: string` - Error message
+
+**Hierarchy:**
+- FirebaseFirestoreError (base)
+  - FirebaseFirestoreInitializationError
+  - FirebaseFirestoreQuotaError
+
+**When to Use:**
+- Throwing custom Firestore errors
+- Type-safe error handling
+- Error code for conditional logic
+- Structured error information
+
+## Common Mistakes to Avoid
+
+1. ❌ Importing Firebase in domain layer
+   - ✅ Keep domain Firebase-free
+
+2. ❌ Anemic domain models
+   - ✅ Add behavior to entities
+
+3. ❌ Business logic in infrastructure
+   - ✅ Put business logic in domain
+
+4. ❌ Not validating business rules
+   - ✅ Validate in domain layer
+
+5. ❌ Leaking domain logic
+   - ✅ Keep domain logic contained
+
+## AI Agent Instructions
+
+### When Creating Domain Entity
+
+1. Define entity interface
+2. Add business logic methods
+3. Validate invariants
+4. Keep Firebase-free
+5. Export for infrastructure use
+
+### When Creating Domain Service
+
+1. Identify business logic
+2. Create service class
+3. Implement business rules
+4. Keep pure functions
+5. Test in isolation
+
+### When Creating Domain Error
+
+1. Extend base error class
+2. Add error code
+3. Provide clear message
+4. Include context
+5. Export for use
+
+## Code Quality Standards
+
+### Domain Layer
+
+- No Firebase imports
+- Pure TypeScript
+- Business logic only
+- Type-safe entities
+- Clear interfaces
+
+### Testing
+
+- Test domain in isolation
+- Mock infrastructure
+- Test business rules
+- Validate invariants
+- Unit test coverage
+
+## Related Documentation
+
+- [Firestore Module README](../../README.md)
+- [Firestore Infrastructure README](../../infrastructure/README.md)
+- [Firestore Errors README](../errors/README.md)
+- [Quota Constants README](../constants/README.md)
+
+## Architecture
+
+### Domain Layer Responsibilities
+
+**What Domain Does:**
+- Defines business entities
+- Contains business logic
+- Validates business rules
+- Provides domain services
+- Defines domain errors
+
+**What Domain Doesn't Do:**
+- No Firebase SDK usage
+- No database operations
+- No HTTP requests
+- No external integrations
+- No UI concerns
+
+### DDD Principles
+
+**Strategic Patterns:**
+- Entities (identity-based objects)
+- Value Objects (immutable values)
+- Domain Services (stateless operations)
+- Aggregates (consistency boundaries)
+- Repositories (infrastructure concern)
+
+**Tactical Patterns:**
+- Factory (creation)
+- Strategy (algorithms)
+- Specification (business rules)
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Firestore Module Team

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

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