MONGOID-5684 Ensure hash-typed fields return Hash

lib/mongoid/attributes.rb

@@ -101,6 +101,11 @@ def read_attribute(name)
     # @api private
     def process_raw_attribute(name, raw, field)
       value = field ? field.demongoize(raw) : raw
+      # When demongoize converts a BSON::Document to a plain Hash (i.e.
+      # legacy_hash_fields is false), store the plain Hash back into
+      # attributes so that in-place mutations on the returned value are
+      # visible to dirty tracking.
+      attributes[name] = value if raw.is_a?(BSON::Document) && !value.is_a?(BSON::Document)
       is_relation = relations.key?(name)
       attribute_will_change!(name) if value.resizable? && !is_relation
       value

lib/mongoid/config.rb

@@ -78,6 +78,11 @@ module Config
     # Store BigDecimals as Decimal128s instead of strings in the db.
     option :map_big_decimal_to_decimal128, default: true
 
+    # When true (the default), preserve legacy behavior where Hash-typed fields
+    # return BSON::Document after loading from the database. Set to false to
+    # have Hash-typed fields return plain Hash, matching the declared field type.
+    option :legacy_hash_fields, default: true
+
     # Allow BSON::Decimal128 to be parsed and returned directly in
     # field values. When BSON 5 is present and this option is set to false
     # (the default), BSON::Decimal128 values in the database will be returned

lib/mongoid/extensions/hash.rb

@@ -105,6 +105,23 @@ def to_criteria
       Mongoid.deprecate(self, :to_criteria)
 
       module ClassMethods
+        # Turn the object from a Mongo-friendly type back to the Ruby type.
+        # When +legacy_hash_fields+ is false, converts BSON::Document to a
+        # plain Hash recursively so that Hash-typed fields always return Hash.
+        # Plain Hash inputs are returned as-is; conversion is only needed once
+        # (when the raw BSON::Document is first read from the database).
+        #
+        # @param [ Object ] object The object to demongoize.
+        #
+        # @return [ Hash | Object | nil ] The demongoized object.
+        def demongoize(object)
+          return if object.nil?
+          return object unless object.is_a?(BSON::Document) &&
+                               !Mongoid.config.legacy_hash_fields
+
+          object.each_with_object({}) { |(k, v), h| h[k] = ::Hash.demongoize(v) }
+        end
+
         # Turn the object from the ruby type we deal with to a Mongo friendly
         # type.
         #

perf/benchmark_hash_demongoize.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Benchmarks Hash.demongoize performance for the three scenarios relevant to
+# MONGOID-5684:
+#
+#   legacy     - legacy_hash_fields: true (BSON::Document returned as-is, O(1))
+#   first read - legacy_hash_fields: false, BSON::Document input (conversion, O(N))
+#   subsequent - legacy_hash_fields: false, plain Hash input (returns self, O(1))
+#
+# Each scenario uses a separate Benchmark.ips block with the config flag set
+# before measurement begins, so the flag is stable during the entire run.
+#
+# Run with:
+#   bundle exec ruby perf/benchmark_hash_demongoize.rb
+
+require 'benchmark/ips'
+require 'mongoid'
+
+# ---------------------------------------------------------------------------
+# Test documents
+# ---------------------------------------------------------------------------
+
+EMPTY = BSON::Document.new.freeze
+
+FLAT = BSON::Document.new(
+  'name' => 'Alice',
+  'age' => 30,
+  'active' => true,
+  'score' => 9.5,
+  'tag' => 'vip'
+).freeze
+
+# Three levels deep, 10 keys at each level. Leaf values are integers.
+NESTED = BSON::Document.new(
+  10.times.to_h do |i|
+    [
+      "l1_#{i}",
+      BSON::Document.new(
+        10.times.to_h do |j|
+          [
+            "l2_#{j}",
+            BSON::Document.new(
+              10.times.to_h { |k| [ "l3_#{k}", k ] }
+            )
+          ]
+        end
+      )
+    ]
+  end
+).freeze
+
+# Pre-converted plain Hash equivalents for the "subsequent read" scenario.
+Mongoid.config.legacy_hash_fields = false
+EMPTY_PLAIN  = Hash.demongoize(EMPTY)
+FLAT_PLAIN   = Hash.demongoize(FLAT)
+NESTED_PLAIN = Hash.demongoize(NESTED)
+Mongoid.config.legacy_hash_fields = true
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+CASES = [
+  [ 'empty (0 keys)',              EMPTY,  EMPTY_PLAIN ],
+  [ 'flat (5 keys)',               FLAT,   FLAT_PLAIN ],
+  [ 'nested (3 levels, 10 keys)',  NESTED, NESTED_PLAIN ]
+].freeze
+
+def section(title)
+  puts "\n#{'=' * 60}"
+  puts title
+  puts '=' * 60
+end
+
+# ---------------------------------------------------------------------------
+# Scenario 1: legacy behavior (flag = true)
+# Config is set once before the block; all three cases share the same flag.
+# ---------------------------------------------------------------------------
+
+section 'Scenario 1: legacy_hash_fields: true (BSON::Document returned as-is)'
+
+Mongoid.config.legacy_hash_fields = true
+Benchmark.ips do |x|
+  x.config(warmup: 2, time: 5)
+  CASES.each do |label, bson, _|
+    x.report(label) { Hash.demongoize(bson) }
+  end
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# Scenario 2: first read (flag = false, BSON::Document input)
+# This is the O(N) path: allocates and populates a new plain Hash.
+# ---------------------------------------------------------------------------
+
+section 'Scenario 2: legacy_hash_fields: false, BSON::Document input (first read)'
+
+Mongoid.config.legacy_hash_fields = false
+Benchmark.ips do |x|
+  x.config(warmup: 2, time: 5)
+  CASES.each do |label, bson, _|
+    x.report(label) { Hash.demongoize(bson) }
+  end
+  x.compare!
+end
+
+# ---------------------------------------------------------------------------
+# Scenario 3: subsequent reads (flag = false, plain Hash input)
+# After the write-back in process_raw_attribute, attributes holds a plain Hash.
+# This should be O(1): two type checks, one return.
+# ---------------------------------------------------------------------------
+
+section 'Scenario 3: legacy_hash_fields: false, plain Hash input (subsequent reads)'
+
+Mongoid.config.legacy_hash_fields = false
+Benchmark.ips do |x|
+  x.config(warmup: 2, time: 5)
+  CASES.each do |label, _, plain|
+    x.report(label) { Hash.demongoize(plain) }
+  end
+  x.compare!
+end
+
+Mongoid.config.legacy_hash_fields = true

spec/mongoid/changeable_spec.rb

@@ -251,6 +251,63 @@
           end
         end
       end
+
+      context 'when the attribute is a hash field and legacy_hash_fields is true (default)' do
+        let(:person) do
+          Person.create!(map: { 'location' => 'Home' })
+        end
+
+        let(:reloaded) do
+          Person.find(person.id)
+        end
+
+        it 'returns a BSON::Document after loading from the database' do
+          expect(reloaded.map).to be_a(BSON::Document)
+        end
+      end
+
+      context 'when the attribute is a hash field and legacy_hash_fields is false' do
+        around do |example|
+          Mongoid.config.legacy_hash_fields = false
+          example.run
+        ensure
+          Mongoid.config.legacy_hash_fields = true
+        end
+
+        let(:person) do
+          Person.create!(map: { 'location' => 'Home' })
+        end
+
+        let(:reloaded) do
+          Person.find(person.id)
+        end
+
+        it 'returns a plain Hash after loading from the database' do
+          expect(reloaded.map).to be_a(Hash)
+          expect(reloaded.map).not_to be_a(BSON::Document)
+        end
+
+        it 'returns the correct value' do
+          expect(reloaded.map).to eq({ 'location' => 'Home' })
+        end
+
+        context 'when the field is modified after loading' do
+          before do
+            reloaded.map['location'] = 'Work'
+          end
+
+          it 'field_was returns a plain Hash' do
+            old_value, = reloaded.map_change
+            expect(old_value).to be_a(Hash)
+            expect(old_value).not_to be_a(BSON::Document)
+          end
+
+          it 'field_was holds the original value' do
+            old_value, = reloaded.map_change
+            expect(old_value).to eq({ 'location' => 'Home' })
+          end
+        end
+      end
     end
 
     context 'when the attribute has not changed from the persisted value' do

spec/mongoid/extensions/hash_spec.rb

@@ -179,6 +179,56 @@
         expect(demongoized).to eq(1)
       end
     end
+
+    context 'when the object is a BSON::Document and legacy_hash_fields is true' do
+      let(:doc) { BSON::Document.new('x' => 1, 'y' => 2) }
+
+      it 'returns the BSON::Document unchanged (legacy behavior)' do
+        expect(Hash.demongoize(doc)).to be_a(BSON::Document)
+        expect(Hash.demongoize(doc)).to equal(doc)
+      end
+    end
+
+    context 'when the object is a BSON::Document and legacy_hash_fields is false' do
+      around do |example|
+        Mongoid.config.legacy_hash_fields = false
+        example.run
+      ensure
+        Mongoid.config.legacy_hash_fields = true
+      end
+
+      let(:doc) { BSON::Document.new('x' => 1, 'y' => 2) }
+
+      it 'returns a plain Hash' do
+        result = Hash.demongoize(doc)
+        expect(result).to be_a(Hash)
+        expect(result).not_to be_a(BSON::Document)
+      end
+
+      it 'preserves the key/value data' do
+        result = Hash.demongoize(doc)
+        expect(result).to eq({ 'x' => 1, 'y' => 2 })
+      end
+
+      context 'when the object is a plain Hash' do
+        let(:plain) { { 'x' => 1, 'y' => 'hello' } }
+
+        it 'returns the same object unchanged' do
+          expect(Hash.demongoize(plain)).to equal(plain)
+        end
+      end
+
+      context 'when the BSON::Document has nested BSON::Documents' do
+        let(:nested) { BSON::Document.new('a' => BSON::Document.new('b' => 3)) }
+
+        it 'recursively converts nested BSON::Documents to plain Hash' do
+          result = Hash.demongoize(nested)
+          expect(result['a']).to be_a(Hash)
+          expect(result['a']).not_to be_a(BSON::Document)
+          expect(result['a']['b']).to eq(3)
+        end
+      end
+    end
   end
 
   describe '.mongoize' do