Axiom Combine Patterns

Combine Patterns

Overview

Combine remains embedded in massive production codebases — UIKit delegates, NotificationCenter bridging, KVO observation, and @Published properties are everywhere. New code prefers async/await, but interop and maintenance of existing Combine pipelines is daily work. This skill covers the decisions and pitfalls that matter: when to use Combine vs async/await, how to avoid memory leaks, and how to bridge between the two paradigms.

Core principle: Combine is not dead — it's mature. The question isn't "should I use Combine?" but "is Combine the right tool for THIS specific data flow?"

When to Use This Skill

• Working with existing Combine pipelines
• Deciding between Combine and async/await for a new data flow
• Debugging AnyCancellable memory leaks or silent pipeline failures
• Using @Published or ObservableObject
• Bridging Combine publishers with async/await code
• Working with Subjects (PassthroughSubject, CurrentValueSubject)

When NOT to Use This Skill

• Timer.publish patterns → route via axiom-ios-concurrency to timer-patterns skill (dedicated timer lifecycle coverage)
• @Observable migration from ObservableObject → use axiom-swift-concurrency (modern observation)
• UIKit ↔ SwiftUI bridging → route via axiom-ios-ui (view wrapping, not data flow)
• General async/await patterns → use axiom-swift-concurrency

Example Prompts

• "Should I use Combine or async/await for this?"
• "My Combine pipeline silently stops producing values"
• "How do I convert a publisher to an async sequence?"
• "AnyCancellable is leaking — where do I store it?"
• "What's the difference between combineLatest and zip?"
• "How do I debounce a text field with Combine?"
• "My @Published property update isn't reaching the view"
• "How do I bridge a Combine publisher into async/await code?"

Part 1: Combine vs async/await Decision Tree

Quick Decision

Is it a one-shot operation (network call, file read)?
├─ Yes → async/await (simpler, no cancellable management)
│
Does it need time-based operators (debounce, throttle, delay)?
├─ Yes → Combine (built-in operators, no manual implementation)
│
Are you combining multiple ongoing streams?
├─ Yes → Combine (combineLatest, merge, zip are purpose-built)
│
Is this new code on iOS 17+?
├─ Yes → async/await + @Observable (modern pattern)
│
Is it existing Combine code that works?
└─ Yes → Keep it. Bridge at boundaries when async/await code needs the data.

Part 2: Publisher/Subscriber Lifecycle

AnyCancellable Storage Rules

AnyCancellable cancels its subscription when deallocated. If you don't store it, the pipeline is cancelled immediately after setup.

❌ Pipeline dies instantly

func setupPipeline() {
    publisher
        .sink { value in
            self.handle(value)  // Never called
        }
    // AnyCancellable returned by sink is discarded → subscription cancelled
}

✅ Store in Set

private var cancellables = Set<AnyCancellable>()

func setupPipeline() {
    publisher
        .sink { [weak self] value in
            self?.handle(value)
        }
        .store(in: &cancellables)
}

Why Set, Not Array

Set<AnyCancellable> is the idiomatic choice because:

• store(in:) works with both Set and RangeReplaceableCollection (including Array), but Set is conventional
• Order doesn't matter for subscriptions
• Prevents accidental duplicates if setup runs twice

4 Memory Leak Patterns

Leak 1: Strong self in sink

// ❌ LEAK: sink closure captures self strongly
publisher
    .sink { value in
        self.handle(value)  // Strong capture → retain cycle
    }
    .store(in: &cancellables)

// ✅ FIX: weak self
publisher
    .sink { [weak self] value in
        self?.handle(value)
    }
    .store(in: &cancellables)

Leak 2: Missing store(in:)

// ❌ LEAK: cancellable assigned to local var, not stored
let cancellable = publisher.sink { handle($0) }
// cancellable deallocated at end of scope → pipeline cancelled

// ✅ FIX: store in instance property
publisher.sink { [weak self] in self?.handle($0) }
    .store(in: &cancellables)

Leak 3: Over-retained cancellables

// ❌ LEAK: cancellables set never cleared, old pipelines accumulate
func refreshData() {
    // Each call adds another subscription without removing the previous one
    dataPublisher
        .sink { [weak self] in self?.update($0) }
        .store(in: &cancellables)
}

// ✅ FIX: clear before re-subscribing
func refreshData() {
    cancellables.removeAll()  // Cancel previous subscriptions
    dataPublisher
        .sink { [weak self] in self?.update($0) }
        .store(in: &cancellables)
}

Leak 4: assign(to:on:) strong capture

assign(to:on:) captures the on: parameter strongly. When the target is self, you get a retain cycle: self → cancellables → subscription → self.

// ❌ LEAK: assign(to:on:) retains self strongly — deinit never called
userPublisher
    .map { $0.name }
    .assign(to: \.displayName, on: self)
    .store(in: &cancellables)

// ✅ FIX: use assign(to:) with @Published projected value (iOS 14+)
userPublisher
    .map { $0.name }
    .assign(to: &$displayName)
// No store(in:) needed — subscription tied to @Published property lifetime

Key difference: assign(to: &$prop) does NOT return an AnyCancellable — the subscription is managed internally and cancelled when the @Published property's owner deallocates. No retain cycle, no cancellable storage needed.

If you must support iOS 13, use sink with [weak self] instead.

Part 3: Essential Operators

One canonical example per group. These cover 90% of real-world usage.

Transform

// map: transform each value
publisher.map { $0.name }

// compactMap: transform + filter nil
publisher.compactMap { Int($0) }

// flatMap: one-to-many (each value produces a new publisher)
searchText
    .flatMap { query in
        api.search(query)  // Returns a publisher
    }

flatMap gotcha: Without .switchToLatest() or maxPublishers: .max(1), flatMap creates a new inner publisher for every upstream value. For search-as-you-type, use map + switchToLatest instead:

searchText
    .map { query in api.search(query) }
    .switchToLatest()  // Cancels previous search when new query arrives

Combine Multiple Sources

// combineLatest: latest value from each, fires when ANY changes
Publishers.CombineLatest(namePublisher, agePublisher)
    .map { name, age in "\(name), \(age)" }

// merge: interleave values from same-type publishers
Publishers.Merge(localUpdates, remoteUpdates)
    .sink { update in handle(update) }

// zip: pairs values 1:1 (waits for both to produce)
Publishers.Zip(requestA, requestB)
    .sink { responseA, responseB in /* both complete */ }

Time-Based

// debounce: wait until values stop arriving (search-as-you-type)
searchTextPublisher
    .debounce(for: .milliseconds(300), scheduler: RunLoop.main)
    .sink { [weak self] query in self?.search(query) }
    .store(in: &cancellables)

// throttle: emit at most once per interval (scroll position)
scrollOffsetPublisher
    .throttle(for: .milliseconds(100), scheduler: RunLoop.main, latest: true)
    .sink { [weak self] offset in self?.updateHeader(offset) }
    .store(in: &cancellables)

Error Handling

// tryMap: transform that can throw
publisher.tryMap { data in
    try JSONDecoder().decode(Model.self, from: data)
}

// mapError: convert error types
publisher.mapError { error in
    AppError.network(error)
}

// replaceError: provide fallback value (terminates error path)
publisher.replaceError(with: defaultValue)

// retry: re-subscribe on failure
publisher.retry(3)  // Retry up to 3 times before propagating error

Error handling order matters: retry should come before replaceError. Retry re-subscribes to the upstream publisher; replaceError terminates the error and makes the pipeline infallible.

api.fetchData()
    .retry(3)                    // Try 3 more times on failure
    .replaceError(with: cached)  // If all retries fail, use cache
    .sink { data in update(data) }
    .store(in: &cancellables)

replaceError after flatMap kills the outer pipeline: If replaceError is downstream of flatMap, a single inner publisher error terminates the entire pipeline — not just that one request. Move error handling inside flatMap so each inner publisher handles its own errors:

// ❌ One API error kills the entire pipeline
$searchText
    .flatMap { query in api.search(query) }
    .replaceError(with: [])  // Pipeline completes on first error
    .sink { ... }

// ✅ Each search handles its own errors independently
$searchText
    .flatMap { query in
        api.search(query)
            .replaceError(with: [])  // Only this search affected
    }
    .sink { ... }

Part 4: @Published + ObservableObject

willSet Timing

@Published fires its publisher in willSet, not didSet. This means subscribers see the new value before the property has actually been set on the object.

class ViewModel: ObservableObject {
    @Published var count = 0

    init() {
        $count.sink { newValue in
            // 'newValue' is the incoming value
            // BUT self.count is still the OLD value here
            print("New: \(newValue), Current: \(self.count)")
            // Prints "New: 1, Current: 0" when count is set to 1
        }
        .store(in: &cancellables)
    }
}

If you need to read the property's value after it's been set, don't subscribe to $count — use a didSet observer instead, or read self.count after a brief deferral. The $ publisher is designed for reacting to the incoming value, not for reading post-mutation state.

Nested ObservableObject Trap

SwiftUI does NOT observe nested ObservableObject changes. Only the top-level object's objectWillChange triggers view updates.

// ❌ View won't update when settings.theme changes
class AppState: ObservableObject {
    @Published var settings = Settings()  // Settings is also ObservableObject
}

class Settings: ObservableObject {
    @Published var theme = "light"  // Changes here don't propagate
}

// ✅ FIX: Forward objectWillChange manually
class AppState: ObservableObject {
    @Published var settings = Settings()
    private var cancellables = Set<AnyCancellable>()

    init() {
        settings.objectWillChange
            .sink { [weak self] _ in
                self?.objectWillChange.send()
            }
            .store(in: &cancellables)
    }
}

Better fix for iOS 17+: Migrate to @Observable, which handles nested observation automatically. See axiom-swift-concurrency for migration patterns.

Thread Safety Warning

@Published is NOT thread-safe. Setting a @Published property from a background thread triggers objectWillChange off the main thread, which can crash SwiftUI views.

// ❌ CRASH: @Published set from background thread
class ViewModel: ObservableObject {
    @Published var data: [Item] = []

    func fetch() {
        Task {
            let items = await api.fetchItems()
            data = items  // Background thread → crash
        }
    }
}

// ✅ FIX: Ensure main thread
@MainActor
class ViewModel: ObservableObject {
    @Published var data: [Item] = []

    func fetch() {
        Task {
            let items = await api.fetchItems()
            data = items  // Safe — @MainActor ensures main thread
        }
    }
}

Part 5: Bridging Combine and async/await

Publisher → AsyncSequence

Use .values to consume any publisher as an async sequence:

let cancellable = notificationPublisher
    .sink { notification in handle(notification) }

// ✅ Modern equivalent using .values
for await notification in notificationPublisher.values {
    handle(notification)
}

Caveats with .values:

• The for await loop runs indefinitely until the publisher completes or the Task is cancelled
• Errors thrown by the publisher terminate the loop
• Only one consumer — if two for await loops consume the same .values, behavior is undefined

async/await → Publisher

Wrap an async function in Future for Combine consumption:

func fetchUser(id: String) async throws -> User { ... }

// Wrap as a Combine publisher
let userPublisher = Future<User, Error> { promise in
    Task {
        do {
            let user = try await fetchUser(id: "123")
            promise(.success(user))
        } catch {
            promise(.failure(error))
        }
    }
}

Future executes immediately — it runs its closure when created, not when subscribed. Wrap in Deferred if you need lazy execution:

let lazyPublisher = Deferred {
    Future<User, Error> { promise in
        Task {
            do {
                let user = try await fetchUser(id: "123")
                promise(.success(user))
            } catch {
                promise(.failure(error))
            }
        }
    }
}

Gradual Migration Strategy

Don't rewrite working Combine code. Bridge at the boundary:

Combine pipeline  →  .values  →  async/await code
                     (bridge)

async function    →  Future   →  Combine pipeline
                     (bridge)

Migration priority:

1. New code: write in async/await
2. Boundary: bridge with .values or Future
3. Existing Combine: leave working pipelines alone
4. Rewrite: only when the pipeline needs significant changes anyway

Part 6: Subjects

PassthroughSubject vs CurrentValueSubject

// Event-driven: no initial value, late subscribers miss past events
let taps = PassthroughSubject<Void, Never>()
taps.send()

// State-driven: always has a current value
let isLoading = CurrentValueSubject<Bool, Never>(false)
isLoading.value = true  // Direct access
isLoading.send(false)   // Also works

Send-After-Completion Pitfall

Once a Subject receives a completion event, all subsequent send() calls are silently ignored. No crash, no error — just silence.

let subject = PassthroughSubject<Int, Never>()

subject.send(1)           // Delivered
subject.send(completion: .finished)
subject.send(2)           // Silently ignored — no crash, no warning

// This is the most common cause of "my pipeline stopped working"

Diagnosis: If a pipeline silently stops producing values, check whether anything upstream sent a .finished or .failure completion. Once complete, the pipeline is dead.

Part 7: Cold vs Hot Publishers (share/multicast)

Most Combine publishers are cold — they start work when subscribed and each subscriber gets its own independent execution. URLSession.dataTaskPublisher fires a new HTTP request per subscriber.

// ❌ Two subscribers = two network requests
let publisher = URLSession.shared
    .dataTaskPublisher(for: url)
    .map(\.data)
    .eraseToAnyPublisher()

publisher.sink { cache.store($0) }.store(in: &cancellables)  // Request 1
publisher.sink { display($0) }.store(in: &cancellables)       // Request 2

share()

.share() makes a cold publisher hot — the first subscriber triggers the work, subsequent subscribers share the output:

// ✅ One request, shared result
let publisher = URLSession.shared
    .dataTaskPublisher(for: url)
    .map(\.data)
    .share()
    .eraseToAnyPublisher()

publisher.sink { cache.store($0) }.store(in: &cancellables)  // Triggers request
publisher.sink { display($0) }.store(in: &cancellables)       // Shares result

share() Gotchas

When to use share()

Multiple subscribers to the same expensive publisher?
├─ No → Don't use share() (unnecessary complexity)
│
├─ Yes, all subscribe at the same time?
│   └─ Yes → share() works
│
└─ Yes, subscribers attach at different times?
    └─ Use multicast(subject:) with CurrentValueSubject, or cache the result in a property

Anti-Rationalization

Pressure Scenarios

Scenario 1: "Let's migrate all Combine code to async/await"

Setup: Tech lead wants to modernize the codebase. "Combine is legacy, let's rip it out."

Pressure: Authority + scope creep. The entire data layer uses Combine publishers, @Published properties, and operator chains.

Expected with skill: Push back with the gradual migration strategy (Part 5). New code uses async/await. Boundaries use .values and Future. Existing working pipelines stay until they need changes. Full rewrite is the most expensive option with the least benefit.

Pushback template: "Combine isn't deprecated — Apple still ships it in every SDK. A full rewrite of working pipelines introduces bugs we don't have today. Let's bridge at boundaries: new code in async/await, .values to consume existing publishers, and we only rewrite a pipeline when we're already changing it significantly."

Scenario 2: "Pipeline silently stopped — just recreate it"

Setup: A Combine pipeline stopped producing values after a refactor. No crash, no error.

Pressure: Time pressure. "Just tear it down and rebuild."

Expected with skill: Diagnose before rebuilding. Check: (1) Was a completion sent upstream? (send-after-completion, Part 6). (2) Is the AnyCancellable still alive? (storage rules, Part 2). (3) Did the publisher error without handling? (replaceError / catch, Part 3). These three causes cover 90% of silent pipeline failures.

Diagnostic checklist:

1. Is the AnyCancellable still stored? (Set not cleared, not deallocated)
2. Did anything upstream send .finished or .failure?
3. Is there a tryMap or other throwing operator without error handling?
4. Was switchToLatest used where the outer publisher completed?

Pushback template: "Before rebuilding, let me check four things: cancellable lifecycle, upstream completions, unhandled errors, and switchToLatest completion. One of these is almost always the cause. It takes 5 minutes to diagnose vs 30 minutes to rebuild and test."

Scenario 3: "Settings changes aren't updating the UI"

Setup: A settings screen uses a nested ObservableObject. The parent AppState holds a Settings object. When the user changes settings.theme, the UI doesn't update.

Pressure: "The binding works in isolation, it must be a SwiftUI bug. Let me just force a refresh with objectWillChange.send()."

Expected with skill: Recognize the nested ObservableObject trap (Part 4). SwiftUI does NOT observe nested ObservableObject changes — only the top-level object's objectWillChange triggers view updates. The fix is either forwarding objectWillChange from the nested object, or migrating to @Observable (iOS 17+) which handles nesting automatically.

Anti-pattern without skill: Sprinkling objectWillChange.send() calls throughout the code, adding @Published to every nested property (which doesn't help), or restructuring the model to flatten everything into one object (losing separation of concerns).

Pushback template: "SwiftUI only observes the top-level ObservableObject. Nested objects need their objectWillChange forwarded to the parent. Part 4 has the exact pattern — it's a 5-line fix in the parent's init, not a SwiftUI bug."

Resources

WWDC: 2019-722, 2019-721, 2020-10034

Docs: /combine, /combine/anycancellable, /combine/published

Skills: swift-concurrency, memory-debugging