v-silin/reactiveswift

Streams of values over time

Streams of values over time. Tailored for Swift.

☕️ Looking for Cocoa extensions? 🎉 Getting Started ⚠️ Still using Swift 2.x?

🚄 Release Roadmap

What is ReactiveSwift?

ReactiveSwift offers composable, declarative and flexible primitives that are built around the grand concept of streams of values over time.

These primitives can be used to uniformly represent common Cocoa and generic programming patterns that are fundamentally an act of observation, e.g. delegate pattern, callback closures, notifications, control actions, responder chain events, futures/promises and key-value observing (KVO).

Because all of these different mechanisms can be represented in the same way, it’s easy to declaratively compose them together, with less spaghetti code and state to bridge the gap.

Core Reactive Primitives

Signal: a unidirectional stream of events.

The owner of a Signal has unilateral control of the event stream. Observers may register their interests in the future events at any time, but the observation would have no side effect on the stream or its owner.

It is like a live TV feed — you can observe and react to the content, but you cannot have a side effect on the live feed or the TV station.

let channel: Signal<Program, NoError> = tvStation.channelOne
channel.observeValues { program in ... }

Event: the basic transfer unit of an event stream.

A Signal may have any arbitrary number of events carrying a value, following by an eventual terminal event of a specific reason.

It is like a frame in a one-time live feed — seas of data frames carry the visual and audio data, but the feed would eventually be terminated with a special frame to indicate "end of stream".

SignalProducer: deferred work that creates a stream of values.

SignalProducer defers work — of which the output is represented as a stream of values — until it is started. For every invocation to start the SignalProducer, a new Signal is created and the deferred work is subsequently invoked.

It is like a on-demand streaming service — even though the episode is streamed like a live TV feed, you can choose what you watch, when to start watching and when to interrupt it.

let frames: SignalProducer<VideoFrame, ConnectionError> = vidStreamer.streamAsset(id: tvShowId)
let interrupter = frames.start { frame in ... }
interrupter.dispose()

Lifetime: limits the scope of an observation

When observing a Signal or SignalProducer, it doesn't make sense to continue emitting values if there's no longer anyone observing them. Consider the video stream: once you stop watching the video, the stream can be automatically closed by providing a Lifetime:

class VideoPlayer {
  private let (lifetime, token) = Lifetime.make()

  func play() {
    let frames: SignalProducer<VideoFrame, ConnectionError> = ...
    frames.take(during: lifetime).start { frame in ... }
  }
}

Property: an observable box that always holds a value.

Property is a variable that can be observed for its changes. In other words, it is a stream of values with a stronger guarantee than Signal — the latest value is always available, and the stream would never fail.

It is like the continuously updated current time offset of a video playback — the playback is always at a certain time offset at any time, and it would be updated by the playback logic as the playback continues.

let currentTime: Property<TimeInterval> = video.currentTime
print("Current time offset: \(currentTime.value)")
currentTime.signal.observeValues { timeBar.timeLabel.text = "\($0)" }

Action: a serialized worker with a preset action.

When being invoked with an input, Action apply the input and the latest state to the preset action, and pushes the output to any interested parties.

It is like an automatic vending machine — after choosing an option with coins inserted, the machine would process the order and eventually output your wanted snack. Notice that the entire process is mutually exclusive — you cannot have the machine to serve two customers concurrently.

// Purchase from the vending machine with a specific option.
vendingMachine.purchase
    .apply(snackId)
    .startWithResult { result
        switch result {
        case let .success(snack):
            print("Snack: \(snack)")

        case let .failure(error):
            // Out of stock? Insufficient fund?
            print("Transaction aborted: \(error)")
        }
    }

// The vending machine.
class VendingMachine {
    let purchase: Action<Int, Snack, VendingMachineError>
    let coins: MutableProperty<Int>

    // The vending machine is connected with a sales recorder.
    init(_ salesRecorder: SalesRecorder) {
        coins = MutableProperty(0)
        purchase = Action(state: coins, enabledIf: { $0 > 0 }) { coins, snackId in
            return SignalProducer { observer, _ in
                // The sales magic happens here.
                // Fetch a snack based on its id
            }
        }

        // The sales recorders are notified for any successful sales.
        purchase.values.observeValues(salesRecorder.record)
    }
}

References

For more details about the concepts and primitives in ReactiveSwift, check these documentations out:

1. Framework Overview

   An overview of the behaviors and the suggested use cases of the ReactiveSwift primitives and utilities.

2. Basic Operators

   An overview of the operators provided to compose and transform these primitives.

3. Design Guidelines

   Contracts of the ReactiveSwift primitives, Best Practices with ReactiveSwift, and Guidelines on implementing custom operators.

Example: online search

Let’s say you have a text field, and whenever the user types something into it, you want to make a network request which searches for that query.

Please note that the following examples use Cocoa extensions in ReactiveCocoa for illustration.

Observing text edits

The first step is to observe edits to the text field, using a RAC extension to UITextField specifically for this purpose:

let searchStrings = textField.reactive.continuousTextValues

This gives us a Signal which sends values of type String?.

Making network requests

With each string, we want to execute a network request. ReactiveSwift offers an URLSession extension for doing exactly that:

let searchResults = searchStrings
    .flatMap(.latest) { (query: String?) -> SignalProducer<(Data, URLResponse), AnyError> in
        let request = self.makeSearchRequest(escapedQuery: query)
        return URLSession.shared.reactive.data(with: request)
    }
    .map { (data, response) -> [SearchResult] in
        let string = String(data: data, encoding: .utf8)!
        return self.searchResults(fromJSONString: string)
    }
    .observe(on: UIScheduler())

This has transformed our producer of Strings into a producer of Arrays containing the search results, which will be forwarded on the main thread (using the UIScheduler).

Additionally, flatMap(.latest) here ensures that only one search—the latest—is allowed to be running. If the user types another character while the network request is still in flight, it will be cancelled before starting a new one. Just think of how much code that would take to do by hand!

Receiving the results

Since the source of search strings is a Signal which has a hot signal semantic, the transformations we applied are automatically evaluated whenever new values are emitted from searchStrings.

Therefore, we can simply observe the signal using Signal.observe(_:):

searchResults.observe { event in
    switch event {
    case let .value(results):
        print("Search results: \(results)")

    case let .failed(error):
        print("Search error: \(error)")

    case .completed, .interrupted:
        break
    }
}

Here, we watch for the Value event, which contains our results, and just log them to the console. This could easily do something else instead, like update a table view or a label on screen.

Handling failures

In this example so far, any network error will generate a Failed event, which will terminate the event stream. Unfortunately, this means that future queries won’t even be attempted.

To remedy this, we need to decide what to do with failures that occur. The quickest solution would be to log them, then ignore them:

    .flatMap(.latest) { (query: String) -> SignalProducer<(Data, URLResponse), AnyError> in
        let request = self.makeSearchRequest(escapedQuery: query)

        return URLSession.shared.reactive
            .data(with: request)
            .flatMapError { error in
                print("Network error occurred: \(error)")
                return SignalProducer.empty
            }
    }

By replacing failures with the empty event stream, we’re able to effectively ignore them.

However, it’s probably more appropriate to retry at least a couple of times before giving up. Conveniently, there’s a retry operator to do exactly that!

Our improved searchResults producer might look like this:

let searchResults = searchStrings
    .flatMap(.latest) { (query: String) -> SignalProducer<(Data, URLResponse), AnyError> in
        let request = self.makeSearchRequest(escapedQuery: query)

        return URLSession.shared.reactive
            .data(with: request)
            .retry(upTo: 2)
            .flatMapError { error in
                print("Network error occurred: \(error)")
                return SignalProducer.empty
            }
    }
    .map { (data, response) -> [SearchResult] in
        let string = String(data: data, encoding: .utf8)!
        return self.searchResults(fromJSONString: string)
    }
    .observe(on: UIScheduler())

Throttling requests

Now, let’s say you only want to actually perform the search periodically, to minimize traffic.

ReactiveCocoa has a declarative throttle operator that we can apply to our search strings:

let searchStrings = textField.reactive.continuousTextValues
    .throttle(0.5, on: QueueScheduler.main)

This prevents values from being sent less than 0.5 seconds apart.

To do this manually would require significant state, and end up much harder to read! With ReactiveCocoa, we can use just one operator to incorporate time into our event stream.

Debugging event streams

Due to its nature, a stream's stack trace might have dozens of frames, which, more often than not, can make debugging a very frustrating activity. A naive way of debugging, is by injecting side effects into the stream, like so:

let searchString = textField.reactive.continuousTextValues
    .throttle(0.5, on: QueueScheduler.main)
    .on(event: { print ($0) }) // the side effect

This will print the stream's events, while preserving the original stream behaviour. Both SignalProducer and Signal provide the logEvents operator, that will do this automatically for you:

let searchString = textField.reactive.continuousTextValues
    .throttle(0.5, on: QueueScheduler.main)
    .logEvents()

For more information and advance usage, check the Debugging Techniques document.

How does ReactiveSwift relate to RxSwift?

RxSwift is a Swift implementation of the ReactiveX (Rx) APIs. While ReactiveCocoa was inspired and heavily influenced by Rx, ReactiveSwift is an opinionated implementation of functional reactive programming, and intentionally not a direct port like RxSwift.

ReactiveSwift differs from RxSwift/ReactiveX where doing so:

• Results in a simpler API
• Addresses common sources of confusion
• Matches closely to Swift, and sometimes Cocoa, conventions

The following are a few important differences, along with their rationales.

Signals and SignalProducers (“hot” and “cold” observables)

One of the most confusing aspects of Rx is that of “hot”, “cold”, and “warm” observables (event streams).

In short, given just a method or function declaration like this, in C#:

IObservable<string> Search(string query)

… it is impossible to tell whether subscribing to (observing) that IObservable will involve side effects. If it does involve side effects, it’s also impossible to tell whether each subscription has a side effect, or if only the first one does.

This example is contrived, but it demonstrates a real, pervasive problem that makes it extremely hard to understand Rx code (and pre-3.0 ReactiveCocoa code) at a glance.

ReactiveSwift addresses this by distinguishing side effects with the separate Signal and SignalProducer types. Although this means there’s another type to learn about, it improves code clarity and helps communicate intent much better.

In other words, ReactiveSwift’s changes here are simple, not easy.

Typed errors

When Signals and SignalProducers are allowed to fail in ReactiveSwift, the kind of error must be specified in the type system. For example, Signal<Int, AnyError> is a signal of integer values that may fail with an error of type AnyError.

More importantly, RAC allows the special type NoError to be used instead, which statically guarantees that an event stream is not allowed to send a failure. This eliminates many bugs caused by unexpected failure events.

In Rx systems with types, event streams only specify the type of their values—not the type of their errors—so this sort of guarantee is impossible.

Naming

In most versions of Rx, Streams over time are known as Observables, which parallels the Enumerable type in .NET. Additionally, most operations in Rx.NET borrow names from LINQ, which uses terms reminiscent of relational databases, like Select and Where.

ReactiveSwift, on the other hand, focuses on being a native Swift citizen first and foremost, following the Swift API Guidelines as appropriate. Other naming differences are typically inspired by significantly better alternatives from Haskell or Elm (which is the primary source for the “signal” terminology).

UI programming

Rx is basically agnostic as to how it’s used. Although UI programming with Rx is very common, it has few features tailored to that particular case.

ReactiveSwift takes a lot of inspiration from ReactiveUI, including the basis for Actions.

Unlike ReactiveUI, which unfortunately cannot directly change Rx to make it more friendly for UI programming, ReactiveSwift has been improved many times specifically for this purpose—even when it means diverging further from Rx.

Getting started

ReactiveSwift supports macOS 10.9+, iOS 8.0+, watchOS 2.0+, tvOS 9.0+ and Linux.

Carthage

If you use Carthage to manage your dependencies, simply add ReactiveSwift to your Cartfile:

github "ReactiveCocoa/ReactiveSwift" ~> 1.1

If you use Carthage to build your dependencies, make sure you have added ReactiveSwift.framework, and Result.framework to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase.

CocoaPods

If you use CocoaPods to manage your dependencies, simply add ReactiveSwift to your Podfile:

pod 'ReactiveSwift', '~> 1.1'

Swift Package Manager

If you use Swift Package Manager, simply add ReactiveSwift as a dependency of your package in Package.swift:

.Package(url: "https://github.com/ReactiveCocoa/ReactiveSwift.git", majorVersion: 1)

Git submodule

1. Add the ReactiveSwift repository as a submodule of your application’s repository.
2. Run git submodule update --init --recursive from within the ReactiveCocoa folder.
3. Drag and drop ReactiveSwift.xcodeproj and Carthage/Checkouts/Result/Result.xcodeproj into your application’s Xcode project or workspace.
4. On the “General” tab of your application target’s settings, add ReactiveSwift.framework, and Result.framework to the “Embedded Binaries” section.
5. If your application target does not contain Swift code at all, you should also set the EMBEDDED_CONTENT_CONTAINS_SWIFT build setting to “Yes”.

Playground

We also provide a great Playground, so you can get used to ReactiveCocoa's operators. In order to start using it:

1. Clone the ReactiveSwift repository.
2. Retrieve the project dependencies using one of the following terminal commands from the ReactiveSwift project root directory:
   • git submodule update --init --recursive OR, if you have Carthage installed
   • carthage checkout
3. Open ReactiveSwift.xcworkspace
4. Build Result-Mac scheme
5. Build ReactiveSwift-macOS scheme
6. Finally open the ReactiveSwift.playground
7. Choose View > Show Debug Area

Have a question?

If you need any help, please visit our GitHub issues or Stack Overflow. Feel free to file an issue if you do not manage to find any solution from the archives.

Release Roadmap

Current Stable Release:

Plan of Record

ReactiveSwift 2.0

It targets Swift 3.1.x. The estimated schedule is Spring 2017.

The release contains breaking changes. But they are not expected to affect the general mass of users, but only a few specific use cases.

The primary goal of ReactiveSwift 2.0 is to adopt concrete same-type requirements, and remove as many single-implementation protocols as possible.

ReactiveSwift 2.0 may include other proposed breaking changes.

As Swift 4.0 introduces library evolution and resilience, it is important for us to have a clean and steady API to start with. The expectation is to have the API cleanup and the reviewing to be concluded in ReactiveSwift 2.0, before we move on to ReactiveSwift 3.0 and Swift 4.0. Any contribution to help realising this goal is welcomed.

ReactiveSwift 3.0

It targets Swift 4.0.x. The estimated schedule is late 2017.

The release may contain breaking changes, depending on what features are being delivered by Swift 4.0.

ReactiveSwift 3.0 would focus on two main goals:

1. Swift 4.0 Library Evolution and Resilience
2. Adapt to new features introduced in Swift 4.0 Phase 2.