Yorkie

iOS SDK

Through Yorkie iOS SDK, you can efficiently build collaborative applications. On the client-side implementation, you can create Documents that are automatically synced with remote peers with minimal effort.

If you want to install the SDK, refer to the Getting Started with iOS SDK.

Client

Client is a normal client that can communicate with the server. It has Documents and sends changes of the Document from local to the server to synchronize with other replicas remotely.

Creating a Client

We can create a Client using Client(rpcAddress: RPCAddress(host:,port:), options:). After the Client has been activated, it is connected to the server and ready to use.

let client = Client(rpcAddress: RPCAddress(host: "api.yorkie.dev", port: 443), options: ClientOptions(
    apiKey: "xxxxxxxxxxxxxxxxxxxx"
))
try await client.activate()

Subscribing to Client events

We can use client.eventStream to subscribe to client-based events, such as status-changed, stream-connection-status-changed.

target.eventStream.sink { event in
    switch event.type {
    case .statusChanged:
        ()
    case .streamConnectionStatusChanged:
        ()
    default:
        break
    }
}

By using the value of the stream-connection-status-changed event, it is possible to determine whether the Client is connected to the network.

If you want to know about other ClientEvents, please refer to the ClientEventType.

Document

Document is a primary data type in Yorkie, which provides a JSON-like updating experience that makes it easy to represent your application's model. A Document can be updated without being attached to the client, and its changes are automatically propagated to other clients when the Document is attached to the Client or when the network is restored.

Creating a Document

We can create a Document using Document(key:). Let's create a Document with a key and attach it to the Client.

let doc = Document(key: "doc-1")

The document key is used to identify the Document in Yorkie. It is a string that can be freely defined by the user.

Attaching the Document

When you attach, the client notifies the server that it is subscribing to this document. If the document does not exist on the server, it will be created, and any local changes that occurred will be updated to the server's document. If the server already has a document associated with the provided key, it sends the existing changes to the client, which are then applied to synchronize the document.

Once attached, the document becomes synchronized with other clients. This ensures that any modifications made by one client are instantly propagated to other clients collaborating on the same document.

The second and third arguments are belows.

• initialPresence(Optional): Sets the initial presence of the client that attaches the document. The presence is shared with other users participating in the document. It must be Codable.
• isRealtimeSync(Optional): Specifies whether to enable real-time synchronization. The default value is true, which means synchronization occurs automatically. If set to false, you should manually control the synchronization.

try await clientA.attach(doc, ["color: "blue", "cursor": ["x": 0, "y": 0]], true)

Updating presence

The Document.update() method allows you to make changes to the state of the current user's presence.

Specific properties provided will be changed. The existing presence object will be updated by merging the new changes. In other words, properties not specified in the update function will remain unchanged.

try await doc.update { root, presence in
  presence.set(["cursor": ["x": 1, "y": 1]])
}
// final state
// presence = { color: 'blue', cursor: { x: 1, y: 1 } }
// we can see that the changes made were merged and the final state of the current user's presence is as we desire

// let's say 'color' is a property of cursor
try await client.attach(doc, ["cursor": ["x": 0, "y": 0, "color": "red"]])

try await doc.update { root, presence in 
  // we want to change the x y coordinates of our cursor
    presence.set(["cursor": ["x": 1, "y": 1]])
}

// final state
// presence = { cursor: { x: 1, y: 1 } } 
// we can see that all properties inside cursor get replaced (i.e. we lose the property 'color')

Getting presence

Document.getPresence(clientID)

It returns the presence of a specific client.

await doc.getPresence(client.id!) // ["color": "blue", "cursor": ["x": 1, "y": 1]]

Document.getMyPresence()

It returns the presence of the current client that has attached to the document.

await doc.getMyPresence() // ["color": "blue", "cursor": ["x": 1, "y": 1]]

Document.getPresences()

It returns an array about all clients currently participating in the document. Each entry in the array includes the client's id and presence.

let users = await doc.getPresences()
for (clientID, presence) in users {
    // Do somethins
}

Document.subscribePresence(.presence)

This method allows you to subscribe to all presence-related changes. By subscribing to these events, you can be notified when specific changes occur within the document, such as clients attaching, detaching, or modifying their presence.

await doc.subscribePresence { event in
    if event.type == .initialized {
        // Array of other users currently participating in the document
        // event.value;
    }
    
    if event.type == .watched {
        // A user has joined the document editing in online
        // event.value;
    }
    
    if event.type == .unwatched {
        // A user has left the document editing
        // event.value;
    }
    
    if event.type == .presenceChanged {
        // A user has updated their presence
        // event.value;
    }
}

Document.subscribePresence(.myPresence)

This method is specifically for subscribing to changes in the presence of the current client that has attached to the document.

The possible event.type are: initialized, presenceChanged.

await doc.subscribePresence(.myPresence) { event in
    // Do something
}

Document.subscribePresence(.others)

This method enables you to subscribe to changes in the presence of other clients participating in the document.

The possible event.type are: watched, unwatched, presenceChanged.

await doc.subscribePresence(.others) { event in
    if event.type == .watched {
        addUser(event.value)
    }
    
    if event.type == .unwatched {
        removeUser(event.value)
    }

    if event.type == .presenceChanged {
        updateUser(event.value)
    }
}

Editing the Document

Document.update(:,message:) enables you to modify a Document. The optional message allows you to add a description to the change. If the Document is attached to the Client, all changes are automatically synchronized with other Clients.

let message = "update document for test";
try await doc.update({ root in
  root.obj = [:]                      // {"obj":{}}
  let obj = root.obj as! JSONObject
  obj.num = Int64(1)                  // {"obj":{"num":1}}
  obj.obj = ["str": "a"]              // {"obj":{"num":1,"obj":{"str":"a"}}}
  obj.arr = [Int64(1), Int64(2)]      // {"obj":{"num":1,"obj":{"str":"a"},"arr":[1,2]}}
}, message: message);

Under the hood, root in the update function creates a change, a set of operations, using a JavaScript proxy. Every element has its unique ID, created by the logical clock. This ID is used by Yorkie to track which object is which.

You can get the contents of the Document using doc.getRoot().

let root = doc.getRoot()
print(root.obj!) // {"num":1,"obj":{"str":"a"},"arr":[1,2]}
let obj = root.obj as! JSONObject
print(obj.num!)  // 1
print(obj.obj!)  // {"str":"a"}
print(obj.arr!)  // [1,2]

Subscribing to Document

Document.subscribe()

A Document can be modified by changes generated remotely or locally in Yorkie.

Whenever the Document is modified, change events are triggered and we can subscribe to these events using the document.subscribe(callback).

The callback is called with an event object, and the event.type property indicates the source of the change, which can be one of the following values: localChange, remoteChange or snapshot.

When the event.type is localChange or remoteChange, the event.value is a ChangeInfo, which has message, operations and actorID properties.

For more information about changeInfo for document events, please refer to the ChangeInfo.

await self.doc.subscribe { event in
    if event.type == .localChange {
        print(event)
    } else if let event = event as? RemoteChangeEvent {
        let changeInfo = event.value
        
        changeInfo.operations.forEach { op in
            switch (op.type) {
            case .increase:
                // Do something...
                break
            default:
                break
            }
        }
    }
}

Document.subscribe("$.path")

Additionally, you can subscribe to changes for a specific path in the Document using doc.subscribe(targetPath, callback) with a path argument, such as $.todos, where the $ sign indicates the root of the document. The callback function is called when the target path and its nested values are changed.

With this feature, you can easily subscribe to changes for a specific part of the document and perform different actions based on the updated values.

await doc.subscribe("$.todos") { event in 
  // The callback will be called when the root.todos or its nested values change.
  Task {
    let target = try? await target.getValueByPath(path: "$.todos") // You can get the value by path.
  }
  // Do something...
}

Changing Synchronization Setting

To change the synchronization setting for a document, you can use client.pause(doc) and client.resume(doc).

When you pause a document, the synchronization process will no longer occur in realtime, and you will need to manually execute the synchronization to ensure that the changes are propagated to other clients.

To resume the realtime synchronization, you can call client.resume(doc).

// 1. Pause real-time sync
try await client.pause(doc)
try await client.sync(doc) // To perform synchronization, you need to manually call the sync function

// 2. Resume real-time sync
try await client.resume(doc)

Changing Synchronization Mode

By default, Yorkie synchronizes a document in push-pull mode, where local changes are pushed to the server, and remote changes are pulled from the server.

If you only want to send your changes and not receive remote changes, you can use push-only mode.

For realtime synchronization, you can use client.pauseRemoteChanges(doc) and client.resumeRemoteChanges(doc).

For manual synchronization, you can pass the desired sync mode to client.sync(doc, syncMode).

// Pause remote changes for realtime sync
try await client.pauseRemoteChanges(doc)
// Resume remote changes for realtime sync
try await client.resumeRemoteChanges(doc)

// Manual sync in Push-Only mode
try await client.sync(doc, .pushOnly)
// Manual sync in Push-Pull mode
try await client.sync(doc, .pushPull)

Detaching the Document

If the document is no longer used, it should be detached to increase the efficiency of GC removing CRDT tombstones. For more information about GC, please refer to Garbage Collection.

try await client.detach(doc)

Custom CRDT types

Custom CRDT types are data types that can be used for special applications such as text editors and counters, unlike general JSON data types such as JSONObject and JSONArray. Custom CRDT types can be created in the callback function of document.update.

JSONText

JSONText provides supports for collaborative text editing. In addition, contents in JSONText can have attributes; for example, characters can be bold, italic, or underlined.

try await doc.update{ root in
    root.text = JSONText() // {"text":[]}
    (root.text as? JSONText)?.edit(0, 0, "hello")               // {"text":[{"val":"hello"}]}
    (root.text as? JSONText)?.edit(0, 1, "H")                   // {"text":[{"val":"H"},{"val":"ello"}]}
    (root.text as? JSONText)?.setStyle(fromIdx: 0, toIdx: 1, attributes: ["bold": true])    // {"text":[{"attrs":{"bold":"true"},"val":"H"},{"val":"ello"}]}
}

Selection using presence

The temporary client information, such as text selection, does not need to be stored in the document permanently. Instead, it can be effectively shared using presence.

When transmitting text selection information, it is essential to convert the index, which can vary based on the text state, into the position used by Yorkie.JSONText. This converted position selection can then be sent and applied through presence.

Here is an example where presence is used to share text selection between users in CodeMirror editor.

• When the text selection is changed:

let range: NSRange  // eg. selected range converted from selectedTextRange of UITextView

let fromIdx = range.location
let toIdx = range.location + range.length

try await doc.update { root, presence in
    if let range = try? (root.content as? JSONText)?.indexRangeToPosRange((fromIdx, toIdx)) {
        presence.set(["from": range.0, "to": range.1])
    }
}

• When applying other user's selection changes:

await doc.subscribePresence(.others) { event in 
    if let event = event as? PresenceChangedEvent {
        if let fromPos: TextPosStruct = decodePresence(event.value["from"]),
            let toPos: TextPosStruct = decodePresence(event.value["to"]) {
            if let (fromIdx, toIdx) = try? await(document.getRoot().content as? JSONText)?.posRangeToIndexRange((fromPos, toPos)) {
                // Handle the updated selection in the editor
            }
        }
    }
}

private func decodePresence<T: Decodable>(_ dictionary: Any?) -> T? {
    guard let dictionary = dictionary as? [String: Any],
            let data = try? JSONSerialization.data(withJSONObject: dictionary, options: [])
    else {
        return nil
    }

    return try? JSONDecoder().decode(T.self, from: data)
}

Text selection can be efficiently shared using presence. Please refer to the following example for a complete code:

An example of Text Editor: Text Editor example

JSONCounter

JSONCounter supports integer types changing with addition and subtraction. If an integer data needs to be modified simultaneously, JSONCounter should be used instead of primitives.

try await doc.update{ root in
    root.counter = JSONCounter(value: Int64(1))                 // {"counter":1}
    (root.counter as? JSONCounter<Int64>)?.increase(value: 2)   // {"counter":3}
    (root.counter as? JSONCounter<Int64>)?.increase(value: 3)   // {"counter":6}
    (root.counter as? JSONCounter<Int64>)?.increase(value: -4)  // {"counter":2}
}

Reference

For details on how to use the iOS SDK, please refer to iOS SDK Reference.