Writable keys

[rcarver]

Here's a few tools I'm using to read and write from GRDB. It's pretty amazing, though I'm still feeling out when and if to use it. Offering these as starting points for more exploration and discussion.

RecordKey

This SharedKey takes the ID of any FetchableRecord, persisting any changes back to the database. Very simple but also pretty limited.

import Dependencies
import GRDB
import Sharing
import SwiftUI

extension SharedKey {
    /// A key that can read and write a GRDB record.
    public static func record<Record>(_ id: Record.ID?) -> Self where Self == RecordKey<Record> {
        RecordKey(recordId: id)
    }
}

public struct RecordKey<Record: Sendable & Equatable>: SharedKey
where Record: Identifiable & FetchableRecord & MutablePersistableRecord,
Record.ID: Sendable & DatabaseValueConvertible {

    let database: any DatabaseWriter
    let fetchKey: FetchKey<Record?>

    public typealias ID = RecordKeyID

    public var id: ID { ID(rawValue: fetchKey.request) }

    struct Request: FetchKeyRequest {
        let recordId: Record.ID?
        func fetch(_ db: Database) throws -> Record? {
            guard let id = self.recordId else { return nil }
            return try Record.fetchOne(db, id: id)
        }
    }

    public init(recordId: Record.ID?, animation: Animation? = nil) {
        @Dependency(\.defaultDatabase) var database
        self.database = database
        self.fetchKey = .fetch(Request(recordId: recordId), animation: animation)
    }

    public func load(context: LoadContext<Record?>, continuation: LoadContinuation<Record?>) {
        self.fetchKey.load(context: context, continuation: continuation)
    }
    public func subscribe(context: LoadContext<Record?>, subscriber: SharedSubscriber<Record?>) -> SharedSubscription {
        self.fetchKey.subscribe(context: context, subscriber: subscriber)
    }
    public func save(_ value: Record?, context: SaveContext, continuation: SaveContinuation) {
        guard var value else {
            continuation.resume()
            return
        }
        do {
            try self.database.write { db in
                try value.save(db)
            }
            continuation.resume()
        } catch {
            continuation.resume(throwing: error)
        }
    }
}

public struct RecordKeyID: Hashable {
    fileprivate let rawValue: AnyHashableSendable

    init(rawValue: any FetchKeyRequest) {
        self.rawValue = AnyHashableSendable(rawValue)
    }
}

UpdateKey

This is more general approach to writable keys, introducing UpdateKeyRequest to define how update is defined in addition to fetch

I came to this pattern in a case where I was using RecordKey above, but needed to extend the fetch from a single record to the record plus some associated join data. In this case I want the record to be savable but not the associated data.

import Dependencies
import GRDB
import Sharing
import SwiftUI

extension SharedKey {
    /// A key that can query and update data in a SQLite database.
    public static func update<Value>(
        _ request: some UpdateKeyRequest<Value>,
        animation: Animation? = nil
    ) -> Self
    where Self == UpdateKey<Value> {
        UpdateKey(request: request, animation: animation)
    }
}

public protocol UpdateKeyRequest<Value>: FetchKeyRequest {
    func update(_ db: Database, _ value: Value) throws
}

public struct UpdateKey<Value: Sendable & Equatable>: SharedKey {

    let database: any DatabaseWriter
    let fetchKey: FetchKey<Value>
    let request: any UpdateKeyRequest<Value>

    public typealias ID = UpdateKeyID

    public var id: ID { ID(rawValue: request) }

    public init(request: some UpdateKeyRequest<Value>, animation: Animation? = nil) {
        @Dependency(\.defaultDatabase) var database
        self.database = database
        self.fetchKey = .fetch(request, animation: animation)
        self.request = request
    }

    public func load(context: LoadContext<Value>, continuation: LoadContinuation<Value>) {
        self.fetchKey.load(context: context, continuation: continuation)
    }
    public func subscribe(context: LoadContext<Value>, subscriber: SharedSubscriber<Value>) -> SharedSubscription {
        self.fetchKey.subscribe(context: context, subscriber: subscriber)
    }
    public func save(_ value: Value, context: SaveContext, continuation: SaveContinuation) {
        do {
            try self.database.write { db in
                try self.request.update(db, value)
            }
            continuation.resume()
        } catch {
            continuation.resume(throwing: error)
        }
    }
}

public struct UpdateKeyID: Hashable {
    fileprivate let rawValue: AnyHashableSendable

    init(rawValue: any UpdateKeyRequest) {
        self.rawValue = AnyHashableSendable(UUID())
    }
}

[mhayes853]

I'm glad to see this as a genericized form of my single-row tables tooling in #7. Regardless, I have some thoughts.

Any SharedKey conformance should have an inherent property of load-save coherence (ie. ensuring that the current value of the @Shared property held in memory is compatible with the value on disk or any values that would be saved to disk). In essence, this kind of limits what kind of queries can be done in any external storage (not just SQLite) to both implement SharedKey, and uphold the property.

With UpdateKey, in addition to mutating the shared value in memory in a disk-compatible way when consuming the @Shared(.update(...)), you must now implement an additional update method in UpdateKeyRequest that is compatible with the coherence property when writing to the database. I don't think the part of mutating the @Shared(.update(...)) is necessary since ValueObservation will automatically reload the persisted value in a way that complies with the coherence property after update runs. In fact, this could cause inconsistencies if the value that was originally set to @Shared(.update(...)) violates the coherence property.

Overall, this isn't much of an issue for a single record joined from a few tables. However, it would be easy to misuse UpdateKey when dealing with complex collection queries with filtering and sorting as it's more work to get the elements in the @Shared(.update(...)) property in the correct order whilst ensuring filtered elements are omitted entirely.

That being said, RecordKey is more constrained, only operating on a primary key, making it easy to conform to the load-save coherence property. Therefore, this seems to be a much better candidate for a SharedKey conformance.

In your particular implementation above, I think we can make it slightly less constrained by allowing records with composite keys or just general unique indexes to be allowed. GRDB has a Record.find(db:key:) method that allows for a [String: (any DatabaseValueConvertible)?] to be used for key where each key of the dictionary represents a column of a primary key or unique index.

Another consideration would be the use of an optional as the underlying return type. To keep it consistent with @SharedReader(.fetchOne(...)), it may be better to throw in the case of a missing record instead of returning an optional. There's also the case in which single-row table records are never optional as a default value can be used when no record is found in the database. Record.find(db:key:) will handle throwing in the case of a non-existent value in GRDB.

This brings us to something like:

import Dependencies
import GRDB
import Sharing
import SwiftUI

extension SharedKey {
  /// A key that can read and write a GRDB record.
  public static func record<Record>(
    key: any DatabaseValueConvertible & Sendable & Hashable
  ) -> Self where Self == RecordKey<Record> {
    RecordKey(keys: ["id": key])
  }

  /// A key that can read and write a GRDB record.
  public static func record<Record>(
    keys: [String: (any DatabaseValueConvertible & Sendable & Hashable)?]
  ) -> Self where Self == RecordKey<Record> {
    RecordKey(keys: keys)
  }
}

public struct RecordKey<Record: Sendable & Equatable>: SharedKey
where Record: FetchableRecord & MutablePersistableRecord {
  let database: any DatabaseWriter
  let keys: [String: (any DatabaseValueConvertible & Sendable & Hashable)?]
  let animation: Animation?

  public typealias ID = RecordKeyID

  public var id: ID {
    ID(rawValue: self.keys)
  }

  public init(
    keys: [String: (any DatabaseValueConvertible & Sendable & Hashable)?],
    animation: Animation? = nil
  ) {
    @Dependency(\.defaultDatabase) var database
    self.database = database
    self.keys = keys
    self.animation = animation
  }

  public func load(context: LoadContext<Record>, continuation: LoadContinuation<Record>) {
    continuation.resume(
      with: Result { try self.database.read { db in try Record.find(db, key: self.keys) } }
    )
  }

  public func subscribe(
    context: LoadContext<Record>,
    subscriber: SharedSubscriber<Record>
  ) -> SharedSubscription {
    let cancellable = ValueObservation.tracking { db in try Record.find(db, key: self.keys) }
      .start(in: self.database, scheduling: .animation(self.animation)) { error in
        subscriber.yield(throwing: error)
      } onChange: { newValue in
        subscriber.yield(newValue)
      }
    return SharedSubscription { cancellable.cancel() }
  }

  public func save(_ value: Record?, context: SaveContext, continuation: SaveContinuation) {
    guard var value else {
      continuation.resume()
      return
    }
    do {
      try self.database.write { db in
        try value.save(db)
      }
      continuation.resume()
    } catch {
      continuation.resume(throwing: error)
    }
  }
}

public struct RecordKeyID: Hashable {
  fileprivate let rawValue: [String: AnyHashableSendable?]

  fileprivate init(rawValue: [String: (any DatabaseValueConvertible & Sendable & Hashable)?]) {
    self.rawValue = rawValue.mapValues { value in
      value.map { AnyHashableSendable($0) }
    }
  }
}

Overall, I think it would be great if this could be less constrained such that it works with records that require more complex joins to fetch, but it would have to be done in such a way to uphold the load-save coherence property.