Written in Swift 5
RxAlamoRecord combines the power of the AlamoRecord and RxSwift libraries to create a networking layer that makes interacting with API's easier than ever reactively.
Requirements
- iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
- Xcode 10.2+
- Swift 5.1
Installation
RxAlamoRecord is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'RxAlamoRecord'Getting Started
RxAlamoRecord can not be used without first understanding the basic principles of AlamoRecord and RxSwift. It is suggested you have a basic understanding of how both libraries work before proceeding.
Purpose
RxAlamoRecord gives you the power to bind your API reponses directly to AlamoRecordRelay and Action objects. Action is a powerful extension library created by the RxSwiftCommunity
AlamoRecordRelay
This object behaves exactly the same as a BehaviorRelay except that an AlamoRecordRelay can emit an error. It is required to use an instance of an AlamoRecordRelay when binding via RxAlamoRecord or else your app will crash if the API request returns an error or fails.
To help simplify the examples, assume these variables are included in each one:
let posts = AlamoRecordRelay<[Post]>(value: [])
let post = AlamoRecordRelay<Post?>(value: nil)
lazy var failureAction: Action<ApplicationError, Swift.Never> = {
return Action { [weak self] error in
// Do something with the error
return Observable.empty()
}
}()
Getting all instances of Post
GET https://jsonplaceholder.typicode.com/posts
Post.rx
.all()
.execute()
.bind(to: posts, failure: failureAction)
.disposed(by: disposeBag)Creating an instance of Post
POST https://jsonplaceholder.typicode.com/posts
Post.rx
.create()
.withParameters(["userId": userId, "title": title, "body": body])
.execute()
.bind(to: post, failure: failureAction)
.disposed(by: disposeBag)Finding an instance of Post
GET https://jsonplaceholder.typicode.com/posts/1
Post.rx
.find(id: 1)
.execute()
.bind(to: post, failure: failureAction)
.disposed(by: disposeBag)Updating an instance of Post
PUT https://jsonplaceholder.typicode.com/posts/1
post.value?
.rx
.update()
.withParameters(["userId": userId, "title": title, "body": body])
.execute()
.bind(to: post, failure: failureAction)
.disposed(by: disposeBag)This can also be done at the class level:
Post.rx
.update(id: 1)
.withParameters(["userId": userId, "title": title, "body": body])
.execute()
.bind(to: post, failure: failureAction)
.disposed(by: disposeBag)Destroying an instance of Post
DELETE https://jsonplaceholder.typicode.com/posts/1
lazy var destroyedAction: Action<Void, Swift.Never> = {
return Action { [weak self] in
// The post is now destroyed
return Observable.empty()
}
}()
post.value?
.rx
.destroy()
.execute()
.bind(to: destroyedAction, failure: failureAction)
.disposed(by: disposeBag)This can also be done at the class level:
Post.rx
.destroy(id: 1)
.execute()
.bind(to: destroyedAction, failure: failureAction)
.disposed(by: disposeBag)Assigning default value on failure
It is also possible to assign a default value to an AlamoRecordRelay/Action object if an API request fails:
let postTitle = AlamoRecordRelay<String?>(value: nil)
Post.rx
.find(id: 1)
.execute()
.map { $0.title }
.bind(to: postTitle, valueOnFailure: "Default Title")
.disposed(by: disposeBag)lazy var postTitleAction: Action<String, Swift.Never> = {
return Action { [weak self] title in
// Do something with the title
return Observable.empty()
}
}()
Post.rx
.find(id: 1)
.execute()
.map { $0.title }
.bind(to: postTitleAction, valueOnFailure: "Default Title")
.disposed(by: disposeBag)Download the example project to see just how easy creating an application with a reactive networking layer is when using RxAlamoRecord!
Author
Dalton Hinterscher, [email protected]
Credits
Reactive Logo used in header image designed by ReactiveX group
License
RxAlamoRecord is available under the MIT license. See the LICENSE file for more info.