Combine Reactive — Expert Decisions
Expert decision frameworks for Combine choices. Claude knows Combine syntax — this skill provides judgment calls for when Combine adds value vs async/await and how to avoid common pitfalls.
Decision Trees
Combine vs Async/Await
What's your data flow pattern?
├─ Single async operation (fetch once)
│ └─ async/await
│ Simpler, built into language
│
├─ Stream of values over time
│ └─ Is it UI-driven (user events)?
│ ├─ YES → Combine (debounce, throttle shine here)
│ └─ NO → AsyncSequence may suffice
│
├─ Combining multiple data sources
│ └─ How many sources?
│ ├─ 2-3 → Combine's CombineLatest, Zip
│ └─ Many → Consider structured concurrency (TaskGroup)
│
└─ Existing codebase uses Combine?
└─ Maintain consistency unless migrating
The trap: Using Combine for simple one-shot async. async/await is cleaner and doesn't need cancellable management.
Subject Type Selection
Do you need to access current value?
├─ YES → CurrentValueSubject
│ Can read .value synchronously
│ New subscribers get current value immediately
│
└─ NO → Is it event-based (discrete occurrences)?
├─ YES → PassthroughSubject
│ No stored value, subscribers only get new emissions
│
└─ NO (need replay of past values) →
Consider external state management
Combine has no built-in ReplaySubject
Operator Chain Design
What transformation is needed?
├─ Value transformation
│ └─ map (simple), compactMap (filter nils), flatMap (nested publishers)
│
├─ Filtering
│ └─ filter, removeDuplicates, first, dropFirst
│
├─ Timing
│ └─ User input → debounce (wait for pause)
│ Scrolling → throttle (rate limit)
│
├─ Error handling
│ └─ Can provide fallback? → catch, replaceError
│ Need retry? → retry(n)
│
└─ Combining streams
└─ Need all values paired? → zip
Need latest from each? → combineLatest
Merge into one stream? → merge
NEVER Do
Subscription Management
NEVER forget to store subscriptions:
// ❌ Subscription cancelled immediately
func loadData() {
publisher.sink { value in
self.data = value // Never called!
}
// sink returns AnyCancellable that's immediately deallocated
}
// ✅ Store in Set<AnyCancellable>
private var cancellables = Set<AnyCancellable>()
func loadData() {
publisher.sink { value in
self.data = value
}
.store(in: &cancellables)
}
NEVER capture self strongly in sink closures:
// ❌ Retain cycle — ViewModel never deallocates
publisher
.sink { value in
self.updateUI(value) // Strong capture!
}
.store(in: &cancellables)
// ✅ Use [weak self]
publisher
.sink { [weak self] value in
self?.updateUI(value)
}
.store(in: &cancellables)
NEVER use assign(to:on:) with classes:
// ❌ Strong reference to self — retain cycle
publisher
.assign(to: \.text, on: self) // Retains self!
.store(in: &cancellables)
// ✅ Use sink with weak self
publisher
.sink { [weak self] value in
self?.text = value
}
.store(in: &cancellables)
// Or use assign(to:) with @Published (no retain cycle)
publisher
.assign(to: &$text) // Safe — doesn't return cancellable
Subject Misuse
NEVER expose subjects directly:
// ❌ External code can send values
class ViewModel {
let users = PassthroughSubject<[User], Never>() // Public subject!
}
// External code:
viewModel.users.send([]) // Breaks encapsulation
// ✅ Expose as Publisher
class ViewModel {
private let usersSubject = PassthroughSubject<[User], Never>()
var users: AnyPublisher<[User], Never> {
usersSubject.eraseToAnyPublisher()
}
}
NEVER send on subject from multiple threads without care:
// ❌ Race condition — undefined behavior
DispatchQueue.global().async {
subject.send(value1)
}
DispatchQueue.global().async {
subject.send(value2)
}
// ✅ Serialize access
let subject = PassthroughSubject<Value, Never>()
let serialQueue = DispatchQueue(label: "subject.serial")
serialQueue.async {
subject.send(value)
}
// Or use .receive(on:) to ensure delivery on specific scheduler
Operator Mistakes
NEVER use flatMap when you mean map:
// ❌ Confusing — flatMap for non-publisher transformation
publisher
.flatMap { user -> AnyPublisher<String, Never> in
Just(user.name).eraseToAnyPublisher() // Overkill!
}
// ✅ Use map for simple transformation
publisher
.map { user in user.name }
NEVER forget to handle errors in sink:
// ❌ Compiler allows this but errors are ignored
publisher // Has Error type
.sink { value in
// Only handles values, error terminates silently
}
// ✅ Handle both completion and value
publisher
.sink(
receiveCompletion: { completion in
if case .failure(let error) = completion {
handleError(error)
}
},
receiveValue: { value in
handleValue(value)
}
)
NEVER debounce without scheduler on main:
// ❌ Debouncing on background scheduler, updating UI
searchText
.debounce(for: .milliseconds(300), scheduler: DispatchQueue.global())
.sink { [weak self] text in
self?.results = search(text) // UI update on background thread!
}
// ✅ Receive on main for UI updates
searchText
.debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
.sink { [weak self] text in
self?.results = search(text)
}
// Or explicitly receive on main
searchText
.debounce(for: .milliseconds(300), scheduler: DispatchQueue.global())
.receive(on: DispatchQueue.main)
.sink { ... }
Essential Patterns
ViewModel with Combine
@MainActor
final class SearchViewModel: ObservableObject {
@Published var searchText = ""
@Published private(set) var results: [SearchResult] = []
@Published private(set) var isLoading = false
@Published private(set) var error: Error?
private let searchService: SearchServiceProtocol
private var cancellables = Set<AnyCancellable>()
init(searchService: SearchServiceProtocol) {
self.searchService = searchService
setupSearch()
}
private func setupSearch() {
$searchText
.debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
.removeDuplicates()
.filter { !$0.isEmpty }
.handleEvents(receiveOutput: { [weak self] _ in
self?.isLoading = true
self?.error = nil
})
.flatMap { [weak self] query -> AnyPublisher<[SearchResult], Never> in
guard let self = self else {
return Just([]).eraseToAnyPublisher()
}
return self.searchService.search(query: query)
.catch { [weak self] error -> Just<[SearchResult]> in
self?.error = error
return Just([])
}
.eraseToAnyPublisher()
}
.receive(on: DispatchQueue.main)
.sink { [weak self] results in
self?.results = results
self?.isLoading = false
}
.store(in: &cancellables)
}
}
Combine to Async Bridge
extension Publisher where Failure == Error {
func async() async throws -> Output {
try await withCheckedThrowingContinuation { continuation in
var cancellable: AnyCancellable?
var didResume = false
cancellable = first()
.sink(
receiveCompletion: { completion in
guard !didResume else { return }
didResume = true
switch completion {
case .finished:
break // Value handled in receiveValue
case .failure(let error):
continuation.resume(throwing: error)
}
cancellable?.cancel()
},
receiveValue: { value in
guard !didResume else { return }
didResume = true
continuation.resume(returning: value)
}
)
}
}
}
// Usage
Task {
let user = try await fetchUserPublisher.async()
}
Event Bus Pattern
final class EventBus {
static let shared = EventBus()
// Private subjects
private let userLoggedInSubject = PassthroughSubject<User, Never>()
private let userLoggedOutSubject = PassthroughSubject<Void, Never>()
private let cartUpdatedSubject = PassthroughSubject<Cart, Never>()
// Public publishers (read-only)
var userLoggedIn: AnyPublisher<User, Never> {
userLoggedInSubject.eraseToAnyPublisher()
}
var userLoggedOut: AnyPublisher<Void, Never> {
userLoggedOutSubject.eraseToAnyPublisher()
}
var cartUpdated: AnyPublisher<Cart, Never> {
cartUpdatedSubject.eraseToAnyPublisher()
}
// Send methods
func send(userLoggedIn user: User) {
userLoggedInSubject.send(user)
}
func sendUserLoggedOut() {
userLoggedOutSubject.send()
}
func send(cartUpdated cart: Cart) {
cartUpdatedSubject.send(cart)
}
}
Quick Reference
Combine vs Async/Await Decision
| Scenario | Prefer | |----------|--------| | Single async call | async/await | | Stream of values | Combine | | User input debouncing | Combine | | Combining multiple API calls | Either (async let or CombineLatest) | | Existing Combine codebase | Combine for consistency | | New project, simple needs | async/await |
Subject Comparison
| Subject | Stores Value | New Subscribers Get | |---------|--------------|---------------------| | PassthroughSubject | No | Only new values | | CurrentValueSubject | Yes | Current + new values |
Common Operators
| Category | Operators | |----------|-----------| | Transform | map, flatMap, compactMap, scan | | Filter | filter, removeDuplicates, first, dropFirst | | Combine | combineLatest, zip, merge | | Timing | debounce, throttle, delay | | Error | catch, retry, replaceError |
Red Flags
| Smell | Problem | Fix | |-------|---------|-----| | Subscription not stored | Immediate cancellation | .store(in: &cancellables) | | Strong self in sink | Retain cycle | [weak self] | | assign(to:on:self) | Retain cycle | Use sink or assign(to:&$property) | | Public Subject | Encapsulation broken | Expose as AnyPublisher | | flatMap for simple transform | Overkill | Use map | | Debounce on background, sink updates UI | Threading bug | receive(on: .main) | | Empty receiveCompletion | Errors ignored | Handle .failure case |