[+] add config option to disable the feature

Author: skcc321

lib/mongoid/attributes.rb

@@ -163,7 +163,7 @@ def remove_attribute(name)
     #
     # @api private
     def clear_demongoized_cache(name)
-      @__demongoized_cache.delete(name)
+      @__demongoized_cache.delete(name) if Mongoid::Config.cache_attribute_values?
     end
     private :clear_demongoized_cache
 
@@ -262,7 +262,7 @@ def write_attributes(attrs = nil)
     # it from the database with missing fields.
     #
     # Cache the projector keyed by __selected_fields to automatically handle
-    # invalidation when selected fields change.
+    # invalidation when selected fields change (only if caching is enabled).
     #
     # @example Is the attribute missing?
     #   document.attribute_missing?("test")
@@ -271,10 +271,14 @@ def write_attributes(attrs = nil)
     #
     # @return [ true | false ] If the attribute is missing.
     def attribute_missing?(name)
-      projector = @__projector_cache.compute_if_absent(__selected_fields) do
-        Projector.new(__selected_fields)
+      if Mongoid::Config.cache_attribute_values?
+        projector = @__projector_cache.compute_if_absent(__selected_fields) do
+          Projector.new(__selected_fields)
+        end
+        !projector.attribute_or_path_allowed?(name)
+      else
+        !Projector.new(__selected_fields).attribute_or_path_allowed?(name)
       end
-      !projector.attribute_or_path_allowed?(name)
     end
 
     # Return type-casted attributes.

lib/mongoid/config.rb

@@ -217,6 +217,23 @@ def validate_isolation_level!(level)
     # document might be ignored, or it might work, depending on the situation.
     option :immutable_ids, default: true
 
+    # When this flag is true, Mongoid will cache demongoized attribute values
+    # to improve read performance. The cache stores both the raw BSON value
+    # and the demongoized Ruby object, automatically invalidating when the
+    # underlying raw value changes.
+    #
+    # This optimization can significantly improve performance for fields with
+    # expensive demongoization (e.g., Time, Date, custom types), especially
+    # in read-heavy workloads.
+    #
+    # The cache is disabled by default to maintain backward compatibility.
+    # Enable it to gain performance improvements:
+    #
+    #   Mongoid.configure do |config|
+    #     config.cache_attribute_values = true
+    #   end
+    option :cache_attribute_values, default: false
+
     # When this flag is true, callbacks for every embedded document will be
     # called only once, even if the embedded document is embedded in multiple
     # documents in the root document's dependencies graph.

lib/mongoid/document.rb

@@ -253,6 +253,7 @@ def prepare_to_process_attributes
     #
     # @api private
     def initialize_field_caches
+      return unless Mongoid::Config.cache_attribute_values?
       @__projector_cache = Concurrent::Map.new
       @__demongoized_cache = Concurrent::Map.new
     end

lib/mongoid/fields.rb

@@ -693,7 +693,8 @@ def create_field_getter(name, meth, field)
             # Don't cache localized fields as they depend on I18n.locale
             elsif field.localized?
               process_raw_attribute(name.to_s, raw, field)
-            else
+            # Check if caching is enabled
+            elsif Mongoid::Config.cache_attribute_values?
               # Atomically fetch or compute the cached value
               # Cache stores [raw_value, demongoized_value] to detect stale cache
               value = @__demongoized_cache.compute_if_absent(name) do
@@ -719,6 +720,9 @@ def create_field_getter(name, meth, field)
               attribute_will_change!(name.to_s) if demongoized_value.resizable? && !is_relation
 
               demongoized_value
+            else
+              # Caching disabled - use original behavior
+              process_raw_attribute(name.to_s, raw, field)
             end
           end
         end

spec/mongoid/config_spec.rb

@@ -846,6 +846,84 @@
     end
   end
 
+  describe 'cache_attribute_values option' do
+    context 'when not set in the config' do
+      it 'defaults to false' do
+        Mongoid::Config.reset
+        configuration = CONFIG.merge(options: {})
+
+        Mongoid.configure { |config| config.load_configuration(configuration) }
+
+        expect(Mongoid::Config.cache_attribute_values).to be(false)
+      end
+    end
+
+    context 'when set to true in the config' do
+      it 'enables field value caching' do
+        Mongoid::Config.reset
+        configuration = CONFIG.merge(options: { cache_attribute_values: true })
+
+        Mongoid.configure { |config| config.load_configuration(configuration) }
+
+        expect(Mongoid::Config.cache_attribute_values).to be(true)
+      end
+    end
+
+    context 'when set to false in the config' do
+      it 'disables field value caching' do
+        Mongoid::Config.reset
+        configuration = CONFIG.merge(options: { cache_attribute_values: false })
+
+        Mongoid.configure { |config| config.load_configuration(configuration) }
+
+        expect(Mongoid::Config.cache_attribute_values).to be(false)
+      end
+    end
+
+    context 'functional behavior' do
+      let(:band_class) do
+        Class.new do
+          include Mongoid::Document
+          store_in collection: 'bands'
+          field :name, type: String
+          field :updated, type: Time
+        end
+      end
+
+      before do
+        stub_const('CacheBand', band_class)
+      end
+
+      it 'uses caching when enabled' do
+        Mongoid::Config.cache_attribute_values = true
+        
+        band = CacheBand.new(name: 'Test', updated: Time.current)
+        
+        # First access should populate cache
+        first_result = band.updated
+        
+        # Second access should return cached value (same object_id if caching works)
+        second_result = band.updated
+        
+        expect(first_result.object_id).to eq(second_result.object_id)
+      end
+
+      it 'does not use caching when disabled' do
+        Mongoid::Config.cache_attribute_values = false
+        
+        band = CacheBand.new(name: 'Test', updated: Time.current)
+        
+        # Each access should call process_raw_attribute
+        first_result = band.updated
+        second_result = band.updated
+        
+        # When caching is disabled, cache objects should not be initialized
+        expect(band.instance_variable_get(:@__demongoized_cache)).to be_nil
+        expect(band.instance_variable_get(:@__projector_cache)).to be_nil
+      end
+    end
+  end
+
   describe 'deprecations' do
     {}.each do |option, default|
 

spec/mongoid/fields/performance_spec.rb

@@ -16,6 +16,15 @@
 # Core field types (String, Integer, Float, etc.) must have exactly 0 allocations
 # to verify the caching optimization is working correctly.
 describe 'Mongoid::Fields performance optimizations' do
+  # Enable caching for all performance tests
+  around do |example|
+    original_value = Mongoid::Config.cache_attribute_values
+    Mongoid::Config.cache_attribute_values = true
+    example.run
+  ensure
+    Mongoid::Config.cache_attribute_values = original_value
+  end
+
   let(:band) do
     Band.new(
       name: 'Test Band',