view_component 4.14.0 → 4.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83cf2f7914c64ec4ca156f19d975d79d311619024fb550fde59c0e6f807ca02c
-  data.tar.gz: 918cc12667440e6a50793addc531431050e06bda525f348c8522487ea0208439
+  metadata.gz: 9da4df780e2f53937b1593ef29fbbf9ce09662b48de7bc56ceae812c43880d2f
+  data.tar.gz: 94c6f23684dc139431a5c912a9e7fab5f70e2e794ba6bb72f5b66211c97f0e8c
 SHA512:
-  metadata.gz: fa5696a0ca7c945fa3ed682fb8f679fd75c462ddb0651b8926e64448392507a5616dcee97218e0a74c3eb4f4d384a89ff2f26fd08d89c9ff86ca961fd6cd410d
-  data.tar.gz: f1ced2760c93c93d46e2ed508ec234abbe498100ccb80d1ef83f6d7c1b17e79b7ecbd44f26745e36a7fef74426da49867bbdef038885b954b04982d788e4c322
+  metadata.gz: 50b36d70558457271f43deb0b67473209af190979ca48c68ce1b3116b27abf06255b0d9312c53382600be23d75aa2304b58926d9e52f314923c4968182b10e53
+  data.tar.gz: c687e6eec0d97bd5ea53b3f5b51012e94ca75bd3d659bd1ac2ea03d3343e4d88e695aa5b822d5fe8f55a4a239163cd3df7048a33195b95132ac95e186a491b7b

data/app/controllers/view_components_system_test_controller.rb

@@ -11,6 +11,7 @@ class ViewComponentsSystemTestController < ActionController::Base # :nodoc:
     end
 
     rescue_from ViewComponent::SystemTestControllerNefariousPathError, with: :render_not_found
+    rescue_from Errno::ENOENT, with: :render_not_found
 
     def system_test_entrypoint
       render file: @path

data/docs/CHANGELOG.md

@@ -10,6 +10,32 @@ nav_order: 6
 
 ## main
 
+## 4.15.0
+
+* Add experimental caching support, opt-in per component via `include ViewComponent::ExperimentallyCacheable`.
+
+    Components have never participated in Rails' template digests, so a `<% cache %>` block wrapping `render MyComponent.new` was never invalidated when the component changed ([#234](https://github.com/ViewComponent/view_component/issues/234), open since 2020).
+
+    Including the module registers the component with Rails' own `ActionView::Digestor`, so fragment caches are invalidated when the component's template, Ruby class, sidecar files, superclasses, child components, or rendered partials change. This includes components and partials rendered from inline templates and `#call` methods. Adding `cache_on` caches the component's own rendered output, optionally guarded by `if:`/`unless:`, and `.cache_digest` exposes the digest for use outside a request.
+
+    ```ruby
+    class MessageComponent < ViewComponent::Base
+      include ViewComponent::ExperimentallyCacheable
+
+      cache_on :message, unless: -> { message.draft? }
+
+      def initialize(message:)
+        @message = message
+      end
+    end
+    ```
+
+    **This API is experimental and may change or be removed in a non-major release.** It's shipping opt-in and per-component precisely so we can iterate on it in response to real-world use. **Please try it and tell us what breaks, what's missing, and what feels wrong in [#234](https://github.com/ViewComponent/view_component/issues/234).** We're especially interested in feedback on: whether `cache_on` is the right shape for declaring cache keys, how the feature behaves with slots and content blocks, and whether the `# Template Dependency:` escape hatch is sufficient for dynamic renders. See [the caching guide](https://viewcomponent.org/guide/caching.html) for details and known caveats.
+
+    This work builds directly on prior art from the community. The `cache_on` API and the case for component-local caching come from [#2126](https://github.com/ViewComponent/view_component/pull/2126) by *Reegan Viljoen*. The approach of integrating with Rails' digest tree rather than reimplementing it comes from [`view_component-cache_digest`](https://github.com/tildeio/view_component-cache_digest) by *Godfrey Chan*. The invalidation cases it's tested against were contributed by *JWShuff* and *timburgan*, drawing on [`view_component-fragment_caching`](https://github.com/patrickarnett/view_component-fragment_caching) by *Patrick Arnett*. The issue was opened and researched by *ozzyaaron*, *pinzonjulian*, and *Derek Kniffin*, and the digest workaround that surfaced the superclass gap came from *cannikin* and *rnestler*. Cache-key correctness issues (formats sharing an entry, positional `nil` collisions, conditional caching, and ignored `cache_on` blocks) were found and reported by *Reegan Viljoen*.
+
+    *Reegan Viljoen*, *Godfrey Chan*, *JWShuff*, *timburgan*, *Patrick Arnett*, *ozzyaaron*, *pinzonjulian*, *Derek Kniffin*, *cannikin*, *rnestler*, *Joel Hawksley*
+
 ## 4.14.0
 
 * Freeze `ReusedInstanceError::MESSAGE` and update `test_renders_component_with_asset_url` to build a fresh `AssetComponent` per render, fixing CI regressions introduced by the GHSA-8qw7-6phv-7q6p remediation.

data/lib/view_component/cache_digest/dependency_tracking.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "action_view/dependency_tracker"
+
+module ViewComponent
+  module CacheDigest
+    # Teaches `ActionView::DependencyTracker` to see components.
+    #
+    # Prepended to the tracker's singleton class rather than to a specific
+    # tracker implementation (`ERBTracker`, `RubyTracker`, or the trackers
+    # registered by the Haml and Slim gems). `find_dependencies` is the single
+    # seam every tracker flows through, so hooking it here works regardless of
+    # which handler a template uses and doesn't depend on tracker internals.
+    #
+    # @private
+    module DependencyTracking
+      def find_dependencies(name, template, view_paths = nil)
+        dependencies = super
+        source = template.source
+
+        # `# Template Dependency: SomeComponent` names a class, which Rails
+        # would resolve as a template path and never find. Swap it for the path
+        # the component is digested under, so the declaration resolves instead
+        # of becoming a missing node.
+        CacheDigest.explicit_component_dependencies(source).each do |declared, virtual_path|
+          dependencies = dependencies - [declared] + [virtual_path]
+        end
+
+        dependencies + CacheDigest.dependencies_in(template)
+      rescue
+        # A broken digest is preferable to a broken render. Falling back to the
+        # dependencies Rails found on its own means the component simply isn't
+        # tracked, which is the pre-existing behavior.
+        super
+      end
+
+      # @private
+      def self.install!
+        tracker = ActionView::DependencyTracker.singleton_class
+        return if tracker.include?(self)
+
+        tracker.prepend(self)
+      end
+    end
+  end
+end

data/lib/view_component/cache_digest/resolver.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module CacheDigest
+    # Synthesizes the templates Rails' `ActionView::Digestor` digests components from.
+    #
+    # Once `DependencyTracking` reports `view_component/cache_digest/foo_component`
+    # as a dependency, the Digestor tries to find a template at that path. No such
+    # file exists: a component's rendered output depends on its template *and* its
+    # Ruby class, its sidecar files, and its superclasses.
+    #
+    # This resolver answers with a synthetic template whose source encodes all of
+    # those inputs. The template is never compiled or rendered; the Digestor only
+    # reads `#source` to hash it and to scan it for further dependencies.
+    #
+    # @private
+    class Resolver < ActionView::Resolver
+      # Extensions whose contents are hashed into the synthetic source.
+      SIDECAR_EXTENSIONS = %w[yml yaml].freeze
+
+      class << self
+        def instance
+          INSTANCE
+        end
+      end
+
+      def find_templates(name, prefix, partial, details, locals = [])
+        virtual_path = [prefix.presence, name].compact.join("/")
+        component = CacheDigest.component_for(virtual_path)
+        return [] unless component
+
+        [build_template(component, virtual_path, details)]
+      rescue
+        # Never let digest resolution break rendering. Returning no template
+        # makes the Digestor treat this as a missing node, which degrades to
+        # the behavior components have without this feature.
+        []
+      end
+
+      def to_s
+        "ViewComponent::CacheDigest::Resolver"
+      end
+      alias_method :to_path, :to_s
+
+      def eql?(other)
+        self.class.equal?(other.class)
+      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.
+      def source_for(component)
+        parts = []
+
+        # Safety net: this template should never be rendered, only digested.
+        parts << "<% raise ViewComponent::CacheDigestTemplateError.new(#{component.name.inspect}) %>"
+
+        # Content hashes of the Ruby files and sidecar files backing the
+        # component and its component superclasses. Hashing rather than
+        # inlining keeps the source small and avoids embedding Ruby that a
+        # tracker might misread as a render call.
+        source_files(component).each do |path|
+          parts << "<%# Resolved Dependency: #{path} #{file_digest(path)} %>"
+        end
+
+        # Everything the component renders from Ruby rather than from a
+        # template: `# Template Dependency:` declarations, components rendered
+        # from `#call` methods, and partials referenced by string path.
+        # Re-emitted so the Digestor resolves them as tree nodes.
+        ruby_dependencies(component).each do |dependency|
+          parts << "<%# Template Dependency: #{dependency} %>"
+        end
+
+        # Template sources verbatim, so trackers can discover the partials and
+        # components they render.
+        template_sources(component).each do |source|
+          parts << source
+        end
+
+        parts.join("\n")
+      end
+
+      # The component and any component superclasses, nearest first. Including
+      # ancestors means editing `ApplicationComponent` invalidates every
+      # component that inherits from it.
+      def component_ancestors(component)
+        component.ancestors.select do |ancestor|
+          ancestor.is_a?(Class) &&
+            ancestor <= ViewComponent::Base &&
+            ancestor != ViewComponent::Base
+        end
+      end
+
+      def source_files(component)
+        component_ancestors(component).flat_map { |ancestor|
+          [ancestor.identifier, *ancestor.sidecar_files(SIDECAR_EXTENSIONS)]
+        }.compact.uniq.select { |path| ::File.exist?(path) }
+      end
+
+      def template_files(component)
+        component_ancestors(component)
+          .flat_map { |ancestor| ancestor.sidecar_files(ActionView::Template::Handlers.extensions) }
+          .uniq
+          .select { |path| ::File.exist?(path) }
+      end
+
+      # Sidecar template files plus inline templates, which live in the Ruby
+      # file and so are invisible to Action View's trackers.
+      def template_sources(component)
+        sources = template_files(component).map { |path| ::File.read(path) }
+
+        component_ancestors(component).each do |ancestor|
+          inline_template = ancestor.__vc_inline_template
+          sources << inline_template.source if inline_template
+        end
+
+        sources.uniq
+      end
+
+      def explicit_dependencies(component)
+        ruby_sources(component).flat_map { |source|
+          declared = source.scan(CacheDigest::EXPLICIT_DEPENDENCY).flatten
+
+          # Component class names are translated to the path they're digested
+          # under; anything else is a template path already.
+          CacheDigest.explicit_component_dependencies(source).each do |name, virtual_path|
+            declared = declared - [name] + [virtual_path]
+          end
+
+          declared
+        }.uniq
+      end
+
+      # Everything a component renders from Ruby code rather than from a
+      # template. Action View's trackers only read templates, so a `#call`
+      # method that renders another component or a partial would otherwise go
+      # unnoticed.
+      def ruby_dependencies(component)
+        virtual_path = CacheDigest.virtual_path_for(component)
+
+        explicit_dependencies(component) |
+          ruby_sources(component).flat_map { |source|
+            CacheDigest.component_paths_in(source) |
+              CacheDigest.partial_paths_in(source, virtual_path)
+          }.uniq
+      end
+
+      def ruby_sources(component)
+        component_ancestors(component).filter_map { |ancestor|
+          path = ancestor.identifier
+          ::File.read(path) if path && ::File.exist?(path)
+        }
+      end
+
+      def file_digest(path)
+        ActiveSupport::Digest.hexdigest(::File.read(path))
+      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.
+      INSTANCE = new
+    end
+  end
+end

data/lib/view_component/cache_digest.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies/autoload"
+require "action_view/digestor"
+require "action_view/render_parser"
+
+module ViewComponent
+  # Integrates ViewComponents into Rails' template digest tree.
+  #
+  # Rails computes a digest for every template from its source and the templates
+  # it renders. That digest is mixed into the key of every `<% cache %>` block in
+  # the template, so editing a partial busts the caches of everything that
+  # renders it.
+  #
+  # Components are invisible to that mechanism for two reasons:
+  #
+  # 1. **Discovery** — `ActionView::DependencyTracker` doesn't recognize
+  #    `render SomeComponent.new(...)` as a dependency.
+  # 2. **Resolution** — component templates live outside the view paths, and a
+  #    component's rendered output depends on its Ruby class and sidecar files,
+  #    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.
+  #
+  # @private
+  module CacheDigest
+    extend ActiveSupport::Autoload
+
+    autoload :DependencyTracking
+    autoload :Resolver
+
+    # Prefix for the synthetic virtual paths components are digested under.
+    #
+    # Namespaced under `view_component/` so it can't collide with an
+    # application partial.
+    VIRTUAL_PATH_PREFIX = "view_component/cache_digest"
+
+    # Matches `render FooComponent`, `render(Foo::BarComponent.new(...))`,
+    # `render FooComponent.with_collection(...)`, etc.
+    #
+    # Deliberately a plain source scan rather than a tracker-specific hook: it
+    # behaves identically for the ERB tracker, the Prism-based Ruby tracker, and
+    # third-party Haml/Slim trackers.
+    RENDER_CALL = /
+      \brender(?:_to_string)?\b   # render or render_to_string
+      \s*\(?\s*                   # optional opening paren
+      (?<const>
+        (?:::)?[A-Z]\w*           # a constant
+        (?:::[A-Z]\w*)*           # optionally namespaced
+      )
+    /x
+
+    # 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.
+      #
+      # Class *names* rather than class objects so the registry survives
+      # autoloader reloads without pinning stale constants in memory.
+      #
+      # @return [Hash{String => String}]
+      def registry
+        @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
+
+        registry[component.virtual_path] = component.name
+      end
+
+      # The synthetic virtual path a component is digested under.
+      #
+      # @return [String, nil]
+      def virtual_path_for(component)
+        return unless component.respond_to?(:virtual_path) && component.virtual_path
+
+        "#{VIRTUAL_PATH_PREFIX}/#{component.virtual_path}"
+      end
+
+      # Resolve a synthetic virtual path back to the component that owns it.
+      #
+      # @return [Class, nil]
+      def component_for(virtual_path)
+        return unless virtual_path.start_with?("#{VIRTUAL_PATH_PREFIX}/")
+
+        name = registry[virtual_path.delete_prefix("#{VIRTUAL_PATH_PREFIX}/")]
+        return unless name
+
+        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.
+      #
+      # @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.
+      #
+      # @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
+        end
+      end
+
+      # Scan a component's Ruby source for partials referenced by string path,
+      # such as `render "posts/byline"` inside a `#call` method.
+      #
+      # Uses Rails' own render parser — the same one `RubyTracker` runs over
+      # compiled templates — rather than a second implementation of the same
+      # analysis. Its results are then narrowed to paths that appear verbatim in
+      # the source, which keeps string literals and discards the speculative
+      # `things/_thing` entries the parser infers from dynamic renders like
+      # `render @thing` or `render FooComponent.new`. Those would resolve to
+      # nothing and only add log noise; components rendered from Ruby are
+      # already found precisely by `component_paths_in`.
+      #
+      # @param source [String] Ruby source
+      # @param name [String] virtual path the source is being digested under
+      # @return [Array<String>] partial virtual paths
+      def partial_paths_in(source, name)
+        return [] unless source.is_a?(String) && source.include?("render")
+
+        RENDER_PARSER.new(name, source).render_calls.uniq.select do |path|
+          source.include?(path) || source.include?(path.sub(%r{(\A|/)_}, '\1'))
+        end
+      rescue
+        # Never let digest computation break rendering.
+        []
+      end
+
+      # Action View has shipped its render parser as a class (Rails 7.1, and
+      # again on main) and as a module holding a `Default` implementation
+      # chosen from Prism or Ripper (Rails 7.2 through 8.1).
+      #
+      # @param parser [Class, Module] `ActionView::RenderParser`
+      # @return [Class]
+      def resolve_render_parser(parser)
+        parser.is_a?(Class) ? parser : parser::Default
+      end
+
+      # Resolve `# Template Dependency: SomeComponent` declarations.
+      #
+      # Rails' escape hatch takes a template path, but the path a component is
+      # digested under is an internal detail. Naming the class instead keeps
+      # that detail out of application code, so `SomeComponent` is translated
+      # to the path the Digestor can resolve.
+      #
+      # @return [Array<Array(String, String)>] pairs of declared name and
+      #   synthetic virtual path
+      def explicit_component_dependencies(source)
+        return [] unless source.is_a?(String) && source.include?("Template Dependency:")
+
+        source.scan(EXPLICIT_DEPENDENCY).flatten.uniq.filter_map do |declared|
+          next unless /\A(?:::)?[A-Z]/.match?(declared)
+
+          component = constantize_component(declared)
+          [declared, virtual_path_for(component)] if component
+        end
+      end
+
+      # Compute the digest of a component using Rails' digest tree.
+      #
+      # @param component [Class] a component that includes `ExperimentallyCacheable`
+      # @param finder [ActionView::LookupContext]
+      # @param format [Symbol]
+      # @return [String]
+      def digest(component, finder: default_finder, format: :html)
+        virtual_path = virtual_path_for(component)
+        return "" unless virtual_path
+
+        ActionView::Digestor.digest(name: virtual_path, format: format, finder: finder)
+      end
+
+      # A lookup context for digesting components outside a request, where no
+      # view context (and therefore no finder) exists.
+      #
+      # @return [ActionView::LookupContext]
+      def default_finder
+        # Not memoized across reloads: view paths change when the app reloads.
+        ActionView::LookupContext.new(ActionController::Base.view_paths)
+      end
+
+      # 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.
+      #
+      # @private
+      def install!
+        DependencyTracking.install!
+
+        ActiveSupport.on_load(:action_controller_base) do
+          resolver = ViewComponent::CacheDigest::Resolver.instance
+
+          append_view_path(resolver) unless view_paths.include?(resolver)
+        end
+      end
+
+      private
+
+      # Resolve a constant name to a component that opted into caching.
+      #
+      # 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?
+
+        component
+      rescue
+        # Never let digest computation break rendering.
+        nil
+      end
+    end
+
+    # Resolved once at load time rather than memoized, so no class-level state
+    # is written after boot.
+    RENDER_PARSER = resolve_render_parser(ActionView::RenderParser)
+  end
+end

data/lib/view_component/errors.rb

@@ -232,4 +232,39 @@ module ViewComponent
       super(MESSAGE.gsub("SETTER_METHOD_NAME", setter_method_name.to_s).gsub("SETTER_NAME", setter_name.to_s))
     end
   end
+
+  class CacheDigestTemplateError < StandardError
+    MESSAGE =
+      "The synthetic cache digest template for COMPONENT was rendered.\n\n" \
+      "This template exists only so Rails can compute a cache digest for the " \
+      "component and is never meant to be rendered. Render the component " \
+      "itself instead.".freeze
+
+    def initialize(component_name)
+      super(MESSAGE.gsub("COMPONENT", component_name.to_s))
+    end
+  end
+
+  class UndefinedCacheKeyMethodError < StandardError
+    MESSAGE =
+      "`cache_on` declared `METHOD` on COMPONENT, but no such method is defined.\n\n" \
+      "To fix this issue, define `METHOD` or remove it from `cache_on`.".freeze
+
+    def initialize(component_name, method_name)
+      super(MESSAGE.gsub("COMPONENT", component_name.to_s).gsub("METHOD", method_name.to_s))
+    end
+  end
+
+  class ContentPassedToCachedComponentError < StandardError
+    MESSAGE =
+      "COMPONENT declares `cache_on`, so it caches its own output, but its caller passed it content.\n\n" \
+      "Content and slots set by the caller aren't part of the cache key, so caching them would risk " \
+      "serving one caller's content to another.\n\n" \
+      "To fix this issue, either remove `cache_on` from COMPONENT, or move the content into the " \
+      "component and derive it from the values declared in `cache_on`.".freeze
+
+    def initialize(component_name)
+      super(MESSAGE.gsub("COMPONENT", component_name.to_s))
+    end
+  end
 end

data/lib/view_component/experimentally_cacheable.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "view_component/cache_digest"
+
+module ViewComponent
+  # Experimental 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 wrapping the component in a view is invalidated when
+  #    the component's template, Ruby class, sidecar files, or child components
+  #    change.
+  # 2. Enables the `cache_on` macro, which caches the component's own rendered
+  #    output.
+  #
+  # ```ruby
+  # class MessageComponent < ViewComponent::Base
+  #   include ViewComponent::ExperimentallyCacheable
+  #
+  #   cache_on :message
+  #
+  #   def initialize(message:)
+  #     @message = message
+  #   end
+  # end
+  # ```
+  module ExperimentallyCacheable
+    extend ActiveSupport::Concern
+
+    # Stands in for `nil` in the cache key. Without it, `expand_cache_key`
+    # renders `nil` and `""` identically, so two components differing only in
+    # 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.
+      #
+      # Each argument names a method on the component whose value is mixed into
+      # the cache key, alongside a digest of the component's source. Private
+      # methods are allowed.
+      #
+      # ```ruby
+      # cache_on :message, :current_user
+      # ```
+      #
+      # Calling `cache_on` opts the component into caching its own output.
+      # Without it, including this module only registers the component with
+      # Rails' digest tree.
+      #
+      # Pass `if:` or `unless:` to cache only some renders. Both accept a method
+      # name or a proc evaluated on the component:
+      #
+      # ```ruby
+      # cache_on :message, if: :persisted?
+      # cache_on :message, unless: -> { message.draft? }
+      # ```
+      #
+      # These methods are called before the component renders, so they can only
+      # depend on the component's own state, not on `helpers` or the view
+      # context.
+      #
+      # @param methods [Array<Symbol>] Methods whose values form the cache key.
+      # @param options [Hash] `:if` and/or `:unless` conditions.
+      # @return [void]
+      def cache_on(*methods, **options, &block)
+        if block
+          raise ArgumentError,
+            "`cache_on` doesn't accept a block. Name the methods whose values form the cache key, " \
+            "such as `cache_on :message`."
+        end
+
+        methods.each do |method|
+          next if method.is_a?(Symbol) || method.is_a?(String)
+
+          raise ArgumentError,
+            "`cache_on` expects method names as symbols, got #{method.class}. " \
+            "Define a method for the value and name it, such as `cache_on :message`."
+        end
+
+        unknown = options.keys - %i[if unless]
+        if unknown.any?
+          raise ArgumentError,
+            "`cache_on` received unknown #{"option".pluralize(unknown.count)} " \
+            "#{unknown.map(&:inspect).to_sentence}. Supported options are `:if` and `:unless`."
+        end
+
+        @__vc_cache_on = __vc_cache_on | methods.map(&:to_sym)
+        @__vc_cache_if = options[:if] if options.key?(:if)
+        @__vc_cache_unless = options[:unless] if options.key?(:unless)
+      end
+
+      # @private
+      def __vc_cache_on
+        @__vc_cache_on ||= superclass.respond_to?(:__vc_cache_on) ? superclass.__vc_cache_on : []
+      end
+
+      # @private
+      def __vc_cache_if
+        return @__vc_cache_if if defined?(@__vc_cache_if)
+
+        superclass.__vc_cache_if if superclass.respond_to?(:__vc_cache_if)
+      end
+
+      # @private
+      def __vc_cache_unless
+        return @__vc_cache_unless if defined?(@__vc_cache_unless)
+
+        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]
+      def __vc_caches_output?
+        __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.
+      #
+      # 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 # rubocop:disable Rails/OutputSafety
+      end
+
+      super.tap do |output|
+        store.write(key, output.to_s)
+      end
+    end
+
+    # The cache key for this rendering of the component.
+    #
+    # Combines the component's identity, its source digest, the requested
+    # format and variant, the current locale, and the values declared with
+    # `cache_on`. Override for full control.
+    #
+    # @param view_context [ActionView::Base]
+    # @return [String]
+    def cache_key(view_context = nil)
+      lookup_context = view_context&.lookup_context
+      format = __vc_cache_format(lookup_context)
+
+      parts = [
+        "view_component",
+        self.class.virtual_path,
+        self.class.cache_digest(finder: lookup_context, format: format),
+        # Included in its own right, not just as a digest input: components that
+        # render every format from one template have the same digest for each.
+        format,
+        __vc_cache_variant(lookup_context),
+        I18n.locale,
+        *__vc_cache_on_values
+      ]
+
+      # Positions are significant, so nils are substituted rather than removed.
+      # Compacting the array would let a nil in one position collapse into a nil
+      # in another.
+      ActiveSupport::Cache.expand_cache_key(
+        parts.map { |part| part.nil? ? NIL_CACHE_VALUE : part }
+      )
+    end
+
+    private
+
+    # Slots set by the caller via `with_*`. Checked before rendering, so slots
+    # a component fills in for itself with a `default_*` method — which resolve
+    # lazily during the render — aren't counted.
+    def __vc_slots_set_by_caller?
+      defined?(@__vc_set_slots) && @__vc_set_slots.present?
+    end
+
+    def __vc_cache_enabled?(view_context)
+      return false unless defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+      return false unless __vc_cache_conditions_met?
+
+      controller = view_context.try(:controller)
+      controller.respond_to?(:perform_caching) && controller.perform_caching
+    end
+
+    def __vc_cache_conditions_met?
+      if (condition = self.class.__vc_cache_if)
+        return false unless __vc_evaluate_cache_condition(condition)
+      end
+
+      if (condition = self.class.__vc_cache_unless)
+        return false if __vc_evaluate_cache_condition(condition)
+      end
+
+      true
+    end
+
+    def __vc_evaluate_cache_condition(condition)
+      return instance_exec(&condition) if condition.respond_to?(:to_proc) && !condition.is_a?(Symbol)
+
+      unless respond_to?(condition, true)
+        raise UndefinedCacheKeyMethodError.new(self.class.name, condition)
+      end
+
+      send(condition)
+    end
+
+    def __vc_cache_on_values
+      self.class.__vc_cache_on.map do |method_name|
+        unless respond_to?(method_name, true)
+          raise UndefinedCacheKeyMethodError.new(self.class.name, method_name)
+        end
+
+        send(method_name)
+      end
+    end
+
+    def __vc_cache_format(lookup_context)
+      Array(lookup_context&.formats).first || :html
+    end
+
+    def __vc_cache_variant(lookup_context)
+      Array(lookup_context&.variants).first
+    end
+  end
+end

data/lib/view_component/version.rb

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

data/lib/view_component.rb

@@ -8,10 +8,12 @@ module ViewComponent
   extend ActiveSupport::Autoload
 
   autoload :Base
+  autoload :CacheDigest
   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.14.0
+  version: 4.15.0
 platform: ruby
 authors:
 - ViewComponent Team
@@ -91,6 +91,9 @@ files:
 - lib/view_component.rb
 - lib/view_component/active_job_serializer.rb
 - lib/view_component/base.rb
+- lib/view_component/cache_digest.rb
+- lib/view_component/cache_digest/dependency_tracking.rb
+- lib/view_component/cache_digest/resolver.rb
 - lib/view_component/collection.rb
 - lib/view_component/compile_cache.rb
 - lib/view_component/compiler.rb
@@ -99,6 +102,7 @@ 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