Miss Electric Eel 2016 RxSwift: ReactiveX for Swift ====================================== [![Travis CI](https://travis-ci.org/ReactiveX/RxSwift.svg?branch=master)](https://travis-ci.org/ReactiveX/RxSwift) ![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20macOS%20%7C%20tvOS%20%7C%20watchOS%20%7C%20Linux-333333.svg) [![pod](https://img.shields.io/cocoapods/v/RxSwift.svg)](https://cocoapods.org/pods/RxSwift) [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) [![Swift Package Manager compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager) Rx is a [generic abstraction of computation](https://youtu.be/looJcaeboBY) expressed through `Observable` interface. This is a Swift version of [Rx](https://github.com/Reactive-Extensions/Rx.NET). It tries to port as many concepts from the original version as possible, but some concepts were adapted for more pleasant and performant integration with iOS/macOS environment. Cross platform documentation can be found on [ReactiveX.io](http://reactivex.io/). Like the original Rx, its intention is to enable easy composition of asynchronous operations and event/data streams. KVO observing, async operations and streams are all unified under [abstraction of sequence](Documentation/GettingStarted.md#observables-aka-sequences). This is the reason why Rx is so simple, elegant and powerful. ## I came here because I want to ... ###### ... understand * [why use rx?](Documentation/Why.md) * [the basics, getting started with RxSwift](Documentation/GettingStarted.md) * [traits](Documentation/Traits.md) - what are `Single`, `Completable`, `Maybe`, `Driver`, and `ControlProperty` ... and why do they exist? * [testing](Documentation/UnitTests.md) * [tips and common errors](Documentation/Tips.md) * [debugging](Documentation/GettingStarted.md#debugging) * [the math behind Rx](Documentation/MathBehindRx.md) * [what are hot and cold observable sequences?](Documentation/HotAndColdObservables.md) ###### ... install * Integrate RxSwift/RxCocoa with my app. [Installation Guide](#installation) ###### ... hack around * with the example app. [Running Example App](Documentation/ExampleApp.md) * with operators in playgrounds. [Playgrounds](Documentation/Playgrounds.md) ###### ... interact * All of this is great, but it would be nice to talk with other people using RxSwift and exchange experiences.
[Join Slack Channel](http://slack.rxswift.org) * Report a problem using the library. [Open an Issue With Bug Template](.github/ISSUE_TEMPLATE.md) * Request a new feature. [Open an Issue With Feature Request Template](Documentation/NewFeatureRequestTemplate.md) * Help out [Check out contribution guide](CONTRIBUTING.md) ###### ... compare * [with other libraries](Documentation/ComparisonWithOtherLibraries.md). ###### ... understand the structure RxSwift comprises five separate components depending on eachother in the following way: ```none ┌──────────────┐ ┌──────────────┐ │ RxCocoa ├────▶ RxRelay │ └───────┬──────┘ └──────┬───────┘ │ │ ┌───────▼──────────────────▼───────┐ │ RxSwift │ └───────▲──────────────────▲───────┘ │ │ ┌───────┴──────┐ ┌──────┴───────┐ │ RxTest │ │ RxBlocking │ └──────────────┘ └──────────────┘ ``` * **RxSwift**: The core of RxSwift, providing the Rx standard as (mostly) defined by [ReactiveX](https://reactivex.io). It has no other dependencies. * **RxCocoa**: Provides Cocoa-specific capabilities for general iOS/macOS/watchOS & tvOS app development, such as Binders, Traits, and much more. It depends on both `RxSwift` and `RxRelay`. * **RxRelay**: Provides `PublishRelay` and `BehaviorRelay`, two [simple wrappers around Subjects](https://github.com/ReactiveX/RxSwift/blob/master/Documentation/Subjects.md#relays). It depends on `RxSwift`. * **RxTest** and **RxBlocking**: Provides testing capabilities for Rx-based systems. It depends on `RxSwift`. ###### ... find compatible * libraries from [RxSwiftCommunity](https://github.com/RxSwiftCommunity). * [Pods using RxSwift](https://cocoapods.org/?q=uses%3Arxswift). ###### ... see the broader vision * Does this exist for Android? [RxJava](https://github.com/ReactiveX/RxJava) * Where is all of this going, what is the future, what about reactive architectures, how do you design entire apps this way? [Cycle.js](https://github.com/cyclejs/cycle-core) - this is javascript, but [RxJS](https://github.com/Reactive-Extensions/RxJS) is javascript version of Rx. ## Usage
Here's an example In Action
Define search for GitHub repositories ...
let searchResults = searchBar.rx.text.orEmpty
    .throttle(.milliseconds(300), scheduler: MainScheduler.instance)
    .distinctUntilChanged()
    .flatMapLatest { query -> Observable<[Repository]> in
        if query.isEmpty {
            return .just([])
        }
        return searchGitHub(query)
            .catchErrorJustReturn([])
    }
    .observeOn(MainScheduler.instance)
... then bind the results to your tableview
searchResults
    .bind(to: tableView.rx.items(cellIdentifier: "Cell")) {
        (index, repository: Repository, cell) in
        cell.textLabel?.text = repository.name
        cell.detailTextLabel?.text = repository.url
    }
    .disposed(by: disposeBag)
## Requirements * Xcode 10.2 * Swift 5.0 For Xcode 10.1 and below, [use RxSwift 4.5](https://github.com/ReactiveX/RxSwift/releases/tag/4.5.0). ## Installation Rx doesn't contain any external dependencies. These are currently the supported options: ### Manual Open Rx.xcworkspace, choose `RxExample` and hit run. This method will build everything and run the sample app ### [CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) ```ruby # Podfile use_frameworks! target 'YOUR_TARGET_NAME' do pod 'RxSwift', '~> 5' pod 'RxCocoa', '~> 5' end # RxTest and RxBlocking make the most sense in the context of unit/integration tests target 'YOUR_TESTING_TARGET' do pod 'RxBlocking', '~> 5' pod 'RxTest', '~> 5' end ``` Replace `YOUR_TARGET_NAME` and then, in the `Podfile` directory, type: ```bash $ pod install ``` ### [Carthage](https://github.com/Carthage/Carthage) Officially supported: Carthage 0.33 and up. Add this to `Cartfile` ``` github "ReactiveX/RxSwift" ~> 5.0 ``` ```bash $ carthage update ``` #### Carthage as a Static Library Carthage defaults to building RxSwift as a Dynamic Library. If you wish to build RxSwift as a Static Library using Carthage you may use the script below to manually modify the framework type before building with Carthage: ```bash carthage update RxSwift --platform iOS --no-build sed -i -e 's/MACH_O_TYPE = mh_dylib/MACH_O_TYPE = staticlib/g' Carthage/Checkouts/RxSwift/Rx.xcodeproj/project.pbxproj carthage build RxSwift --platform iOS ``` ### [Swift Package Manager](https://github.com/apple/swift-package-manager) Create a `Package.swift` file. ```swift // swift-tools-version:5.0 import PackageDescription let package = Package( name: "RxTestProject", dependencies: [ .package(url: "https://github.com/ReactiveX/RxSwift.git", from: "5.0.0") ], targets: [ .target(name: "RxTestProject", dependencies: ["RxSwift", "RxCocoa"]) ] ) ``` ```bash $ swift build ``` To build or test a module with RxTest dependency, set `TEST=1`. ```bash $ TEST=1 swift test ``` ### Manually using git submodules * Add RxSwift as a submodule ```bash $ git submodule add git@github.com:ReactiveX/RxSwift.git ``` * Drag `Rx.xcodeproj` into Project Navigator * Go to `Project > Targets > Build Phases > Link Binary With Libraries`, click `+` and select `RxSwift-[Platform]` and `RxCocoa-[Platform]` targets ## References * [http://reactivex.io/](http://reactivex.io/) * [Reactive Extensions GitHub (GitHub)](https://github.com/Reactive-Extensions) * [RxSwift RayWenderlich.com Book](https://store.raywenderlich.com/products/rxswift-reactive-programming-with-swift) * [Boxue.io RxSwift Online Course](https://boxueio.com/series/rxswift-101) (Chinese 🇨🇳) * [Erik Meijer (Wikipedia)](http://en.wikipedia.org/wiki/Erik_Meijer_%28computer_scientist%29) * [Expert to Expert: Brian Beckman and Erik Meijer - Inside the .NET Reactive Framework (Rx) (video)](https://youtu.be/looJcaeboBY) * [Reactive Programming Overview (Jafar Husain from Netflix)](https://www.youtube.com/watch?v=dwP1TNXE6fc) * [Subject/Observer is Dual to Iterator (paper)](http://csl.stanford.edu/~christos/pldi2010.fit/meijer.duality.pdf) * [Rx standard sequence operators visualized (visualization tool)](http://rxmarbles.com/) * [Haskell](https://www.haskell.org/)