Add first class component cache

Gemfile

@@ -41,7 +41,7 @@ group :development, :test do
   gem "simplecov", "< 1"
   gem "slim", "~> 5"
   gem "sprockets-rails", "~> 3"
-  gem "standard", "~> 1"
+  gem "standard", "~> 1.54.0"
   gem "tailwindcss-rails", "~> 4"
   gem "turbo-rails"
   gem "warning"

Gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -55,6 +56,8 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     activejob (8.1.3)
       activesupport (= 8.1.3)
       globalid (>= 0.3.6)
@@ -456,7 +459,7 @@ DEPENDENCIES
   simplecov-console (< 1)
   slim (~> 5)
   sprockets-rails (~> 3)
-  standard (~> 1)
+  standard (~> 1.54.0)
   tailwindcss-rails (~> 4)
   turbo-rails
   view_component!
@@ -473,6 +476,7 @@ CHECKSUMS
   actionpack (8.1.3) sha256=af998cae4d47c5d581a2cc363b5c77eb718b7c4b45748d81b1887b25621c29a3
   actiontext (8.1.3) sha256=d291019c00e1ea9e6463011fa214f6081a56d7b9a1d224e7d3f6384c1dafc7d2
   actionview (8.1.3) sha256=1347c88c7f3edb38100c5ce0e9fb5e62d7755f3edc1b61cce2eb0b2c6ea2fd5d
+  actionview_precompiler (0.4.0) sha256=33b6bd6ec4c1b856e02fdf5f6512c9eb4a92ac1c0545e941b3e354b7d540ed1c
   activejob (8.1.3) sha256=a149b1766aa8204c3c3da7309e4becd40fcd5529c348cffbf6c9b16b565fe8d3
   activemodel (8.1.3) sha256=90c05cbe4cef3649b8f79f13016191ea94c4525ce4a5c0fb7ef909c4b91c8219
   activerecord (8.1.3) sha256=8003be7b2466ba0a2a670e603eeb0a61dd66058fccecfc49901e775260ac70ab

docs/CHANGELOG.md

@@ -10,6 +10,10 @@ nav_order: 6
 
 ## main
 
+* Add experimental support for caching by including `ViewComponent::ExperimentallyCacheable`.
+
+    *Reegan Viljoen*
+
 ## 4.12.0
 
 * Fix stale render context on reused component instances. A `ViewComponent::Base` instance memoized its controller, helpers, request, view context, lookup context, view flow, and requested format details on first render via `||=`. Rendering the same instance a second time (intentionally or via aliasing) reused that stale context, which could leak data across requests, sessions, or users. `#render_in` now resets these ivars on every call so each render derives its context from the current view.

docs/guide/caching.md

@@ -0,0 +1,95 @@
+---
+layout: default
+title: Caching
+parent: How-to guide
+---
+
+# Caching
+
+Experimental
+{: .label }
+
+Caching is experimental. To cache a component, include `ViewComponent::ExperimentallyCacheable` and declare cache dependencies using `cache`:
+
+```ruby
+class CacheComponent < ViewComponent::Base
+  include ViewComponent::ExperimentallyCacheable
+
+  attr_reader :foo, :bar
+
+  cache do
+    [foo, bar]
+  end
+
+  def initialize(foo:, bar:)
+    @foo = foo
+    @bar = bar
+  end
+end
+```
+
+```erb
+<p><%= Time.zone.now %></p>
+<p><%= "#{foo} #{bar}" %></p>
+```
+
+Components that include `ViewComponent::ExperimentallyCacheable` but do not call `cache` render normally without fragment caching.
+
+Caching only reads and writes fragments when controller caching is enabled.
+
+## Dependencies
+
+The `cache` block is evaluated in the component instance context. Returned values are expanded via `ActiveSupport::Cache.expand_cache_key`, so Active Record models, `GlobalID`, arrays, plain strings, and values returned by private methods work as expected.
+
+```ruby
+class UserComponent < ViewComponent::Base
+  include ViewComponent::ExperimentallyCacheable
+
+  def initialize(user:)
+    @user = user
+  end
+
+  cache do
+    [@user]
+  end
+end
+```
+
+## Conditional caching
+
+Use `cache_if` to cache only when a condition is met:
+
+```ruby
+class UserComponent < ViewComponent::Base
+  include ViewComponent::ExperimentallyCacheable
+
+  cache_if :cacheable?
+
+  cache do
+    [@user]
+  end
+
+  def initialize(user:, cacheable: true)
+    @user = user
+    @cacheable = cacheable
+  end
+
+  private
+
+  def cacheable?
+    @cacheable
+  end
+end
+```
+
+`cache_if` accepts a symbol, a boolean value, or a block.
+
+## Cache invalidation
+
+The cache key includes a digest of the component, its sidecar files, and ViewComponents rendered by the component.
+
+Caches are invalidated when the component source, sidecar templates, sidecar translations, or rendered child ViewComponents change.
+
+## Limitations
+
+Changes to partial and layout string dependencies will not invalidate the cache. Modify `RAILS_CACHE_ID` or `RAILS_APP_VERSION` to invalidate these caches on deploy.

gemfiles/rails_7.1.gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -60,6 +61,8 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     activejob (7.1.6)
       activesupport (= 7.1.6)
       globalid (>= 0.3.6)

gemfiles/rails_7.2.gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -55,6 +56,8 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     activejob (7.2.3)
       activesupport (= 7.2.3)
       globalid (>= 0.3.6)

gemfiles/rails_8.0.gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -52,6 +53,8 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     activejob (8.0.4)
       activesupport (= 8.0.4)
       globalid (>= 0.3.6)

gemfiles/rails_8.1.gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -55,6 +56,8 @@ GEM
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     activejob (8.1.2)
       activesupport (= 8.1.2)
       globalid (>= 0.3.6)

gemfiles/rails_main.gemfile.lock

@@ -112,6 +112,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -120,6 +121,8 @@ GEM
   specs:
     action_text-trix (2.1.19)
       railties
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     allocation_stats (0.1.5)
@@ -486,6 +489,7 @@ CHECKSUMS
   actionpack (8.2.0.alpha)
   actiontext (8.2.0.alpha)
   actionview (8.2.0.alpha)
+  actionview_precompiler (0.4.0) sha256=33b6bd6ec4c1b856e02fdf5f6512c9eb4a92ac1c0545e941b3e354b7d540ed1c
   activejob (8.2.0.alpha)
   activemodel (8.2.0.alpha)
   activerecord (8.2.0.alpha)

gemfiles/rails_main_head.gemfile.lock

@@ -112,6 +112,7 @@ PATH
   specs:
     view_component (4.12.0)
       actionview (>= 7.1.0)
+      actionview_precompiler (>= 0.4)
       activesupport (>= 7.1.0)
       concurrent-ruby (~> 1)
 
@@ -120,6 +121,8 @@ GEM
   specs:
     action_text-trix (2.1.19)
       railties
+    actionview_precompiler (0.4.0)
+      actionview (>= 6.0.a)
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     allocation_stats (0.1.5)
@@ -456,6 +459,7 @@ CHECKSUMS
   actionpack (8.2.0.alpha)
   actiontext (8.2.0.alpha)
   actionview (8.2.0.alpha)
+  actionview_precompiler (0.4.0) sha256=33b6bd6ec4c1b856e02fdf5f6512c9eb4a92ac1c0545e941b3e354b7d540ed1c
   activejob (8.2.0.alpha)
   activemodel (8.2.0.alpha)
   activerecord (8.2.0.alpha)

lib/view_component.rb

@@ -12,6 +12,7 @@ module ViewComponent
   autoload :CompileCache
   autoload :Config
   autoload :Deprecation
+  autoload :ExperimentallyCacheable
   autoload :InlineTemplate
   autoload :Instrumentation
   autoload :Preview

lib/view_component/cache_digestor.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+require "view_component/template_dependency_extractor"
+
+module ViewComponent
+  class CacheDigestor
+    def self.digest(component)
+      new(component: component).digest
+    end
+
+    def initialize(component:)
+      @component_class = component.is_a?(Class) ? component : component.class
+      @digests = {}
+      @file_cache = {}
+      @constant_cache = {}
+    end
+
+    def digest
+      digest_for_component(@component_class)
+    end
+
+    private
+
+    # Prevents infinite recursion when components render each other cyclically.
+    IN_PROGRESS = :__vc_in_progress
+    private_constant :IN_PROGRESS
+
+    def digest_for_component(component_class)
+      return "" unless component_class <= ViewComponent::Base
+      name = component_class.name || component_class.object_id
+
+      cached_digest = @digests[name]
+      return "" if cached_digest == IN_PROGRESS
+      return cached_digest if cached_digest
+
+      @digests[name] = IN_PROGRESS
+
+      digest = Digest::SHA1.new
+
+      update_digest(digest, cached_file_contents(component_class.identifier))
+
+      inline_template = component_class.__vc_inline_template
+      if inline_template
+        inline_source = inline_template.source
+        update_digest(digest, inline_source)
+        update_template_dependency_digests(digest, inline_source, inline_template.language, component_class.identifier)
+      end
+
+      component_class.sidecar_files(ActionView::Template.template_handler_extensions).sort.each do |path|
+        template_source = cached_file_contents(path)
+        update_digest(digest, template_source)
+        update_template_dependency_digests(digest, template_source, File.extname(path).delete_prefix("."), path)
+      end
+
+      component_class.sidecar_files(%w[yml yaml]).sort.each do |path|
+        update_digest(digest, cached_file_contents(path))
+      end
+
+      @digests[name] = digest.hexdigest
+    end
+
+    def update_template_dependency_digests(digest, template_source, handler, identifier)
+      return unless template_source&.include?("render")
+
+      dependencies = ViewComponent::TemplateDependencyExtractor.new(template_source, handler, identifier: identifier).extract
+      update_dependency_digests(digest, dependencies)
+    end
+
+    def update_dependency_digests(digest, dependencies)
+      dependencies.each do |dep|
+        next unless uppercase_constant?(dep)
+
+        klass = cached_constantize(dep)
+        next unless klass
+
+        update_digest(digest, digest_for_component(klass))
+      end
+    end
+
+    def update_digest(digest, value)
+      return unless value
+
+      digest.update(value)
+      digest.update("\n")
+    end
+
+    def uppercase_constant?(dep)
+      return false unless dep
+
+      first = dep.getbyte(0)
+      first && first >= 65 && first <= 90
+    end
+
+    def cached_constantize(constant_name)
+      @constant_cache.fetch(constant_name) do
+        @constant_cache[constant_name] = constant_name.safe_constantize
+      end
+    end
+
+    def cached_file_contents(path)
+      return nil if path.nil?
+
+      @file_cache.fetch(path) do
+        @file_cache[path] = File.file?(path) ? File.read(path) : nil
+      end
+    end
+  end
+end