RxSwift

RxBlocking provides a set of blocking operators designed to simplify unit testing by allowing you to synchronously wait for observable emissions.

CRITICAL: Do not use these operators in production applications. They are intended exclusively for testing purposes to avoid complex asynchronous testing setups.

RxSwift uses a short-circuit logic for errors: if one sequence terminates with an error, all dependent sequences also terminate.

To manage errors:

• Use the catch operator to recover from a failure by providing a new sequence.
• Use the retry operator to re-subscribe to the sequence if it encounters an error.
• For UI binding, ensure an Observable cannot fail by using catchErrorJustReturn(value) (note: this completes the underlying sequence) or retry if you need the sequence to continue producing elements.

// Example of catching an error to return a fallback value
images = word
    .filter { $0.containsString("important") }
    .flatMap { word in
        return self.api.loadFlickrFeed("karate")
            .catchError { error in
                return just(JSON(1))
            }
      }

RxSwift is built on the duality between two ways of accessing sequences: the Push interface and the Pull interface.

• Push interface (Observer pattern): Elements are pushed to the observer as they occur over time. This is the foundation of an Observable sequence. For example, observing mouse cursor positions over time forms an observable sequence where each new position is 'pushed' to you.
• Pull interface (Iterator / Enumerator / Generator): The consumer requests the next element from the sequence. This is the standard way to handle synchronous sequences.

This duality is what allows RxSwift to bridge the gap between asynchronous callback-based worlds and the synchronous world of sequence transformations.

Traits (formerly known as Units) are wrapper structs that wrap a single read-only Observable sequence. They use Swift's type system to communicate specific observable properties across interface boundaries, providing semantic meaning and syntactical sugar for specific use cases.

Key characteristics:

• Optionality: Traits are entirely optional; you can use raw Observable sequences everywhere as all core APIs support them.
• Implementation: They are essentially a builder pattern. You can transform any Trait back into a vanilla observable sequence by calling .asObservable().
• Termination: Most RxSwift traits (Single, Completable, Maybe) are designed to terminate after their specific event (success, completion, or error).

struct Single<Element> {
    let source: Observable<Element>
}

struct Driver<Element> {
    let source: Observable<Element>
}

Rx handles 'transient state' (like managing pending requests, debouncing input, or handling errors during a sequence) without requiring manual flags or extra variables.

For example, in an autocomplete search box, you can combine throttle, distinctUntilChanged, and flatMapLatest to automatically cancel pending requests when new input arrives and manage the loading/error states.

searchTextField.rx.text
    .throttle(.milliseconds(300), scheduler: MainScheduler.instance)
    .distinctUntilChanged()
    .flatMapLatest { query in
        API.getSearchResults(query)
            .retry(3)
            .startWith([]) // clears results on new search term
            .catchErrorJustReturn([])
    }
    .subscribe(onNext: { results in
      // bind to ui
    })
    .disposed(by: disposeBag)

RxSwift guarantees that Observer callbacks are executed serially. Even if elements are produced on different threads, a producer cannot send a new .next event until the previous observer.on(.next(element)) call has finished execution. Similarly, a terminating .completed or .error event cannot be sent until the final .next event processing has finished. This ensures that event processing remains predictable and avoids race conditions within the observer's logic.

```swift
someObservable
  .subscribe { (e: Event<Element>) in
      print("Event processing started")
      // processing
      print("Event processing ended")
  }

// Guaranteed output order: // Event processing started // Event processing ended // Event processing started // Event processing ended

In RxSwift, Relay types are specialized versions of Subjects designed for scenarios where you want to ensure the stream never terminates. While standard Subjects can receive .completed or .error events which terminate the sequence, Relays are guaranteed to only emit .next events.

RxRelay provides three types of Relays that mirror the behavior of their corresponding Subjects:

• PublishRelay (mirrors PublishSubject)
• BehaviorRelay (mirrors BehaviorSubject)
• ReplayRelay (mirrors ReplaySubject)

Use a Relay when you need a long-lived stream that should never stop emitting values due to an error or completion event.

An Observable (or observable sequence) defines how a sequence is generated and what parameters are used, but it does not perform any work or cause side effects upon creation.

Sequence generation and side effects (like network requests or mouse events) only begin when the subscribe method is called. This is a fundamental concept: calling a method that returns an Observable is a lazy operation.

func searchWikipedia(searchTerm: String) -> Observable<Results> {}

let searchForMe = searchWikipedia("me") // No work is performed here

let cancel = searchForMe
  .subscribe(onNext: { results in // Sequence generation starts here
      print(results)
  })