y-rb 0.3.2-arm64-darwin → 0.4.0-arm64-darwin

data/lib/y/array.rb

@@ -19,7 +19,7 @@ module Y
   #   array.concat([3, 4, 5])
   #
   #   array.to_a == [1, 2, 3, 4, 5] # true
-  class Array
+  class Array # rubocop:disable Metrics/ClassLength
     include Enumerable
 
     # @!attribute [r] document
@@ -29,7 +29,7 @@ module Y
 
     # Create a new array instance
     #
-    # @param [Y::Doc] doc
+    # @param doc [Y::Doc]
     def initialize(doc = nil)
       @document = doc || Y::Doc.new
 
@@ -38,25 +38,26 @@ module Y
 
     # Retrieves element at position
     #
-    # @return [Object]
+    # @return [true|false|Float|Integer|String|Array|Hash]
     def [](index)
-      yarray_get(index)
+      document.current_transaction { |tx| yarray_get(tx, index) }
     end
 
     # Inserts value at position
     #
-    # @param [Integer] index
-    # @param [true|false|Float|Integer|String|Array|Hash] value
+    # @param index [Integer]
+    # @param value [true|false|Float|Integer|String|Array|Hash]
     # @return [void]
     def []=(index, value)
-      yarray_insert(transaction, index, value)
+      document.current_transaction { |tx| yarray_insert(tx, index, value) }
     end
 
     # Adds an element to the end of the array
     #
+    # @param value [true|false|Float|Integer|String|::Array|Hash]
     # @return [void]
     def <<(value)
-      yarray_push_back(transaction, value)
+      document.current_transaction { |tx| yarray_push_back(tx, value) }
     end
 
     # Attach listener to array changes
@@ -65,19 +66,18 @@ module Y
     #   local = Y::Doc.new
     #
     #   arr = local.get_array("my array")
-    #   arr.attach(->(delta) { pp delta })
+    #   arr.attach { |delta| pp delta }
     #
     #   local.transact do
     #     arr << 1
     #   end
     #
-    # @param [Proc] callback
-    # @param [Block] block
+    # @param block [Block]
     # @return [Integer]
-    def attach(callback, &block)
-      return yarray_observe(callback) unless callback.nil?
+    def attach(&block)
+      raise "provide block" unless block
 
-      yarray_observe(block.to_proc) unless block.nil?
+      yarray_observe(block.to_proc)
     end
 
     # Adds to array all elements from each Array in `other_arrays`.
@@ -91,19 +91,21 @@ module Y
     #
     #   arr.to_a == [1, 2, 3] # true
     #
-    # @param [Array<Array<Object>>] other_arrays
+    # @param other_arrays [Array<Array<Object>>]
     # @return [void]
     def concat(*other_arrays)
-      combined = other_arrays.reduce([]) do |values, arr|
-        values.concat(arr) if arr.is_a?(::Array)
-      end
+      document.current_transaction do |tx|
+        combined = other_arrays.reduce([]) do |values, arr|
+          values.concat(arr) if arr.is_a?(::Array)
+        end
 
-      yarray_insert_range(transaction, size, combined)
+        yarray_insert_range(tx, yarray_length(tx), combined)
+      end
     end
 
     # Detach listener
     #
-    # @param [Integer] subscription_id
+    # @param subscription_id [Integer]
     # @return [void]
     def detach(subscription_id)
       yarray_unobserve(subscription_id)
@@ -111,7 +113,7 @@ module Y
 
     # @return [void]
     def each(&block)
-      yarray_each(block)
+      document.current_transaction { |tx| yarray_each(tx, &block) }
     end
 
     # Check if the array is empty
@@ -123,31 +125,35 @@ module Y
 
     # Returns first element in array if there is at least one
     #
-    # @return [Object|nil]
+    # @return [true|false|Float|Integer|String|::Array|Hash|nil]
     def first
-      yarray_get(0)
+      document.current_transaction { |tx| yarray_get(tx, 0) }
     end
 
     # Returns last element in array if there is at least one element
     #
-    # @return [Object|nil]
+    # @return [true|false|Float|Integer|String|::Array|Hash|nil]
     def last
-      len = yarray_length
-      return yarray_get(yarray_length - 1) if len.positive?
+      document.current_transaction do |tx|
+        len = yarray_length(tx)
+        return yarray_get(tx, len - 1) if len.positive?
 
-      nil
+        nil
+      end
     end
 
     # rubocop:disable Naming/MethodParameterName
 
     # Removes last (n) element(s) from array
     #
-    # @param [Integer|nil] n Number of elements to remove
+    # @param n [Integer|nil] Number of elements to remove
     # @return [void]
     def pop(n = nil)
-      len = size
-      yarray_remove(transaction, len - 1) if n.nil?
-      yarray_remove_range(transaction, len - n, n) unless n.nil?
+      document.current_transaction do |tx|
+        len = yarray_length(tx)
+        yarray_remove(tx, len - 1) if n.nil?
+        yarray_remove_range(tx, len - n, n) unless n.nil?
+      end
     end
 
     # rubocop:enable Naming/MethodParameterName
@@ -158,11 +164,14 @@ module Y
 
     # Removes first (n) element(s) from array
     #
-    # @param [Integer|nil] n Number of elements to remove
+    # @param n [Integer|nil] Number of elements to remove
     # @return [void]
     def shift(n = nil)
-      yarray_remove(transaction, 0) if n.nil?
-      yarray_remove_range(transaction, 0, n) unless nil?
+      document.current_transaction do |tx|
+        yarray_remove(tx, 0) if n.nil?
+
+        yarray_remove_range(tx, 0, n) unless nil?
+      end
     end
 
     # rubocop:enable Naming/MethodParameterName
@@ -171,7 +180,7 @@ module Y
     #
     # @return [Integer]
     def size
-      yarray_length
+      document.current_transaction { |tx| yarray_length(tx) }
     end
 
     alias length size
@@ -208,147 +217,152 @@ module Y
     #
     # @return [void]
     def slice!(*args)
-      if args.size.zero?
-        raise ArgumentError,
-              "Provide one of `index`, `range`, `start, length` as arguments"
-      end
-
-      if args.size == 1
-        arg = args.first
+      document.current_transaction do |tx| # rubocop:disable Metrics/BlockLength
+        if args.size.zero?
+          raise ArgumentError,
+                "Provide one of `index`, `range`, `start, length` as arguments"
+        end
 
-        if arg.is_a?(Range)
-          if arg.exclude_end?
-            yarray_remove_range(transaction, arg.first,
-                                arg.last - arg.first)
-          end
-          unless arg.exclude_end?
-            yarray_remove_range(transaction, arg.first,
-                                arg.last + 1 - arg.first)
+        if args.size == 1
+          arg = args.first
+
+          if arg.is_a?(Range)
+            if arg.exclude_end?
+              yarray_remove_range(tx, arg.first,
+                                  arg.last - arg.first)
+            end
+            unless arg.exclude_end?
+              yarray_remove_range(tx, arg.first,
+                                  arg.last + 1 - arg.first)
+            end
+            return nil
           end
-          return nil
-        end
 
-        if arg.is_a?(Numeric)
-          yarray_remove(transaction, arg.to_int)
-          return nil
+          if arg.is_a?(Numeric)
+            yarray_remove(tx, arg.to_int)
+            return nil
+          end
         end
-      end
 
-      if args.size == 2
-        first, second = args
+        if args.size == 2
+          first, second = args
 
-        if first.is_a?(Numeric) && second.is_a?(Numeric)
-          yarray_remove_range(transaction, first, second)
-          return nil
+          if first.is_a?(Numeric) && second.is_a?(Numeric)
+            yarray_remove_range(tx, first, second)
+            return nil
+          end
         end
-      end
 
-      raise ArgumentError, "Please check your arguments, can't slice."
+        raise ArgumentError, "Please check your arguments, can't slice."
+      end
     end
 
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     # Convert this array to a Ruby Array
     #
-    # @return [Array<Object>]
+    # @return [Array<true|false|Float|Integer|String|::Array|Hash>]
     def to_a
-      yarray_to_a
+      document.current_transaction { |tx| yarray_to_a(tx) }
     end
 
     # Adds an element to the beginning of the array
     #
     # @return [void]
     def unshift(value)
-      yarray_push_front(transaction, value)
+      document.current_transaction { |tx| yarray_push_front(tx, value) }
     end
 
     alias prepend unshift
 
-    private
-
     # @!method yarray_each(proc)
     #   Iterates over all elements in Array by calling the provided proc
     #   with the value as argument.
     #
-    # @param [Proc<Object>] proc A proc that is called for every element
+    # @param proc [Proc<Object>] A proc that is called for every element
+    # @!visibility private
 
-    # @!method yarray_get(index)
+    # @!method yarray_get(transaction, index)
     #   Retrieves content as specified index
     #
-    # @param [Integer] index
+    # @param index [Integer]
     # @return [Object]
+    # @!visibility private
 
     # @!method yarray_insert(transaction, index, content)
     #   Inserts content at specified index
     #
-    # @param [Y::Transaction] transaction
-    # @param [Integer] index
-    # @param [Boolean, Float, Integer, Array, Hash, Text] content
+    # @param transaction [Y::Transaction]
+    # @param index [Integer]
+    # @param content [Boolean, Float, Integer, Array, Hash, Text]
     # @return [void]
+    # @!visibility private
 
     # @!method yarray_insert_range(transaction, index, arr)
     #   Inserts all elements of a given array at specified index
     #
-    # @param [Y::Transaction] transaction
-    # @param [Integer] index
-    # @param [Array<Boolean, Float, Integer, Array, Hash, Text>] arr
+    # @param transaction [Y::Transaction]
+    # @param index [Integer]
+    # @param arr [Array<Boolean|Float|Integer|Array|Hash|Text>]
     # @return [void]
+    # @!visibility private
 
-    # @!method yarray_length
+    # @!method yarray_length(transaction)
     #   Returns length of array
     #
+    # @param transaction [Y::Transaction]
     # @return [Integer] Length of array
+    # @!visibility private
 
     # @!method yarray_push_back(transaction, value)
     #   Adds an element to the end of the array
     #
-    # @param [Y::Transaction] transaction
-    # @param [Object] value
+    # @param transaction [Y::Transaction]
+    # @param value [Object]
     # @return [void]
+    # @!visibility private
 
     # @!method yarray_push_front(transaction, value)
     #   Adds an element to the front of the array
     #
-    # @param [Y::Transaction] transaction
-    # @param [Object] value
+    # @param transaction [Y::Transaction]
+    # @param value [Object]
     # @return [void]
+    # @!visibility private
 
-    # @!method yarray_observe(callback)
+    # @!method yarray_observe(proc)
     #
-    # @param [Proc] callback
+    # @param proc [Proc]
     # @return [Integer]
+    # @!visibility private
 
     # @!method yarray_remove(transaction, index)
     #   Removes a single element from array at index
     #
-    # @param [Y::Transaction] transaction
-    # @param [Integer] index
+    # @param transaction [Y::Transaction]
+    # @param index [Integer]
     # @return [void]
+    # @!visibility private
 
     # @!method yarray_remove_range(transaction, index, length)
     #   Removes a range of elements from array
     #
-    # @param [Y::Transaction] transaction
-    # @param [Integer] index
-    # @param [Integer] length
+    # @param transaction [Y::Transaction]
+    # @param index [Integer]
+    # @param length [Integer]
     # @return [void]
+    # @!visibility private
 
-    # @!method yarray_to_a
+    # @!method yarray_to_a(transaction)
     #   Transforms the array into a Ruby array
-    #
+    # @param transaction [Y::Transaction]
     # @return [Array]
+    # @!visibility private
 
     # @!method yarray_unobserve(subscription_id)
     #
-    # @param [Integer] subscription_id
+    # @param subscription_id [Integer]
     # @return [void]
-
-    # A reference to the current active transaction of the document this map
-    # belongs to.
-    #
-    # @return [Y::Transaction] A transaction object
-    def transaction
-      document.current_transaction
-    end
+    # @!visibility private
   end
 end

data/lib/y/awareness.rb

@@ -31,7 +31,19 @@ module Y
   #   awareness.local_state = local_state
   #   awareness.diff # [1,227,245,175,195,11,1,65,123, …]
   #
+  # @example Two connected clients
+  #   local_state_a = { name: "User A" }.to_json
   #
+  #   client_a = Y::Awareness.new
+  #   client_a.local_state = local_state
+  #
+  #   local_state_b = { name: "User B" }.to_json
+  #
+  #   client_b = Y::Awareness.new
+  #   client_b.local_state = local_state_b
+  #
+  #   client_a.sync(client_b.diff)
+  #   client_a.clients # {1242157267=>"{\"name\":\"User A\"}", 2401067547=>…
   class Awareness
     # Applies an incoming update. This gets the local awareness instance in
     # sync with changes from another client. i.e., updates the state of another
@@ -43,7 +55,7 @@ module Y
     #   awareness = Y::Awareness.new
     #   awareness.sync(update)
     #
-    # @param [Array<Integer>] diff A binary encoded update
+    # @param diff [Array<Integer>] A binary encoded update
     # @return [void]
     def sync(diff)
       yawareness_apply_update(diff)
@@ -131,7 +143,7 @@ module Y
 
     # Unsubscribe from changes
     #
-    # @param [Integer] subscription_id
+    # @param subscription_id [Integer]
     # @return [void]
     def detach(subscription_id)
       yawareness_remove_on_update(subscription_id)
@@ -140,7 +152,7 @@ module Y
     # Clears out a state of a given client, effectively marking it as
     # disconnected.
     #
-    # @param [Integer] client_id Clears the state for given client_id
+    # @param client_id [Integer] Clears the state for given client_id
     # @return [void]
     def remove_state(client_id)
       yawareness_remove_state(client_id)
@@ -160,7 +172,7 @@ module Y
     # be known to a current Awareness instance, otherwise a
     # Error::ClientNotFound error will be returned.
     #
-    # @param [::Array<Integer>] clients A list of client IDs
+    # @param clients [::Array<Integer>] 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)
@@ -172,22 +184,26 @@ module Y
     # @!method yawareness_apply_update(update)
     #   Applies an update
     #
-    # @param [Y::AwarenessUpdate] A structure that represents an encodable state
+    # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
     #   of an Awareness struct.
+    # @!visibility private
 
     # @!method yawareness_apply_update(update)
     #   Applies an update
     #
-    # @param [Y::AwarenessUpdate] A structure that represents an encodable state
+    # @param A [Y::AwarenessUpdate] Structure that represents an encodable state
     #   of an Awareness struct.
+    # @!visibility private
 
     # @!method yawareness_clean_local_state
     #   Clears out a state of a current client , effectively marking it as
     #   disconnected.
+    # @!visibility private
 
     # @!method yawareness_client_id
     #   Returns a globally unique client ID of an underlying Doc.
     # @return [Integer] The Client ID
+    # @!visibility private
 
     # @!method yawareness_clients
     #   Returns a state map of all of the clients
@@ -196,28 +212,33 @@ module Y
     #   replicated to other clients as a JSON string.
     #
     # @return [Hash<Integer, String>] Map of clients
+    # @!visibility private
 
     # @!method yawareness_local_state
     #
     # @return [String|nil] Returns a JSON string state representation of a
     #   current Awareness instance.
+    # @!visibility private
 
     # @!method yawareness_on_update(callback, &block)
     #
-    # @param [Proc] A callback handler for updates
+    # @param callback [callback]
     # @return [Integer] The subscription ID
+    # @!visibility private
 
     # @!method yawareness_remove_on_update(subscription_id)
     #
-    # @param [Integer] subscription_id The subscription id to remove
+    # @param subscription_id [Integer] The subscription id to remove
+    # @!visibility private
 
     # @!method yawareness_remove_state(client_id)
     #   Clears out a state of a given client, effectively marking it as
     #   disconnected.
     #
-    # @param [Integer] client_id A Client ID
+    # @param client_id [Integer] A Client ID
     # @return [String|nil] Returns a JSON string state representation of a
     #   current Awareness instance.
+    # @!visibility private
 
     # @!method yawareness_set_local_state(state)
     #   Sets a current Awareness instance state to a corresponding JSON string.
@@ -225,16 +246,18 @@ module Y
     #   AwarenessUpdate and it will trigger an event to be emitted if current
     #   instance was created using [Awareness::with_observer] method.
     #
-    # @param [String] Returns a state map of all of the clients tracked by
+    # @param Returns [String] 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.
+    # @!visibility private
 
     # @!method yawareness_update
     #   Returns a serializable update object which is representation of a
     #   current Awareness state.
     #
     # @return [Y::AwarenessUpdate] The update object
+    # @!visibility private
 
     # @!method yawareness_update_with_clients(clients)
     #   Returns a serializable update object which is representation of a
@@ -243,24 +266,27 @@ module Y
     #   These clients must all be known to a current Awareness instance,
     #   otherwise an error will be returned.
     #
-    # @param [::Array<Integer>] clients
+    # @param clients [::Array<Integer>]
     # @return [::Array<Integer>] A serialized (binary encoded) update object
+    # @!visibility private
 
     # rubocop:enable Lint/UselessAccessModifier
   end
 
-  # rubocop:disable Lint/UselessAccessModifier
+  # @!visibility private
   class AwarenessEvent
-    private
+    private # rubocop:disable Lint/UselessAccessModifier
 
     # @!method added
     # @return [::Array<Integer>] Added clients
+    # @!visibility private
 
     # @!method updated
     # @return [::Array<Integer>] Updated clients
+    # @!visibility private
 
     # @!method removed
     # @return [::Array<Integer>] Removed clients
+    # @!visibility private
   end
-  # rubocop:enable Lint/UselessAccessModifier
 end