⛅️ CombineCloudKit

Swift Combine extensions for reactive CloudKit record processing. Designed for simplicity.

CombineCloudKit exposes CloudKit operations as Combine publishers. Publishers can be used to process values over time, using Combine’s declarative API.

📦 Adding CombineCloudKit to Your Project

CombineCloudKit supports Swift Package Manager, CocoaPods, and Carthage. You can use whichever you prefer, but Swift Package Manager is most likely to be supported in the future.

Swift Package Manager

Add a dependency on CombineCloudKit to your Package.swift using Xcode or the Swift Package Manager. Optionally, specify a version requirement.

dependencies: [
  .package(url: "https://github.com/chris-araman/CombineCloudKit.git", from: "1.0.0")
]

Then resolve the dependency:

swift package resolve

To update to the latest CombineCloudKit version compatible with your version requirement:

swift package update CombineCloudKit

CocoaPods

Add a dependency on CombineCloudKit to your Podfile. Optionally, specify a version requirement.

pod 'CombineCloudKit', '~>1.0'

Then install the dependency:

pod install

To update to the latest CombineCloudKit version compatible with your version requirement:

pod update CombineCloudKit

Carthage

Add a dependency on CombineCloudKit to your Cartfile. Optionally, specify a version requirement.

github "chris-araman/CombineCloudKit" ~> 1.0

Because Carthage assumes dependencies are provided as shared frameworks, but Swift Package Manager builds only libraries or executables, we have to generate an .xcodeproj for Carthage to use.

⚠️ The generate-xcodeproj command has been deprecated. This solution may stop working in a future release of the Swift Package Manager.

carthage bootstrap --no-build
pushd Carthage/Checkouts/CombineCloudKit && swift package generate-xcodeproj && popd
carthage bootstrap --use-xcframeworks

To update to the latest CombineCloudKit version compatible with your version requirement:

carthage update CombineCloudKit --use-xcframeworks

🌤 Using CombineCloudKit in Your Project

Combine allows you to chain value processing Publishers for one or more Subscribers. Here, we perform a query on our CKDatabase, then process the results asynchronously. As each CKRecord is read from the database, it is passed to the map publisher which publishes the value of the record’s name field. Any errors in the chain so far can be handled in the catch publisher, which passes CKRecordValue values along to our sink subscriber where the final values are processed.

import CloudKit
import Combine
import CombineCloudKit

func queryDueItems(database: CKDatabase, due: Date) {
  let cancellable = database
    .performQuery(ofType: "ToDoItem", where: NSPredicate(format: "due >= %@", due))
    .map { record: CKRecord -> CKRecordValue in
      // Map each ToDoItem to its Name
      print("Received record: \(record)")
      return record["Name"]
    }.catch { error: Error in
      // Handle any upstream error
      print("Received error: \(error)")
    }.sink { value: CKRecordValue in
      // Process the Name of each ToDoItems
      print("Received result: \(value)")
    }

  // ...
}

Queueing and Cancellation

Just creating a Publisher does not queue a CloudKit operation. An operation is queued only once a Subscriber subscribes to the Publisher and indicates Demand.

Note that the Cancellable subscriber from sink will cancel the upstream publishers when it is deinitialized. Take care to ensure that your subscribers live long enough to process values. If a CombineCloudKit publisher is cancelled before it is finished emitting values, the underlying CKOperation will be cancelled. This may be desirable when performing a query and processing only the first few results. However, failing to wait for completion of a save, delete, or modify operation may result in undesirable cancellation.

Note that because the atBackgroundPriority publishers are built on CKDatabase methods that do not provide means of cancellation, they will not respond to requests for cancellation. If you need the publishers to respond to requests for cooperative cancellation, please use the publishers that do not have atBackgroundPriority in their names. You can still specify QualityOfService.background by passing in a CKOperation.Configuration.

If two or more Subscribers subscribe to the same CombineCloudKit Publisher, the operation will be queued twice. This may be surprising if you’re new to Combine! Queueing the same database operation twice could be inefficient or potentially harmful. If you need to subscribe to a Publisher twice, use the share and makeConnectable operators. This will ensure the operation is queued only once.

I considered making the Publishers all conform to ConnectablePublisher by default, but that would require all callers to call connect explicitly or to use the autoconnect operator, even if they did not intend to share the Publisher.

For more on this topic, please review: