React to Changes - Swift SDK

Register a Realm Change Listener

You can register a notification handler on an entire realm. Realm Database calls the notification handler whenever any write transaction involving that Realm is committed. The handler receives no information about the change.

Register a Collection Change Listener

You can register a notification handler on a collection within a realm.

Realm Database notifies your handler:

• After first retrieving the collection.

• Whenever a write transaction adds, changes, or removes objects in the collection.

Notifications describe the changes since the prior notification with three lists of indices: the indices of the objects that were deleted, inserted, and modified.

Collection notifications provide a change parameter that reports which objects are deleted, added, or modified during the write transaction. This RealmCollectionChange resolves to an array of index paths that you can pass to a UITableView's batch update methods.

Register an Object Change Listener

You can register a notification handler on a specific object within a Realm. Realm Database notifies your handler:

• When the object is deleted.

• When any of the object's properties change.

The handler receives information about what fields changed and whether the object was deleted.

Register a Key Path Change Listener

In addition to registering a notification handler on an object or collection, you can pass an optional string keyPaths parameter to specify the key path or key paths to watch.

// Define the dog class.
class Dog: Object {
    @Persisted var name = ""
    @Persisted var favoriteToy = ""
    @Persisted var age: Int?
}
var objectNotificationToken: NotificationToken?
func objectNotificationExample() {
    let dog = Dog()
    dog.name = "Max"
    dog.favoriteToy = "Ball"
    dog.age = 2
    // Open the default realm.
    let realm = try! Realm()
    try! realm.write {
        realm.add(dog)
    }
    // Observe notifications on some of the object's key paths. Keep a strong
    // reference to the notification token or the observation will stop.
    // Invalidate the token when done observing.
    objectNotificationToken = dog.observe(keyPaths: ["favoriteToy", "age"], { change in
        switch change {
        case .change(let object, let properties):
            for property in properties {
                print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'")
            }
        case .error(let error):
            print("An error occurred: \(error)")
        case .deleted:
            print("The object was deleted.")
        }
    })
    // Now update to trigger the notification
    try! realm.write {
        dog.favoriteToy = "Frisbee"
    }
    // When you specify one or more key paths, changes to other properties
    // do not trigger notifications. In this example, changing the "name"
    // property does not trigger a notification.
    try! realm.write {
        dog.name = "Maxamillion"
    }
}

You can observe a partially type-erased PartialKeyPath on Objects or RealmCollections.

objectNotificationToken = dog.observe(keyPaths: [\Dog.favoriteToy, \Dog.age], { change in

When you specify keyPaths, only changes to those keyPaths trigger notification blocks. Any other changes do not trigger notification blocks.

class Dog: Object {
    @Persisted var name = ""
    @Persisted var siblings: List<Dog>
    @Persisted var age: Int?
}

Write Silently

You can write to a realm without sending a notification to a specific observer by passing the observer's notification token in an array to realm.write(withoutNotifying:_:):

Stop Watching for Changes

Observation stops when the token returned by an observe call becomes invalid. You can explicitly invalidate a token by calling its invalidate() method.

Key-value Observation

React to Changes to a Class Projection

Like other realm objects, you can react to changes to a class projection. When you register a class projection change listener, you see notifications for changes made through the class projection object directly. You also see notifications for changes to the underlying object's properties that project through the class projection object.

Properties on the underlying object that are not @Projected in the class projection do not generate notifications.

This notification block fires for changes in:

• Person.firstName property of the class projection's underlying Person object, but not changes to Person.lastName or Person.friends.

• PersonProjection.firstName property, but not another class projection that uses the same underlying object's property.

let realm = try! Realm()
let projectedPerson = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })!
let token = projectedPerson.observe(keyPaths: ["firstName"], { change in
    switch change {
    case .change(let object, let properties):
        for property in properties {
            print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'")
        }
    case .error(let error):
        print("An error occurred: \(error)")
    case .deleted:
        print("The object was deleted.")
    }
})
// Now update to trigger the notification
try! realm.write {
    projectedPerson.firstName = "David"
}

Notification Delivery

If you don't need strict guarantees around when notifications are delivered, subscribe to a dispatch queue instead of the main thread. If your notification logic does need strict guarantees, use care in how you write things in your notification handlers. Otherwise, you may trigger this error:

Cannot register notification blocks from within write transactions.

This issue occurs when you try to perform updates as a result of a notification, but the notification occurs while a write transaction is in progress.

The observe function takes a dispatch queue. If that's set, Realm delivers notifications there instead of to the current thread. Realm's notification system promises that notifications for writes on different threads are always delivered synchronously as part of the refresh process. As long as you aren't performing writes on the current thread, you can rely on the guarantee that your app cannot see the value you read from an object change without receiving a notification about the change in between the reads.