doc: add readme

Author: Leeeon233

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-  "cSpell.words": ["oplog", "uniffi", "xcframework"]
+  "cSpell.words": ["oplog", "uniffi", "xcframework", "Zhao"]
 }

README.md

@@ -1,8 +1,17 @@
 # Loro-swift
 
+<p align="center">
+  <a aria-label="X" href="https://x.com/loro_dev" target="_blank">
+    <img alt="" src="https://img.shields.io/badge/Twitter-black?style=for-the-badge&logo=Twitter">
+  </a>
+  <a aria-label="Discord-Link" href="https://discord.gg/tUsBSVfqzf" target="_blank">
+    <img alt="" src="https://img.shields.io/badge/Discord-black?style=for-the-badge&logo=discord">
+  </a>
+</p>
+
 This repository contains experimental Swift bindings for [Loro CRDT](https://github.com/loro-dev/loro).
 
-If you have any suggestions for API, please feel free to create an issue.
+If you have any suggestions for API, please feel free to create an issue or join our [Discord](https://discord.gg/tUsBSVfqzf) community.
 
 ## Usage
 
@@ -14,7 +23,7 @@ let package = Package(
     products: [......],
     dependencies:[
         ...,
-        .package(url: "https://github.com/loro-dev/loro-swift.git")
+        .package(url: "https://github.com/loro-dev/loro-swift.git", from: 0.16.2)
     ],
     targets:[
         .executableTarget(
@@ -26,6 +35,47 @@ let package = Package(
 
 ```
 
+## Examples
+
+```swift
+import Loro
+
+// create a Loro document
+let doc = LoroDoc()
+
+// create Root Container by getText, getList, getMap, getTree, getMovableList, getCounter
+let text = doc.getText(id: "text")
+
+try! text.insert(pos: 0, s: "abc")
+try! text.delete(pos: 0, len: 1)
+let s = text.toString()
+// XCTAssertEqual(s, "bc")
+
+// subscribe the event
+let subId = doc.subscribeRoot{ diffEvent in
+    print(diffEvent)
+}
+// unsubscribe
+doc.unsubscribe(subId: id)
+
+// export updates or snapshot
+
+let doc2 = LoroDoc()
+let snapshot = doc.exportSnapshot()
+let updates = doc.exportFrom(vv: VersionVector())
+
+// import updates or snapshot
+try! doc2.import(snapshot)
+try! doc2.import(updates)
+// import batch of updates or snapshot
+try! doc2.importBatch(bytes: [snapshot, updates])
+
+// checkout to any version
+let startFrontiers = doc.oplogFrontiers()
+try! doc.checkout(frontiers: startFrontiers)
+doc.checkoutToLatest()
+```
+
 ## Develop
 
 If you wanna build and develop this project, you need first run this script:

Sources/Loro/Container.swift

@@ -95,8 +95,6 @@ extension LoroCounter: ContainerLike{}
 extension LoroUnknown: ContainerLike{}
 
 
-
-
 extension LoroList: ContainerLike{
     public func pushContainer(child: ContainerLike) throws -> ContainerLike{
         let idx = self.len()

Sources/Loro/Event.swift

@@ -0,0 +1,35 @@
+
+
+class ClosureSubscriber: Subscriber {
+    private let closure: (DiffEvent) -> Void
+
+    public init(closure: @escaping (DiffEvent) -> Void) {
+        self.closure = closure
+    }
+
+    public func onDiff(diff: DiffEvent) {
+        closure(diff)
+    }
+}
+
+extension LoroDoc{
+    /** Subscribe all the events.
+     *
+     * The callback will be invoked when any part of the [loro_internal::DocState] is changed. 
+     * Returns a subscription id that can be used to unsubscribe.
+     */
+    public func subscribeRoot(callback: @escaping (DiffEvent)->Void) -> SubId {
+        let closureSubscriber = ClosureSubscriber(closure: callback)
+        return self.subscribeRoot(subscriber: closureSubscriber)
+    }
+
+    /** Subscribe the events of a container.
+     *
+     * The callback will be invoked when the container is changed.
+     * Returns a subscription id that can be used to unsubscribe.
+     */
+     public func subscribe(containerId: ContainerId, callback: @escaping (DiffEvent)->Void) -> SubId {
+        let closureSubscriber = ClosureSubscriber(closure: callback)
+        return self.subscribe(containerId: containerId, subscriber: closureSubscriber)
+    }
+}

Sources/Loro/LoroFFI.swift

@@ -4208,14 +4208,14 @@ public func FfiConverterTypeLoroValueLike_lower(_ value: LoroValueLike) -> Unsaf
 
 
 
-public protocol SubscriberProtocol : AnyObject {
+public protocol Subscriber : AnyObject {
 
     func onDiff(diff: DiffEvent) 
 
 }
 
-open class Subscriber:
-    SubscriberProtocol {
+open class SubscriberImpl:
+    Subscriber {
     fileprivate let pointer: UnsafeMutableRawPointer!
 
     /// Used to instantiate a [FFIObject] without an actual pointer, for fakes in tests, mostly.
@@ -4265,17 +4265,65 @@ open func onDiff(diff: DiffEvent) {try! rustCall() {
 
 }
 
+
+// Put the implementation in a struct so we don't pollute the top-level namespace
+fileprivate struct UniffiCallbackInterfaceSubscriber {
+
+    // Create the VTable using a series of closures.
+    // Swift automatically converts these into C callback functions.
+    static var vtable: UniffiVTableCallbackInterfaceSubscriber = UniffiVTableCallbackInterfaceSubscriber(
+        onDiff: { (
+            uniffiHandle: UInt64,
+            diff: RustBuffer,
+            uniffiOutReturn: UnsafeMutableRawPointer,
+            uniffiCallStatus: UnsafeMutablePointer<RustCallStatus>
+        ) in
+            let makeCall = {
+                () throws -> () in
+                guard let uniffiObj = try? FfiConverterTypeSubscriber.handleMap.get(handle: uniffiHandle) else {
+                    throw UniffiInternalError.unexpectedStaleHandle
+                }
+                return uniffiObj.onDiff(
+                     diff: try FfiConverterTypeDiffEvent.lift(diff)
+                )
+            }
+
+            
+            let writeReturn = { () }
+            uniffiTraitInterfaceCall(
+                callStatus: uniffiCallStatus,
+                makeCall: makeCall,
+                writeReturn: writeReturn
+            )
+        },
+        uniffiFree: { (uniffiHandle: UInt64) -> () in
+            let result = try? FfiConverterTypeSubscriber.handleMap.remove(handle: uniffiHandle)
+            if result == nil {
+                print("Uniffi callback interface Subscriber: handle missing in uniffiFree")
+            }
+        }
+    )
+}
+
+private func uniffiCallbackInitSubscriber() {
+    uniffi_loro_fn_init_callback_vtable_subscriber(&UniffiCallbackInterfaceSubscriber.vtable)
+}
+
 public struct FfiConverterTypeSubscriber: FfiConverter {
+    fileprivate static var handleMap = UniffiHandleMap<Subscriber>()
 
     typealias FfiType = UnsafeMutableRawPointer
     typealias SwiftType = Subscriber
 
     public static func lift(_ pointer: UnsafeMutableRawPointer) throws -> Subscriber {
-        return Subscriber(unsafeFromRawPointer: pointer)
+        return SubscriberImpl(unsafeFromRawPointer: pointer)
     }
 
     public static func lower(_ value: Subscriber) -> UnsafeMutableRawPointer {
-        return value.uniffiClonePointer()
+        guard let ptr = UnsafeMutableRawPointer(bitPattern: UInt(truncatingIfNeeded: handleMap.insert(obj: value))) else {
+            fatalError("Cast to UnsafeMutableRawPointer failed")
+        }
+        return ptr
     }
 
     public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> Subscriber {
@@ -6830,10 +6878,10 @@ private var initializationResult: InitializationResult = {
     if (uniffi_loro_checksum_method_lorodoc_state_vv() != 1627) {
         return InitializationResult.apiChecksumMismatch
     }
-    if (uniffi_loro_checksum_method_lorodoc_subscribe() != 56858) {
+    if (uniffi_loro_checksum_method_lorodoc_subscribe() != 28252) {
         return InitializationResult.apiChecksumMismatch
     }
-    if (uniffi_loro_checksum_method_lorodoc_subscribe_root() != 41210) {
+    if (uniffi_loro_checksum_method_lorodoc_subscribe_root() != 7800) {
         return InitializationResult.apiChecksumMismatch
     }
     if (uniffi_loro_checksum_method_lorodoc_unsubscribe() != 32901) {
@@ -7124,7 +7172,7 @@ private var initializationResult: InitializationResult = {
     if (uniffi_loro_checksum_method_lorovaluelike_as_loro_value() != 23668) {
         return InitializationResult.apiChecksumMismatch
     }
-    if (uniffi_loro_checksum_method_subscriber_on_diff() != 56592) {
+    if (uniffi_loro_checksum_method_subscriber_on_diff() != 462) {
         return InitializationResult.apiChecksumMismatch
     }
     if (uniffi_loro_checksum_method_valueorcontainer_as_container() != 61163) {
@@ -7178,6 +7226,7 @@ private var initializationResult: InitializationResult = {
 
     uniffiCallbackInitContainerIdLike()
     uniffiCallbackInitLoroValueLike()
+    uniffiCallbackInitSubscriber()
     return InitializationResult.ok
 }()
 

Tests/LoroTests/LoroTests.swift

@@ -2,14 +2,55 @@ import XCTest
 @testable import Loro
 
 final class LoroTests: XCTestCase {
-    func testExample() throws {
-        // XCTest Documentation
-        // https://developer.apple.com/documentation/xctest
-
-        // Defining Test Cases and Test Methods
-        // https://developer.apple.com/documentation/xctest/defining_test_cases_and_test_methods
+    func testEvent(){
+        let doc = LoroDoc()
+        var num = 0
+        let id = doc.subscribeRoot{ diffEvent in
+            num += 1
+        }
+        let list = doc.getList(id: "list")
+        try! list.insert(pos: 0, v: 123)
+        doc.commit()
+        XCTAssertEqual(num, 1)
+        doc.unsubscribe(subId: id)
+    }
+    
+    func testText(){
+        let doc = LoroDoc()
+        let text = doc.getText(id: "text")
+        try! text.insert(pos: 0, s: "abc")
+        try! text.delete(pos: 0, len: 1)
+        let s = text.toString()
+        XCTAssertEqual(s, "bc")
+    }
+    
+    func testSync(){
+        let doc = LoroDoc()
+        try! doc.setPeerId(peer: 0)
+        let text = doc.getText(id: "text")
+        try! text.insert(pos: 0, s: "abc")
+        try! text.delete(pos: 0, len: 1)
+        let s = text.toString()
+        XCTAssertEqual(s, "bc")
+        
+        let doc2 = LoroDoc()
+        try! doc2.setPeerId(peer: 1)
+        let text2 = doc2.getText(id: "text")
+        try! text2.insert(pos: 0, s:"123")
+        try! doc2.import(bytes: doc.exportSnapshot())
+        try! doc2.importBatch(bytes: [doc.exportSnapshot(), doc.exportFrom(vv: VersionVector())])
+        XCTAssertEqual(text2.toString(), "bc123")
+    }
+    
+    func testCheckout(){
         let doc = LoroDoc()
-        try! doc.setPeerId(peer: 12)
-        assert(doc.peerId()==12)
+        try! doc.setPeerId(peer: 0)
+        let text = doc.getText(id: "text")
+        try! text.insert(pos: 0, s: "abc")
+        try! text.delete(pos: 0, len: 1)
+        
+        let startFrontiers = doc.oplogFrontiers()
+        try! doc.checkout(frontiers: startFrontiers)
+        doc.checkoutToLatest()
     }
 }

loro-rs/src/loro.udl

@@ -22,6 +22,11 @@ interface ContainerIdLike{
     ContainerID as_container_id(ContainerType ty);
 };
 
+[Trait, WithForeign]
+interface Subscriber{
+    void on_diff(DiffEvent diff);
+};
+
 // ============= LORO DOC =============
 
 interface LoroDoc{
@@ -725,11 +730,6 @@ interface Frontiers{
 
 // ============= EVENTS =============
 
-[Trait]
-interface Subscriber{
-    void on_diff(DiffEvent diff);
-};
-
 dictionary DiffEvent{
     /// How the event is triggered.
     EventTriggerKind triggered_by;

scripts/build_swift_ffi.sh

@@ -101,7 +101,7 @@ $cargo_build --target wasm32-wasi --locked --release
 mkdir -p "${BUILD_FOLDER}/includes"
 cp "${SWIFT_FOLDER}/loroFFI.h" "${BUILD_FOLDER}/includes"
 cp "${SWIFT_FOLDER}/loroFFI.modulemap" "${BUILD_FOLDER}/includes/module.modulemap"
-cp "${SWIFT_FOLDER}/loro.swift" "${THIS_SCRIPT_DIR}/../Sources/Loro/LoroFFI.swift"
+cp -f "${SWIFT_FOLDER}/loro.swift" "${THIS_SCRIPT_DIR}/../Sources/Loro/LoroFFI.swift"
 
 echo "▸ Lipo (merge) x86 and arm simulator static libraries into a fat static binary"
 mkdir -p "${BUILD_FOLDER}/ios-simulator/release"