Support InertiaRails.once prop

Author: skryukov

lib/inertia_rails/base_prop.rb

@@ -3,7 +3,7 @@
 module InertiaRails
   # Base class for all props.
   class BaseProp
-    def initialize(&block)
+    def initialize(**, &block)
       @block = block
     end
 

lib/inertia_rails/defer_prop.rb

@@ -2,6 +2,7 @@
 
 module InertiaRails
   class DeferProp < IgnoreOnFirstLoadProp
+    prepend PropOnceable
     prepend PropMergeable
 
     DEFAULT_GROUP = 'default'

lib/inertia_rails/inertia_rails.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'inertia_rails/prop_onceable'
 require 'inertia_rails/prop_mergeable'
 require 'inertia_rails/base_prop'
 require 'inertia_rails/ignore_on_first_load_prop'
@@ -8,6 +9,7 @@
 require 'inertia_rails/optional_prop'
 require 'inertia_rails/defer_prop'
 require 'inertia_rails/merge_prop'
+require 'inertia_rails/once_prop'
 require 'inertia_rails/scroll_prop'
 require 'inertia_rails/configuration'
 require 'inertia_rails/meta_tag'
@@ -36,6 +38,10 @@ def always(&block)
       AlwaysProp.new(&block)
     end
 
+    def once(...)
+      OnceProp.new(...)
+    end
+
     def merge(...)
       MergeProp.new(...)
     end
@@ -44,8 +50,8 @@ def deep_merge(match_on: nil, &block)
       MergeProp.new(deep_merge: true, match_on: match_on, &block)
     end
 
-    def defer(group: nil, merge: nil, deep_merge: nil, match_on: nil, &block)
-      DeferProp.new(group: group, merge: merge, deep_merge: deep_merge, match_on: match_on, &block)
+    def defer(...)
+      DeferProp.new(...)
     end
 
     def scroll(metadata = nil, **options, &block)

lib/inertia_rails/merge_prop.rb

@@ -2,6 +2,7 @@
 
 module InertiaRails
   class MergeProp < BaseProp
+    prepend PropOnceable
     prepend PropMergeable
 
     def initialize(**_props, &block)

lib/inertia_rails/once_prop.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  class OnceProp < BaseProp
+    prepend PropOnceable
+
+    def initialize(**, &block)
+      @once = true
+      super(&block)
+    end
+  end
+end

lib/inertia_rails/optional_prop.rb

@@ -2,5 +2,6 @@
 
 module InertiaRails
   class OptionalProp < IgnoreOnFirstLoadProp
+    prepend PropOnceable
   end
 end

lib/inertia_rails/prop_onceable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module PropOnceable
+    attr_reader :once_key, :once_expires_in
+
+    def initialize(**props, &block)
+      @once = props.fetch(:once, false)
+      @once_key = props[:key]
+      @once_expires_in = props[:expires_in]
+      @fresh = props.fetch(:fresh, false)
+
+      super
+    end
+
+    def once?
+      @once
+    end
+
+    def fresh?
+      @fresh
+    end
+
+    def expires_at
+      return nil unless @once_expires_in
+
+      timestamp = case @once_expires_in
+                  when ActiveSupport::Duration
+                    (Time.current + @once_expires_in).to_f
+                  when Numeric
+                    Time.current.to_f + @once_expires_in
+                  else
+                    raise ArgumentError, "Invalid `expires_in` value: #{@once_expires_in.inspect}"
+                  end
+
+      (timestamp * 1000).to_i
+    end
+  end
+end

lib/inertia_rails/renderer.rb

@@ -48,7 +48,7 @@ def render
                                   else
                                     "#{@response.headers['Vary']}, X-Inertia"
                                   end
-      if @request.headers['X-Inertia']
+      if @request.inertia?
         @response.set_header('X-Inertia', 'true')
         @render_method.call json: page.to_json, status: @response.status, content_type: Mime[:json]
       else
@@ -97,15 +97,17 @@ def merge_props(shared_props, props, deep_merge)
     def computed_props
       # rubocop:disable Style/MultilineBlockChain
       @props
-        .tap do |merged_props| # Always keep errors in the props
-          if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
-            errors = merged_props[:errors]
-            merged_props[:errors] = InertiaRails.always { errors }
-          end
+        .tap do |merged_props|
+        # Always keep errors in the props
+        if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
+          errors = merged_props[:errors]
+          merged_props[:errors] = InertiaRails.always { errors }
         end
+      end
         .then { |props| deep_transform_props(props) } # Internal hydration/filtering
         .then { |props| @configuration.prop_transformer(props: props) } # Apply user-defined prop transformer
-        .tap do |props| # Add meta tags last (never transformed)
+        .tap do |props|
+        # Add meta tags last (never transformed)
         props[:_inertia_meta] = meta_tags if meta_tags.present?
       end
       # rubocop:enable Style/MultilineBlockChain
@@ -128,6 +130,9 @@ def page
       @page[:scrollProps] = scroll_props if scroll_props.present?
       @page.merge!(resolve_merge_props)
 
+      once_props = resolve_once_props
+      @page[:onceProps] = once_props if once_props.present?
+
       @page
     end
 
@@ -173,6 +178,17 @@ def resolve_merge_props
       }.delete_if { |_, v| v.blank? }
     end
 
+    def resolve_once_props
+      @props.each_with_object({}) do |(key, prop), result|
+        next unless prop.try(:once?)
+        next if excluded_by_partial_request?([key.to_s])
+
+        once_key = (prop.once_key || key).to_s
+
+        result[once_key] = { prop: key.to_s, expiresAt: prop.expires_at }.compact
+      end
+    end
+
     def resolve_match_on_props
       all_merge_props.filter_map do |key, prop|
         prop.match_on.map! { |ms| "#{key}.#{ms}" } if prop.match_on.present?
@@ -251,6 +267,10 @@ def partial_except_keys
       @partial_except_keys ||= (@request.headers['X-Inertia-Partial-Except'] || '').split(',').compact_blank!
     end
 
+    def except_once_keys
+      @except_once_keys ||= (@request.headers['X-Inertia-Except-Once-Props'] || '').split(',').compact_blank!
+    end
+
     def rendering_partial_component?
       @request.headers['X-Inertia-Partial-Component'] == @component
     end
@@ -265,19 +285,38 @@ def resolve_component(component)
 
     def keep_prop?(prop, path)
       return true if prop.is_a?(AlwaysProp)
-
-      if rendering_partial_component? && (partial_keys.present? || partial_except_keys.present?)
-        path_with_prefixes = path_prefixes(path)
-        return false if excluded_by_only_partial_keys?(path_with_prefixes)
-        return false if excluded_by_except_partial_keys?(path_with_prefixes)
-      end
+      return false if excluded_by_once_cache?(prop, path)
+      return false if excluded_by_partial_request?(path)
 
       # Precedence: Evaluate IgnoreOnFirstLoadProp only after partial keys have been checked
       return false if prop.is_a?(IgnoreOnFirstLoadProp) && !rendering_partial_component?
 
       true
     end
 
+    def excluded_by_once_cache?(prop, path)
+      return false unless prop.try(:once?)
+      return false if prop.try(:fresh?)
+      return false if explicitly_requested?(path)
+
+      once_key = (prop.once_key || path.join('.')).to_s
+      except_once_keys.include?(once_key)
+    end
+
+    def explicitly_requested?(path)
+      return false unless rendering_partial_component? && partial_keys.present?
+
+      path_with_prefixes = path_prefixes(path)
+      (path_with_prefixes & partial_keys).any?
+    end
+
+    def excluded_by_partial_request?(path)
+      return false unless rendering_partial_component? && (partial_keys.present? || partial_except_keys.present?)
+
+      path_with_prefixes = path_prefixes(path)
+      excluded_by_only_partial_keys?(path_with_prefixes) || excluded_by_except_partial_keys?(path_with_prefixes)
+    end
+
     def path_prefixes(parts)
       (0...parts.length).map do |i|
         parts[0..i].join('.')

spec/dummy/app/controllers/inertia_render_test_controller.rb

@@ -189,4 +189,80 @@ def reset_test
       regular_prop: 'regular value',
     }
   end
+
+  def once_props
+    render inertia: 'TestComponent', props: {
+      cached_data: InertiaRails.once { 'expensive data' },
+      regular: 'regular prop',
+    }
+  end
+
+  def once_props_with_expires_in
+    render inertia: 'TestComponent', props: {
+      cached_data: InertiaRails.once(expires_in: 1.hour) { 'expensive data with expiration' },
+    }
+  end
+
+  def once_props_with_custom_key
+    render inertia: 'TestComponent', props: {
+      cached_data: InertiaRails.once(key: 'my_custom_key') { 'expensive data with custom key' },
+    }
+  end
+
+  def deferred_once_props
+    render inertia: 'TestComponent', props: {
+      name: 'Brian',
+      deferred_cached: InertiaRails.defer(once: true) { 'deferred and cached' },
+    }
+  end
+
+  inertia_share only: [:shared_once_props] do
+    {
+      shared_cached: InertiaRails.once { 'shared once data' },
+    }
+  end
+
+  def shared_once_props
+    render inertia: 'TestComponent', props: {
+      name: 'Brian',
+    }
+  end
+
+  def nested_once_props
+    render inertia: 'TestComponent', props: {
+      nested: {
+        cached: InertiaRails.once { 'nested cached data' },
+      },
+      regular: 'regular prop',
+    }
+  end
+
+  def multiple_once_props
+    render inertia: 'TestComponent', props: {
+      cached_one: InertiaRails.once { 'first cached' },
+      cached_two: InertiaRails.once { 'second cached' },
+      regular: 'regular prop',
+    }
+  end
+
+  def once_props_not_fresh
+    render inertia: 'TestComponent', props: {
+      cached_data: InertiaRails::OnceProp.new { 'cached data' },
+      regular: 'regular prop',
+    }
+  end
+
+  def once_props_fresh
+    render inertia: 'TestComponent', props: {
+      cached_data: InertiaRails::OnceProp.new(fresh: true) { 'fresh data' },
+      regular: 'regular prop',
+    }
+  end
+
+  def once_props_fresh_and_non_fresh
+    render inertia: 'TestComponent', props: {
+      foo: InertiaRails::OnceProp.new(fresh: true) { 'bar' },
+      baz: InertiaRails::OnceProp.new { 'qux' },
+    }
+  end
 end

spec/dummy/config/routes.rb

@@ -44,6 +44,16 @@
   get 'prepend_merge_test' => 'inertia_render_test#prepend_merge_test'
   get 'nested_paths_test' => 'inertia_render_test#nested_paths_test'
   get 'reset_test' => 'inertia_render_test#reset_test'
+  get 'once_props' => 'inertia_render_test#once_props'
+  get 'once_props_with_expires_in' => 'inertia_render_test#once_props_with_expires_in'
+  get 'once_props_with_custom_key' => 'inertia_render_test#once_props_with_custom_key'
+  get 'deferred_once_props' => 'inertia_render_test#deferred_once_props'
+  get 'shared_once_props' => 'inertia_render_test#shared_once_props'
+  get 'nested_once_props' => 'inertia_render_test#nested_once_props'
+  get 'multiple_once_props' => 'inertia_render_test#multiple_once_props'
+  get 'once_props_not_fresh' => 'inertia_render_test#once_props_not_fresh'
+  get 'once_props_fresh' => 'inertia_render_test#once_props_fresh'
+  get 'once_props_fresh_and_non_fresh' => 'inertia_render_test#once_props_fresh_and_non_fresh'
   get 'non_inertiafied' => 'inertia_test#non_inertiafied'
   get 'deeply_nested_props' => 'inertia_render_test#deeply_nested_props'