view_component 4.17.0 → 4.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49aef67be789faf45059eeab902b02dcc50197a5b2da2482306966f809c3a2a3
-  data.tar.gz: e8bab208c38f90f778eef18ba4f2f9a41593c88b4332870b537d11deaafcb647
+  metadata.gz: 2f3ee513a8505728d9295aa0a7c6ce8e228f256058c13f67591ac7697ab4eec1
+  data.tar.gz: 7b4a193c71baab6711b130dde0dbe2e84297db77d1e3ae1ac26805fe7272b796
 SHA512:
-  metadata.gz: 786b0a2c41adef88d25b11755a567b9adc356830ea2d23e9eb16b20d2882c38cbee10c0c14a6b2e052363f200b5493bdca493fdda87c514a109c93fac8501cb6
-  data.tar.gz: 7eb9c8c3234baf98fd725cdaf0d9ceae6a083f068bb043ed12b8db4162666370e4ad70f449adc5477c056dc72d12f6850090933579944480fd7618b2e3c0b51a
+  metadata.gz: b196d2a623e878c83325fe8ed684e0d8c938e9daa51668d1fd0665628162d29d6856748d76b65917fe3c6a3849486d77f1a8f50929d1207501fb5d66a2c9d37f
+  data.tar.gz: aecd6d15e2e16dac5557f9e9a082b191a9c36a604dbc9e4cd067aedeee0e478e7fd0d380267d2a623977c3b58f6666e9ead18ac8e9119a2c6216f350d14bb834

data/docs/CHANGELOG.md

@@ -10,6 +10,12 @@ nav_order: 6
 
 ## main
 
+## 4.18.0
+
+* Enable caching support for all components by default, and rename `ViewComponent::ExperimentallyCacheable` to `ViewComponent::Cacheable`. Including the module is no longer necessary. Breaking: remove existing `include ViewComponent::ExperimentallyCacheable` lines. Caching is no longer experimental.
+
+    *Erik Axel Nielsen, Joel Hawksley*
+
 ## 4.17.0
 
 * Only register the executor hook that watches component templates when Action View doesn't cache templates at boot. With template caching on, as in production, the hook did nothing but still read `ActionView::Base.cache_template_loading` on every request. That value lives in a class variable, which non-main Ractors can't read on Ruby 4.0, so under Rails' experimental `Rails.application.ractorize!` every request failed.

data/lib/view_component/base.rb

@@ -3,10 +3,12 @@
 require "action_view"
 require "action_view/base"
 require "view_component/collection"
+require "view_component/cache_digest"
 require "view_component/compile_cache"
 require "view_component/compiler"
 require "view_component/config"
 require "view_component/errors"
+require "view_component/cacheable"
 require "view_component/inline_template"
 require "view_component/preview"
 require "view_component/request_details"
@@ -31,6 +33,20 @@ end
 module ViewComponent
   class Base
     class << self
+      # A digest of the component's source, ancestors, and rendered dependencies.
+      #
+      # @param finder [ActionView::LookupContext, nil]
+      # @param format [Symbol]
+      #
+      # @return [String]
+      def cache_digest(finder: nil, format: :html)
+        ViewComponent::CacheDigest.digest(
+          self,
+          finder: finder || ViewComponent::CacheDigest.default_finder,
+          format: format
+        )
+      end
+
       delegate(*ViewComponent::Config.defaults.keys, to: :config)
 
       # Returns the current config.
@@ -106,6 +122,10 @@ module ViewComponent
     def render_in(view_context, **, &block)
       self.class.__vc_compile(raise_errors: true) unless self.class.__vc_compiled?
 
+      if self.class.__vc_cache_output && !@__vc_cache_bypassed
+        return __vc_render_cached(view_context, block)
+      end
+
       __vc_check_reused_instance!
       __vc_reset_render_state!
 
@@ -423,6 +443,21 @@ module ViewComponent
       @view_context.instance_variable_set(:@virtual_path, old_virtual_path)
     end
 
+    # Use the component's source digest for fragments inside its own template.
+    #
+    # @private
+    def digest_path_from_template(template)
+      component_path = self.class.virtual_path
+      return super unless component_path && template.virtual_path == component_path
+
+      digest = self.class.cache_digest(
+        finder: lookup_context,
+        format: template.format || lookup_context.formats.first || :html
+      )
+
+      digest.present? ? "#{component_path}:#{digest}" : component_path
+    end
+
     private
 
     attr_reader :view_context
@@ -668,6 +703,7 @@ module ViewComponent
         # owner is included in a prefix like `ApplicationComponent.inherited`.
         child.identifier = caller_locations(1, 10).reject { |l| l.base_label == "inherited" }[0].path
         child.virtual_path = child.name&.underscore
+        ViewComponent::CacheDigest.register(child)
 
         # Set collection parameter to the extended component
         child.with_collection_parameter(__vc_provided_collection_parameter)
@@ -707,6 +743,17 @@ module ViewComponent
         @__vc_compiler ||= Compiler.new(self)
       end
 
+      # Synthetic digest source computed at boot. Not inherited, since each
+      # component's source differs.
+      #
+      # @private
+      attr_accessor :__vc_cache_digest_source
+
+      # @private
+      def __vc_template_formats
+        __vc_compiler.template_formats
+      end
+
       # Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):
       #
       # ```ruby
@@ -857,6 +904,8 @@ module ViewComponent
       attr_reader :__vc_provided_collection_parameter
     end
 
+    include ViewComponent::Cacheable
+
     ActiveSupport.run_load_hooks(:view_component, self)
   end
 end

data/lib/view_component/cache_digest/digestor_lookup.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "action_view/digestor"
+
+module ViewComponent
+  module CacheDigest
+    # Lets `ActionView::Digestor` find the synthetic templates `Resolver` builds.
+    #
+    # Prepended to the Digestor's singleton class rather than appending
+    # `Resolver` to the application's view paths, so the resolver is only ever
+    # consulted while digesting. Code that walks `view_paths` and expects every
+    # entry to be a file system resolver is unaffected.
+    #
+    # @private
+    module DigestorLookup
+      # @private
+      def self.install!
+        digestor = ActionView::Digestor.singleton_class
+        return if digestor.include?(self)
+
+        digestor.prepend(self)
+      end
+
+      private
+
+      def find_template(finder, name, prefixes, partial, keys)
+        Resolver.instance.find_templates(name, prefixes.first, partial, {formats: finder.formats}).first || super
+      end
+    end
+  end
+end

data/lib/view_component/cache_digest/resolver.rb

@@ -42,21 +42,11 @@ module ViewComponent
       end
       alias_method :==, :eql?
 
-      private
-
-      def build_template(component, virtual_path, details)
-        ActionView::Template.new(
-          source_for(component),
-          "view_component cache digest for #{component.name}",
-          ActionView::Template.handler_for_extension(:erb),
-          locals: [],
-          format: Array(details[:formats]).first || :html,
-          virtual_path: virtual_path
-        )
-      end
-
       # The synthetic source. Every section exists to change this string when
       # something the component renders from changes.
+      #
+      # @param component [Class]
+      # @return [String]
       def source_for(component)
         parts = []
 
@@ -88,6 +78,19 @@ module ViewComponent
         parts.join("\n")
       end
 
+      private
+
+      def build_template(component, virtual_path, details)
+        ActionView::Template.new(
+          component.__vc_cache_digest_source || source_for(component),
+          "view_component cache digest for #{component.name}",
+          ActionView::Template.handler_for_extension(:erb),
+          locals: [],
+          format: Array(details[:formats]).first || :html,
+          virtual_path: virtual_path
+        )
+      end
+
       # The component and any component superclasses, nearest first. Including
       # ancestors means editing `ApplicationComponent` invalidates every
       # component that inherits from it.
@@ -165,8 +168,9 @@ module ViewComponent
       end
 
       # Built once at load time rather than memoized, so no class-level state
-      # is written after boot. The resolver is stateless: it reads from disk on
-      # every call so it can't go stale when a component changes.
+      # is written after boot. Unless sources were precomputed at boot, the
+      # resolver reads from disk on every call so it can't go stale when a
+      # component changes.
       INSTANCE = new
     end
   end

data/lib/view_component/cache_digest.rb

@@ -21,15 +21,15 @@ module ViewComponent
   #    not just its template.
   #
   # This module fixes both, reusing Rails' own `ActionView::Digestor` rather than
-  # reimplementing static analysis. Components opt in individually by including
-  # `ViewComponent::ExperimentallyCacheable`; until at least one component does,
-  # every hook here short-circuits.
+  # reimplementing static analysis. Every discovered component is tracked
+  # automatically, independently of output caching.
   #
   # @private
   module CacheDigest
     extend ActiveSupport::Autoload
 
     autoload :DependencyTracking
+    autoload :DigestorLookup
     autoload :Resolver
 
     # Prefix for the synthetic virtual paths components are digested under.
@@ -56,8 +56,7 @@ module ViewComponent
     # Rails' escape hatch for dependencies static analysis can't see.
     EXPLICIT_DEPENDENCY = /#\s*Template Dependency:\s*(\S+)/
     class << self
-      # Virtual paths of components that have opted into caching, mapped to
-      # their class names.
+      # Virtual paths of components, mapped to their class names.
       #
       # Class *names* rather than class objects so the registry survives
       # autoloader reloads without pinning stale constants in memory.
@@ -67,11 +66,6 @@ module ViewComponent
         @registry ||= {}
       end
 
-      # @return [Boolean] whether any component has opted in.
-      def enabled?
-        !registry.empty?
-      end
-
       # @private
       def register(component)
         return unless component.virtual_path && component.name
@@ -108,28 +102,22 @@ module ViewComponent
         constantize_component(name)
       end
 
-      # Scan a template's source for renders of cacheable components.
-      #
-      # Called for every template Rails digests, so it exits early when the
-      # feature is unused.
+      # Scan a template's source for renders of components.
       #
       # @return [Array<String>] synthetic virtual paths
       def dependencies_in(template)
-        return [] unless enabled?
-
         component_paths_in(template.source)
       end
 
       # Scan arbitrary source (a template or a component's Ruby file) for
-      # renders of cacheable components.
+      # renders of components.
       #
       # @return [Array<String>] synthetic virtual paths
       def component_paths_in(source)
         return [] unless source.is_a?(String) && source.include?("render")
 
         source.scan(RENDER_CALL).flatten.uniq.filter_map do |constant_name|
-          component = constantize_component(constant_name)
-          virtual_path_for(component) if component
+          registered_path_for(constantize_component(constant_name))
         end
       end
 
@@ -182,17 +170,19 @@ module ViewComponent
           next unless /\A(?:::)?[A-Z]/.match?(declared)
 
           component = constantize_component(declared)
-          [declared, virtual_path_for(component)] if component
+          virtual_path = registered_path_for(component)
+          [declared, virtual_path] if virtual_path
         end
       end
 
       # Compute the digest of a component using Rails' digest tree.
       #
-      # @param component [Class] a component that includes `ExperimentallyCacheable`
+      # @param component [Class] a component class
       # @param finder [ActionView::LookupContext]
       # @param format [Symbol]
       # @return [String]
       def digest(component, finder: default_finder, format: :html)
+        register(component)
         virtual_path = virtual_path_for(component)
         return "" unless virtual_path
 
@@ -210,24 +200,53 @@ module ViewComponent
 
       # Wire the tracker and resolver into Action View.
       #
-      # Called each time a component includes `ExperimentallyCacheable`. Both
-      # steps below are individually idempotent, so no "already installed" flag
-      # is kept. Both hooks short-circuit while the registry is empty, so
-      # applications that never opt in are unaffected.
+      # Installed during engine initialization. Both steps are idempotent.
       #
       # @private
       def install!
         DependencyTracking.install!
+        DigestorLookup.install!
+      end
 
-        ActiveSupport.on_load(:action_controller_base) do
-          resolver = ViewComponent::CacheDigest::Resolver.instance
+      # Compute component digests at boot, so requests read them from memory
+      # instead of reading and scanning source files.
+      #
+      # Only safe when templates are cached at boot: the precomputed sources are
+      # never refreshed.
+      #
+      # @param components [Array<Class>]
+      # @return [void]
+      # @private
+      def precompute!(components)
+        # Register everything first: a registration expires every memoized
+        # digest, so registering midway would discard digests already warmed.
+        components.each { |component| register(component) }
+
+        components.each do |component|
+          component.__vc_cache_digest_source = Resolver.instance.source_for(component).freeze
+        end
 
-          append_view_path(resolver) unless view_paths.include?(resolver)
+        # Warms the same digest cache requests read, since a lookup context's
+        # cache is shared by every context with the same details.
+        components.each do |component|
+          component.__vc_template_formats.each do |format|
+            finder = ActionView::LookupContext.new(ActionController::Base.view_paths, formats: [format])
+            component.cache_digest(finder: finder, format: format)
+          end
         end
       end
 
       private
 
+      # Record the actual class name rather than trying to reverse a virtual
+      # path, which may contain acronyms or be overridden by the component.
+      def registered_path_for(component)
+        return unless component
+
+        register(component)
+        virtual_path_for(component)
+      end
+
       # Drop Action View's memoized template digests, leaving its resolver
       # caches alone: no template changed, only the set of dependencies the
       # Digestor can see.
@@ -235,15 +254,14 @@ module ViewComponent
         ActionView::LookupContext::DetailsKey.digest_caches.each(&:clear)
       end
 
-      # Resolve a constant name to a component that opted into caching.
+      # Resolve a constant name to any ViewComponent.
       #
       # Returns nil for anything else, including constants that don't exist.
       # Autoloading here is safe: the template is about to render this constant
       # anyway.
       def constantize_component(constant_name)
         component = constant_name.safe_constantize
-        return unless component.is_a?(Class)
-        return unless component.respond_to?(:__vc_cacheable?) && component.__vc_cacheable?
+        return unless component.is_a?(Class) && component < ViewComponent::Base
 
         component
       end

data/lib/view_component/{experimentally_cacheable.rb → cacheable.rb}

@@ -3,26 +3,13 @@
 require "view_component/cache_digest"
 
 module ViewComponent
-  # Experimental caching support for ViewComponents.
+  # Caching support for ViewComponents.
   #
-  # **This API is experimental.** It may change or be removed in a non-major
-  # release. Please share feedback in
-  # https://github.com/ViewComponent/view_component/issues/234.
-  #
-  # Including this module does two things:
-  #
-  # 1. Registers the component with Rails' template digest tree, so a
-  #    `<% cache %>` block is invalidated when the component's template, Ruby
-  #    class, sidecar files, or child components change. This covers blocks
-  #    wrapping the component in a view and blocks inside the component's own
-  #    template.
-  # 2. Enables the `cache_on` macro, which caches the component's own rendered
-  #    output.
+  # Provides the `cache_on` macro, which caches the component's own rendered
+  # output. Components don't cache their output until they call `cache_on`.
   #
   # ```ruby
   # class MessageComponent < ViewComponent::Base
-  #   include ViewComponent::ExperimentallyCacheable
-  #
   #   cache_on :message
   #
   #   def initialize(message:)
@@ -30,7 +17,7 @@ module ViewComponent
   #   end
   # end
   # ```
-  module ExperimentallyCacheable
+  module Cacheable
     extend ActiveSupport::Concern
 
     # Stands in for `nil` in the cache key. Without it, `expand_cache_key`
@@ -38,11 +25,6 @@ module ViewComponent
     # that respect would share an entry.
     NIL_CACHE_VALUE = :__vc_nil
 
-    included do
-      ViewComponent::CacheDigest.install!
-      ViewComponent::CacheDigest.register(self)
-    end
-
     class_methods do
       # Declare the values that identify a rendering of this component.
       #
@@ -55,8 +37,7 @@ module ViewComponent
       # ```
       #
       # Calling `cache_on` opts the component into caching its own output.
-      # Without it, including this module only registers the component with
-      # Rails' digest tree.
+      # Components that don't call it aren't cached.
       #
       # Pass `if:` or `unless:` to cache only some renders. Both accept a method
       # name or a proc evaluated on the component:
@@ -119,11 +100,6 @@ module ViewComponent
         superclass.__vc_cache_unless if superclass.respond_to?(:__vc_cache_unless)
       end
 
-      # @private
-      def __vc_cacheable?
-        true
-      end
-
       # Whether this component caches its own rendered output.
       #
       # @return [Boolean]
@@ -131,67 +107,11 @@ module ViewComponent
         __vc_cache_on.any?
       end
 
-      # A digest of everything this component renders from: its template, its
-      # Ruby class, its sidecar files, its superclasses, and the components and
-      # partials it renders.
-      #
-      # Computed with Rails' own `ActionView::Digestor`, so it's the same digest
-      # used to invalidate `<% cache %>` blocks.
+      # `__vc_caches_output?`, stored when the component compiles so rendering
+      # reads a flag instead of computing it.
       #
-      # Usable outside a request, where no view context exists:
-      #
-      # ```ruby
-      # MessageComponent.cache_digest
-      # ```
-      #
-      # @param finder [ActionView::LookupContext] Defaults to a lookup context
-      #   built from `ActionController::Base.view_paths`.
-      # @param format [Symbol]
-      # @return [String]
-      def cache_digest(finder: nil, format: :html)
-        ViewComponent::CacheDigest.digest(
-          self,
-          finder: finder || ViewComponent::CacheDigest.default_finder,
-          format: format
-        )
-      end
-
       # @private
-      def inherited(child)
-        super
-        ViewComponent::CacheDigest.register(child)
-      end
-    end
-
-    # Renders the component, reading from and writing to the Rails cache when
-    # `cache_on` has been declared.
-    #
-    # @private
-    def render_in(view_context, **, &block)
-      return super unless self.class.__vc_caches_output?
-
-      # Content provided by the caller isn't part of the cache key, so caching
-      # it would serve one caller's content to another. Raised whether or not
-      # caching is currently enabled, so the conflict surfaces in development
-      # and test rather than only in production.
-      if block || __vc_content_set_by_with_content_defined? || __vc_slots_set_by_caller?
-        raise ContentPassedToCachedComponentError.new(self.class.name)
-      end
-
-      return super unless __vc_cache_enabled?(view_context)
-
-      store = Rails.cache
-      key = cache_key(view_context)
-
-      if (cached = store.read(key))
-        # Safe to mark as HTML-safe: the cached string was produced by this same
-        # rendering pipeline, which escapes output before it's written.
-        return cached.html_safe
-      end
-
-      super.tap do |output|
-        store.write(key, output.to_s)
-      end
+      attr_accessor :__vc_cache_output
     end
 
     # The cache key for this rendering of the component.
@@ -226,34 +146,39 @@ module ViewComponent
       )
     end
 
-    # The digest Rails mixes into the key of a `<% cache %>` block.
-    #
-    # `ActionView::Helpers::CacheHelper` digests the virtual path of whichever
-    # template is rendering. Inside a component that path is the component's
-    # own, which resolves to nothing: component templates aren't in the view
-    # paths. The Digestor returns an empty digest, `CacheHelper` falls back to
-    # the bare virtual path, and the fragment never invalidates.
-    #
-    # Substituting the digest the component already computes makes a `cache`
-    # block in a component template behave like one in a view. Everything else
-    # the component renders — a partial, say — keeps Rails' behavior.
-    #
-    # @private
-    def digest_path_from_template(template)
-      component_path = self.class.virtual_path
-      return super unless component_path && template.virtual_path == component_path
-
-      digest = self.class.cache_digest(
-        finder: lookup_context,
-        format: template.format || __vc_cache_format(lookup_context)
-      )
+    private
+
+    # Renders through the Rails cache. Called by `Base#render_in` for
+    # components that declare `cache_on`.
+    def __vc_render_cached(view_context, content_block)
+      # Content provided by the caller isn't part of the cache key, so caching
+      # it would serve one caller's content to another. Raised whether or not
+      # caching is currently enabled, so the conflict surfaces in development
+      # and test rather than only in production.
+      if content_block || __vc_content_set_by_with_content_defined? || __vc_slots_set_by_caller?
+        raise ContentPassedToCachedComponentError.new(self.class.name)
+      end
+
+      return __vc_render_uncached(view_context) unless __vc_cache_enabled?(view_context)
+
+      store = Rails.cache
+      key = cache_key(view_context)
+
+      if (cached = store.read(key))
+        # Safe to mark as HTML-safe: the cached string was produced by this same
+        # rendering pipeline, which escapes output before it's written.
+        return cached.html_safe
+      end
 
-      # An empty digest means the component couldn't be resolved. Falling back
-      # to the bare virtual path matches what `CacheHelper` does with one.
-      digest.present? ? "#{component_path}:#{digest}" : component_path
+      __vc_render_uncached(view_context).tap do |output|
+        store.write(key, output.to_s)
+      end
     end
 
-    private
+    def __vc_render_uncached(view_context)
+      @__vc_cache_bypassed = true
+      render_in(view_context)
+    end
 
     # Slots set by the caller via `with_*`. Checked before rendering, so slots
     # a component fills in for itself with a `default_*` method — which resolve

data/lib/view_component/compiler.rb

@@ -50,6 +50,8 @@ module ViewComponent
 
         define_render_template_for
 
+        @component.__vc_cache_output = @component.__vc_caches_output?
+
         @component.__vc_register_default_slots
         @component.__vc_build_i18n_backend
 
@@ -76,6 +78,14 @@ module ViewComponent
       filtered_templates
     end
 
+    # Formats the component has templates for. Inline templates and `#call`
+    # methods have no format of their own and render as HTML.
+    #
+    # @return [Array<Symbol>]
+    def template_formats
+      gather_templates.map { |template| template.format || :html }.uniq
+    end
+
     private
 
     attr_reader :templates

data/lib/view_component/engine.rb

@@ -3,11 +3,16 @@
 require "rails"
 require "view_component/config"
 require "view_component/deprecation"
+require "view_component/cache_digest"
 
 module ViewComponent
   class Engine < Rails::Engine # :nodoc:
     config.view_component = ViewComponent::Config.current
 
+    initializer "view_component.cache_digest" do
+      ViewComponent::CacheDigest.install!
+    end
+
     initializer "view_component.set_configs" do |app|
       options = app.config.view_component
 
@@ -89,10 +94,11 @@ module ViewComponent
       ActiveSupport.on_load(:after_initialize) do
         if Rails.application.config.eager_load
           ActiveSupport::Notifications.instrument("compile.view_component") do
-            ViewComponent::Base.descendants.each do |component|
-              next if component.anonymous?
+            components = ViewComponent::Base.descendants.reject(&:anonymous?)
+            components.each(&:__vc_compile)
 
-              component.__vc_compile
+            if ActionView::Base.cache_template_loading
+              ViewComponent::CacheDigest.precompute!(components.select(&:__vc_compiled?))
             end
           end
         end

data/lib/view_component/version.rb

@@ -3,7 +3,7 @@
 module ViewComponent
   module VERSION
     MAJOR = 4
-    MINOR = 17
+    MINOR = 18
     PATCH = 0
     PRE = nil
 

data/lib/view_component.rb

@@ -9,11 +9,11 @@ module ViewComponent
 
   autoload :Base
   autoload :CacheDigest
+  autoload :Cacheable
   autoload :Compiler
   autoload :CompileCache
   autoload :Config
   autoload :Deprecation
-  autoload :ExperimentallyCacheable
   autoload :InlineTemplate
   autoload :Instrumentation
   autoload :Preview

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component
 version: !ruby/object:Gem::Version
-  version: 4.17.0
+  version: 4.18.0
 platform: ruby
 authors:
 - ViewComponent Team
@@ -93,7 +93,9 @@ files:
 - lib/view_component/base.rb
 - lib/view_component/cache_digest.rb
 - lib/view_component/cache_digest/dependency_tracking.rb
+- lib/view_component/cache_digest/digestor_lookup.rb
 - lib/view_component/cache_digest/resolver.rb
+- lib/view_component/cacheable.rb
 - lib/view_component/collection.rb
 - lib/view_component/compile_cache.rb
 - lib/view_component/compiler.rb
@@ -102,7 +104,6 @@ files:
 - lib/view_component/deprecation.rb
 - lib/view_component/engine.rb
 - lib/view_component/errors.rb
-- lib/view_component/experimentally_cacheable.rb
 - lib/view_component/inline_template.rb
 - lib/view_component/instrumentation.rb
 - lib/view_component/preview.rb