y-rb 0.2.0 → 0.3.1

data/ext/yrb/src/yxml_element.rs

@@ -23,45 +23,39 @@ impl YXmlElement {
     pub(crate) fn yxml_element_get(&self, index: u32) -> Option<Value> {
         self.0.borrow().get(index).map(|node| match node {
             Xml::Element(el) => Value::from(YXmlElement(RefCell::from(el))),
-            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text)))
+            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text))),
         })
     }
-    pub(crate) fn yxml_element_get_attribute(
-        &self,
-        name: String
-    ) -> Option<String> {
+    pub(crate) fn yxml_element_get_attribute(&self, name: String) -> Option<String> {
         self.0.borrow().get_attribute(&*name)
     }
     pub(crate) fn yxml_element_insert_attribute(
         &self,
         transaction: &YTransaction,
         name: String,
-        value: String
+        value: String,
     ) {
-        self.0.borrow_mut().insert_attribute(
-            &mut *transaction.0.borrow_mut(),
-            name,
-            value
-        );
+        self.0
+            .borrow_mut()
+            .insert_attribute(&mut *transaction.0.borrow_mut(), name, value);
     }
     pub(crate) fn yxml_element_insert_element(
         &self,
         transaction: &YTransaction,
         index: u32,
-        name: String
+        name: String,
     ) -> YXmlElement {
-        let element = self.0.borrow_mut().insert_elem(
-            &mut *transaction.0.borrow_mut(),
-            index,
-            name
-        );
+        let element =
+            self.0
+                .borrow_mut()
+                .insert_elem(&mut *transaction.0.borrow_mut(), index, name);
 
         YXmlElement(RefCell::from(element))
     }
     pub(crate) fn yxml_element_insert_text(
         &self,
         transaction: &YTransaction,
-        index: u32
+        index: u32,
     ) -> YXmlText {
         let text = self
             .0
@@ -73,19 +67,18 @@ impl YXmlElement {
     pub(crate) fn yxml_element_next_sibling(&self) -> Option<Value> {
         self.0.borrow().next_sibling().map(|item| match item {
             Xml::Element(el) => Value::from(YXmlElement(RefCell::from(el))),
-            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text)))
+            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text))),
         })
     }
-    pub(crate) fn yxml_element_observe(
-        &self,
-        block: Proc
-    ) -> Result<u32, Error> {
+    pub(crate) fn yxml_element_observe(&self, block: Proc) -> Result<u32, Error> {
         let change_added = Symbol::new("added").to_static();
         let change_retain = Symbol::new("retain").to_static();
         let change_removed = Symbol::new("removed").to_static();
 
-        let subscription_id = self.0.borrow_mut().observe(
-            move |transaction, xml_element_event| {
+        let subscription_id = self
+            .0
+            .borrow_mut()
+            .observe(move |transaction, xml_element_event| {
                 let delta = xml_element_event.delta(transaction);
                 let changes = RArray::with_capacity(delta.len());
 
@@ -103,9 +96,9 @@ impl YXmlElement {
                                 .aset(change_added, RArray::from_vec(values))
                                 .expect("cannot create change::added payload");
 
-                            changes.push(payload).expect(
-                                "cannot push payload to list of changes"
-                            );
+                            changes
+                                .push(payload)
+                                .expect("cannot push payload to list of changes");
                         }
                         Change::Retain(position) => {
                             let payload = RHash::new();
@@ -113,19 +106,19 @@ impl YXmlElement {
                                 .aset(change_retain, *position)
                                 .expect("cannot create change::retain payload");
 
-                            changes.push(payload).expect(
-                                "cannot push payload to list of changes"
-                            );
+                            changes
+                                .push(payload)
+                                .expect("cannot push payload to list of changes");
                         }
                         Change::Removed(position) => {
                             let payload = RHash::new();
-                            payload.aset(change_removed, *position).expect(
-                                "cannot create change::removed payload"
-                            );
+                            payload
+                                .aset(change_removed, *position)
+                                .expect("cannot create change::removed payload");
 
-                            changes.push(payload).expect(
-                                "cannot push payload to list of changes"
-                            );
+                            changes
+                                .push(payload)
+                                .expect("cannot push payload to list of changes");
                         }
                     }
                 }
@@ -133,8 +126,7 @@ impl YXmlElement {
                 block
                     .call::<(RArray,), Value>((changes,))
                     .expect("cannot call block");
-            }
-        );
+            });
 
         Ok(subscription_id.into())
     }
@@ -147,13 +139,13 @@ impl YXmlElement {
     pub(crate) fn yxml_element_prev_sibling(&self) -> Option<Value> {
         self.0.borrow().prev_sibling().map(|item| match item {
             Xml::Element(el) => Value::from(YXmlElement(RefCell::from(el))),
-            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text)))
+            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text))),
         })
     }
     pub(crate) fn yxml_element_push_element_back(
         &self,
         transaction: &YTransaction,
-        name: String
+        name: String,
     ) -> YXmlElement {
         let xml_element = self
             .0
@@ -165,7 +157,7 @@ impl YXmlElement {
     pub(crate) fn yxml_element_push_element_front(
         &self,
         transaction: &YTransaction,
-        name: String
+        name: String,
     ) -> YXmlElement {
         let xml_element = self
             .0
@@ -174,10 +166,7 @@ impl YXmlElement {
 
         YXmlElement(RefCell::from(xml_element))
     }
-    pub(crate) fn yxml_element_push_text_back(
-        &self,
-        transaction: &YTransaction
-    ) -> YXmlText {
+    pub(crate) fn yxml_element_push_text_back(&self, transaction: &YTransaction) -> YXmlText {
         let xml_text = self
             .0
             .borrow_mut()
@@ -185,10 +174,7 @@ impl YXmlElement {
 
         YXmlText(RefCell::from(xml_text))
     }
-    pub(crate) fn yxml_element_push_text_front(
-        &self,
-        transaction: &YTransaction
-    ) -> YXmlText {
+    pub(crate) fn yxml_element_push_text_front(&self, transaction: &YTransaction) -> YXmlText {
         let xml_text = self
             .0
             .borrow_mut()
@@ -196,27 +182,20 @@ impl YXmlElement {
 
         YXmlText(RefCell::from(xml_text))
     }
-    pub(crate) fn yxml_element_remove_attribute(
-        &self,
-        transaction: &YTransaction,
-        name: String
-    ) {
-        self.0.borrow_mut().remove_attribute::<&str>(
-            &mut *transaction.0.borrow_mut(),
-            &name.as_str()
-        );
+    pub(crate) fn yxml_element_remove_attribute(&self, transaction: &YTransaction, name: String) {
+        self.0
+            .borrow_mut()
+            .remove_attribute::<&str>(&mut *transaction.0.borrow_mut(), &name.as_str());
     }
     pub(crate) fn yxml_element_remove_range(
         &self,
         transaction: &YTransaction,
         index: u32,
-        length: u32
+        length: u32,
     ) {
-        self.0.borrow_mut().remove_range(
-            &mut *transaction.0.borrow_mut(),
-            index,
-            length
-        );
+        self.0
+            .borrow_mut()
+            .remove_range(&mut *transaction.0.borrow_mut(), index, length);
     }
     pub(crate) fn yxml_element_size(&self) -> u32 {
         self.0.borrow().len()

data/ext/yrb/src/yxml_text.rs

@@ -21,53 +21,38 @@ impl YXmlText {
         transaction: &YTransaction,
         index: u32,
         length: u32,
-        attrs: RHash
+        attrs: RHash,
     ) -> Result<(), Error> {
         map_rhash_to_attrs(attrs).map(|a| {
-            self.0.borrow_mut().format(
-                &mut *transaction.0.borrow_mut(),
-                index,
-                length,
-                a
-            );
+            self.0
+                .borrow_mut()
+                .format(&mut *transaction.0.borrow_mut(), index, length, a);
         })
     }
-    pub(crate) fn yxml_text_get_attribute(
-        &self,
-        name: String
-    ) -> Option<String> {
+    pub(crate) fn yxml_text_get_attribute(&self, name: String) -> Option<String> {
         self.0.borrow().get_attribute(&*name)
     }
-    pub(crate) fn yxml_text_insert(
-        &self,
-        transaction: &YTransaction,
-        index: u32,
-        content: String
-    ) {
-        self.0.borrow_mut().insert(
-            &mut *transaction.0.borrow_mut(),
-            index,
-            &*content
-        )
+    pub(crate) fn yxml_text_insert(&self, transaction: &YTransaction, index: u32, content: String) {
+        self.0
+            .borrow_mut()
+            .insert(&mut *transaction.0.borrow_mut(), index, &*content)
     }
     pub(crate) fn yxml_text_insert_attribute(
         &self,
         transaction: &YTransaction,
         name: String,
-        value: String
+        value: String,
     ) {
-        self.0.borrow_mut().insert_attribute(
-            &mut *transaction.0.borrow_mut(),
-            name,
-            value
-        )
+        self.0
+            .borrow_mut()
+            .insert_attribute(&mut *transaction.0.borrow_mut(), name, value)
     }
     pub(crate) fn yxml_text_insert_embed_with_attributes(
         &self,
         transaction: &YTransaction,
         index: u32,
         content: Value,
-        attrs: RHash
+        attrs: RHash,
     ) -> Result<(), Error> {
         let yvalue = YValue::from(content);
         let avalue = Any::from(yvalue);
@@ -77,7 +62,7 @@ impl YXmlText {
                 &mut *transaction.0.borrow_mut(),
                 index,
                 avalue,
-                a
+                a,
             );
         })
     }
@@ -85,12 +70,12 @@ impl YXmlText {
         &self,
         transaction: &YTransaction,
         index: u32,
-        embed: Value
+        embed: Value,
     ) {
         self.0.borrow_mut().insert_embed(
             &mut *transaction.0.borrow_mut(),
             index,
-            Any::from(YValue::from(embed))
+            Any::from(YValue::from(embed)),
         )
     }
     pub(crate) fn yxml_text_insert_with_attributes(
@@ -98,14 +83,14 @@ impl YXmlText {
         transaction: &YTransaction,
         index: u32,
         content: String,
-        attrs: RHash
+        attrs: RHash,
     ) -> Result<(), Error> {
         map_rhash_to_attrs(attrs).map(|a| {
             self.0.borrow_mut().insert_with_attributes(
                 &mut *transaction.0.borrow_mut(),
                 index,
                 &*content,
-                a
+                a,
             );
         })
     }
@@ -115,7 +100,7 @@ impl YXmlText {
     pub(crate) fn yxml_text_next_sibling(&self) -> Option<Value> {
         self.0.borrow().next_sibling().map(|item| match item {
             Xml::Element(el) => Value::from(YXmlElement(RefCell::from(el))),
-            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text)))
+            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text))),
         })
     }
     pub(crate) fn yxml_text_parent(&self) -> Option<Value> {
@@ -127,14 +112,10 @@ impl YXmlText {
     pub(crate) fn yxml_text_prev_sibling(&self) -> Option<Value> {
         self.0.borrow().prev_sibling().map(|item| match item {
             Xml::Element(el) => Value::from(YXmlElement(RefCell::from(el))),
-            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text)))
+            Xml::Text(text) => Value::from(YXmlText(RefCell::from(text))),
         })
     }
-    pub(crate) fn yxml_text_push(
-        &self,
-        transaction: &YTransaction,
-        content: String
-    ) {
+    pub(crate) fn yxml_text_push(&self, transaction: &YTransaction, content: String) {
         self.0
             .borrow_mut()
             .push(&mut *transaction.0.borrow_mut(), &*content)
@@ -143,13 +124,11 @@ impl YXmlText {
         &self,
         transaction: &YTransaction,
         index: u32,
-        length: u32
+        length: u32,
     ) {
-        self.0.borrow_mut().remove_range(
-            &mut *transaction.0.borrow_mut(),
-            index,
-            length
-        );
+        self.0
+            .borrow_mut()
+            .remove_range(&mut *transaction.0.borrow_mut(), index, length);
     }
     pub(crate) fn yxml_text_to_s(&self) -> String {
         self.0.borrow().to_string()

data/lib/y/array.rb

@@ -20,6 +20,8 @@ module Y
   #
   #   array.to_a == [1, 2, 3, 4, 5] # true
   class Array
+    include Enumerable
+
     # @!attribute [r] document
     #
     # @return [Y::Doc] The document this array belongs to

data/lib/y/awareness.rb

@@ -1,53 +1,172 @@
 # frozen_string_literal: true
 
 module Y
+  # The Awareness class implements a simple shared state protocol that can be
+  # used for non-persistent data like awareness information (cursor, username,
+  # status, ..). Each client can update its own local state and listen to state
+  # changes of remote clients.
+  #
+  # Each client is identified by a unique client id (something we borrow from
+  # doc.client_id). A client can override its own state by propagating a message
+  # with an increasing timestamp (clock). If such a message is received, it is
+  # applied if the known state of that client is older than the new state
+  # (`clock < new_clock`). If a client thinks that a remote client is offline,
+  # it may propagate a message with `{ clock, state: null, client }`. If such a
+  # message is received, and the known clock of that client equals the received
+  # clock, it will clean the state.
+  #
+  # Before a client disconnects, it should propagate a null state with an
+  # updated clock.
+  #
+  # Awareness is an integral part of collaborative applications, you can read
+  # more about the concept here: https://docs.yjs.dev/getting-started/adding-awareness
+  #
+  # @example Instantiate awareness instance and encode update for broadcast
+  #   local_state = {
+  #     editing: { field: "description", pos: 0 },
+  #     name: "Hannes Moser"
+  #   }.to_json
+  #
+  #   awareness = Y::Awareness.new
+  #   awareness.local_state = local_state
+  #   awareness.diff # [1,227,245,175,195,11,1,65,123, …]
+  #
+  #
   class Awareness
-    def apply_update(update)
-      yawareness_apply_update(update)
+    # Applies an incoming update. This gets the local awareness instance in
+    # sync with changes from another client. i.e., updates the state of another
+    # user in the local awareness instance.
+    #
+    # @example Apply an incoming update
+    #   update = [1,227,245,175,195,11,1,65,123, …]
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.sync(update)
+    #
+    # @param [Array<Integer>] diff A binary encoded update
+    # @return [void]
+    def sync(diff)
+      yawareness_apply_update(diff)
     end
 
+    # Clears out a state of a current client, effectively marking it as
+    # disconnected.
+    #
+    # @return [void]
     def clean_local_state
       yawareness_clean_local_state
     end
 
+    # Returns a globally unique client ID of an underlying Doc.
+    #
+    # @return [Integer] Returns the client_id of the local user
     def client_id
       yawareness_client_id
     end
 
+    # Returns a state map of all of the clients tracked by current Awareness
+    # instance. Those states are identified by their corresponding ClientIDs.
+    # The associated state is represented and replicated to other clients as a
+    # JSON string.
+    #
+    # @example Instantiate awareness instance and encode update for broadcast
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #   awareness.clients # {312134501=>"{\"editing\":{\"field\":\"descriptio …
+    #
+    # @return [Hash] All clients and their current state
     def clients
       yawareness_clients
     end
 
+    # Returns a JSON string state representation of a current Awareness
+    # instance.
+    #
+    # @example Create local state and inspect it
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #   local_state # "{\"editing\":{\"field\":\"description\",\"pos\":0}, …
+    #
+    # @return [String] The current state of the local client
     def local_state
       yawareness_local_state
     end
 
+    # Sets a current Awareness instance state to a corresponding JSON string.
+    # This state will be replicated to other clients as part of the
+    # AwarenessUpdate.
+    #
+    # @example Set local state
+    #   local_state = {
+    #     editing: { field: "description", pos: 0 },
+    #     name: "Hannes Moser"
+    #   }.to_json
+    #
+    #   awareness = Y::Awareness.new
+    #   awareness.local_state = local_state
+    #
+    # @return [void]
     def local_state=(json)
       yawareness_set_local_state(json)
     end
 
+    # Subscribes to changes
+    #
+    # @return [Integer] The subscription ID
     def attach(callback, &block)
       return yawareness_on_update(callback) unless callback.nil?
 
       yawareness_on_update(block.to_proc) unless block.nil?
     end
 
+    # Unsubscribe from changes
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
     def detach(subscription_id)
       yawareness_remove_on_update(subscription_id)
     end
 
+    # Clears out a state of a given client, effectively marking it as
+    # disconnected.
+    #
+    # @param [Integer] client_id Clears the state for given client_id
+    # @return [void]
     def remove_state(client_id)
       yawareness_remove_state(client_id)
     end
 
-    def update
+    # Returns a serializable update object which is representation of a current
+    # Awareness state.
+    #
+    # @return [::Array<Integer>] Binary encoded update of the local instance
+    def diff
       yawareness_update
     end
 
-    def update_with_clients(clients)
+    # Returns a serializable update object which is representation of a current
+    # Awareness state. Unlike Awareness::update, this method variant allows to
+    # prepare update only for a subset of known clients. These clients must all
+    # be known to a current Awareness instance, otherwise a
+    # Error::ClientNotFound error will be returned.
+    #
+    # @param [::Array<Integer>] clients A list of client IDs
+    # @return [String] Binary encoded update including all given client IDs
+    def diff_with_clients(*clients)
       yawareness_update_with_clients(clients)
     end
 
+    # rubocop:disable Lint/UselessAccessModifier
     private
 
     # @!method yawareness_apply_update(update)
@@ -56,6 +175,12 @@ module Y
     # @param [Y::AwarenessUpdate] A structure that represents an encodable state
     #   of an Awareness struct.
 
+    # @!method yawareness_apply_update(update)
+    #   Applies an update
+    #
+    # @param [Y::AwarenessUpdate] A structure that represents an encodable state
+    #   of an Awareness struct.
+
     # @!method yawareness_clean_local_state
     #   Clears out a state of a current client , effectively marking it as
     #   disconnected.
@@ -90,7 +215,7 @@ module Y
     #   Clears out a state of a given client, effectively marking it as
     #   disconnected.
     #
-    # @param [Integer] A Client ID
+    # @param [Integer] client_id A Client ID
     # @return [String|nil] Returns a JSON string state representation of a
     #   current Awareness instance.
 
@@ -118,35 +243,24 @@ module Y
     #   These clients must all be known to a current Awareness instance,
     #   otherwise an error will be returned.
     #
-    # @param [Array<Integer>]
-    # @return [Y::AwarenessUpdate] The update object
+    # @param [::Array<Integer>] clients
+    # @return [::Array<Integer>] A serialized (binary encoded) update object
+
+    # rubocop:enable Lint/UselessAccessModifier
   end
 
-  # rubocop:disable Lint/EmptyClass
+  # rubocop:disable Lint/UselessAccessModifier
   class AwarenessEvent
     private
 
     # @!method added
-    # @return [Array<Integer>] Added clients
+    # @return [::Array<Integer>] Added clients
 
     # @!method updated
-    # @return [Array<Integer>] Updated clients
+    # @return [::Array<Integer>] Updated clients
 
     # @!method removed
-    # @return [Array<Integer>] Removed clients
-  end
-  # rubocop:enable Lint/EmptyClass
-
-  class AwarenessUpdate
-    def encode
-      yawareness_update_encode
-    end
-
-    private
-
-    # @!method yawareness_update_encode
-    #   Encode the awareness state for simple transport
-    #
-    # @return [Array<Integer>] Encoded update
+    # @return [::Array<Integer>] Removed clients
   end
+  # rubocop:enable Lint/UselessAccessModifier
 end

data/lib/y/doc.rb

@@ -113,7 +113,7 @@ module Y
     # @return [Y::XMLElement]
     def get_xml_element(name)
       xml_element = current_transaction.get_xml_element(name)
-      xml_element.document = self
+      xml_element&.document = self
       xml_element
     end
 

data/lib/y/map.rb

@@ -18,6 +18,8 @@ module Y
   #   map[:hello] = "world"
   #   puts map[:hello]
   class Map
+    include Enumerable
+
     # @!attribute [r] document
     #
     # @return [Y::Doc] The document this map belongs to

data/lib/y/text.rb

@@ -115,7 +115,7 @@ module Y
     # - Hash (where the the types of key and values must be supported)
     #
     # @param [Integer] index
-    # @param [String, Float, Array, Hash] value
+    # @param [String, Numeric, Array, Hash] value
     # @param [Hash|nil] attrs
     # @return [void]
     def insert(index, value, attrs = nil)

data/lib/y/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Y
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end