3.0 Migration guide

warning

Ditto SDK 2.X.X Deprecation Notice

On December 7, 2022, Ditto SDK Version 2.X.X is nearing end of life and will be deprecated.

On January 18, 2023, Ditto SDK Version 2.X.X will be unsupported. Ditto SDK Version 2.X.X will no longer be able to synchronize with the Big Peer after January 18, 2023. In order for applications to continue to synchronize with the Big Peer, your development teams are required to update and release a new version of your application that has been updated to Ditto SDK Version 3.0.X or higher prior to January 18, 2023.

This is a migration guide that covers the most substantial changes. For a comprehensive list of all deprecated and removed methods, see the changelog.

Replicated Growable Array (RGA) is removed from the API

In v2, the Replicated Growable Array (RGA) was deprecated. In v3, they are entirely removed from the API. You'll still be able to read legacy RGA fields, but not write to them.

Observe will no longer implicitly create subscriptions

observe is now removed from the API.

Instead, use subscribe and observeLocal together. If you have .observe() double check that you are also subscribing to that data in an application-wide Ditto manager object.

• If you want to sync something use .subscribe().
• Use observeLocal to listen for changes and render documents in the user interface.

For example, if you have this code:

let liveQuery = collection.find(query).observe { (docs, event) in   ...}

You need to now expand this to be:

let subscription = collection.find(query).subscribe()let liveQuery = collection.find(query).observeLocal { (docs, event) in   ...}

Further, it is best practice to separate your subscribe functions from observe.

For example, you should create a DittoManager singleton to hold subscribe calls:

class DittoManager {
    var ditto: Ditto    var subscription: DittoSubscription
    static var shared = DittoManager()
    init() {        self.ditto = Ditto(identity: .onlinePlayground(appID: "MY_APP", token: "MY_TOKEN"))        self.subscription = self.ditto.store["orders"].find(getOrdersQuery()).subscribe()    }
    getOrdersQuery () {        return "restaurantId == '\(MyApp.restaurantId)' && forScreen == '\(MyApp.deviceType)'"    }}

And use observeLocal in your ViewModel to watch whenever the device's database is updated with changes. Both local and remote changes will fire this callback.

class OrdersListViewModel: ObservableObject {    @Published var orders = [Order]()
    init() {        self.liveQuery = DittoManager.shared.ditto.store["orders"]            .findAll()            .observeLocal(eventHandler: {  docs, event in                self.orders = docs.map({ Order(document: $0) })            }    }}

Swift changes

Removal of Codable Support in DittoSwift

• The current Codable Support in v1 forced magic types with no escape hatch. There was no way to customize the _id field to a struct or class’s property name nor any ability to annotate that certain properties should behave like CRDTs.
• Ditto v3 deprecates native Codable support.
• Native Codable support will be removed completely in v5, but there will be an alternative Codable implementation.

If you have a struct or class that you want to map to a Document, please start populating the fields using our document accessors explicitly. This is verbose but will prepare your code for the removal of Codable support from our core library.

class Car {    var id: String    var name: String    var mileage: Int
    init(document: DittoDocument) {        self.id = document.id.stringValue        self.name = document["name"].register?.stringValue ?? ""        self.mileage = document["mileage"].register?.intValue ?? 0  }}

Android changes

All instances of ID are now Id. For example, findByID is now findById. For the full list of deprecations, see the changelog.