ProjectionObservable

The Projection’s underlying type - a child of Realm Object or EmbeddedObject.

The object being projected

Registers a block to be called each time the projection’s underlying object changes.

The block will be asynchronously called after each write transaction which deletes the underlying object or modifies any of the projected properties of the object, including self-assignments that set a property to its existing value.

For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

If no key paths are given, the block will be executed on any insertion, modification, or deletion for all projected properties, including projected properties of any nested, linked objects. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, if:

class Person: Object {
    @Persisted var firstName: String
    @Persisted var lastName = ""
    @Persisted public var friends: List<Person>
}

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var name
    @Projected(\Person.lastName.localizedUppercase) var lastNameCaps
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String>
}

let token = projectedPerson.observe(keyPaths: ["name"], { changes in
   // ...
})

• The above notification block fires for changes to the Person.firstName property of the the projection’s underlying Person Object, but not for any changes made to Person.lastName or Person.friends list.
• The notification block fires for changes of PersonProjection.name property, but not for another projection’s property change.

• If the observed key path were ["firstFriendsName"], then any insertion, deletion, or modification of the firstName of the friends list will trigger the block. A change to someFriend.lastName would not trigger the block (where someFriend is an element contained in friends)

If no queue is given, notifications are delivered via the standard run loop, and so can’t be delivered while the run loop is blocked by other activity. If a queue is given, notifications are delivered to that queue instead. When notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.

Unlike with List and Results, there is no “initial” callback made after you add a new notification block.

You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

It is safe to capture a strong reference to the observed object within the callback block. There is no retain cycle due to that the callback is retained by the returned token and not by the object itself.

   let token = projectedPerson.observe { changes in
       if case .change(_, let propertyChanges) = changes {
           propertyChanges[0].newValue as? String, "Winterfell" // Will notify the new value
           propertyChanges[1].newValue as? String, "555-555-555" // Will notify with the current value, which hasn't change.
       }
   })

   try realm.write {
       person.address.country = "Winterfell"
   }
   ```

Registers a block to be called each time the projection’s underlying object changes.

The block will be asynchronously called after each write transaction which deletes the underlying object or modifies any of the projected properties of the object, including self-assignments that set a property to its existing value.

For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

If no key paths are given, the block will be executed on any insertion, modification, or deletion for all projected properties, including projected properties of any nested, linked objects. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, if:

class Person: Object {
    @Persisted var firstName: String
    @Persisted var lastName = ""
    @Persisted public var friends: List<Person>
}

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var name
    @Projected(\Person.lastName.localizedUppercase) var lastNameCaps
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String>
}

let token = projectedPerson.observe(keyPaths: [\PersonProjection.name], { changes in
   // ...
})

• The above notification block fires for changes to the firstName property of the Object, but not for any changes made to lastName or friends list.

• If the observed key path were [\PersonProjection.firstFriendsName], then any insertion, deletion, or modification of the firstName of the friends list will trigger the block. A change to someFriend.lastName would not trigger the block (where someFriend is an element contained in friends)

If no queue is given, notifications are delivered via the standard run loop, and so can’t be delivered while the run loop is blocked by other activity. If a queue is given, notifications are delivered to that queue instead. When notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.

Unlike with List and Results, there is no “initial” callback made after you add a new notification block.

You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

It is safe to capture a strong reference to the observed object within the callback block. There is no retain cycle due to that the callback is retained by the returned token and not by the object itself.

Registers a block to be called each time the projection’s underlying object changes.

The block will be asynchronously called on the actor after each write transaction which deletes the underlying object or modifies any of the projected properties of the object, including self-assignments that set a property to its existing value.

For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

If no key paths are given, the block will be executed on any insertion, modification, or deletion for all projected properties, including projected properties of any nested, linked objects. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, if:

class Person: Object {
    @Persisted var firstName: String
    @Persisted var lastName = ""
    @Persisted public var friends: List<Person>
}

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var name
    @Projected(\Person.lastName.localizedUppercase) var lastNameCaps
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String>
}

let token = projectedPerson.observe(keyPaths: ["name"], { changes in
   // ...
})

• The above notification block fires for changes to the Person.firstName property of the the projection’s underlying Person Object, but not for any changes made to Person.lastName or Person.friends list.
• The notification block fires for changes of PersonProjection.name property, but not for another projection’s property change.
• If the observed key path were ["firstFriendsName"], then any insertion, deletion, or modification of the firstName of the friends list will trigger the block. A change to someFriend.lastName would not trigger the block (where someFriend is an element contained in friends)

Notifications are delivered to a function isolated to the given actor, on that actors executor. If the actor is performing blocking work, multiple notifications may be coalesced into a single notification.

Unlike with Collection notifications, there is no “Initial” notification and there is no gap between when this function returns and when changes will first be captured.

You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

Registers a block to be called each time the projection’s underlying object changes.

The block will be asynchronously called on the actor after each write transaction which deletes the underlying object or modifies any of the projected properties of the object, including self-assignments that set a property to its existing value.

For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

If no key paths are given, the block will be executed on any insertion, modification, or deletion for all projected properties, including projected properties of any nested, linked objects. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, if:

class Person: Object {
    @Persisted var firstName: String
    @Persisted var lastName = ""
    @Persisted public var friends: List<Person>
}

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var name
    @Projected(\Person.lastName.localizedUppercase) var lastNameCaps
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String>
}

let token = projectedPerson.observe(keyPaths: [\PersonProjection.name], { changes in
   // ...
})

• The above notification block fires for changes to the Person.firstName property of the the projection’s underlying Person Object, but not for any changes made to Person.lastName or Person.friends list.
• The notification block fires for changes of PersonProjection.name property, but not for another projection’s property change.
• If the observed key path were [\.firstFriendsName], then any insertion, deletion, or modification of the firstName of the friends list will trigger the block. A change to someFriend.lastName would not trigger the block (where someFriend is an element contained in friends)

Notifications are delivered to a function isolated to the given actor, on that actors executor. If the actor is performing blocking work, multiple notifications may be coalesced into a single notification.

Unlike with Collection notifications, there is no “Initial” notification and there is no gap between when this function returns and when changes will first be captured.

You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.