Ditto Swift SDK

Use the shipping API: DittoIdentity, startSync() and collection APIs are deprecated on 4.14.x and removed in v5. Establish the package pin first; emit non-deprecated forms for that line, preferring forms that also exist in v5. Do not invent APIs from memory.

Read only the reference sections needed for the task. For long files, inspect the contents first and read the matching section. Do not preload all references or the README; the latter holds the capability/evidence map for coverage reviews.

What this skill does

Writes and reviews Ditto Swift code: initialization, authentication, store access, sync, lifetimes, threading and Xcode/SwiftPM configuration. Supports 4.14.x (LTS), 5.0.x, 5.1.x and 5.2.0, on iOS, iPadOS, macOS and Mac Catalyst with SwiftUI/UIKit/AppKit.

New apps and integration failures

For a new runnable Swift app, follow getting-started.md and project-deliverables.md. Use the bundled generator for a SwiftUI Xcode project; integrate existing apps in place. For failures, use troubleshooting.md. Load these only for that task.

When to use this skill

Use for Swift Ditto integration and required permissions/entitlements. Other topics have separate skills; load one only when the task needs its semantics:

Supported versions and packages

SwiftPM: https://github.com/getditto/DittoSwiftPackage, product DittoSwift. Read the relevant section of versions.md for package pins, platform minimums or version differences.

For new apps and POCs, check the package manager for the latest stable release and use that resolved version. 5.2.0 is the latest version this skill knows about, not a permanent recommendation or claim about today’s latest release. Preserve an existing project’s selected version unless an upgrade is requested. If a newer release is found, read its release notes/API changes and validate the generated code. If lookup is unavailable, state that limitation; do not silently call 5.2.0 “latest”. The generator resolves the latest stable SwiftPM tag by default; see setup.md.

Read sdk-5.2.md when adopting 5.2.0 features or reviewing an upgrade: encryption, store deletion, startup configuration and behavior fixes. The 5.2.0 public Swift API lacks Ditto.close() despite the release notes; release all strong references before Ditto.deleteStore.

Capability exceptions

Full twenty-row evidence map: README.md, for capability reviews only.

Minimum viable app

import DittoSwift
import Foundation  // v5 does not re-export Foundation

let ditto = try await Ditto.open(config: DittoConfig(   // `await`, not openSync
    databaseID: "REPLACE_ME_WITH_YOUR_DATABASE_ID",
    connect: .server(url: URL(string: "REPLACE_ME_WITH_YOUR_CONNECT_URL")!)))

// Install BEFORE sync.start(), and await the login inside it.
ditto.auth?.expirationHandler = { ditto, _ in await reauthenticate(ditto) }
try ditto.sync.start()

let query = "SELECT * FROM cars WHERE mileage > :min"
let arguments: [String: Any?] = ["min": 100]
let subscription = try ditto.sync.registerSubscription(query: query, arguments: arguments)
let observer = try ditto.store.registerObserver(query: query, arguments: arguments) { @Sendable result in
    for item in result.items {
        defer { item.dematerialize() }
        print(item.value["make"] as? String ?? "")      // [String: Any?] is not Sendable
    }
}
try await ditto.store.execute(query: "INSERT INTO cars DOCUMENTS (:car)",
                              arguments: ["car": ["make": "Toyota", "mileage": 120]])

Hold ditto, subscription and observer — see § Object lifetimes. Starting this once from SwiftUI and hopping to the main actor without losing ordering are both in references/concurrency.md. Complete runnable programs: examples/minimal-app.md and examples/swiftui-app.md.

Concurrency and threading model

Read concurrency.md for callback delivery and the ordered observer→stream→consumer bridge. Core constraints:

• Never assume main-actor delivery. deliverOn: is ignored on 5.0.x; hop explicitly inside callbacks.
• Extract Sendable values from [String: Any?] inside the callback. Do expensive conversion there; send only the final UI assignment to the main actor.
• Use one stream consumer, not one unordered Task per delivery. .bufferingNewest(1) coalesces UI snapshots. Ditto is Sendable on v5; no actor wrapper/shim is needed.
• On 4.14.x use @preconcurrency import DittoSwift for Swift 6.
• For handlerWithSignalNext, call signalNext() exactly once per delivery. auth.expirationHandler is async, Sendable and off-main: it must not touch UI state.

Object lifetimes and retention

Keep one app-lived strong Ditto reference at the composition root. Its store, sync, presence, auth, smallPeerInfo and experimental hold weak parent references: retaining a child does not keep Ditto alive; using it after release can fatalError.

Dropping observer/subscription handles does not cancel them; work/captures remain until cancelled or Ditto is destroyed. Releasing AnyCancellable does cancel. Cancel at the owning scope's boundary (onDisappear/viewDidDisappear; deinit only where actor isolation permits). Do not cache computed sync.subscriptions or store.observers snapshots. Handle table/teardown: lifetimes.md.

Anti-patterns

Read anti-patterns.md for wrong/right forms.

• Numeric casts can silently lose rows: CBOR chooses numeric widths by value; use NSNumber or Codable instead of assuming Double.
• Missing signalNext() stops delivery forever without an error; use defer { signalNext() } as the handler's first line.
• Fresh DittoTransportConfig() disables other P2P radios while sync stays active; use ditto.updateTransportConfig { … }.
• Dematerializing before DittoDiffer.diff crashes: diff → extract → dematerialize; preserve item positions with map, not compactMap.
• A retroactive Sendable shim conflicts on v5; delete it (use preconcurrency on v4).
• sync.isActive means started, not connected; inspect presence server connectivity.
• Copy the portal's Connect via SDK URL; deriving it from the database ID fails auth.

Version differences

versions.md owns deltas and upgrade/rollback results. On 4.14.x call try ditto.disableSyncWithV3() before mutating DQL. 5.1.0/5.2.0 are arm64-only; 4.14.x/5.0.x also ship x86_64. 4.14.6 throws for some use-after-release calls where v5 calls fatalError; preserve parent ownership on every line.

References

Choose the matching row and section; these are alternatives, not a reading checklist.