Repository files navigation

A Swift implementation ofTanStack Query for SwiftUI applications, providing powerful asynchronous state management with caching, synchronization, and infinite queries.

Inspired by TanStack Query - This library brings the beloved patterns and features of TanStack Query (formerly React Query) to the Swift ecosystem, adapted for SwiftUI and Swift's concurrency model.

• 🚀Swift 6 Compatible - Full strict concurrency support
• 🔄Automatic Refetching - On mount, focus, reconnect
• 📱iOS 16+ Support - Built with Perception library for broad compatibility
• ⚡️Request Deduplication - Automatic request optimization
• 🗑️Garbage Collection - Smart memory management
• 📊Infinite Queries - Built-in pagination support
• 🔧Type Safe - Full Swift type safety
• 📱Multi-Platform - iOS, macOS, tvOS, and watchOS

• Swift 6.0+
• iOS 16.0+ / macOS 13.0+ / tvOS 16.0+ / watchOS 9.0+

Add SwiftUI Query to yourPackage.swift file:

dependencies:[.package(url:"https://github.com/muzix/SwiftUIQuery.git", from:"0.2.0")]

Or add it through Xcode:

1. File → Add Package Dependencies
2. Enter the repository URL:https://github.com/muzix/SwiftUIQuery.git
3. Select the version

import SwiftUIimport SwiftUIQuery@mainstructMyApp:App{varbody:someScene{WindowGroup{ContentView().queryClient() // Add QueryClient to environment}}}

import SwiftUIimport SwiftUIQuerystructContentView:View{varbody:someView{UseQuery(            queryKey:"todos",            queryFn:{ _intryawaitfetchTodos()}){ resultinswitch result.status{case.loading:ProgressView("Loading...")case.error:Text("Error:\(result.error?.localizedDescription??"Unknown error")")case.success:List(result.data??[]){ todoinText(todo.title)}}}}func fetchTodos()asyncthrows->[Todo]{        // Your API call here}}

structPokemonListView:View{varbody:someView{UseInfiniteQuery(            queryKey:"pokemon-list",            queryFn:{ _, pageParaminletoffset= pageParam??0returntryawaitPokemonAPI.fetchPokemonPage(offset: offset)},            getNextPageParam:{ pagesinletcurrentTotal= pages.reduce(0){ total, pagein                     total+ page.results.count}return pages.last?.next!=nil? currentTotal:nil},            initialPageParam:0){ resultinScrollView{LazyVStack{                    // Render all pagesForEach(result.data?.pages??[]){ pageinForEach(page.results){ pokemoninPokemonRow(pokemon: pokemon)}}                                        // Load more buttonif result.hasNextPage{Button("Load More"){Task{await result.fetchNextPage()}}.onAppear{                            // Auto-load on scrollTask{await result.fetchNextPage()}}}}}.refreshable{try?await result.refetch()}}}}

1. Clone the repository
2. Install development tools:

   brew bundle

This project uses SwiftLint and SwiftFormat to maintain code quality and consistency.

makehelp# Show all available commandsmake lint# Run SwiftLintmake lint-fix# Auto-fix SwiftLint issuesmake format# Format code with SwiftFormatmake format-check# Check if formatting is neededmake check# Run all checks (lint + format)make fix# Fix all issues (lint + format)make build# Build with strict concurrencymaketest# Run testsmake ci# Run full CI suite

To ensure code quality before commits:

cat> .git/hooks/pre-commit<< 'EOF'#!/bin/bashmake checkEOFchmod +x .git/hooks/pre-commit

Run tests with strict concurrency:

maketest

The project follows TanStack Query's architecture. Key documentation:

• CLAUDE.md - Development guide and instructions
• principles.md - Core principles and Swift 6 compliance
• api-design.md - API patterns and usage examples
• roadmap.md - Development roadmap
• feature-parity.md - TanStack Query feature comparison

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Runmake check to ensure code quality
4. Commit your changes
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

MIT License

This project is heavily inspired byTanStack Query (formerly React Query), created byTanner Linsley and maintained by the TanStack team. We aim to bring the same powerful patterns, architectural principles, and developer experience to the Swift ecosystem.

• ✅Query Caching - Automatic request deduplication and intelligent caching
• ✅Background Refetching - Stale-while-revalidate pattern
• ✅Automatic Retries - Configurable retry logic with exponential backoff
• ✅Infinite Queries - Built-in pagination and infinite scrolling support
• ✅Lifecycle Management - Automatic refetch on mount, focus, and reconnect
• ✅Garbage Collection - Smart cleanup of unused query data
• ✅DevTools Integration - Built-in debugging and inspection tools

Special thanks to the TanStack Query team for creating such an excellent library that has transformed how developers handle server state management. This Swift implementation follows the same core principles while embracing Swift's type system and concurrency model.