live_cable 0.0.1

data/lib/live_cable/delegation/methods.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Delegation
+    module Methods
+      private
+
+      def decorate_getters(methods)
+        methods.each do |method|
+          decorate_getter(method)
+        end
+      end
+
+      def decorate_getter(method)
+        define_method(method) do |*pos, **kwargs, &block|
+          create_delegator(
+            __getobj__.method(method).call(*pos, **kwargs, &block)
+          )
+        end
+      end
+
+      def decorate_mutators(methods)
+        methods.each do |method|
+          decorate_mutator(method)
+        end
+      end
+
+      def decorate_mutator(method)
+        define_method(method) do |*pos, **kwargs, &block|
+          notify_live_cable_observers
+
+          __getobj__.method(method).call(*pos, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/delegation/model.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Delegation
+    module Model
+      extend Methods
+
+      decorate_mutator :assign_attributes
+      decorate_mutator :update
+    end
+  end
+end

data/lib/live_cable/delegator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Delegation modules for different data types.
+  # Each module defines which methods should trigger change notifications.
+  module Delegation
+    extend ActiveSupport::Autoload
+
+    autoload :Array
+    autoload :Hash
+    autoload :Methods
+    autoload :Model
+
+    # Maps Ruby classes to their delegation modules.
+    # When a value of one of these types is stored in a container,
+    # it will be wrapped in a Delegator and extended with the appropriate module.
+    SUPPORTED = {
+      ::ActiveRecord::Base => Delegation::Model,
+      ::Array => Delegation::Array,
+      ::Hash => Delegation::Hash,
+    }.freeze
+  end
+
+  # Wraps mutable objects (Arrays, Hashes, Models) to track changes.
+  #
+  # The Delegator uses Ruby's SimpleDelegator to transparently wrap objects
+  # and intercept method calls. When mutative methods are called, observers
+  # are notified so the component can be re-rendered.
+  #
+  # @example Automatic wrapping
+  #   container[:tags] = ['ruby', 'rails']
+  #   # Container automatically wraps the array in a Delegator
+  #   container[:tags] << 'rspec'  # Triggers observer notification
+  #
+  # @example Manual creation
+  #   delegator = Delegator.new(['ruby', 'rails'])
+  #   delegator.add_live_cable_observer(observer, :tags)
+  #   delegator << 'rspec'  # Notifies observer
+  #
+  # Architecture:
+  # - Delegator extends SimpleDelegator to wrap the target object
+  # - Dynamically extends with type-specific delegation modules (Array/Hash/Model)
+  # - Each delegation module decorates mutative methods to notify observers
+  # - Getter methods are not decorated (no notification on read)
+  # - Nested structures automatically get wrapped in new Delegators with the same observers
+  #
+  # Supported Types:
+  # - Array: Tracks push, <<, delete, etc.
+  # - Hash: Tracks []=, delete, merge!, etc.
+  # - ActiveRecord::Base: Tracks assign_attributes, update, etc.
+  class Delegator < SimpleDelegator
+    include ObserverTracking
+
+    # @param value [Object] The object to wrap and track
+    def initialize(value)
+      super
+
+      # Extend with the appropriate delegation module based on value's type
+      Delegation::SUPPORTED.each do |klass, delegator|
+        if value.is_a?(klass)
+          extend delegator
+        end
+      end
+    end
+
+    # Factory method to create a Delegator only if the value's type is supported.
+    # Returns the original value unchanged if not supported.
+    #
+    # @param value [Object] The value to potentially wrap
+    # @param variable [Symbol] The reactive variable name
+    # @param observer [Observer] The observer to attach
+    # @return [Delegator, Object] Wrapped value or original value
+    def self.create_if_supported(value, variable, observer)
+      if supported?(value)
+        return new(value).tap do |delegator|
+          delegator.add_live_cable_observer(observer, variable)
+        end
+      end
+
+      value
+    end
+
+    # Check if a value's type can be wrapped in a Delegator.
+    #
+    # @param value [Object] The value to check
+    # @return [Boolean] true if value can be delegated
+    def self.supported?(value)
+      Delegation::SUPPORTED.keys.any? { |c| value.is_a?(c) }
+    end
+
+    private
+
+    # Create a new Delegator for nested values (e.g., nested arrays/hashes).
+    # Propagates all observers from the parent delegator to the child.
+    #
+    # @param value [Object] The nested value to wrap
+    # @return [Delegator, Object] Wrapped value or original if not supported
+    #
+    # @example Nested arrays
+    #   outer = Delegator.new([['inner']])
+    #   inner = outer[0]  # Returns a Delegator wrapping ['inner']
+    #   inner << 'new'    # Notifies same observers as outer
+    def create_delegator(value)
+      return value unless self.class.supported?(value)
+
+      # Create new delegator and propagate all observers from parent
+      self.class.new(value).tap do |delegator|
+        live_cable_observers.each do |variable, observers|
+          observers.each { |observer| delegator.add_live_cable_observer(observer, variable) }
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Engine < ::Rails::Engine
+    config.before_configuration do |app|
+      # Setup autoloader to use Live namespace for components
+      Rails.autoloaders.main.push_dir(app.root.join('app/live'), namespace: Live)
+
+      # Add LiveCable to importmap
+      app.config.importmap.paths << root.join('config/importmap.rb')
+    end
+
+    initializer 'live_cable.assets_precompile' do |app|
+      app.config.assets.precompile << %w[live_cable/**/*.js]
+    end
+
+    initializer 'live_cable.active_record' do
+      ActiveSupport.on_load :active_record do
+        include ModelObserver
+      end
+    end
+  end
+end

data/lib/live_cable/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Error < StandardError; end
+end

data/lib/live_cable/model_observer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module ModelObserver
+    include ObserverTracking
+
+    def _write_attribute(...)
+      notify_live_cable_observers
+
+      super
+    end
+  end
+end

data/lib/live_cable/observer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Observer pattern implementation for tracking changes to reactive variables.
+  #
+  # The Observer is attached to delegated values (Arrays, Hashes, ActiveRecord models)
+  # and notifies the container when changes occur. This enables automatic re-rendering
+  # of components when their data changes.
+  #
+  # @example Basic usage
+  #   container = Container.new
+  #   observer = Observer.new(container)
+  #   observer.notify(:username)  # Marks :username as dirty in the container
+  #
+  # Architecture:
+  # - Each Container has one Observer instance
+  # - Delegators (Array/Hash wrappers) hold references to observers
+  # - When a mutative method is called on a delegator, it notifies all its observers
+  # - The observer marks the variable as dirty in the container's changeset
+  # - After processing a message, the connection broadcasts changes to all dirty components
+  class Observer
+    # @param container [LiveCable::Container] The container to notify of changes
+    def initialize(container)
+      @container = container
+    end
+
+    # Notify the container that a variable has changed.
+    # This marks the variable as "dirty" so the component will be re-rendered.
+    #
+    # @param variable [Symbol] The name of the reactive variable that changed
+    # @return [void]
+    #
+    # @example
+    #   observer.notify(:tags)  # Component will re-render because :tags changed
+    def notify(variable)
+      container.mark_dirty(variable)
+    end
+
+    private
+
+    # @return [LiveCable::Container]
+    attr_reader :container
+  end
+end

data/lib/live_cable/observer_tracking.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Mixin for objects that need to track and notify observers of changes.
+  #
+  # This module is included in both Delegator and ModelObserver to provide
+  # a consistent interface for attaching observers and notifying them of changes.
+  #
+  # @example Usage in a Delegator
+  #   class MyDelegator < SimpleDelegator
+  #     include ObserverTracking
+  #
+  #     def mutate!
+  #       # ... perform mutation ...
+  #       notify_live_cable_observers  # Notify all observers
+  #     end
+  #   end
+  #
+  # Architecture:
+  # - Objects can have multiple observers attached
+  # - Each observer is associated with a specific variable name
+  # - When the object changes, all observers are notified
+  # - Observers then mark their variables as dirty in their containers
+  module ObserverTracking
+    # Attach an observer to track changes to a specific variable.
+    # The same observer can be attached multiple times for different variables.
+    #
+    # @param observer [LiveCable::Observer] The observer to notify of changes
+    # @param variable [Symbol] The reactive variable name this observer tracks
+    # @return [void]
+    #
+    # @example
+    #   observer = Observer.new(container)
+    #   tags_array.add_live_cable_observer(observer, :tags)
+    #   tags_array << 'ruby'  # Observer will be notified
+    def add_live_cable_observer(observer, variable)
+      observers = live_cable_observers_for(variable)
+
+      unless observers.include?(observer)
+        observers << observer
+      end
+    end
+
+    private
+
+    # Get the hash of all observers, keyed by variable name.
+    #
+    # @return [Hash<Symbol, Array<Observer>>] Variable name => observers
+    def live_cable_observers
+      @live_cable_observers ||= {}
+    end
+
+    # Get the list of observers for a specific variable.
+    #
+    # @param variable [Symbol] The variable name
+    # @return [Array<Observer>] List of observers for this variable
+    def live_cable_observers_for(variable)
+      live_cable_observers[variable] ||= []
+    end
+
+    # Notify all attached observers that this object has changed.
+    # Called automatically by mutative methods in delegation modules.
+    #
+    # @return [void]
+    def notify_live_cable_observers
+      live_cable_observers.each do |variable, observers|
+        observers.each { |observer| observer.notify(variable) }
+      end
+    end
+  end
+end

data/lib/live_cable/render_context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class RenderContext
+    def initialize(component)
+      @component = component
+      @children = []
+    end
+
+    # @return [Array<LiveCable::Component>]
+    attr_reader :children
+
+    def reset
+      self.children = []
+    end
+
+    def add_component(child)
+      return unless component.live_connection
+
+      component.live_connection.add_component(child)
+      children << child
+    end
+
+    # @return [LiveCable::Component, nil]
+    def get_component(live_id)
+      component.live_connection&.get_component(live_id)
+    end
+
+    # @return [LiveCable::Connection]
+    def live_connection
+      component.live_connection
+    end
+
+    private
+
+    # @return [LiveCable::Component]
+    attr_reader :component
+  end
+end

data/lib/live_cable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LiveCable
+  extend ActiveSupport::Autoload
+
+  autoload :Error
+  autoload :Component
+  autoload :Connection
+  autoload :Container
+  autoload :CsrfChecker
+  autoload :Delegator
+  autoload :ModelObserver
+  autoload :Observer
+  autoload :ObserverTracking
+  autoload :RenderContext
+
+  def self.instance_from_string(string, id)
+    klass = Live
+    klass_string = string.camelize
+
+    begin
+      klass_string.split('::').each do |part|
+        unless klass.const_defined?(part)
+          raise Error, "Component Live::#{klass_string} not found, make sure it is located in the Live:: module"
+        end
+
+        klass = klass.const_get(part)
+      end
+    rescue NameError
+      raise LiveCable::Error, "Invalid component name \"#{string}\" - Live::#{klass_string} not found"
+    end
+
+    klass = "Live::#{klass_string}".safe_constantize
+
+    unless klass < LiveCable::Component
+      raise 'Components must extend LiveCable::Component'
+    end
+
+    klass.new(id)
+  end
+end
+
+module Live
+  # For components to live in
+end
+
+require 'live_cable/engine' if defined?(Rails::Engine)

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: live_cable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Craig Blanchette
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: ''
+email: craig.blanchette@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/assets/javascript/controllers/live_controller.js
+- app/assets/javascript/live_cable_blessing.js
+- app/assets/javascript/subscriptions.js
+- app/channels/live_channel.rb
+- app/helpers/live_cable_helper.rb
+- config/importmap.rb
+- lib/live_cable.rb
+- lib/live_cable/component.rb
+- lib/live_cable/connection.rb
+- lib/live_cable/container.rb
+- lib/live_cable/csrf_checker.rb
+- lib/live_cable/delegation/array.rb
+- lib/live_cable/delegation/hash.rb
+- lib/live_cable/delegation/methods.rb
+- lib/live_cable/delegation/model.rb
+- lib/live_cable/delegator.rb
+- lib/live_cable/engine.rb
+- lib/live_cable/error.rb
+- lib/live_cable/model_observer.rb
+- lib/live_cable/observer.rb
+- lib/live_cable/observer_tracking.rb
+- lib/live_cable/render_context.rb
+homepage: https://rubygems.org/gems/live_cable
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/isometriks/live_cable
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Live Components over ActionCable
+test_files: []