• Stars
    star
    1,153
  • Rank 40,446 (Top 0.8 %)
  • Language
    Swift
  • License
    MIT License
  • Created over 8 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

RxSwift extension for RealmSwift's types

RxRealm

Carthage Compatible Version Swift Package Manager compatible License Platform

This library is a thin wrapper around RealmSwift ( Realm Docs ).

Table of contents:

  1. Observing object collections
  2. Observing a single object
  3. Write transactions
  4. Automatically binding table and collection views
  5. Example app

Observing object collections

RxRealm can be used to create Observables from objects of type Results, List, LinkingObjects or AnyRealmCollection. These types are typically used to load and observe object collections from the Realm Mobile Database.

Observable.collection(from:synchronousStart:)

Emits an event each time the collection changes:

let realm = try! Realm()
let laps = realm.objects(Lap.self)

Observable.collection(from: laps)
  .map { 
    laps in "\(laps.count) laps"
  }
  .subscribe(onNext: { text  in
    print(text)
  })

The above prints out "X laps" each time a lap is added or removed from the database. If you set synchronousStart to true (the default value), the first element will be emitted synchronously - e.g. when you're binding UI it might not be possible for an asynchronous notification to come through.

Observable.array(from:synchronousStart:)

Upon each change fetches a snapshot of the Realm collection and converts it to an array value (for example if you want to use array methods on the collection):

let realm = try! Realm()
let laps = realm.objects(Lap.self)

Observable.array(from: laps)
  .map { array in
    return array.prefix(3) //slice of first 3 items
  }
  .subscribe(onNext: { text  in
    print(text)
  })
Observable.changeset(from:synchronousStart:)

Emits every time the collection changes and provides the exact indexes that has been deleted, inserted or updated:

let realm = try! Realm()
let laps = realm.objects(Lap.self)

Observable.changeset(from: laps)
  .subscribe(onNext: { results, changes in
    if let changes = changes {
      // it's an update
      print(results)
      print("deleted: \(changes.deleted)")
      print("inserted: \(changes.inserted)")
      print("updated: \(changes.updated)")
    } else {
      // it's the initial data
      print(results)
    }
  })
Observable.arrayWithChangeset(from:synchronousStart:)

Combines the result of Observable.array(from:) and Observable.changeset(from:) returning an Observable<Array<T>, RealmChangeset?>

let realm = try! Realm()
let laps = realm.objects(Lap.self))

Observable.arrayWithChangeset(from: laps)
  .subscribe(onNext: { array, changes in
    if let changes = changes {
    // it's an update
    print(array.first)
    print("deleted: \(changes.deleted)")
    print("inserted: \(changes.inserted)")
    print("updated: \(changes.updated)")
  } else {
    // it's the initial data
    print(array)
  }
  })

Observing a single object

There's a separate API to make it easier to observe a single object:

Observable.from(object: ticker)
    .map { ticker -> String in
        return "\(ticker.ticks) ticks"
    }
    .bindTo(footer.rx.text)

This API uses the Realm object notifications under the hood to listen for changes.

This method will by default emit the object initial state as its first next event. You can disable this behavior by using the emitInitialValue parameter and setting it to false.

Finally you can set changes to which properties constitute an object change you'd like to observe for:

Observable.from(object: ticker, properties: ["name", "id", "family"]) ...

Write transactions

rx.add()

Writing objects to existing realm reference. You can add newly created objects to a Realm that you already have initialized:

let realm = try! Realm()
let messages = [Message("hello"), Message("world")]

Observable.from(messages)
  .subscribe(realm.rx.add())

Be careful, this will retain your Realm until the Observable completes or errors out.

Realm.rx.add()

Writing to the default Realm. You can leave it to RxRealm to grab the default Realm on any thread your subscribe and write objects to it:

let messages = [Message("hello"), Message("world")]

Observable.from(messages)
  .subscribe(Realm.rx.add())
Realm.rx.add(configuration:)

Writing to a custom Realm. If you want to switch threads and not use the default Realm, provide a Realm.Configuration. You an also provide an error handler for the observer to be called if either creating the realm reference or the write transaction raise an error:

var config = Realm.Configuration()
/* custom configuration settings */

let messages = [Message("hello"), Message("world")]
Observable.from(messages)
  .observeOn( /* you can switch threads here */ )     
  .subscribe(Realm.rx.add(configuration: config, onError: {elements, error in
    if let elements = elements {
      print("Error \(error.localizedDescription) while saving objects \(String(describing: elements))")
    } else {
      print("Error \(error.localizedDescription) while opening realm.")
    }
  }))

If you want to create a Realm on a different thread manually, allowing you to handle errors, you can do that too:

let messages = [Message("hello"), Message("world")]

Observable.from(messages)
  .observeOn( /* you can switch threads here */ )
  .subscribe(onNext: {messages in
    let realm = try! Realm()
    try! realm.write {
      realm.add(messages)
    }
  })
rx.delete()

Deleting object(s) from an existing realm reference:

let realm = try! Realm()
let messages = realm.objects(Message.self)
Observable.from(messages)
  .subscribe(realm.rx.delete())

Be careful, this will retain your realm until the Observable completes or errors out.

Realm.rx.delete()

Deleting from the object's realm automatically. You can leave it to RxRealm to grab the Realm from the first object and use it:

Observable.from(someCollectionOfPersistedObjects)
  .subscribe(Realm.rx.delete())

Automatically binding table and collection views

RxRealm does not depend on UIKit/Cocoa and it doesn't provide built-in way to bind Realm collections to UI components.

a) Non-animated binding

You can use the built-in RxCocoa bindTo(_:) method, which will automatically drive your table view from your Realm results:

Observable.from( [Realm collection] )
  .bindTo(tableView.rx.items) {tv, ip, element in
    let cell = tv.dequeueReusableCell(withIdentifier: "Cell")!
    cell.textLabel?.text = element.text
    return cell
  }
  .addDisposableTo(bag)

b) Animated binding with RxRealmDataSources

The separate library RxRealmDataSources mimics the default data sources library behavior for RxSwift.

RxRealmDataSources allows you to bind an observable collection of Realm objects directly to a table or collection view:

// create data source
let dataSource = RxTableViewRealmDataSource<Lap>(
  cellIdentifier: "Cell", cellType: PersonCell.self) {cell, ip, lap in
    cell.customLabel.text = "\(ip.row). \(lap.text)"
}

// RxRealm to get Observable<Results>
let realm = try! Realm()
let lapsList = realm.objects(Timer.self).first!.laps
let laps = Observable.changeset(from: lapsList)

// bind to table view
laps
  .bindTo(tableView.rx.realmChanges(dataSource))
  .addDisposableTo(bag)

The data source will reflect all changes via animations to the table view:

RxRealm animated changes

If you want to learn more about the features beyond animating changes, check the RxRealmDataSources README.

Example app

To run the example project, clone the repo, and run pod install from the Example directory first. The app uses RxSwift, RxCocoa using RealmSwift, RxRealm to observe Results from Realm.

Further you're welcome to peak into the RxRealmTests folder of the example app, which features the library's unit tests.

Installation

This library depends on both RxSwift and RealmSwift 1.0+.

CocoaPods

RxRealm requires CocoaPods 1.1.x or higher.

RxRealm is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "RxRealm"

Carthage

To integrate RxRealm into your Xcode project using Carthage, specify it in your Cartfile:

github "RxSwiftCommunity/RxRealm"

Run carthage update to build the framework and drag the built RxRealm.framework into your Xcode project.

Swift Package Manager

In your Package.swift:

let package = Package(
  name: "Example",
  dependencies: [
    .package(url: "https://github.com/RxSwiftCommunity/RxRealm.git", from: "1.0.1")
  ],
  targets: [
    .target(name: "Example", dependencies: ["RxRealm"])
  ]
)

TODO

  • Test add platforms and add compatibility for the pod

License

This library belongs to RxSwiftCommunity. Maintainer is Marin Todorov.

RxRealm is available under the MIT license. See the LICENSE file for more info.

More Repositories

1

RxDataSources

UITableView and UICollectionView Data Sources for RxSwift (sections, animated updates, editing ...)
Swift
3,054
star
2

RxFlow

RxFlow is a navigation framework for iOS applications based on a Reactive Flow Coordinator pattern
Swift
1,872
star
3

RxAlamofire

RxSwift wrapper around the elegant HTTP networking in Swift Alamofire
Swift
1,612
star
4

RxKeyboard

Reactive Keyboard in iOS
Swift
1,533
star
5

RxGesture

RxSwift reactive wrapper for view gestures
Swift
1,369
star
6

RxSwiftExt

A collection of Rx operators & tools not found in the core RxSwift distribution
Swift
1,317
star
7

Action

Abstracts actions to be performed in RxSwift.
Swift
875
star
8

RxOptional

RxSwift extensions for Swift optionals and "Occupiable" types
Swift
701
star
9

RxAnimated

Animated RxCocoa bindings
Swift
686
star
10

NSObject-Rx

Handy RxSwift extensions on NSObject, including rx.disposeBag.
Swift
640
star
11

RxMarbles

RxMarbles iOS app
Swift
482
star
12

RxViewModel

ReactiveViewModel-esque using RxSwift
Swift
401
star
13

RxTheme

Theme management based on Rx
Swift
381
star
14

RxReachability

RxSwift bindings for Reachability
Swift
283
star
15

RxNimble

Nimble extensions making unit testing with RxSwift easier 🎉
Swift
265
star
16

RxWebKit

RxWebKit is a RxSwift wrapper for WebKit
Swift
248
star
17

RxFirebase

RxSwift extensions for Firebase
Swift
224
star
18

RxKingfisher

Reactive extension for the Kingfisher image downloading and caching library
Swift
223
star
19

RxGRDB

Reactive extensions for SQLite
Swift
218
star
20

RxSwiftUtilities

Helpful classes and extensions for RxSwift
Swift
189
star
21

RxCoreLocation

RxCoreLocation is a reactive abstraction to manage Core Location.
Swift
181
star
22

RxMediaPicker

A reactive wrapper built around UIImagePickerController.
Swift
179
star
23

RxCoreData

RxSwift extensions for Core Data
C
164
star
24

RxRealmDataSources

An easy way to bind an RxRealm observable to a table or collection view
Swift
161
star
25

RxState

Redux implementation in Swift using RxSwift
Swift
153
star
26

RxStarscream

A lightweight extension to subscribe Starscream websocket events with RxSwift
Swift
152
star
27

RxVisualDebugger

WIP! Very quick and very dirty test for a visual Rx debugger
JavaScript
142
star
28

RxLocalizer

RxLocalizer allows you to localize your apps, using RxSwift 🚀
Swift
134
star
29

RxBiBinding

Reactive two-way binding
Swift
126
star
30

RxReduce

RxReduce is a lightweight framework that ease the implementation of a state container pattern in a Reactive Programming compliant way.
Swift
125
star
31

RxMKMapView

RxMKMapView is a RxSwift wrapper for MKMapView `delegate`.
Swift
121
star
32

RxASDataSources

RxDataSource for AsyncDisplayKit/Texture
Swift
119
star
33

RxCocoa-Texture

RxCocoa Extension Library for Texture.
Swift
100
star
34

RxGoogleMaps

RxSwift reactive wrapper for GoogleMaps SDK
Swift
95
star
35

RxSegue

Swift
80
star
36

FirebaseRxSwiftExtensions

Extension Methods for Firebase and RxSwift
Swift
77
star
37

RxMultipeer

A testable RxSwift wrapper around MultipeerConnectivity
Swift
69
star
38

RxIGListKit

RxSwift wrapper for IGListKit
Swift
62
star
39

RxBinding

Simple data binding operators ~> and <~> for RxSwift.
Swift
62
star
40

RxPager

Pager for RxSwift
Swift
60
star
41

RxCoreMotion

Provides an easy and straight-forward way to use Apple iOS CoreMotion responses as Rx Observables.
Swift
60
star
42

RxFileMonitor

RxSwift wrapper around CoreFoundation file events (FSEvent*)
Swift
60
star
43

RxFirebase-Deprecated

Implement RxSwift with the new Firebase
Swift
54
star
44

RxAlert

Swift
50
star
45

RxSnippets

Several snippets for work with RxSwift
50
star
46

RxCookbook

Community driven RxSwift cookbook 🍴📚
50
star
47

rxswiftcommunity.github.io

For projects that support RxSwift
Ruby
50
star
48

RxController

A library for developing iOS app with MVVM-C based on RxFlow and RxSwift.
Swift
42
star
49

RxHttpClient

Simple Http client (Use RxSwift for stream data)
Swift
39
star
50

RxEventHub

`RxEventHub` makes multicasting event easy, type-safe and error-free, use it instead of `NSNotificationCenter` now!
Swift
36
star
51

RxModal

Subscribe to your modal flows
Swift
28
star
52

RxBatteryManager

A Reactive BatteryManager in Swift for iOS
Swift
24
star
53

RxAlertViewable

A simple alert library with RxSwift MVVM supported.
Swift
20
star
54

contributors

Guidelines for contributing to the RxSwiftCommunity, and a good place to raise questions.
20
star
55

guides.rxswift.org

Content of the website guides.rxswift.org
HTML
19
star
56

RxAVFoundation

RxAVFoundation (based on RxSwift)
Swift
17
star
57

RxTask

An RxSwift implementation of a command line runner.
Swift
15
star
58

RxContacts

RxContacts is a RxSwift wrapper around the Contacts Framework.
Swift
13
star
59

RxTestExt

A collection of operators & tools not found in the core RxTest distribution
Swift
13
star
60

RxVision

RxVision (based on RxSwift)
Swift
13
star
61

RxCoreNFC

RxCoreNFC (based on RxSwift)
Swift
11
star
62

RxCloudKit

RxCloudKit (based on RxSwift)
Swift
9
star
63

RxARKit

RxARKit (based on RxSwift)
Swift
9
star
64

RxTapAction

Reactive extensions for adding tap action gesture to UIView or UICollectionView.
Swift
9
star
65

RxSceneKit

RxSceneKit (based on RxSwift)
Swift
5
star
66

SimplestDemostrationOfUsingOperator

Simplest way to show how `using` operator works.
Swift
5
star
67

Docs

RxSwift Official Docs - Generated by Jazzy
HTML
5
star
68

RxSocket.io

Rx wrapper over socket.io library with Generic functions
Swift
5
star
69

RxSpriteKit

RxSpriteKit (based on RxSwift)
Swift
4
star
70

RxOnDemandResources

RxOnDemandResources (based on RxSwift)
Swift
4
star
71

FakeRepo

This is a temporary fake repo, please ignore it :)
Swift
2
star
72

peril

Settings for the RxSwiftCommunity organization's Peril server
TypeScript
2
star