Support cursors at end of document

.github/workflows/ci.yaml

@@ -26,7 +26,7 @@ jobs:
             automergeFFI.xcframework.zip
             libuniffi_automerge.a
             libuniffi_automerge_threads.a
-          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(rust/Cargo.lock) }}
+          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(AutomergeUniffi/automergeFFI.h) }}-{{ hashFiles(rust/Cargo.lock) }}-{{ hashFiles(rust/src/doc.rs) }}
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
@@ -63,7 +63,7 @@ jobs:
             automergeFFI.xcframework.zip
             libuniffi_automerge.a
             libuniffi_automerge_threads.a
-          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(rust/Cargo.lock) }}
+          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(AutomergeUniffi/automergeFFI.h) }}-{{ hashFiles(rust/Cargo.lock) }}-{{ hashFiles(rust/src/doc.rs) }}
       - name: Get swift version
         run: swift --version
       - name: Swift tests
@@ -91,7 +91,7 @@ jobs:
             automergeFFI.xcframework.zip
             libuniffi_automerge.a
             libuniffi_automerge_threads.a
-          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(rust/Cargo.lock) }}
+          key: automerge-dependencies-{{ hashFiles(AutomergeUniffi/automerge.swift) }}-{{ hashFiles(AutomergeUniffi/automergeFFI.h) }}-{{ hashFiles(rust/Cargo.lock) }}-{{ hashFiles(rust/src/doc.rs) }}
       - name: Cache Toolchain for WebAssembly
         id: cache-wasm-toolchain
         uses: actions/cache@v4

AutomergeUniffi/automerge.swift

@@ -773,8 +773,7 @@ open class Doc:
         try FfiConverterSequenceTypePatch.lift(rustCallWithError(FfiConverterTypeDocError.lift) {
             uniffi_uniffi_automerge_fn_method_doc_apply_encoded_changes_with_patches(
                 self.uniffiClonePointer(),
-                FfiConverterSequenceUInt8
-                    .lower(changes),
+                FfiConverterSequenceUInt8.lower(changes),
                 $0
             )
         })
@@ -1313,8 +1312,7 @@ open class Doc:
         try FfiConverterSequenceTypePatch.lift(rustCallWithError(FfiConverterTypeReceiveSyncError.lift) {
             uniffi_uniffi_automerge_fn_method_doc_receive_sync_message_with_patches(
                 self.uniffiClonePointer(),
-                FfiConverterTypeSyncState
-                    .lower(state),
+                FfiConverterTypeSyncState.lower(state),
                 FfiConverterSequenceUInt8.lower(msg),
                 $0
             )

Sources/Automerge/Automerge.docc/Curation/Document.md

@@ -62,9 +62,9 @@
 ### Setting and Reading cursors
 
 - ``cursor(obj:position:)``
-- ``cursorAt(obj:position:heads:)``
-- ``cursorPosition(obj:cursor:)``
-- ``cursorPositionAt(obj:cursor:heads:)``
+- ``cursor(obj:position:heads:)``
+- ``position(obj:cursor:)``
+- ``position(obj:cursor:heads:)``
 
 ### Updating counters
 

Sources/Automerge/Automerge.docc/ModelingData.md

@@ -120,9 +120,9 @@ See the documentation for ``Document`` for more detail on the individual methods
 ### Setting and Reading cursors
 
 - ``Automerge/Document/cursor(obj:position:)``
-- ``Automerge/Document/cursorAt(obj:position:heads:)``
-- ``Automerge/Document/cursorPosition(obj:cursor:)``
-- ``Automerge/Document/cursorPositionAt(obj:cursor:heads:)``
+- ``Automerge/Document/cursor(obj:position:heads:)``
+- ``Automerge/Document/position(obj:cursor:)``
+- ``Automerge/Document/position(obj:cursor:heads:)``
 
 ### Updating counters
 

Sources/Automerge/Cursor.swift

@@ -5,10 +5,10 @@ typealias FfiPosition = AutomergeUniffi.Position
 /// A opaque type that represents a location within an array or text object that adjusts with insertions and deletes to
 /// maintain its relative position.
 ///
-/// Set a cursor using ``Document/cursor(obj:position:)``, or ``Document/cursorAt(obj:position:heads:)`` to place a
+/// Set a cursor using ``Document/cursor(obj:position:)``, or ``Document/cursor(obj:position:heads:)`` to place a
 /// cursor at a previous point in time.
-/// Retrieve the cursor position from the document using ``Document/cursorPosition(obj:cursor:)``, or use
-/// ``Document/cursorPositionAt(obj:cursor:heads:)`` to get the cursor position at a previous point in time.
+/// Retrieve the cursor position from the document using ``Document/position(obj:cursor:)``, or use
+/// ``Document/position(obj:cursor:heads:)`` to get the cursor position at a previous point in time.
 public struct Cursor: Equatable, Hashable, Sendable {
     var bytes: [UInt8]
 }
@@ -24,7 +24,7 @@ extension Cursor: CustomStringConvertible {
 ///
 /// ### See Also
 /// - ``Document/cursor(obj:position:)``
-/// - ``Document/cursorAt(obj:position:heads:)``
+/// - ``Document/cursor(obj:position:heads:)``
 public enum Position {
     case cursor(Cursor)
     case index(UInt64)

Sources/Automerge/Document.swift

@@ -582,10 +582,34 @@ public final class Document: @unchecked Sendable {
 
     /// Establish a cursor at the position you specify in the list or text object you provide.
     ///
+    /// In collaborative applications, maintaining stable cursor positions is crucial. Traditional index-based
+    /// positions can become outdated due to document modifications. This method ensures the cursor stays
+    /// correctly anchored regardless of changes.
+    ///
+    /// `Cursor` provides a reliable way to track positions over time without being affected by document changes.
+    /// The cursor remains anchored to the following character, and if placed at the end of the document,
+    /// it will persistently stay attached to the end.
+    ///
+    /// ```swift
+    /// "ABC"   // scenario
+    /// "A|BC"  // set cursor at `1`, cursor is attached to `B`
+    /// "AZ|BC" // insert `Z` at `1`
+    /// ```
+    ///
+    /// To retrieve the original absolute index-based positions, use:
+    /// - ``position(obj:cursor:)``
+    /// - ``position(obj:cursor:heads:)``
+    ///
     /// - Parameters:
     ///   - obj: The object identifier of the list or text object.
     ///   - position: The index position in the list, or index for a text object based on ``TextEncoding``.
+    ///     When using a position equal to or greater than the current length of the object,
+    ///     the cursor will track the end of the document as it changes.
     /// - Returns: A cursor that references the position you specified.
+    ///
+    /// ### See Also
+    /// ``cursor(obj:position:heads:)``
+    ///
     public func cursor(obj: ObjId, position: UInt64) throws -> Cursor {
         try lock {
             sendObjectWillChange()
@@ -596,12 +620,36 @@ public final class Document: @unchecked Sendable {
 
     /// Establish a cursor at the position and point of time you specify in the list or text object you provide.
     ///
+    /// In collaborative applications, maintaining stable cursor positions is crucial. Traditional index-based
+    /// positions can become outdated due to document modifications. This method ensures the cursor stays
+    /// correctly anchored regardless of changes.
+    ///
+    /// `Cursor` provides a reliable way to track positions over time without being affected by document changes.
+    /// The cursor remains anchored to the following character, and if placed at the end of the document,
+    /// it will persistently stay attached to the end.
+    ///
+    /// ```swift
+    /// "ABC"   // scenario
+    /// "A|BC"  // set cursor at `1`, cursor is attached to `B`
+    /// "AZ|BC" // insert `Z` at `1`
+    /// ```
+    ///
+    /// To retrieve the original absolute index-based positions, use:
+    /// - ``position(obj:cursor:)``
+    /// - ``position(obj:cursor:heads:)``
+    ///
     /// - Parameters:
     ///   - obj: The object identifier of the list or text object.
     ///   - position: The index position in the list, or index for a text object based on ``TextEncoding``.
+    ///     When using a position equal to or greater than the object's length at the specified point in time,
+    ///     the cursor will track the end of the document as it changes.
     ///   - heads: The set of ``ChangeHash`` that represents a point of time in the history the document.
     /// - Returns: A cursor that references the position and point in time you specified.
-    public func cursorAt(obj: ObjId, position: UInt64, heads: Set<ChangeHash>) throws -> Cursor {
+    ///
+    /// ### See Also
+    /// ``cursor(obj:position:)``
+    ///
+    public func cursor(obj: ObjId, position: UInt64, heads: Set<ChangeHash>) throws -> Cursor {
         try lock {
             sendObjectWillChange()
             defer { sendObjectDidChange() }
@@ -613,28 +661,44 @@ public final class Document: @unchecked Sendable {
         }
     }
 
-    /// The current position of the cursor for the list or text object you provide.
+    /// Retrieves the absolute index-based position for the list or text object you provide.
+    ///
+    /// While cursors provide stable positions in a collaborative environment, this method allows you to convert
+    /// a cursor back into an absolute index-based position.
     ///
     /// - Parameters:
     ///   - obj: The object identifier of the list or text object.
     ///   - cursor: The cursor created for this list or text object
     /// - Returns: The index position of a list, or index for a text object based on ``TextEncoding``, of the cursor.
-    public func cursorPosition(obj: ObjId, cursor: Cursor) throws -> UInt64 {
+    ///
+    /// ### See Also
+    /// ``cursor(obj:position:)``
+    /// ``cursor(obj:position:heads:)``
+    ///
+    public func position(obj: ObjId, cursor: Cursor) throws -> UInt64 {
         try lock {
             try self.doc.wrapErrors {
                 try $0.cursorPosition(obj: obj.bytes, cursor: cursor.bytes)
             }
         }
     }
 
-    /// The historical position of the cursor for the list or text object and point in time you provide.
+    /// Retrieves the absolute index-based position for the list or text object and point in time you provide.
+    ///
+    /// While cursors provide stable positions in a collaborative environment, this method allows you to convert
+    /// a cursor back into an absolute index-based position.
     ///
     /// - Parameters:
     ///   - obj: The object identifier of the list or text object.
     ///   - cursor: The cursor created for this list or text object
     ///   - heads: The set of ``ChangeHash`` that represents a point of time in the history the document.
     /// - Returns: The index position of a list, or index for a text object based on ``TextEncoding``, of the cursor.
-    public func cursorPositionAt(obj: ObjId, cursor: Cursor, heads: Set<ChangeHash>) throws -> UInt64 {
+    ///
+    /// ### See Also
+    /// ``cursor(obj:position:)``
+    /// ``cursor(obj:position:heads:)``
+    ///
+    public func position(obj: ObjId, cursor: Cursor, heads: Set<ChangeHash>) throws -> UInt64 {
         try lock {
             try self.doc.wrapErrors {
                 try $0.cursorPositionAt(obj: obj.bytes, cursor: cursor.bytes, heads: heads.map(\.bytes))

Tests/AutomergeTests/TestText.swift

@@ -45,28 +45,40 @@ class TextTestCase: XCTestCase {
         let heads = doc.heads()
 
         let c_hello = try! doc.cursor(obj: text, position: 0)
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_hello), 0)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_hello), 0)
 
         let c_world = try! doc.cursor(obj: text, position: 6)
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_world), 6)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_world), 6)
 
         try doc.spliceText(obj: text, start: 6, delete: 0, value: "wonderful ")
         XCTAssertEqual(try! doc.text(obj: text), "hello wonderful world!")
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_hello), 0)
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_world), 16)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_hello), 0)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_world), 16)
 
         try doc.spliceText(obj: text, start: 0, delete: 5, value: "Greetings")
         XCTAssertEqual(try! doc.text(obj: text), "Greetings wonderful world!")
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_hello), 9)
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_world), 20)
-        XCTAssertEqual(try! doc.cursorPositionAt(obj: text, cursor: c_world, heads: heads), 6)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_hello), 9)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_world), 20)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_world, heads: heads), 6)
 
         // let's time travel with cursor
-        let c_heads_world = try! doc.cursorAt(obj: text, position: 6, heads: heads)
-        XCTAssertEqual(try! doc.cursorPosition(obj: text, cursor: c_heads_world), 20)
+        let c_heads_world = try! doc.cursor(obj: text, position: 6, heads: heads)
+        XCTAssertEqual(try! doc.position(obj: text, cursor: c_heads_world), 20)
         XCTAssertEqual(c_heads_world.description, c_world.description)
     }
 
+    func testCursorAtEndDocument() throws {
+        let doc = Document(textEncoding: .graphemeCluster)
+        let text = try! doc.putObject(obj: ObjId.ROOT, key: "text", ty: .Text)
+
+        try doc.spliceText(obj: text, start: 0, delete: 0, value: "hello world!")
+        let c_hello = try! doc.cursor(obj: text, position: doc.length(obj: text))
+        try doc.spliceText(obj: text, start: doc.length(obj: text), delete: 0, value: "🏡🧑‍🧑‍🧒‍🧒")
+
+        let position = try! doc.position(obj: text, cursor: c_hello)
+        XCTAssertEqual(position, UInt64("hello world!🏡🧑‍🧑‍🧒‍🧒".count))
+    }
+
     func testRepeatedTextInsertion() throws {
         let characterCollection: [String] =
             "a bcdef ghijk lmnop qrstu vwxyz ABCD EFGHI JKLMN OPQRS TUVWX YZ😀😎🤓⚁ ♛⛺︎🕰️⏰⏲️ ⏱️🧭".map { char in

rust/src/doc.rs

@@ -1,7 +1,6 @@
 use std::sync::{Arc, RwLock, RwLockWriteGuard};
 
-use am::sync::SyncDoc;
-use automerge as am;
+use automerge::{self as am, sync::SyncDoc, CursorPosition};
 use automerge::{transaction::Transactable, ReadDoc};
 
 use crate::actor_id::ActorId;
@@ -346,7 +345,15 @@ impl Doc {
     pub fn cursor(&self, obj: ObjId, position: u64) -> Result<Cursor, DocError> {
         let obj = am::ObjId::from(obj);
         let doc = self.0.read().unwrap();
-        Ok(doc.get_cursor(obj, position as usize, None)?.into())
+        let index = position as usize;
+        let position = if index >= doc.length(&obj) {
+            CursorPosition::End
+        } else {
+            CursorPosition::Index(index)
+        };
+        doc.get_cursor(&obj, position, None)
+            .map(|c| c.into())
+            .map_err(|error| DocError::Internal(error))
     }
 
     pub fn cursor_at(
@@ -361,7 +368,15 @@ impl Doc {
             .into_iter()
             .map(am::ChangeHash::from)
             .collect::<Vec<_>>();
-        Ok(doc.get_cursor(obj, position as usize, Some(&heads))?.into())
+        let index = position as usize;
+        let cursor_position = if index >= doc.length(&obj) {
+            CursorPosition::End
+        } else {
+            CursorPosition::Index(index)
+        };
+        doc.get_cursor(&obj, cursor_position, Some(&heads))
+            .map(|c| c.into())
+            .map_err(|error| DocError::Internal(error))
     }
 
     pub fn cursor_position(&self, obj: ObjId, cursor: Cursor) -> Result<u64, DocError> {