Swift V4→V5 API Migration Guide

I need help migrating a Ditto Swift application from v4 to v5. Focus on these critical changes:

INITIALIZATION:


- In v4 when adding the `DittoSwift` package, it would add in the `DittoObjC` package product dependencies.  In v5, `DittoObjC` is no longer a separate product — it's bundled into `DittoSwift`.  This means that you no longer need to add the `DittoObjC` package product dependencies to your project and you need to remove the `DittoObjC` package product dependencies from your project in order to get the project to build.
- These are the following places the `DittoObjC` package product dependencies are usually used:
    - 1. `PBXBuildFile` section — removed the `DittoObjC in Frameworks` entry
    - 2. `PBXFrameworksBuildPhase` — removed `DittoObjC in Frameworks` from the `files` array
    - 3. `PBXNativeTarget.packageProductDependencies` — removed the `DittoObjC` reference
    - 4. `XCSwiftPackageProductDependency` — removed the entire `DittoObjC` dependency entry
- Replace `Ditto(identity:)` with `try await Ditto.open(config:)` using async/await.
- Create a `DittoConfig` with `databaseID` and a connect mode
- `.onlinePlayground(appID:token:enableDittoCloudSync:customAuthURL:)` → `DittoConfig(databaseID: appID, connect: .server(url:))`
- `.onlineWithAuthentication(appID:enableDittoCloudSync:customAuthURL:)` → `DittoConfig(databaseID: appID, connect: .server(url:))` + auth `expirationHandler`
- `.offlinePlayground(appID:)` → `DittoConfig(databaseID: appID, connect: .smallPeersOnly(privateKey: nil))`
- `.sharedKey(appID:sharedKey:)` → `DittoConfig(databaseID: appID, connect: .smallPeersOnly(privateKey: sharedKey))`
- `.manual(certificateConfig:)` → **No replacement** — removed in v5
- The `Ditto(identity:)` initializer is removed. You MUST use `try await Ditto.open(config:)` or `Ditto.openSync(config:)`
- Remove `disableSyncWithV3()` calls — v3 protocol is fully dropped in v5
- Remove `updateTransportConfig` workaround patterns for adding websocket URLs — `DittoConfig` handles the server URL directly. Note: `updateTransportConfig` itself still exists in v5 for advanced transport configuration
- Remove `ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")` — v5 defaults to `false`
- IMPORTANT: If your v4 app used the default (strict=true), set `DQL_STRICT_MODE=true` BEFORE starting sync to maintain v4 behavior. Objects that were replaced whole in v4 will silently merge at field level in v5 without this.
- v5 default persistence directory is `ditto-{databaseID}` (was `ditto` in v4). Set `persistenceDirectory` explicitly if maintaining v4 directory structure

SYNC:
The sync API moved from top-level Ditto methods to the `ditto.sync` sub-object.
- `try ditto.startSync()` → `try ditto.sync.start()`
- `ditto.stopSync()` → `ditto.sync.stop()`
- `ditto.isSyncActive` → `ditto.sync.isActive`

AUTHENTICATION:
The `DittoAuthenticationDelegate` protocol is removed. Replace with the `expirationHandler` closure.
- Set `ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in ... }` after `Ditto.open(config:)`
- The handler signature is `@Sendable (_ ditto: Ditto, _ timeUntilExpiration: TimeInterval) async -> Void`
- Inside the handler, call `expiredDitto.auth?.login(token:provider:completion:)` (use a distinct closure parameter name to avoid shadowing the outer `ditto`)
- Use `.development` provider for playground/test tokens
- The handler is called when `timeUntilExpiration == 0` (initial auth or expired) and when `timeUntilExpiration > 0` (token expiring soon — refresh). Handle both cases.
- `authenticator.loginWithToken(_:provider:completion:)` → `ditto.auth?.login(token:provider:completion:)`
- `DittoAuthenticationDelegate.authenticationRequired(authenticator:)` → removed, use `expirationHandler` with `timeUntilExpiration == 0`
- `DittoAuthenticationDelegate.authenticationExpiringSoon(authenticator:secondsRemaining:)` → removed, use `expirationHandler` with `timeUntilExpiration > 0`
- `ditto.delegate = MyAuthDelegate()` → `ditto.auth?.expirationHandler = { ... }`

OBSERVERS:
The callback-based `registerObserver` API is the same in v5 — it returns `DittoStoreObserver` with callback handlers.
- `ditto.store.registerObserver(query:arguments:deliverOn:handler:)` → same API, returns `DittoStoreObserver`
- v5 adds `Codable` argument overloads: `registerObserver(query:arguments: Codable, deliverOn:handler:)`
- Call `item.dematerialize()` after extracting data from `DittoQueryResultItem` to free native memory — do not use the item after this call
- `observer.stop()` / `observer.cancel()` for cleanup is still the pattern

BACK PRESSURE (Signal Next):
Use `registerObserver(query:arguments:deliverOn:handlerWithSignalNext:)` when your handler needs time to process results.
- Changes that occur while your handler is processing are coalesced — you get one callback with the latest state, not every intermediate change
- You must call `signalNext()` to receive the next update
- Standard observer auto-signals after handler returns

COLLECTION API → DQL:
All `.collection()` APIs are **removed**. Replace with `store.execute()` using DQL.
- `ditto.store.collection("cars").find("color == 'blue'").exec()` → `try await ditto.store.execute(query: "SELECT * FROM cars WHERE color = :color", arguments: ["color": "blue"])`
- `ditto.store.collection("cars").findByID(id).exec()` → `try await ditto.store.execute(query: "SELECT * FROM cars WHERE _id = :id", arguments: ["id": id])`
- `ditto.store.collection("cars").upsert(value)` → `try await ditto.store.execute(query: "INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE", arguments: ["doc": value])`
- `ditto.store.collection("cars").findByID(id).update { doc in doc?["color"].set("green") }` → `try await ditto.store.execute(query: "UPDATE cars SET color = :color WHERE _id = :id", arguments: ["color": "green", "id": id])`
- `ditto.store.collection("cars").findByID(id).remove()` → `try await ditto.store.execute(query: "DELETE FROM cars WHERE _id = :id", arguments: ["id": id])`
- `ditto.store.collection("cars").findByID(id).evict()` → `try await ditto.store.execute(query: "EVICT FROM cars WHERE _id = :id", arguments: ["id": id])`
- Always use parameterized queries with `:paramName` — NEVER use string interpolation in DQL queries

LIVE QUERIES → STORE OBSERVERS:
- `collection.find("...").observeLocal { docs, event in ... }` → `ditto.store.registerObserver(query: "SELECT * FROM ...", arguments: [...]) { result in ... }`
- `liveQuery?.stop()` → `observer.stop()`
- v4 handler: `(docs: [DittoDocument], event: DittoLiveQueryEvent) -> Void`
- v5 handler: `(result: DittoQueryResult) -> Void` where result has `.items` containing `DittoQueryResultItem` objects
- Extract your model from `item.jsonData()` then call `item.dematerialize()` to free native memory
- When using `item.jsonData()`, you need to make sure you import the Swift Foundation framework

SUBSCRIPTIONS:
- `ditto.store.collection("cars").find("color == 'red'").subscribe()` → `try ditto.sync.registerSubscription(query: "SELECT * FROM cars WHERE color = :color", arguments: ["color": "red"])`
- `DittoSubscription` → replaced by `DittoSyncSubscription`

COUNTERS:
- `doc?["viewCount"].counter?.increment(by: 1.0)` → `try await ditto.store.execute(query: "UPDATE cars APPLY viewCount PN_INCREMENT BY :n WHERE _id = :id", arguments: ["n": 1, "id": id])`
- DO NOT initialize counter fields in insert documents. Counters are created on first `PN_INCREMENT`. Inserting `0` creates a REGISTER, not a COUNTER.
- Decrement by passing a negative value: `["n": -1]`

PRESENCE:
- `peer.peerKeyString` → `peer.peerKey` (type is `String` in both v4 and v5, but property renamed)
- `peer.osV2` → `peer.os`
- `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- `connection.peerKeyString1` / `peerKeyString2` → `connection.peer1` / `connection.peer2` (now `String`)
- `connection.approximateDistanceInMeters` → **removed, no replacement**
- `ditto.observePeers(_:)` → `ditto.presence.observe(didChangeHandler:)`
- `DittoRemotePeer` struct (deprecated) → use `DittoPeer` in `DittoPresenceGraph`
- `DittoAddress` struct → removed

DITTO CLASS:
- `Ditto(identity:)` → `try await Ditto.open(config:)` or `Ditto.openSync(config:)`
- `ditto.activated` → `ditto.isActivated`
- `ditto.appID` → `ditto.config.databaseID`
- `ditto.transportDiagnostics()` → removed
- `ditto.runGarbageCollection()` → removed (automatic in v5)
- `ditto.disableSyncWithV3()` → removed (v3 protocol dropped)
- `ditto.isHistoryTrackingEnabled` → removed

DISK USAGE:
- `DiskUsage` → `DittoDiskUsage`
- `diskUsage.exec` → `diskUsage.item`
- `DiskUsageObserverHandle` → `DittoDiskUsageObserver`
- `DiskUsageItem` → `DittoDiskUsageItem` (property names `.path`, `.sizeInBytes`, `.childItems` are unchanged)

LOGGING:
- `DittoLogger` class name is unchanged in both v4 and v5, but is now `final` and `Sendable` in v5
- `DittoLogger.setLogFile()` → removed — use `export(to:)` instead

ERRORS:
- `DittoSwiftError` typealias → removed, use `DittoError` directly
- `migrationError` error case → removed

TRANSPORT CONFIG:
- `DittoHTTPListenConfig.staticContentPath` → removed
- Default `webSocketSync` — check if your app relied on v4 default; explicitly set `true` if needed

TYPES & PROTOCOLS:
- `DittoConnectionPriority` enum → removed
- `DittoTransportSnapshot` struct → removed (with transport diagnostics)
- `DittoExperimental.jsonByTranscoding(cbor:)` → removed
- All public types are now `final` and `Sendable` for Swift concurrency
- `DittoConfig` and `DittoConfigConnect` conform to `Sendable` and `Codable`
- `DittoConnection` now conforms to `Identifiable`, `Equatable`, `Hashable`, and `Sendable`

SWIFT 6 COMPATIBILITY:
- `DittoConnection` gaining `Identifiable` conformance causes `filter` ambiguity in Swift 6. Fix: annotate closure parameter explicitly:
  ```swift
  // BROKEN in Swift 6
  connections.filter { $0.peer1 == localKey }
  // FIXED
  connections.filter { (conn: DittoConnection) in conn.peer1 == localKey }
  ```
- Auth handler: `expirationHandler` closure is `@Sendable` and `async`. If your Ditto manager is an `actor`, use `await` when accessing actor-isolated state inside `Task { }` blocks within the handler.

REMOVED APIs (no replacement):
- `ditto.transportDiagnostics()` — low-level transport debug info
- `ditto.runGarbageCollection()` — CRDT GC controls
- `ditto.disableSyncWithV3()` — v3 protocol fully dropped
- `ditto.isHistoryTrackingEnabled` — history tracking removed
- `DittoIdentity.manual(certificateConfig:)` — manual identity type
- `Connection.approximateDistanceInMeters` — peer distance estimation
- `DittoHTTPListenConfig.staticContentPath` — static file serving
- `DittoStore.queriesHash(queries:)` — hash-based query deduplication
- `DittoStore.queriesHashMnemonic(queries:)` — query mnemonic hashing
- `DittoConnectionPriority` enum — connection priority
- `DittoTransportSnapshot` struct — removed with transport diagnostics
- `DittoRemotePeer` struct (deprecated) — use `DittoPeer` in `DittoPresenceGraph`
- `DittoAddress` struct — removed
- `DittoExperimental.jsonByTranscoding(cbor:)` — CBOR-to-JSON utility
- `DittoSwiftError` typealias — use `DittoError` directly
- `migrationError` error case — removed
- `DittoLogger.setLogFile()` — use `export(to:)` instead

NEW APIs:
- `Ditto.open(config:): async throws -> Ditto` — async factory method
- `Ditto.openSync(config:): throws -> Ditto` — synchronous factory alternative
- `ditto.config: DittoConfig` — read the config used to open this instance
- `ditto.isActivated: Bool` — replaces `ditto.activated`
- `DittoStore.newAttachment(data: Data, metadata:)` — create attachment from in-memory `Data` (v4 was file path only)
- `DittoStore.registerObserver(query:arguments: some Codable, ...)` — overloads accepting `Codable` query arguments
- `DittoSync.registerSubscription(query:arguments: some Codable)` — overload accepting `Codable` arguments
- `DittoDiskUsageObserver` — standalone observer class (was nested `DiskUsage.DiskUsageObserverHandle`)
- `DittoDiskUsageItem` — renamed from `DiskUsageItem`
- `DittoSyncSubscription.queryArgumentsCBORData` / `.queryArgumentsJSONData` / `.id` — introspection properties
- `DittoConnection` conforms to `Identifiable`, `Equatable`, `Hashable`, and `Sendable`
- All public types now `final` and `Sendable` for Swift concurrency
- `DittoConfig` and `DittoConfigConnect` conform to `Sendable` and `Codable`
- `DittoSmallPeerInfo.metadataJSONString` removed — use `metadataJSONData` instead (which already existed in v4)

BEFORE (v4):
```swift
let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "https://your-server.ditto.live")
    )
)

ditto.updateTransportConfig { config in
    config.connect.webSocketURLs.insert("wss://...")
}
ditto.disableSyncWithV3()
try? ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")
try? ditto.startSync()

// Observer — callback with manual cleanup
var observer: DittoStoreObserver?
observer = ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    DispatchQueue.main.async {
        self.cars = result.items.compactMap { Car($0.jsonData()) }
    }
}

// Must manually stop in deinit
deinit { observer?.stop() }

// Presence
ditto.observePeers { peers in
    for peer in peers {
        print(peer.peerKeyString, peer.isConnectedToDittoCloud)
    }
}

// Cleanup
observer?.stop()
ditto.stopSync()
```

AFTER (v5):
```swift
let config = DittoConfig(
    databaseID: "your-database-id",
    connect: .server(url: URL(string: "https://your-server.ditto.live")!)
)
let ditto = try await Ditto.open(config: config)

// Authentication
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
    expiredDitto.auth?.login(token: "your-token", provider: .development) { clientInfo, error in
        if let error = error {
            print("Ditto auth failed: \(error), client info: \(String(describing: clientInfo)), time until expiration: \(timeUntilExpiration)s")
        }
    }
}

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// try await ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = true")

try ditto.sync.start()

// Observer — callback-based, same pattern as v4 but with dematerialize()
let observer = try ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    let cars = result.items.compactMap { item -> Car? in
        let car = Car(item.jsonData())
        item.dematerialize()  // Free native memory — do not use item after this
        return car
    }
    DispatchQueue.main.async { self.cars = cars }
}
// Cleanup: observer.stop()

// Subscription — DQL-based
let sub = try ditto.sync.registerSubscription(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
)

// Presence
ditto.presence.observe { graph in
    let allPeers = [graph.localPeer] + graph.remotePeers
    for peer in allPeers {
        print(peer.peerKey, peer.isConnectedToDittoServer)
    }
}

// Cleanup
sub.cancel()
ditto.sync.stop()
```

CHECKLIST:

Initialization:
- Replace `Ditto(identity:)` with `try await Ditto.open(config:)`
- Add `try await` for initialization — `Ditto.open(config:)` is async and throws
- Create `DittoConfig` with `databaseID` and connect mode (`.server(url:)` or `.smallPeersOnly(privateKey:)`)
- Set `DQL_STRICT_MODE=true` BEFORE `sync.start()` if maintaining v4 strict behavior
- Set `persistenceDirectory` if maintaining v4 directory structure
- Remove `disableSyncWithV3()` calls
- Remove `updateTransportConfig` workaround patterns for websocket URLs (method still exists for advanced use)
- Remove `ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")` (v5 default)

Authentication:
- Remove `DittoAuthenticationDelegate` conformance and class
- Remove `ditto.delegate = MyAuthDelegate()` assignment
- Set `ditto.auth?.expirationHandler` closure after `Ditto.open(config:)`
- Handler signature is `@Sendable (_ ditto: Ditto, _ timeUntilExpiration: TimeInterval) async -> Void`
- Use `timeUntilExpiration == 0` check for initial auth vs `> 0` for refresh
- Use `.development` provider for playground/test tokens

Sync:
- Replace `try ditto.startSync()` with `try ditto.sync.start()`
- Replace `ditto.stopSync()` with `ditto.sync.stop()`
- Replace `ditto.isSyncActive` with `ditto.sync.isActive`

Observers:
- Replace `collection.observeLocal { }` with `store.registerObserver(query:arguments:handler:)`
- Call `item.dematerialize()` after extracting data from `DittoQueryResultItem`
- Use `handlerWithSignalNext:` for back-pressure control on expensive operations
- Cleanup with `observer.stop()`

Data Operations:
- Replace all `.collection("x").find(...)` chains with `store.execute(query:arguments:)` DQL
- Use parameterized queries with `:paramName` — never string interpolation
- Replace `.upsert()` with `INSERT INTO ... DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE`
- Replace `.update { }` closures with `UPDATE SET` DQL
- Replace `.remove()` with `DELETE FROM`
- Replace `.evict()` with `EVICT FROM`