Skip to content

roadmap.md

Latest commit

 

History

History
133 lines (102 loc) · 4.94 KB

roadmap.md

File metadata and controls

133 lines (102 loc) · 4.94 KB

SwiftUI Query - Development Roadmap

This document outlines the complete implementation roadmap for SwiftUI Query, organized by priority and implementation phases.

Progress Summary

Phase 1 - Foundation: ✅ COMPLETED

  • Core Types & Protocols: ✅ COMPLETED (Tasks 1-5)
  • Cache Infrastructure: ✅ COMPLETED (Tasks 6-7)
  • Core Query Engine: ✅ COMPLETED (Tasks 9, 11-12)
  • SwiftUI Integration: ✅ COMPLETED (Tasks 14-15)

Current Status: 12 of 25 core tasks completed (48%)

  • 130 comprehensive unit tests passing
  • Swift 6 strict concurrency compliance verified
  • Perception library integrated for iOS 16+ compatibility
  • Basic useQuery functionality working in SwiftUI

Phase 1: Foundation (High Priority)

Core Types & Protocols

  • Task 1: Create foundational types (QueryKey protocol, RetryConfig, RefetchTriggers/RefetchOnAppear, QueryMeta)
  • Task 2: Implement QueryState and FetchStatus enums
  • Task 3: Create QueryOptions and InfiniteQueryOptions structs
  • Task 4: Implement InfiniteData struct for pagination
  • Task 5: Create QueryObserverIdentifier and QueryError types

Cache Infrastructure

  • Task 6: Implement thread-safe Mutex actor for cache synchronization
  • Task 7: Create QueryCache class with thread-safe operations

Core Query Engine

  • Task 9: Create Query class with state management and lifecycle
  • Task 11: Create QueryClient class with query management methods
  • Task 12: Implement QueryObserver class with reactive state

SwiftUI Integration

  • Task 14: Implement QueryClientProvider singleton and environment setup
  • Task 15: Create UseQuery SwiftUI view component

Phase 2: Extended Features (Medium Priority)

Infinite Query Support

  • Task 10: Implement InfiniteQuery class for pagination support
  • Task 13: Create InfiniteQueryObserver class with pagination methods
  • Task 16: Implement UseInfiniteQuery SwiftUI view component

Lifecycle Monitoring

  • Task 17: Create AppLifecycleMonitor for app foreground/background detection
  • Task 18: Implement NetworkMonitor for connectivity changes

Advanced Features

  • Task 8: Implement MutationCache class (basic structure)
  • Task 19: Add retry logic with exponential backoff
  • Task 20: Implement garbage collection timers for inactive queries
  • Task 21: Add refetch interval timers and background handling
  • Task 23: Add query invalidation and refetch methods

Quality Assurance

  • Task 24: Create comprehensive unit tests for foundational types (28 tests passing)
  • Task 24b: Create unit tests for remaining components (cache, observers, etc.)

Phase 3: Optimization & Polish (Low Priority)

Performance Optimizations

  • Task 22: Implement structural sharing for data optimization

Documentation

  • Task 25: Add DocC documentation for all public APIs

Implementation Guidelines

Dependencies

Each phase builds upon the previous:

  • Phase 1 provides the foundation for all query operations
  • Phase 2 adds advanced features and lifecycle management
  • Phase 3 focuses on performance and documentation

Key Requirements

  • Swift 6 strict concurrency mode compatible
  • Built with Perception library for iOS 16 compatibility
  • Zero external dependencies beyond Perception
  • Match TanStack Query's architecture and behavior

Testing Strategy

  • Unit tests for all public APIs
  • Integration tests for SwiftUI components
  • Performance tests for cache operations
  • Memory leak tests for observers and timers

Architecture Principles

  1. Observer Pattern: Reactive updates using Perception
  2. Stale-While-Revalidate: Show cached data while refetching
  3. Thread Safety: All operations are Sendable and thread-safe
  4. Framework Agnostic Core: Separate business logic from SwiftUI

Milestone Checkpoints

Milestone 1: Basic Query Functionality ✅ COMPLETED

Complete Phase 1 tasks 1-7, 9, 11-12, 14-15

  • ✅ Basic useQuery equivalent working in SwiftUI
  • ✅ Thread-safe caching system
  • ✅ Query lifecycle management

Milestone 2: Feature Complete

Complete Phase 2 tasks 8, 10, 13, 16-21, 23-24

  • Infinite query support
  • App lifecycle integration
  • Advanced query features
  • Comprehensive test coverage

Milestone 3: Production Ready

Complete Phase 3 tasks 22, 25

  • Performance optimizations
  • Complete documentation
  • Ready for public release

Success Criteria

Each task must meet:

  • Compiles with Swift 6 strict concurrency
  • Matches corresponding TanStack Query behavior
  • Includes unit tests
  • Follows SwiftUI best practices
  • Uses Perception for state management

Reference Implementation

Always reference TanStack Query source code in Documentation/query/packages/:

  • query-core/src/ - Core logic and architecture
  • react-query/src/ - Framework integration patterns

Adapt TypeScript patterns to Swift idioms while maintaining behavioral consistency.