Repository files navigation

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

CombineCloudKit exposesCloudKit operations asCombine publishers. Publishers can be used to process values overtime, using Combine's declarative API.

I am unfortunately unable to maintain this project moving forward. If you would like to fork and maintain it, please reach out.

Please consider making use of the new async functionality in CloudKit and SwiftData.

CombineCloudKit supportsSwift Package Manager,CocoaPods, andCarthage. You can use whicheveryou prefer, but Swift Package Manager is most likely to be supported in the future.

Add a dependency on CombineCloudKit to yourPackage.swift usingXcode or theSwift Package Manager. Optionally, specify aversion 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

Add adependency onCombineCloudKit to yourPodfile. Optionally, specify aversion requirement.

pod'CombineCloudKit','~>1.0'

Theninstall the dependency:

pod install

Toupdate to the latest CombineCloudKit versioncompatible with your version requirement:

pod update CombineCloudKit

Add a dependency on CombineCloudKit to yourCartfile.Optionally, specify aversion requirement.

github "chris-araman/CombineCloudKit" ~> 1.0

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

⚠️ Thegenerate-xcodeproj command has been deprecated. This solution may stop working in a future release of the SwiftPackage Manager.

carthage bootstrap --no-buildpushd Carthage/Checkouts/CombineCloudKit&& swift package generate-xcodeproj&&popdcarthage bootstrap --use-xcframeworks

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

carthage update CombineCloudKit --use-xcframeworks

Combine allows you to chain value processingPublishersfor one or moreSubscribers. Here, we perform a query onourCKDatabase, then process the resultsasynchronously. As eachCKRecord is read from thedatabase, it is passed to themappublisher which publishes the value of the record's name field. Any errors in the chain so far can be handled in thecatch publisher, which passesCKRecordValue valuesalong to oursink subscriber where thefinal values are processed.

import CloudKitimport Combineimport CombineCloudKitfunc queryDueItems(database:CKDatabase, due:Date){letcancellable= database.performQuery(ofType:"ToDoItem", where:NSPredicate(format:"due >= %@", due)).map{record: CKRecord-> CKRecordValuein      // Map each ToDoItem to its Nameprint("Received record:\(record)")returnrecord["Name"]}.catch{error: Errorin      // Handle any upstream errorprint("Received error:\(error)")}.sink{value: CKRecordValuein      // Process the Name of each ToDoItemsprint("Received result:\(value)")}  // ...}

Just creating aPublisher does not queue a CloudKit operation. An operation is queued only once aSubscribersubscribes to thePublisher and indicatesDemand.

Note that theCancellable subscriber fromsink will cancel the upstream publisherswhen it is deinitialized. Take care to ensure that your subscribers live long enough to process values. If aCombineCloudKit publisher is cancelled before it is finished emitting values, the underlyingCKOperation will be cancelled. This may be desirablewhen performing a query and processing only the first few results. However, failing to wait for completion of asave,delete, ormodify operation may result in undesirable cancellation.

Note that because theatBackgroundPriority publishers are built onCKDatabase methods that do not provide means ofcancellation, they will not respond to requests for cancellation. If you need the publishers to respond to requests forcooperative cancellation, please use the publishers that do not haveatBackgroundPriority in their names. You canstill specifyQualityOfService.backgroundby passing in aCKOperation.Configuration.

If two or moreSubscribers subscribe to the same CombineCloudKitPublisher, 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 orpotentially harmful. If you need to subscribe to aPublisher twice, use theshare andmakeConnectableoperators. This will ensure the operation is queued only once.

I considered making thePublishers all conform toConnectablePublisherby default, but that would require all callers to callconnectexplicitly or to use theautoconnectoperator, even if they did not intend to share thePublisher.

For more on this topic, please review:

• Controlling Publishing with Connectable Publishers

💯%documented usingJazzy.Hosted byGitHub Pages.

Contributions are welcome!

To learn more about Combine and CloudKit, watch these videos from WWDC:

• Introducing Combine
• Combine in Practice

...or review Apple's documentation:

• CloudKit Overview
• CloudKit Documentation
• Combine Documentation

If you're looking for Swift concurrency extensions for CloudKit usingasync,await,andAsyncSequence, take a look atAsyncCloudKit!

CombineCloudKit was created byChris Araman. It is published under theMIT license.