ValueObservation

public struct ValueObservation<Reducer> where Reducer : _ValueReducer

ValueObservation tracks changes in the results of database requests, and notifies fresh values whenever the database changes.

For example:

let observation = ValueObservation.tracking { db in
    try Player.fetchAll(db)
}

let cancellable = try observation.start(
    in: dbQueue,
    onError: { error in ... },
    onChange: { players: [Player] in
        print("Players have changed.")
    })

  • Default is false. Set this property to true when the observation requires write access in order to fetch fresh values. Fetches are then wrapped inside a savepoint.

    Don’t set this flag to true unless you really need it. A read/write observation is less efficient than a read-only observation.

    Declaration

    Swift

    public var requiresWriteAccess: Bool
    Show on GitHub

Starting Observation

  • Starts the value observation in the provided database reader (such as a database queue or database pool).

    The observation lasts until the returned cancellable is cancelled or deallocated.

    For example:

    let observation = ValueObservation.tracking { db in
    try Player.fetchAll(db)
}

let cancellable = try observation.start(
    in: dbQueue,
    onError: { error in ... },
    onChange: { players: [Player] in
        print("fresh players: \(players)")
    })

    By default, fresh values are dispatched asynchronously on the main queue. You can change this behavior by providing a scheduler. For example, .immediate notifies all values on the main queue as well, and the first one is immediately notified when the start() method is called:

    let cancellable = try observation.start(
    in: dbQueue,
    scheduling: .immediate, // <-
    onError: { error in ... },
    onChange: { players: [Player] in
        print("fresh players: \(players)")
    })
// <- here "fresh players" is already printed.

    Declaration

    Swift

    public func start(
    in reader: DatabaseReader,
    scheduling scheduler: ValueObservationScheduler = .async(onQueue: .main),
    onError: @escaping (Error) -> Void,
    onChange: @escaping (Reducer.Value) -> Void) -> DatabaseCancellable

    Parameters

    reader

    A DatabaseReader.
    scheduler

    A Scheduler. By default, fresh values are dispatched asynchronously on the main queue.
    onError

    A closure that is provided eventual errors that happen during observation
    onChange

    A closure that is provided fresh values

    Return Value

    a DatabaseCancellable

    Show on GitHub

  • Returns a ValueObservation which notifies the results of calling the given transformation which each element notified by this value observation.

    Declaration

    Swift

    public func map<T>(_ transform: @escaping (Reducer.Value) -> T)
    -> ValueObservation<ValueReducers.Map<Reducer, T>>
    Show on GitHub

Creating ValueObservation

  • Creates a ValueObservation which notifies the values returned by the fetch function whenever a database transaction changes them.

    The fetch function must always performs the same database requests. The stability of the observed database region allows optimizations.

    When you want to observe a varying database region, use the ValueObservation.trackingVaryingRegion(_:) method instead.

    For example:

    let observation = ValueObservation.tracking { db in
    try Player.fetchAll(db)
}

let cancellable = try observation.start(
    in: dbQueue,
    onError: { error in ... },
    onChange:) { players: [Player] in
        print("Players have changed")
    })

    Declaration

    Swift

    public static func tracking<Value>(
    _ fetch: @escaping (Database) throws -> Value)
    -> ValueObservation<ValueReducers.Fetch<Value>>

    Parameters

    fetch

    A function that fetches the observed value from the database.
    Show on GitHub

  • Creates a ValueObservation which notifies the values returned by the fetch function whenever a database transaction changes them.

    Declaration

    Swift

    public static func trackingVaryingRegion<Value>(
    _ fetch: @escaping (Database) throws -> Value)
    -> ValueObservation<ValueReducers.Fetch<Value>>

    Parameters

    fetch

    A function that fetches the observed value from the database.
    Show on GitHub

Available where Reducer.Value: Equatable