y-rb 0.3.2-x64-mingw32

data/lib/y/awareness.rb

@@ -0,0 +1,266 @@
+# 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
+    # 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
+
+    # 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
+
+    # 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)
+    #   Applies an update
+    #
+    # @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.
+
+    # @!method yawareness_client_id
+    #   Returns a globally unique client ID of an underlying Doc.
+    # @return [Integer] The Client ID
+
+    # @!method yawareness_clients
+    #   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.
+    #
+    # @return [Hash<Integer, String>] Map of clients
+
+    # @!method yawareness_local_state
+    #
+    # @return [String|nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+
+    # @!method yawareness_on_update(callback, &block)
+    #
+    # @param [Proc] A callback handler for updates
+    # @return [Integer] The subscription ID
+
+    # @!method yawareness_remove_on_update(subscription_id)
+    #
+    # @param [Integer] subscription_id The subscription id to remove
+
+    # @!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
+    # @return [String|nil] Returns a JSON string state representation of a
+    #   current Awareness instance.
+
+    # @!method yawareness_set_local_state(state)
+    #   Sets a current Awareness instance state to a corresponding JSON string.
+    #   This state will be replicated to other clients as part of the
+    #   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
+    #   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.
+
+    # @!method yawareness_update
+    #   Returns a serializable update object which is representation of a
+    #   current Awareness state.
+    #
+    # @return [Y::AwarenessUpdate] The update object
+
+    # @!method yawareness_update_with_clients(clients)
+    #   Returns a serializable update object which is representation of a
+    #   current Awareness state. Unlike [Y::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 an error will be returned.
+    #
+    # @param [::Array<Integer>] clients
+    # @return [::Array<Integer>] A serialized (binary encoded) update object
+
+    # rubocop:enable Lint/UselessAccessModifier
+  end
+
+  # rubocop:disable Lint/UselessAccessModifier
+  class AwarenessEvent
+    private
+
+    # @!method added
+    # @return [::Array<Integer>] Added clients
+
+    # @!method updated
+    # @return [::Array<Integer>] Updated clients
+
+    # @!method removed
+    # @return [::Array<Integer>] Removed clients
+  end
+  # rubocop:enable Lint/UselessAccessModifier
+end

data/lib/y/doc.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "transaction"
+
+module Y
+  # @example Create a local and remote doc and syncs the diff
+  #   local = Y::Doc.new
+  #   local_map = local.get_map("my map")
+  #   local_map[:hello] = "world"
+  #
+  #   remote = Y::Doc.new
+  #
+  #   diff = local.diff(remote.state)
+  #   remote.sync(diff)
+  #
+  #   remote_map = remote.get_map("my_map")
+  #   pp remote_map.to_h #=> {hello: "world"}
+  class Doc
+    ZERO_STATE = [0].freeze
+    private_constant :ZERO_STATE
+
+    # Commit current transaction
+    #
+    # This is a convenience method that invokes {Y::Transaction#commit} on the
+    # current transaction used by this document.
+    #
+    # @return [void]
+    def commit
+      current_transaction.commit
+    end
+
+    # The currently active transaction for this document
+    # @return [Y::Transaction]
+    def current_transaction
+      @current_transaction ||= begin
+        transaction = ydoc_transact
+        transaction.document = self
+        transaction
+      end
+    end
+
+    # Create a diff between this document and another document. The diff is
+    # created based on a state vector provided by the other document. It only
+    # returns the missing blocks, as binary encoded sequence.
+    #
+    # @param [::Array<Int>] state The state to create the diff against
+    # @return [::Array<Int>] Binary encoded diff
+    def diff(state = ZERO_STATE)
+      ydoc_encode_diff_v1(state)
+    end
+
+    # Creates a full diff for the current document. It is similar to {#diff},
+    # but does not take a state. Instead it creates an empty state and passes it
+    # to the encode_diff function.
+    #
+    # @return [::Array<Int>] Binary encoded diff
+    def full_diff
+      empty_state = Y::Doc.new.state
+      ydoc_encode_diff_v1(empty_state)
+    end
+
+    # Gets or creates a new array by name
+    #
+    # If the optional values array is present, fills the array up with elements
+    # from the provided array. If the array already exists and isn't
+    # empty, elements are pushed to the end of the array.
+    #
+    # @param [String] name The name of the structure
+    # @param [::Array] values Optional initial values
+    # @return [Y::Array]
+    def get_array(name, values = nil)
+      array = current_transaction.get_array(name)
+      array.document = self
+      array.concat(values) unless values.nil?
+      array
+    end
+
+    # Gets or creates a new map by name
+    #
+    # If the optional input hash is present, fills the map up with key-value
+    # pairs from the provided input hash. If the map already exists and isn't
+    # empty, any existing keys are overridden and new keys are added.
+    #
+    # @param [String] name The name of the structure
+    # @param [Hash] input Optional initial map key-value pairs
+    # @return [Y::Map]
+    def get_map(name, input = nil)
+      map = current_transaction.get_map(name)
+      map.document = self
+      input&.each { |key, value| map[key] = value }
+      map
+    end
+
+    # Gets or creates a new text by name
+    #
+    # If the optional input string is provided, fills a new text with the string
+    # at creation time. If the text isn't new and not empty, appends the input
+    # to the end of the text.
+    #
+    # @param [String] name The name of the structure
+    # @param [String] input Optional initial text value
+    # @return [Y::Text]
+    def get_text(name, input = nil)
+      text = current_transaction.get_text(name)
+      text.document = self
+      text << input unless input.nil?
+      text
+    end
+
+    # Gets or creates a new XMLElement by name
+    #
+    # @param [String] name The name of the structure
+    # @return [Y::XMLElement]
+    def get_xml_element(name)
+      xml_element = current_transaction.get_xml_element(name)
+      xml_element&.document = self
+      xml_element
+    end
+
+    # Gets or creates a new XMLText by name
+    #
+    # @param [String] name The name of the structure
+    # @param [String] input Optional initial text value
+    # @return [Y::XMLText]
+    def get_xml_text(name, input = nil)
+      xml_text = current_transaction.get_xml_text(name)
+      xml_text.document = self
+      xml_text << input unless input.nil?
+      xml_text
+    end
+
+    # Creates a state vector of this document. This can be used to compare the
+    # state of two documents with each other and to later on sync them.
+    #
+    # @return [::Array<Int>] Binary encoded state vector
+    def state
+      current_transaction.state
+    end
+
+    # Synchronizes this document with the diff from another document
+    #
+    # @param [::Array<Int>] diff Binary encoded update
+    # @return [void]
+    def sync(diff)
+      current_transaction.apply(diff)
+    end
+
+    # Restores a specific document from an update that contains full state
+    #
+    # This is doing the same as {#sync}, but it exists to be explicit about
+    # the intent. This is the companion to {#full_diff}.
+    #
+    # @param [::Array<Int>] full_diff Binary encoded update
+    # @return [void]
+    def restore(full_diff)
+      current_transaction.apply(full_diff)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+
+    # Creates a new transaction and provides it to the given block
+    #
+    # @example Insert into text
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #
+    #   doc.transact do
+    #     text << "Hello, World!"
+    #   end
+    #
+    # @yield [transaction]
+    # @yieldparam [Y::Transaction] transaction
+    # @yieldreturn [void]
+    # @return [Y::Transaction]
+    def transact
+      current_transaction.commit
+
+      if block_given?
+        # create new transaction just for the lifetime of this block
+        tmp_transaction = ydoc_transact
+        tmp_transaction.document = self
+
+        # override transaction for the lifetime of the block
+        @current_transaction = tmp_transaction
+
+        yield tmp_transaction
+
+        tmp_transaction.commit
+      end
+
+      # create new transaction
+      @current_transaction = ydoc_transact
+      @current_transaction.document = self
+
+      current_transaction
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # @!method ydoc_encode_diff_v1
+    #   Encodes the diff of current document state vs provided state
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_encode_diff_v1(other_state)
+    #
+    # @return [Array<Integer>] Binary encoded update
+    # @!visibility private
+
+    # @!method ydoc_transact
+    #   Creates a new transaction for the document
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_transact
+    #
+    # @return [Y::Transaction] The transaction object
+    # @!visibility private
+  end
+end

data/lib/y/map.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Y
+  # A map can be used to store and retrieve key-value pairs.
+  #
+  # The map is the replicated counterpart to a Hash. It supports a subset
+  # of the Hash operations, like adding, getting and deleting values by key.
+  #
+  # Someone should not instantiate a map directly, but use {Y::Doc#get_map}
+  # instead.
+  #
+  # @example
+  #   doc = Y::Doc.new
+  #   map = doc.get_map("my map")
+  #
+  #   map[:hello] = "world"
+  #   puts map[:hello]
+  class Map
+    include Enumerable
+
+    # @!attribute [r] document
+    #
+    # @return [Y::Doc] The document this map belongs to
+    attr_accessor :document
+
+    # Create a new map instance
+    #
+    # @param [Y::Doc] doc
+    def initialize(doc = nil)
+      @document = doc || Y::Doc.new
+
+      super()
+    end
+
+    # Attach a listener to get notified about any changes to the map
+    #
+    # @param [Proc] callback
+    # @param [Block] block
+    # @return [Integer]
+    def attach(callback, &block)
+      return ymap_observe(callback) unless callback.nil?
+
+      ymap_observe(block.to_proc) unless block.nil?
+    end
+
+    # Removes all map entries
+    #
+    # @return [Self]
+    def clear
+      ymap_clear(transaction)
+      self
+    end
+
+    # rubocop:disable Layout/LineLength
+
+    # Deletes the entry for the given key and returns its associated value.
+    #
+    # @example Deletes the entry and return associated value
+    #
+    #   m = doc.get_map("my map")
+    #   m[:bar] = 1
+    #   m.delete(:bar) # => 1
+    #   m # => {}
+    #
+    # @example Unknown key is handled in block
+    #
+    #   m = doc.get_map("my map")
+    #   m.delete(:nosuch) { |key| "Key #{key} not found" }# => "Key nosuch not found"
+    #   m # => {}
+    #
+    # @param [String, Symbol] key
+    # @return [void]
+    def delete(key)
+      value = ymap_remove(transaction, key)
+      if block_given? && key?(key)
+        yield key
+      else
+        value
+      end
+    end
+
+    # rubocop:enable Layout/LineLength
+
+    # Detach listener
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
+    def detach(subscription_id)
+      ymap_unobserve(subscription_id)
+    end
+
+    # @return [void]
+    def each(&block)
+      ymap_each(block)
+    end
+
+    # @return [true|false]
+    def key?(key)
+      ymap_contains(key)
+    end
+
+    alias has_key? key?
+
+    # @return [Object]
+    def [](key)
+      ymap_get(key)
+    end
+
+    # @return [void]
+    def []=(key, val)
+      ymap_insert(transaction, key, val)
+    end
+
+    # Returns size of map
+    #
+    # @return [Integer]
+    def size
+      ymap_size
+    end
+
+    # Returns a Hash representation of this map
+    #
+    # @return [Hash]
+    def to_h
+      ymap_to_h
+    end
+
+    # Returns a JSON representation of map
+    #
+    # @return [String] JSON string
+    def to_json(*_args)
+      to_h.to_json
+    end
+
+    private
+
+    # @!method ymap_clear()
+    #   Removes all key-value pairs from Map
+
+    # @!method ymap_contains(key)
+    #   Check if a certain key is in the Map
+    #
+    # @param [String|Symbol] key
+    # @return [Boolean] True, if and only if the key exists
+
+    # @!method ymap_each(proc)
+    #   Iterates over all key-value pairs in Map by calling the provided proc
+    #   with the key and the value as arguments.
+    #
+    # @param [Proc<String, Any>] proc A proc that is called for every element
+
+    # @!method ymap_get(key)
+    #   Returns stored value for key or nil if none is present
+    #
+    # @param [String|Symbol] key
+    # @return [Any|Nil] Value or nil
+
+    # @!method ymap_insert(transaction, key, value)
+    #   Insert value for key. In case the key already exists, the previous value
+    #   will be overwritten.
+    #
+    # @param [Y::Transaction] transaction
+    # @param [String|Symbol] key
+    # @param [Any] value
+
+    # @!method ymap_observe(callback)
+    #
+    # @param [Proc] callback
+    # @return [Integer]
+
+    # @!method ymap_remove(transaction, key)
+    #   Removes key-value pair from Map if key exists.
+    #
+    # @param [Y::Transaction] transaction
+    # @param [String|Symbol] key
+
+    # @!method ymap_size()
+    #   Returns number of key-value pairs stored in map
+    #
+    # @return [Integer] Number of key-value pairs
+
+    # @!method ymap_to_h()
+    #   Returns a Hash representation of the Map
+    #
+    # @return [Hash] Hash representation of Map
+
+    # @!method ymap_unobserve(subscription_id)
+    #
+    # @param [Integer] subscription_id
+    # @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
+  end
+end