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.

Dalton Hinterscher

Last update: Aug 7, 2020

Related tags

Reactive Programming api activerecord ios json networking rxswift alamofire reactive-programming

Overview

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)