2020-09-22 19:39:29 +03:00
< img src = "https://raw.githubusercontent.com/ReactiveX/RxSwift/main/assets/Rx_Logo_M.png" alt = "Miss Electric Eel 2016" width = "36" height = "36" > RxSwift: ReactiveX for Swift
2015-04-08 01:28:38 +03:00
======================================
2018-12-28 20:05:16 +03:00
[![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)
2016-03-18 00:35:23 +03:00
2015-07-28 00:28:04 +03:00
Rx is a [generic abstraction of computation ](https://youtu.be/looJcaeboBY ) expressed through `Observable<Element>` interface.
This is a Swift version of [Rx ](https://github.com/Reactive-Extensions/Rx.NET ).
2016-10-07 14:00:51 +03:00
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.
2015-07-28 00:28:04 +03:00
Cross platform documentation can be found on [ReactiveX.io ](http://reactivex.io/ ).
2015-05-19 21:32:00 +03:00
Like the original Rx, its intention is to enable easy composition of asynchronous operations and event/data streams.
2015-07-28 00:28:04 +03:00
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.
2015-05-19 21:32:00 +03:00
2016-02-14 17:10:14 +03:00
## I came here because I want to ...
2015-04-10 11:33:25 +03:00
2016-02-14 17:31:03 +03:00
###### ... understand
2016-02-14 17:29:12 +03:00
2016-02-25 01:16:12 +03:00
* [why use rx? ](Documentation/Why.md )
2016-03-12 22:12:59 +03:00
* [the basics, getting started with RxSwift ](Documentation/GettingStarted.md )
2019-01-16 10:17:55 +03:00
* [traits ](Documentation/Traits.md ) - what are `Single` , `Completable` , `Maybe` , `Driver` , and `ControlProperty` ... and why do they exist?
2016-03-12 22:12:59 +03:00
* [testing ](Documentation/UnitTests.md )
* [tips and common errors ](Documentation/Tips.md )
* [debugging ](Documentation/GettingStarted.md#debugging )
2016-02-15 01:26:18 +03:00
* [the math behind Rx ](Documentation/MathBehindRx.md )
2016-02-25 01:16:12 +03:00
* [what are hot and cold observable sequences? ](Documentation/HotAndColdObservables.md )
2016-08-21 19:45:44 +03:00
2016-02-14 17:29:12 +03:00
###### ... install
2015-05-10 01:16:44 +03:00
2016-09-23 16:57:00 +03:00
* Integrate RxSwift/RxCocoa with my app. [Installation Guide ](#installation )
2015-05-10 01:16:44 +03:00
2016-02-14 17:29:12 +03:00
###### ... hack around
2015-05-10 01:16:44 +03:00
2016-05-12 14:42:23 +03:00
* with the example app. [Running Example App ](Documentation/ExampleApp.md )
2016-02-14 17:29:12 +03:00
* with operators in playgrounds. [Playgrounds ](Documentation/Playgrounds.md )
2015-05-10 01:16:44 +03:00
2016-02-14 17:29:12 +03:00
###### ... interact
2015-04-08 01:28:38 +03:00
2019-03-31 22:36:34 +03:00
* All of this is great, but it would be nice to talk with other people using RxSwift and exchange experiences. < br /> [Join Slack Channel](http://slack.rxswift.org)
2016-10-23 20:39:58 +03:00
* Report a problem using the library. [Open an Issue With Bug Template ](.github/ISSUE_TEMPLATE.md )
2016-02-14 17:10:14 +03:00
* Request a new feature. [Open an Issue With Feature Request Template ](Documentation/NewFeatureRequestTemplate.md )
2017-11-29 01:24:41 +03:00
* Help out [Check out contribution guide ](CONTRIBUTING.md )
2015-04-08 01:28:38 +03:00
2016-02-14 17:31:03 +03:00
###### ... compare
2015-07-28 00:28:04 +03:00
2016-02-15 01:26:18 +03:00
* [with other libraries ](Documentation/ComparisonWithOtherLibraries.md ).
2015-05-03 19:02:59 +03:00
2019-04-09 21:25:03 +03:00
###### ... understand the structure
2020-08-16 21:33:36 +03:00
RxSwift comprises five separate components depending on each other in the following way:
2019-04-09 21:25:03 +03:00
```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.
2019-12-27 23:29:18 +03:00
* **RxCocoa**: Provides Cocoa-specific capabilities for general iOS/macOS/watchOS & tvOS app development, such as Shared Sequences, Traits, and much more. It depends on both `RxSwift` and `RxRelay` .
2020-01-09 10:15:50 +03:00
* **RxRelay**: Provides `PublishRelay` , `BehaviorRelay` and `ReplayRelay` , three [simple wrappers around Subjects ](https://github.com/ReactiveX/RxSwift/blob/master/Documentation/Subjects.md#relays ). It depends on `RxSwift` .
2019-04-09 21:25:03 +03:00
* **RxTest** and **RxBlocking** : Provides testing capabilities for Rx-based systems. It depends on `RxSwift` .
2015-09-09 12:44:25 +03:00
2016-02-15 01:26:18 +03:00
###### ... find compatible
2015-09-09 12:44:25 +03:00
2016-02-15 01:26:18 +03:00
* libraries from [RxSwiftCommunity ](https://github.com/RxSwiftCommunity ).
* [Pods using RxSwift ](https://cocoapods.org/?q=uses%3Arxswift ).
2015-09-09 12:44:25 +03:00
2016-02-14 17:31:03 +03:00
###### ... see the broader vision
2015-09-09 12:44:25 +03:00
2016-02-25 01:16:12 +03:00
* Does this exist for Android? [RxJava ](https://github.com/ReactiveX/RxJava )
2016-02-14 17:10:14 +03:00
* 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.
2015-09-09 12:44:25 +03:00
2016-04-20 13:08:42 +03:00
## Usage
2016-04-20 14:39:16 +03:00
2016-04-20 13:48:31 +03:00
< table >
< tr >
< th width = "30%" > Here's an example< / th >
< th width = "30%" > In Action< / th >
< / tr >
< tr >
2016-04-20 14:39:16 +03:00
< td > Define search for GitHub repositories ...< / td >
2016-04-20 13:48:31 +03:00
< th rowspan = "9" > < img src = "https://raw.githubusercontent.com/kzaher/rxswiftcontent/master/GithubSearch.gif" > < / th >
< / tr >
< tr >
< td > < div class = "highlight highlight-source-swift" > < pre >
2016-12-08 17:45:28 +03:00
let searchResults = searchBar.rx.text.orEmpty
2019-04-16 20:28:34 +03:00
.throttle(.milliseconds(300), scheduler: MainScheduler.instance)
2016-04-20 13:08:42 +03:00
.distinctUntilChanged()
2017-03-20 03:18:34 +03:00
.flatMapLatest { query -> Observable< [Repository]> in
2016-12-17 19:12:47 +03:00
if query.isEmpty {
return .just([])
}
2016-04-20 13:08:42 +03:00
return searchGitHub(query)
.catchErrorJustReturn([])
}
2016-04-20 13:48:31 +03:00
.observeOn(MainScheduler.instance)< / pre > < / div > < / td >
< / tr >
< tr >
2016-04-20 14:39:16 +03:00
< td > ... then bind the results to your tableview< / td >
2016-04-20 13:48:31 +03:00
< / tr >
< tr >
< td width = "30%" > < div class = "highlight highlight-source-swift" > < pre >
2016-04-20 13:08:42 +03:00
searchResults
2017-03-20 02:06:38 +03:00
.bind(to: tableView.rx.items(cellIdentifier: "Cell")) {
2016-04-20 13:48:31 +03:00
(index, repository: Repository, cell) in
2016-04-20 13:08:42 +03:00
cell.textLabel?.text = repository.name
cell.detailTextLabel?.text = repository.url
}
2017-01-22 14:37:30 +03:00
.disposed(by: disposeBag)< / pre > < / div > < / td >
2016-04-20 13:48:31 +03:00
< / tr >
< / table >
2016-04-20 13:08:42 +03:00
2016-08-21 19:45:44 +03:00
## Requirements
2020-04-07 07:44:59 +03:00
* Xcode 11.x
* Swift 5.x
2019-04-09 21:25:03 +03:00
2020-04-07 07:44:59 +03:00
For Xcode 10.3.1 and below, [use RxSwift 5.0.1 ](https://github.com/ReactiveX/RxSwift/releases/tag/5.0.1 ).
2016-08-21 19:45:44 +03:00
2016-04-20 13:08:42 +03:00
## Installation
2020-04-07 07:44:59 +03:00
RxSwift doesn't contain any external dependencies.
2016-04-20 13:08:42 +03:00
2020-07-14 05:30:50 +03:00
These are currently the supported installation options:
2016-04-20 13:08:42 +03:00
### Manual
2016-05-12 14:42:23 +03:00
Open Rx.xcworkspace, choose `RxExample` and hit run. This method will build everything and run the sample app
2016-04-20 13:08:42 +03:00
### [CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html)
2017-02-13 11:44:24 +03:00
```ruby
2016-04-20 13:08:42 +03:00
# Podfile
use_frameworks!
target 'YOUR_TARGET_NAME' do
2019-04-09 21:25:03 +03:00
pod 'RxSwift', '~> 5'
pod 'RxCocoa', '~> 5'
2016-04-21 22:31:05 +03:00
end
2018-02-08 12:22:46 +03:00
# RxTest and RxBlocking make the most sense in the context of unit/integration tests
2016-04-21 22:31:05 +03:00
target 'YOUR_TESTING_TARGET' do
2019-04-09 21:25:03 +03:00
pod 'RxBlocking', '~> 5'
pod 'RxTest', '~> 5'
2016-04-20 13:08:42 +03:00
end
```
2016-05-12 14:42:23 +03:00
Replace `YOUR_TARGET_NAME` and then, in the `Podfile` directory, type:
2016-04-20 13:08:42 +03:00
2017-02-13 11:44:24 +03:00
```bash
2016-04-20 13:08:42 +03:00
$ pod install
```
### [Carthage](https://github.com/Carthage/Carthage)
2019-04-19 08:24:21 +03:00
Officially supported: Carthage 0.33 and up.
2016-04-20 13:08:42 +03:00
Add this to `Cartfile`
```
2019-04-09 21:25:03 +03:00
github "ReactiveX/RxSwift" ~> 5.0
2016-04-20 13:08:42 +03:00
```
2017-02-13 11:44:24 +03:00
```bash
2016-04-20 13:08:42 +03:00
$ carthage update
```
2019-04-30 11:04:20 +03:00
#### 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
2019-07-06 17:58:02 +03:00
carthage build RxSwift --platform iOS
2019-04-30 11:04:20 +03:00
```
2016-10-17 03:49:24 +03:00
### [Swift Package Manager](https://github.com/apple/swift-package-manager)
Create a `Package.swift` file.
2017-02-13 11:44:24 +03:00
```swift
2019-04-09 21:25:03 +03:00
// swift-tools-version:5.0
2017-10-18 01:55:45 +03:00
2016-10-17 03:49:24 +03:00
import PackageDescription
let package = Package(
2017-10-18 01:55:45 +03:00
name: "RxTestProject",
dependencies: [
2019-04-09 21:25:03 +03:00
.package(url: "https://github.com/ReactiveX/RxSwift.git", from: "5.0.0")
2017-10-18 01:55:45 +03:00
],
targets: [
.target(name: "RxTestProject", dependencies: ["RxSwift", "RxCocoa"])
]
2016-10-17 03:49:24 +03:00
)
```
2017-02-13 11:44:24 +03:00
```bash
2016-10-27 23:31:44 +03:00
$ swift build
```
2019-04-09 21:25:03 +03:00
To build or test a module with RxTest dependency, set `TEST=1` .
2017-05-02 10:09:28 +03:00
```bash
$ TEST=1 swift test
```
2016-04-20 13:08:42 +03:00
### Manually using git submodules
* Add RxSwift as a submodule
2017-02-13 11:44:24 +03:00
```bash
2016-04-20 13:08:42 +03:00
$ git submodule add git@github.com:ReactiveX/RxSwift.git
```
* Drag `Rx.xcodeproj` into Project Navigator
2020-04-11 16:26:59 +03:00
* Go to `Project > Targets > Build Phases > Link Binary With Libraries` , click `+` and select `RxSwift` , `RxCocoa` and `RxRelay` targets
2016-04-20 13:08:42 +03:00
## References
2015-05-03 19:02:59 +03:00
2015-07-28 00:28:04 +03:00
* [http://reactivex.io/ ](http://reactivex.io/ )
2015-05-03 19:02:59 +03:00
* [Reactive Extensions GitHub (GitHub) ](https://github.com/Reactive-Extensions )
2018-10-31 18:38:18 +03:00
* [RxSwift RayWenderlich.com Book ](https://store.raywenderlich.com/products/rxswift-reactive-programming-with-swift )
2017-06-14 10:07:47 +03:00
* [Boxue.io RxSwift Online Course ](https://boxueio.com/series/rxswift-101 ) (Chinese 🇨🇳)
2015-05-03 19:02:59 +03:00
* [Erik Meijer (Wikipedia) ](http://en.wikipedia.org/wiki/Erik_Meijer_%28computer_scientist%29 )
2015-07-28 00:28:04 +03:00
* [Expert to Expert: Brian Beckman and Erik Meijer - Inside the .NET Reactive Framework (Rx) (video) ](https://youtu.be/looJcaeboBY )
2020-09-10 23:38:22 +03:00
* [Reactive Programming Overview (Jafar Husain from Netflix) ](https://youtu.be/-8Y1-lE6NSA )
2015-05-03 19:02:59 +03:00
* [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/ )
2019-07-06 17:58:02 +03:00
* [Haskell ](https://www.haskell.org/ )