cable_ready 5.0.0.pre9 → 5.0.0.rc1

data/app/channels/cable_ready/stream.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module CableReady
-  class Stream < ActionCable::Channel::Base
-    include CableReady::StreamIdentifier
+  if defined?(ActionCable)
+    class Stream < ActionCable::Channel::Base
+      include CableReady::StreamIdentifier
 
-    def subscribed
-      locator = verified_stream_identifier(params[:identifier])
-      locator.present? ? stream_from(locator) : reject
+      def subscribed
+        locator = verified_stream_identifier(params[:identifier])
+        locator.present? ? stream_from(locator) : reject
+      end
     end
   end
 end

data/app/helpers/cable_ready/view_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CableReady
+  module ViewHelper
+    include CableReady::Compoundable
+    include CableReady::StreamIdentifier
+
+    def stream_from(...)
+      warn "DEPRECATED: please use `cable_ready_stream_from` instead. The `stream_from` view helper will be removed from a future version of CableReady 5"
+
+      cable_ready_stream_from(...)
+    end
+
+    def updates_for(...)
+      warn "DEPRECATED: please use `cable_ready_updates_for` instead. The `updates_for` view helper will be removed from a future version of CableReady 5"
+
+      cable_ready_updates_for(...)
+    end
+
+    def updates_for_if(...)
+      warn "DEPRECATED: please use `cable_ready_updates_for_if` instead. The `updates_for_if` view helper will be removed from a future version of CableReady 5"
+
+      cable_ready_updates_for_if(...)
+    end
+
+    def cable_ready_stream_from(*keys, html_options: {})
+      tag.cable_ready_stream_from(**build_options(*keys, html_options))
+    end
+
+    def cable_ready_updates_for(*keys, url: nil, debounce: nil, only: nil, ignore_inner_updates: false, html_options: {}, &block)
+      options = build_options(*keys, html_options)
+      options[:url] = url if url
+      options[:debounce] = debounce if debounce
+      options[:only] = only if only
+      options[:"ignore-inner-updates"] = "" if ignore_inner_updates
+      tag.cable_ready_updates_for(**options) { capture(&block) }
+    end
+
+    def cable_ready_updates_for_if(condition, *keys, **options, &block)
+      if condition
+        cable_ready_updates_for(*keys, **options, &block)
+      else
+        capture(&block)
+      end
+    end
+
+    def cable_car
+      CableReady::CableCar.instance
+    end
+
+    private
+
+    def build_options(*keys, html_options)
+      keys.select!(&:itself)
+      {identifier: signed_stream_identifier(compound(keys))}.merge(html_options)
+    end
+  end
+end

data/app/jobs/cable_ready/broadcast_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+if defined?(ActiveJob::Base)
+  class CableReady::BroadcastJob < ActiveJob::Base
+    include CableReady::Broadcaster
+
+    def perform(identifier:, operations:, model: nil)
+      if model.present?
+        cable_ready[identifier.safe_constantize].apply!(operations).broadcast_to(model)
+      else
+        cable_ready[identifier].apply!(operations).broadcast
+      end
+    end
+  end
+end

data/app/models/concerns/cable_ready/updatable/collection_updatable_callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CableReady
   module Updatable
     class CollectionUpdatableCallbacks

data/app/models/concerns/cable_ready/updatable/collections_registry.rb

@@ -1,5 +1,19 @@
+# frozen_string_literal: true
+
 module CableReady
   module Updatable
+    Collection = Struct.new(
+      :klass,
+      :name,
+      :reflection,
+      :options,
+      :foreign_key,
+      :inverse_association,
+      :through_association,
+      :debounce_time,
+      keyword_init: true
+    )
+
     class CollectionsRegistry
       def initialize
         @registered_collections = []
@@ -10,23 +24,35 @@ module CableReady
       end
 
       def broadcast_for!(model, operation)
-        @registered_collections.select { |c| c[:options][:on].include?(operation) }
+        @registered_collections.select { |c| c.options[:on].include?(operation) }
           .each do |collection|
           resource = find_resource_for_update(collection, model)
           next if resource.nil?
 
-          collection[:klass].cable_ready_update_collection(resource, collection[:name], model) if collection[:options][:if].call(resource)
+          collection.klass.cable_ready_update_collection(resource, collection.name, model, debounce: collection.debounce_time) if collection.options[:if].call(resource)
         end
       end
 
       private
 
       def find_resource_for_update(collection, model)
-        raise ArgumentError, "Could not find inverse_of for #{collection[:name]}" unless collection[:inverse_association]
+        collection.reflection ||= collection.klass.reflect_on_association(collection.name)
+
+        collection.foreign_key ||= collection.reflection&.foreign_key
+
+        # lazy load and store through and inverse associations
+        if collection.reflection&.through_reflection?
+          collection.inverse_association ||= collection.reflection&.through_reflection&.inverse_of&.name&.to_s
+          collection.through_association = collection.reflection&.through_reflection&.name&.to_s&.singularize
+        else
+          collection.inverse_association ||= collection.reflection&.inverse_of&.name&.to_s
+        end
+
+        raise ArgumentError, "Could not find inverse_of for #{collection.name}" unless collection.inverse_association
 
         resource = model
-        resource = resource.send(collection[:through_association].underscore) if collection[:through_association]
-        resource.send(collection[:inverse_association].underscore)
+        resource = resource.send(collection.through_association.underscore) if collection.through_association
+        resource.send(collection.inverse_association.underscore)
       end
     end
   end

data/app/models/concerns/cable_ready/updatable/model_updatable_callbacks.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 module CableReady
   module Updatable
     class ModelUpdatableCallbacks
-      def initialize(operation, enabled_operations = %i[create update destroy])
+      def initialize(operation, enabled_operations = %i[create update destroy], debounce: CableReady.config.updatable_debounce_time)
         @operation = operation
         @enabled_operations = enabled_operations
+        @debounce = debounce
       end
 
       def after_commit(model)
@@ -15,13 +18,15 @@ module CableReady
       private
 
       def broadcast_create(model)
-        model.class.send(:broadcast_updates, model.class, {})
+        model.class.send(:broadcast_updates, model.class, {debounce: @debounce})
       end
       alias_method :broadcast_destroy, :broadcast_create
 
       def broadcast_update(model)
-        model.class.send(:broadcast_updates, model.class, {})
-        model.class.send(:broadcast_updates, model.to_global_id, model.respond_to?(:previous_changes) ? {changed: model.previous_changes.keys} : {})
+        changeset = model.respond_to?(:previous_changes) ? {changed: model.previous_changes.keys} : {}
+        options = changeset.merge({debounce: @debounce})
+        model.class.send(:broadcast_updates, model.class, options.dup)
+        model.class.send(:broadcast_updates, model.to_global_id, options)
       end
     end
   end

data/app/models/concerns/cable_ready/updatable.rb

@@ -1,32 +1,49 @@
 # frozen_string_literal: true
 
+require "active_support/concern"
+
 module CableReady
   module Updatable
     extend ::ActiveSupport::Concern
 
+    mattr_accessor :debounce_adapter, default: MemoryCacheDebounceAdapter.instance
+
     included do |base|
-      if base < ActiveRecord::Base
+      if defined?(ActiveRecord) && base < ActiveRecord::Base
         include ExtendHasMany
 
         after_commit CollectionUpdatableCallbacks.new(:create), on: :create
         after_commit CollectionUpdatableCallbacks.new(:update), on: :update
         after_commit CollectionUpdatableCallbacks.new(:destroy), on: :destroy
 
-        def self.enable_updates(*options)
+        def self.enable_updates(...)
+          warn "DEPRECATED: please use `enable_cable_ready_updates` instead. The `enable_updates` class method will be removed from a future version of CableReady 5"
+
+          enable_cable_ready_updates(...)
+        end
+
+        def self.skip_updates(...)
+          warn "DEPRECATED: please use `skip_cable_ready_updates` instead. The `skip_updates` class method will be removed from a future version of CableReady 5"
+
+          skip_cable_ready_updates(...)
+        end
+
+        def self.enable_cable_ready_updates(*options)
           options = options.extract_options!
           options = {
             on: [:create, :update, :destroy],
-            if: -> { true }
+            if: -> { true },
+            debounce: CableReady.config.updatable_debounce_time
           }.merge(options)
 
           enabled_operations = Array(options[:on])
 
-          after_commit(ModelUpdatableCallbacks.new(:create, enabled_operations), {on: :create, if: options[:if]})
-          after_commit(ModelUpdatableCallbacks.new(:update, enabled_operations), {on: :update, if: options[:if]})
-          after_commit(ModelUpdatableCallbacks.new(:destroy, enabled_operations), {on: :destroy, if: options[:if]})
+          after_commit(ModelUpdatableCallbacks.new(:create, enabled_operations, debounce: options[:debounce]), {on: :create, if: options[:if]})
+          after_commit(ModelUpdatableCallbacks.new(:update, enabled_operations, debounce: options[:debounce]), {on: :update, if: options[:if]})
+          after_commit(ModelUpdatableCallbacks.new(:destroy, enabled_operations, debounce: options[:debounce]), {on: :destroy, if: options[:if]})
         end
 
-        def self.skip_updates
+        def self.skip_cable_ready_updates
           skip_updates_classes.push(self)
           yield
         ensure
@@ -38,19 +55,57 @@ module CableReady
     private
 
     module ClassMethods
+      include Compoundable
+
       def has_many(name, scope = nil, **options, &extension)
-        option = options.delete(:enable_updates)
+        option = if options.has_key?(:enable_updates)
+          warn "DEPRECATED: please use `enable_cable_ready_updates` instead. The `enable_updates` option will be removed from a future version of CableReady 5"
+          options.delete(:enable_updates)
+        else
+          options.delete(:enable_cable_ready_updates)
+        end
+
+        descendants = options.delete(:descendants)
+        debounce_time = options.delete(:debounce)
+
+        broadcast = option.present?
+        result = super
+        enrich_association_with_updates(name, option, descendants, debounce: debounce_time) if broadcast
+        result
+      end
+
+      def has_one(name, scope = nil, **options, &extension)
+        option = if options.has_key?(:enable_updates)
+          warn "DEPRECATED: please use `enable_cable_ready_updates` instead. The `enable_updates` option will be removed from a future version of CableReady 5"
+          options.delete(:enable_updates)
+        else
+          options.delete(:enable_cable_ready_updates)
+        end
+
+        descendants = options.delete(:descendants)
+        debounce_time = options.delete(:debounce)
+
         broadcast = option.present?
         result = super
-        enrich_association_with_updates(name, option) if broadcast
+        enrich_association_with_updates(name, option, descendants, debounce: debounce_time) if broadcast
         result
       end
 
       def has_many_attached(name, **options)
-        option = options.delete(:enable_updates)
+        raise("ActiveStorage must be enabled to use has_many_attached") unless defined?(ActiveStorage)
+
+        option = if options.has_key?(:enable_updates)
+          warn "DEPRECATED: please use `enable_cable_ready_updates` instead. The `enable_updates` option will be removed from a future version of CableReady 5"
+          options.delete(:enable_updates)
+        else
+          options.delete(:enable_cable_ready_updates)
+        end
+
+        debounce_time = options.delete(:debounce)
+
         broadcast = option.present?
         result = super
-        enrich_attachments_with_updates(name, option) if broadcast
+        enrich_attachments_with_updates(name, option, debounce: debounce_time) if broadcast
         result
       end
 
@@ -58,49 +113,45 @@ module CableReady
         @cable_ready_collections ||= CollectionsRegistry.new
       end
 
-      def cable_ready_update_collection(resource, name, model)
+      def cable_ready_update_collection(resource, name, model, debounce: CableReady.config.updatable_debounce_time)
         identifier = resource.to_global_id.to_s + ":" + name.to_s
-        broadcast_updates(identifier, model.respond_to?(:previous_changes) ? {changed: model.previous_changes.keys} : {})
+        changeset = model.respond_to?(:previous_changes) ? {changed: model.previous_changes.keys} : {}
+        options = changeset.merge({debounce: debounce})
+
+        broadcast_updates(identifier, options)
       end
 
-      def enrich_association_with_updates(name, option)
+      def enrich_association_with_updates(name, option, descendants = nil, debounce: CableReady.config.updatable_debounce_time)
         reflection = reflect_on_association(name)
 
-        inverse_of = reflection.inverse_of&.name&.to_s
-        through_association = nil
-
-        if reflection.through_reflection?
-          inverse_of = reflection.through_reflection.inverse_of&.name&.to_s
-          through_association = reflection.through_reflection.name.to_s.singularize
-        end
-
         options = build_options(option)
 
-        reflection.klass.send(:include, CableReady::Updatable) unless reflection.klass.respond_to?(:cable_ready_collections)
-
-        reflection.klass.cable_ready_collections.register({
-          klass: self,
-          foreign_key: reflection.foreign_key,
-          name: name,
-          inverse_association: inverse_of,
-          through_association: through_association,
-          options: options
-        })
+        [reflection.klass, *descendants&.map(&:to_s)&.map(&:constantize)].each do |klass|
+          klass.send(:include, CableReady::Updatable) unless klass.respond_to?(:cable_ready_collections)
+          klass.cable_ready_collections.register(Collection.new(
+            klass: self,
+            name: name,
+            options: options,
+            reflection: reflection,
+            debounce_time: debounce
+          ))
+        end
       end
 
-      def enrich_attachments_with_updates(name, option)
+      def enrich_attachments_with_updates(name, option, debounce: CableReady.config.updatable_debounce_time)
         options = build_options(option)
 
         ActiveStorage::Attachment.send(:include, CableReady::Updatable) unless ActiveStorage::Attachment.respond_to?(:cable_ready_collections)
 
-        ActiveStorage::Attachment.cable_ready_collections.register({
+        ActiveStorage::Attachment.cable_ready_collections.register(Collection.new(
           klass: self,
           foreign_key: "record_id",
           name: name,
           inverse_association: "record",
           through_association: nil,
-          options: options
-        })
+          options: options,
+          debounce_time: debounce
+        ))
       end
 
       def build_options(option)
@@ -111,7 +162,7 @@ module CableReady
 
         case option
         when TrueClass
-          # proceed!
+        # proceed!
         when FalseClass
           options[:on] = []
         when Array
@@ -124,7 +175,7 @@ module CableReady
         when Proc
           options[:if] = option
         else
-          raise ArgumentError, "Invalid enable_updates option #{option}"
+          raise ArgumentError, "Invalid enable_cable_ready_updates option #{option}"
         end
 
         options
@@ -132,7 +183,24 @@ module CableReady
 
       def broadcast_updates(model_class, options)
         return if skip_updates_classes.any? { |klass| klass >= self }
-        ActionCable.server.broadcast(model_class, options)
+        raise("ActionCable must be enabled to use Updatable") unless defined?(ActionCable)
+
+        debounce_time = options.delete(:debounce)
+        debounce_time ||= CableReady.config.updatable_debounce_time
+
+        if debounce_time.to_f > 0
+          key = compound([model_class, *options])
+          old_wait_until = CableReady::Updatable.debounce_adapter[key]
+          now = Time.now.to_f
+
+          if old_wait_until.nil? || old_wait_until < now
+            new_wait_until = now + debounce_time.to_f
+            CableReady::Updatable.debounce_adapter[key] = new_wait_until
+            ActionCable.server.broadcast(model_class, options)
+          end
+        else
+          ActionCable.server.broadcast(model_class, options)
+        end
       end
 
       def skip_updates_classes

data/app/models/concerns/extend_has_many.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/concern"
+
 module ExtendHasMany
   extend ::ActiveSupport::Concern
 

data/cable_ready.gemspec

@@ -12,31 +12,29 @@ Gem::Specification.new do |gem|
   gem.summary = "Out-of-Band Server Triggered DOM Operations"
 
   gem.files = Dir[
-    "lib/**/*.rb",
+    "lib/**/*.{rb,rake}",
     "app/**/*.rb",
     "app/assets/javascripts/*",
     "bin/*",
     "[A-Z]*"
   ]
 
-  gem.test_files = Dir["test/**/*.rb"]
+  gem.required_ruby_version = ">= 2.7.0"
 
   rails_version = ">= 5.2"
-  gem.add_dependency "actioncable", rails_version
+
   gem.add_dependency "actionpack", rails_version
   gem.add_dependency "actionview", rails_version
-  gem.add_dependency "activerecord", rails_version
   gem.add_dependency "activesupport", rails_version
   gem.add_dependency "railties", rails_version
-
   gem.add_dependency "thread-local", ">= 1.1.0"
 
   gem.add_development_dependency "magic_frozen_string_literal"
   gem.add_development_dependency "mocha"
   gem.add_development_dependency "pry"
   gem.add_development_dependency "pry-nav"
-  gem.add_development_dependency "rails", rails_version
   gem.add_development_dependency "rake"
   gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "standard", "1.19.1"
   gem.add_development_dependency "standardrb"
 end

data/lib/cable_ready/broadcaster.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/concern"
+
 module CableReady
   module Broadcaster
     include Identifiable

data/lib/cable_ready/cable_car.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "thread/local"
+
 module CableReady
   class CableCar < OperationBuilder
     extend Thread::Local

data/lib/cable_ready/channel.rb

@@ -5,6 +5,7 @@ module CableReady
     attr_reader :identifier
 
     def broadcast(clear: true)
+      raise("Action Cable must be enabled to use broadcast") unless defined?(ActionCable)
       clients_received = ActionCable.server.broadcast identifier, {
         "cableReady" => true,
         "operations" => operations_payload,
@@ -15,6 +16,7 @@ module CableReady
     end
 
     def broadcast_to(model, clear: true)
+      raise("Action Cable must be enabled to use broadcast_to") unless defined?(ActionCable)
       clients_received = identifier.broadcast_to model, {
         "cableReady" => true,
         "operations" => operations_payload,
@@ -24,13 +26,19 @@ module CableReady
       clients_received
     end
 
-    def broadcast_later(clear: true)
-      CableReadyBroadcastJob.perform_later(identifier: identifier, operations: operations_payload)
+    def broadcast_later(clear: true, queue: nil)
+      raise("Action Cable must be enabled to use broadcast_later") unless defined?(ActionCable)
+      CableReady::BroadcastJob
+        .set(queue: queue ? queue.to_sym : CableReady.config.broadcast_job_queue)
+        .perform_later(identifier: identifier, operations: operations_payload)
       reset! if clear
     end
 
-    def broadcast_later_to(model, clear: true)
-      CableReadyBroadcastJob.perform_later(identifier: identifier.name, operations: operations_payload, model: model)
+    def broadcast_later_to(model, clear: true, queue: nil)
+      raise("Action Cable must be enabled to use broadcast_later_to") unless defined?(ActionCable)
+      CableReady::BroadcastJob
+        .set(queue: queue ? queue.to_sym : CableReady.config.broadcast_job_queue)
+        .perform_later(identifier: identifier.name, operations: operations_payload, model: model)
       reset! if clear
     end
   end

data/lib/cable_ready/channels.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "thread/local"
+
 module CableReady
   # This class is a thread local singleton: CableReady::Channels.instance
   # SEE: https://github.com/socketry/thread-local/tree/master/guides/getting-started
@@ -13,7 +15,7 @@ module CableReady
 
     def [](*keys)
       keys.select!(&:itself)
-      identifier = keys.many? || (keys.one? && keys.first.respond_to?(:to_global_id)) ? compound(keys) : keys.pop
+      identifier = (keys.many? || (keys.one? && keys.first.respond_to?(:to_global_id))) ? compound(keys) : keys.pop
       @channels[identifier] ||= CableReady::Channel.new(identifier)
     end
 

data/lib/cable_ready/config.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "monitor"
+require "observer"
+require "singleton"
+
 module CableReady
   # This class is a process level singleton shared by all threads: CableReady::Config.instance
   class Config
@@ -7,14 +11,24 @@ module CableReady
     include Observable
     include Singleton
 
-    attr_accessor :on_failed_sanity_checks, :on_new_version_available
+    attr_accessor :on_failed_sanity_checks, :broadcast_job_queue, :precompile_assets, :updatable_debounce_time
     attr_writer :verifier_key
 
+    def on_new_version_available
+      warn "NOTICE: The `config.on_new_version_available` option has been removed from the CableReady initializer. You can safely remove this option from your initializer."
+    end
+
+    def on_new_version_available=(_)
+      warn "NOTICE: The `config.on_new_version_available` option has been removed from the CableReady initializer. You can safely remove this option from your initializer."
+    end
+
     def initialize
       super
       @operation_names = Set.new(default_operation_names)
       @on_failed_sanity_checks = :exit
-      @on_new_version_available = :ignore
+      @broadcast_job_queue = :default
+      @precompile_assets = true
+      @updatable_debounce_time = 0.1.seconds
     end
 
     def observers
@@ -72,6 +86,7 @@ module CableReady
         set_storage_item
         set_style
         set_styles
+        set_title
         set_value
         text_content
       ]).freeze

data/lib/cable_ready/engine.rb

@@ -1,32 +1,51 @@
+# frozen_string_literal: true
+
 require "rails/engine"
 
 module CableReady
   class Engine < Rails::Engine
+    # If you don't want to precompile CableReady's assets (eg. because you're using webpack),
+    # you can do this in an initializer:
+    #
+    # config.after_initialize do
+    #   config.assets.precompile -= CableReady::Engine::PRECOMPILE_ASSETS
+    # end
+    PRECOMPILE_ASSETS = %w[
+      cable_ready.js
+      cable_ready.umd.js
+    ]
+
+    initializer "cable_ready.assets" do |app|
+      if app.config.respond_to?(:assets) && CableReady.config.precompile_assets
+        app.config.assets.precompile += PRECOMPILE_ASSETS
+      end
+    end
+
     initializer "cable_ready.sanity_check" do
       SanityChecker.check! unless Rails.env.production?
     end
 
+    initializer "cable_ready.mimetype" do
+      Mime::Type.register "text/vnd.cable-ready.json", :cable_ready
+    end
+
     initializer "cable_ready.renderer" do
       ActiveSupport.on_load(:action_controller) do
         ActionController::Renderers.add :operations do |operations, options|
+          warn "DEPRECATED: CableReady's `render operations:` call has been renamed to `render cable_ready:`. Please update your render call."
+
           response.content_type ||= Mime[:cable_ready]
-          render json: operations.dispatch
+          response.headers["X-Cable-Ready-Version"] = CableReady::VERSION
+
+          render json: operations.respond_to?(:dispatch) ? operations.dispatch : operations
         end
 
-        Mime::Type.register "application/vnd.cable-ready.json", :cable_ready
-      end
-    end
+        ActionController::Renderers.add :cable_ready do |operations, options|
+          response.content_type ||= Mime[:cable_ready]
+          response.headers["X-Cable-Ready-Version"] = CableReady::VERSION
 
-    initializer "cable_ready.assets" do |app|
-      if app.config.respond_to?(:assets)
-        app.config.assets.precompile += %w[
-          cable_ready.js
-          cable_ready.min.js
-          cable_ready.min.js.map
-          cable_ready.umd.js
-          cable_ready.umd.min.js
-          cable_ready.umd.min.js.map
-        ]
+          render json: operations.respond_to?(:dispatch) ? operations.dispatch : operations
+        end
       end
     end