From 664e923a086f84b709e9903f601da6d3e8d2e46e Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 13:49:38 +0000
Subject: [PATCH 01/10] add polymorphic

---
 lib/couchbase-orm/utilities/embeds_one.rb | 103 +++++++++++++++-------
 spec/embeds_one_spec.rb                   |  96 ++++++++++++++++++++
 2 files changed, 168 insertions(+), 31 deletions(-)

diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index e42aca64..79c5fee5 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -2,7 +2,7 @@
 
 module CouchbaseOrm
   module EmbedsOne
-    def embeds_one(name, class_name: nil, store_as: nil, validate: true)
+    def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic: false)
       storage_key = (store_as || name).to_sym
       attribute storage_key, :hash, default: nil
 
@@ -15,49 +15,90 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true)
         key: storage_key,
         name: name,
         instance_var: instance_var,
+        polymorphic: polymorphic,
       })
 
       validates_embedded(name) if validate
 
-      # Helper to lazy-resolve class when needed
-      define_method("_resolve_embedded_class_for_#{name}") do
-        @__resolved_classes ||= {}
-        @__resolved_classes[name] ||= begin
-          klass_name.constantize
-        rescue NameError => e
-          warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
-          raise
+      if polymorphic
+        # Add type attribute for polymorphic associations
+        type_key = :"#{name}_type"
+        attribute type_key, :string, default: nil
+
+        # Polymorphic reader
+        define_method(name) do
+          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+          raw = read_attribute(storage_key)
+          type = read_attribute(type_key)
+          return instance_variable_set(instance_var, nil) unless raw.present? && type.present?
+
+          klass = type.constantize
+          obj = klass.new(raw)
+          obj.embedded = true
+          instance_variable_set(instance_var, obj)
         end
-      end
 
-      define_method(name) do
-        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+        # Polymorphic writer
+        define_method("#{name}=") do |val|
+          if val.nil?
+            write_attribute(storage_key, nil)
+            write_attribute(type_key, nil)
+            instance_variable_set(instance_var, nil)
+            next
+          end
 
-        raw = read_attribute(storage_key)
-        return instance_variable_set(instance_var, nil) unless raw.present?
+          obj = val.is_a?(Hash) ? raise(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one") : val
+          obj.embedded = true
 
-        klass = send("_resolve_embedded_class_for_#{name}")
-        obj = klass.new(raw)
-        obj.embedded = true
-        instance_variable_set(instance_var, obj)
-      end
+          raw = obj.serialized_attributes
+          raw.delete('id') if raw['id'].blank?
+
+          write_attribute(storage_key, raw)
+          write_attribute(type_key, obj.class.name)
+          instance_variable_set(instance_var, obj)
+        end
+      else
+        # Helper to lazy-resolve class when needed
+        define_method("_resolve_embedded_class_for_#{name}") do
+          @__resolved_classes ||= {}
+          @__resolved_classes[name] ||= begin
+            klass_name.constantize
+          rescue NameError => e
+            warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
+            raise
+          end
+        end
+
+        define_method(name) do
+          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
 
-      define_method("#{name}=") do |val|
-        if val.nil?
-          write_attribute(storage_key, nil)
-          instance_variable_set(instance_var, nil)
-          next
+          raw = read_attribute(storage_key)
+          return instance_variable_set(instance_var, nil) unless raw.present?
+
+          klass = send("_resolve_embedded_class_for_#{name}")
+          obj = klass.new(raw)
+          obj.embedded = true
+          instance_variable_set(instance_var, obj)
         end
 
-        klass = send("_resolve_embedded_class_for_#{name}")
-        obj = val.is_a?(klass) ? val : klass.new(val)
-        obj.embedded = true
+        define_method("#{name}=") do |val|
+          if val.nil?
+            write_attribute(storage_key, nil)
+            instance_variable_set(instance_var, nil)
+            next
+          end
+
+          klass = send("_resolve_embedded_class_for_#{name}")
+          obj = val.is_a?(klass) ? val : klass.new(val)
+          obj.embedded = true
 
-        raw = obj.serialized_attributes
-        raw.delete('id') if raw['id'].blank?
+          raw = obj.serialized_attributes
+          raw.delete('id') if raw['id'].blank?
 
-        write_attribute(storage_key, raw)
-        instance_variable_set(instance_var, obj)
+          write_attribute(storage_key, raw)
+          instance_variable_set(instance_var, obj)
+        end
       end
 
       define_method(:"#{name}_reset") do
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index a72d08bb..65bd7365 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -66,6 +66,27 @@ class Article < CouchbaseOrm::Base
   embeds_one :comments_container, class_name: 'CommentsContainer'
 end
 
+class Attachment < CouchbaseOrm::Base
+  attribute :filename, :string
+  attribute :attachable_type, :string
+  attribute :attachable_id, :string
+  belongs_to :attachable, polymorphic: true
+end
+
+class Image < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :caption, :string
+end
+
+class Video < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :duration, :integer
+end
+
+class Post < CouchbaseOrm::Base
+  embeds_one :media, polymorphic: true
+end
+
 describe CouchbaseOrm::EmbedsOne do
   let(:raw_data) { { bio: 'Software Engineer' } }
 
@@ -377,4 +398,79 @@ class Article < CouchbaseOrm::Base
       article.destroy! if article&.persisted?
     end
   end
+
+  describe 'polymorphic embeds_one' do
+    it 'can embed different types polymorphically with type attribute' do
+      image = Image.new(url: 'https://example.com/image.jpg', caption: 'A beautiful sunset')
+      post = Post.new(media: image)
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/image.jpg')
+      expect(post.media.caption).to eq('A beautiful sunset')
+      expect(post.attributes['media_type']).to eq('Image')
+    end
+
+    it 'can embed a different polymorphic type' do
+      video = Video.new(url: 'https://example.com/video.mp4', duration: 120)
+      post = Post.new(media: video)
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/video.mp4')
+      expect(post.media.duration).to eq(120)
+      expect(post.attributes['media_type']).to eq('Video')
+    end
+
+    it 'persists and retrieves polymorphic embedded objects correctly' do
+      video = Video.new(url: 'https://example.com/demo.mp4', duration: 90)
+      post = Post.create!(media: video)
+
+      loaded = Post.find(post.id)
+      expect(loaded.media).to be_a(Video)
+      expect(loaded.media.url).to eq('https://example.com/demo.mp4')
+      expect(loaded.media.duration).to eq(90)
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'can switch between different polymorphic types' do
+      image = Image.new(url: 'https://example.com/pic.jpg', caption: 'Original')
+      post = Post.create!(media: image)
+
+      post.media = Video.new(url: 'https://example.com/clip.mp4', duration: 45)
+      post.save!
+
+      post.reload
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/clip.mp4')
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'sets embedded flag on polymorphic embedded objects' do
+      image = Image.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      post = Post.new(media: image)
+
+      expect(post.media.instance_variable_get(:@_embedded)).to be true
+    end
+
+    it 'can set polymorphic embedded to nil' do
+      video = Video.new(url: 'https://example.com/test.mp4', duration: 60)
+      post = Post.new(media: video)
+
+      post.media = nil
+      expect(post.media).to be_nil
+      expect(post.attributes['media']).to be_nil
+      expect(post.attributes['media_type']).to be_nil
+    end
+
+    it 'validates polymorphic embedded objects' do
+      # Assuming Image has validations
+      image = Image.new(url: nil, caption: 'No URL')
+      post = Post.new(media: image)
+
+      # Since Image doesn't have validations in our test setup, this would pass
+      # But demonstrates the structure for validation testing
+      expect(post.media).to be_a(Image)
+    end
+  end
 end

From 02d619d61d7e4bc599f29dcf6d5863a6cf8ba13f Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 13:54:43 +0000
Subject: [PATCH 02/10] add embeds many polymorphic

---
 lib/couchbase-orm/utilities/embeds_many.rb | 123 ++++++++----
 spec/embeds_many_spec.rb                   | 218 +++++++++++++++++++++
 2 files changed, 308 insertions(+), 33 deletions(-)

diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index 2dbb7d41..c81dde9e 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -2,7 +2,7 @@
 
 module CouchbaseOrm
   module EmbedsMany
-    def embeds_many(name, class_name: nil, store_as: nil, validate: true)
+    def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphic: false)
       storage_key = (store_as || name).to_sym
       attribute storage_key, :array, type: :hash, default: []
 
@@ -15,51 +15,108 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true)
         key: storage_key,
         name: name,
         instance_var: instance_var,
+        polymorphic: polymorphic,
       })
 
       validates_embedded(name) if validate
 
-      # Lazy class resolution method
-      define_method("_resolve_embedded_class_for_#{name}") do
-        @__resolved_classes ||= {}
-        @__resolved_classes[name] ||= begin
-          klass_name.constantize
-        rescue NameError => e
-          warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
-          raise
-        end
-      end
+      if polymorphic
+        # Add types attribute for polymorphic associations
+        types_key = :"#{name}_types"
+        attribute types_key, :array, type: :string, default: []
+
+        # Polymorphic reader
+        define_method(name) do
+          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+          raw_array = read_attribute(storage_key)
+          types_array = read_attribute(types_key)
 
-      define_method(name) do
-        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+          embedded_objects = []
+          raw_array.each_with_index do |raw, index|
+            type = types_array[index]
+            next unless raw.present? && type.present?
 
-        klass = send("_resolve_embedded_class_for_#{name}")
-        embedded_objects = read_attribute(storage_key).map do |raw|
-          obj = klass.new(raw)
-          obj.embedded = true
-          obj
+            klass = type.constantize
+            obj = klass.new(raw)
+            obj.embedded = true
+            embedded_objects << obj
+          end
+
+          instance_variable_set(instance_var, embedded_objects)
         end
 
-        instance_variable_set(instance_var, embedded_objects)
-      end
+        # Polymorphic writer
+        define_method("#{name}=") do |val|
+          embedded_objects = []
+          serialized = []
+          types = []
+
+          Array(val).each do |v|
+            if v.nil?
+              next
+            elsif v.is_a?(Hash)
+              raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many"
+            else
+              obj = v
+              obj.embedded = true
+
+              raw = obj.serialized_attributes
+              raw.delete('id') if raw['id'].blank?
 
-      define_method("#{name}=") do |val|
-        klass = send("_resolve_embedded_class_for_#{name}")
+              embedded_objects << obj
+              serialized << raw
+              types << obj.class.name
+            end
+          end
 
-        embedded_objects = []
-        serialized = []
+          write_attribute(storage_key, serialized)
+          write_attribute(types_key, types)
+          instance_variable_set(instance_var, embedded_objects)
+        end
+      else
+        # Lazy class resolution method
+        define_method("_resolve_embedded_class_for_#{name}") do
+          @__resolved_classes ||= {}
+          @__resolved_classes[name] ||= begin
+            klass_name.constantize
+          rescue NameError => e
+            warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
+            raise
+          end
+        end
+
+        define_method(name) do
+          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+          klass = send("_resolve_embedded_class_for_#{name}")
+          embedded_objects = read_attribute(storage_key).map do |raw|
+            obj = klass.new(raw)
+            obj.embedded = true
+            obj
+          end
 
-        Array(val).each do |v|
-          obj = v.is_a?(klass) ? v : klass.new(v)
-          obj.embedded = true
-          raw = obj.serialized_attributes
-          raw.delete('id') if raw['id'].blank?
-          embedded_objects << obj
-          serialized << raw
+          instance_variable_set(instance_var, embedded_objects)
         end
 
-        write_attribute(storage_key, serialized)
-        instance_variable_set(instance_var, embedded_objects)
+        define_method("#{name}=") do |val|
+          klass = send("_resolve_embedded_class_for_#{name}")
+
+          embedded_objects = []
+          serialized = []
+
+          Array(val).each do |v|
+            obj = v.is_a?(klass) ? v : klass.new(v)
+            obj.embedded = true
+            raw = obj.serialized_attributes
+            raw.delete('id') if raw['id'].blank?
+            embedded_objects << obj
+            serialized << raw
+          end
+
+          write_attribute(storage_key, serialized)
+          instance_variable_set(instance_var, embedded_objects)
+        end
       end
 
       define_method(:"#{name}_reset") do
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index d074e163..4dc4bee3 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -67,6 +67,25 @@ class Citizen < CouchbaseOrm::Base
   embeds_many :addresses, class_name: 'AddressWithCity'
 end
 
+class ImageAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :caption, :string
+end
+
+class VideoAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :duration, :integer
+end
+
+class DocumentAttachment < CouchbaseOrm::Base
+  attribute :filename, :string
+  attribute :size, :integer
+end
+
+class Article < CouchbaseOrm::Base
+  embeds_many :attachments, polymorphic: true
+end
+
 describe CouchbaseOrm::EmbedsMany do
   let(:raw_data) { [{ street: '123 Main St' }, { street: '456 Elm St' }] }
 
@@ -354,4 +373,203 @@ class Citizen < CouchbaseOrm::Base
       person.destroy! if person&.persisted?
     end
   end
+
+  describe 'polymorphic embeds_many' do
+    it 'can embed different types polymorphically with types attribute' do
+      image = ImageAttachment.new(url: 'https://example.com/image.jpg', caption: 'A beautiful sunset')
+      video = VideoAttachment.new(url: 'https://example.com/video.mp4', duration: 120)
+      article = Article.new(attachments: [image, video])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+      expect(article.attachments.first.url).to eq('https://example.com/image.jpg')
+      expect(article.attachments.first.caption).to eq('A beautiful sunset')
+      expect(article.attachments.last).to be_a(VideoAttachment)
+      expect(article.attachments.last.url).to eq('https://example.com/video.mp4')
+      expect(article.attachments.last.duration).to eq(120)
+      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'VideoAttachment'])
+    end
+
+    it 'can embed multiple items of the same polymorphic type' do
+      image1 = ImageAttachment.new(url: 'https://example.com/image1.jpg', caption: 'First')
+      image2 = ImageAttachment.new(url: 'https://example.com/image2.jpg', caption: 'Second')
+      article = Article.new(attachments: [image1, image2])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments).to all(be_a(ImageAttachment))
+      expect(article.attachments.first.caption).to eq('First')
+      expect(article.attachments.last.caption).to eq('Second')
+      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'ImageAttachment'])
+    end
+
+    it 'can embed mixed polymorphic types' do
+      image = ImageAttachment.new(url: 'https://example.com/pic.jpg', caption: 'Photo')
+      video = VideoAttachment.new(url: 'https://example.com/clip.mp4', duration: 90)
+      doc = DocumentAttachment.new(filename: 'report.pdf', size: 1024)
+      article = Article.new(attachments: [image, video, doc])
+
+      expect(article.attachments.size).to eq(3)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[2]).to be_a(DocumentAttachment)
+      expect(article.attachments[2].filename).to eq('report.pdf')
+      expect(article.attachments[2].size).to eq(1024)
+    end
+
+    it 'persists and retrieves polymorphic embedded collections correctly' do
+      image = ImageAttachment.new(url: 'https://example.com/demo.jpg', caption: 'Demo')
+      video = VideoAttachment.new(url: 'https://example.com/demo.mp4', duration: 60)
+      article = Article.create!(attachments: [image, video])
+
+      loaded = Article.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments.first).to be_a(ImageAttachment)
+      expect(loaded.attachments.first.url).to eq('https://example.com/demo.jpg')
+      expect(loaded.attachments.last).to be_a(VideoAttachment)
+      expect(loaded.attachments.last.duration).to eq(60)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'can update polymorphic embedded collections' do
+      image = ImageAttachment.new(url: 'https://example.com/original.jpg', caption: 'Original')
+      article = Article.create!(attachments: [image])
+
+      video = VideoAttachment.new(url: 'https://example.com/new.mp4', duration: 45)
+      article.attachments = [video]
+      article.save!
+
+      article.reload
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(VideoAttachment)
+      expect(article.attachments.first.url).to eq('https://example.com/new.mp4')
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'can add to polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/first.jpg', caption: 'First')
+      article = Article.create!(attachments: [image])
+
+      video = VideoAttachment.new(url: 'https://example.com/second.mp4', duration: 30)
+      article.attachments = article.attachments + [video]
+      article.save!
+
+      article.reload
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+      expect(article.attachments.last).to be_a(VideoAttachment)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'sets embedded flag on polymorphic embedded objects' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      video = VideoAttachment.new(url: 'https://example.com/test.mp4', duration: 60)
+      article = Article.new(attachments: [image, video])
+
+      article.attachments.each do |attachment|
+        expect(attachment.instance_variable_get(:@_embedded)).to be true
+      end
+    end
+
+    it 'can set polymorphic embedded collection to empty array' do
+      video = VideoAttachment.new(url: 'https://example.com/test.mp4', duration: 60)
+      article = Article.new(attachments: [video])
+
+      article.attachments = []
+      expect(article.attachments).to eq([])
+      expect(article.attributes['attachments']).to eq([])
+      expect(article.attributes['attachments_types']).to eq([])
+    end
+
+    it 'can set polymorphic embedded collection to nil' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      article.attachments = nil
+      expect(article.attachments).to eq([])
+      expect(article.attributes['attachments']).to eq([])
+      expect(article.attributes['attachments_types']).to eq([])
+    end
+
+    it 'raises error when trying to assign Hash to polymorphic embeds_many' do
+      article = Article.new
+
+      expect {
+        article.attachments = [{ url: 'https://example.com/test.jpg', caption: 'Test' }]
+      }.to raise_error(ArgumentError, 'Cannot infer type from Hash for polymorphic embeds_many')
+    end
+
+    it 'skips nil values in polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image, nil])
+
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+    end
+
+    it 'memoizes polymorphic embedded collection after first access' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+      
+      first_call = article.attachments
+      second_call = article.attachments
+
+      expect(first_call).to equal(second_call)
+    end
+
+    it 'lazily loads polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/lazy.jpg', caption: 'Lazy')
+      article = Article.create!(attachments: [image])
+      article = Article.find(article.id)
+
+      expect(article.instance_variable_defined?(:@__assoc_attachments)).to be false
+
+      _ = article.attachments
+
+      expect(article.instance_variable_defined?(:@__assoc_attachments)).to be true
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'supports reset for polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+      
+      original = article.attachments
+      article.attachments_reset
+
+      new_instance = article.attachments
+      expect(new_instance).to be_an(Array)
+      expect(new_instance).not_to equal(original)
+    end
+
+    it 'does not include id in polymorphic embedded objects if blank' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      expect(article.send(:serialized_attributes)['attachments'].first).not_to include('id')
+    end
+
+    it 'handles empty polymorphic embedded collection on read' do
+      article = Article.new
+      expect(article.attachments).to eq([])
+    end
+
+    it 'preserves order of polymorphic embedded objects' do
+      video = VideoAttachment.new(url: 'https://example.com/first.mp4', duration: 30)
+      image = ImageAttachment.new(url: 'https://example.com/second.jpg', caption: 'Second')
+      doc = DocumentAttachment.new(filename: 'third.pdf', size: 2048)
+      
+      article = Article.create!(attachments: [video, image, doc])
+      article.reload
+
+      expect(article.attachments[0]).to be_a(VideoAttachment)
+      expect(article.attachments[1]).to be_a(ImageAttachment)
+      expect(article.attachments[2]).to be_a(DocumentAttachment)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+  end
 end

From e0403e4bcdd5f774361b6460a33b4078aadb2d49 Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 13:58:08 +0000
Subject: [PATCH 03/10] add documentation

---
 docs/reference/associations.txt | 226 ++++++++++++++++++++++++++++++++
 1 file changed, 226 insertions(+)

diff --git a/docs/reference/associations.txt b/docs/reference/associations.txt
index b2ca1117..37ab0486 100644
--- a/docs/reference/associations.txt
+++ b/docs/reference/associations.txt
@@ -12,6 +12,232 @@ Associations
    :depth: 2
    :class: singlecol
 
+Embedded Associations
+=====================
+
+CouchbaseOrm supports embedding documents within a parent document using
+``embeds_one`` and ``embeds_many``. Unlike referenced associations, embedded
+documents are stored directly within the parent document and do not have their
+own separate document ID in the database. This is useful for modeling
+has-one and has-many relationships where the child documents don't need to exist
+independently.
+
+Embeds One
+----------
+
+Use the ``embeds_one`` association to declare that the parent embeds a single
+child document:
+
+.. code-block:: ruby
+
+  class Profile < CouchbaseOrm::Base
+    attribute :bio, :string
+    attribute :website, :string
+  end
+
+  class User < CouchbaseOrm::Base
+    attribute :name, :string
+    embeds_one :profile
+  end
+
+  user = User.create!(name: 'Alice', profile: { bio: 'Software Engineer' })
+  # => #<User _id: "user::123", name: "Alice", profile: {...}>
+
+  user.profile
+  # => #<Profile bio: "Software Engineer", website: nil>
+
+  user.profile.bio = 'Senior Software Engineer'
+  user.profile = user.profile  # Reassign to track changes
+  user.save!
+
+The embedded document is stored as a hash within the parent:
+
+.. code-block:: ruby
+
+  # In the database, the document looks like:
+  {
+    "_id": "user::123",
+    "name": "Alice",
+    "profile": {
+      "bio": "Software Engineer",
+      "website": null
+    }
+  }
+
+Embedded documents cannot be saved, destroyed, or reloaded independently:
+
+.. code-block:: ruby
+
+  user.profile.save
+  # => raises "Cannot save an embedded document!"
+
+Embeds Many
+-----------
+
+Use the ``embeds_many`` association to declare that the parent embeds multiple
+child documents:
+
+.. code-block:: ruby
+
+  class Address < CouchbaseOrm::Base
+    attribute :street, :string
+    attribute :city, :string
+  end
+
+  class Person < CouchbaseOrm::Base
+    attribute :name, :string
+    embeds_many :addresses
+  end
+
+  person = Person.create!(
+    name: 'Bob',
+    addresses: [
+      { street: '123 Main St', city: 'New York' },
+      { street: '456 Elm St', city: 'Boston' }
+    ]
+  )
+
+  person.addresses
+  # => [#<Address street: "123 Main St", city: "New York">,
+  #     #<Address street: "456 Elm St", city: "Boston">]
+
+  person.addresses << Address.new(street: '789 Oak Ave', city: 'Chicago')
+  person.addresses = person.addresses  # Reassign to track changes
+  person.save!
+
+Polymorphic Embedded Associations
+----------------------------------
+
+Both ``embeds_one`` and ``embeds_many`` support polymorphic associations,
+allowing you to embed different types of documents in the same association:
+
+.. code-block:: ruby
+
+  class Image < CouchbaseOrm::Base
+    attribute :url, :string
+    attribute :caption, :string
+  end
+
+  class Video < CouchbaseOrm::Base
+    attribute :url, :string
+    attribute :duration, :integer
+  end
+
+  class Post < CouchbaseOrm::Base
+    embeds_one :media, polymorphic: true
+  end
+
+  # Embed an image
+  post = Post.create!(media: Image.new(url: 'photo.jpg', caption: 'Sunset'))
+  post.media
+  # => #<Image url: "photo.jpg", caption: "Sunset">
+
+  # Switch to a video
+  post.media = Video.new(url: 'clip.mp4', duration: 120)
+  post.save!
+
+For ``embeds_many`` with polymorphism:
+
+.. code-block:: ruby
+
+  class Article < CouchbaseOrm::Base
+    embeds_many :attachments, polymorphic: true
+  end
+
+  article = Article.create!(
+    attachments: [
+      Image.new(url: 'diagram.png', caption: 'Architecture'),
+      Video.new(url: 'demo.mp4', duration: 90)
+    ]
+  )
+
+  article.attachments
+  # => [#<Image ...>, #<Video ...>]
+
+When using polymorphic embedded associations, the type information is stored
+in a separate attribute (``<name>_type`` for ``embeds_one`` and
+``<name>_types`` for ``embeds_many``).
+
+Custom Storage Keys
+-------------------
+
+Use the ``store_as`` option to specify a different attribute name for storage:
+
+.. code-block:: ruby
+
+  class User < CouchbaseOrm::Base
+    embeds_one :profile, store_as: 'p'
+    embeds_many :addresses, store_as: 'addrs'
+  end
+
+  # In the database:
+  {
+    "_id": "user::123",
+    "p": { "bio": "..." },
+    "addrs": [{ "street": "..." }]
+  }
+
+Embedded Association Validation
+--------------------------------
+
+By default, embedded associations are validated when the parent is validated.
+You can disable this with ``validate: false``:
+
+.. code-block:: ruby
+
+  class Profile < CouchbaseOrm::Base
+    attribute :bio, :string
+    validates :bio, presence: true
+  end
+
+  class User < CouchbaseOrm::Base
+    embeds_one :profile
+  end
+
+  user = User.new(profile: { bio: nil })
+  user.valid?
+  # => false
+  user.errors[:profile]
+  # => ["is invalid"]
+
+  # To disable validation:
+  class User < CouchbaseOrm::Base
+    embeds_one :profile, validate: false
+  end
+
+Custom Class Names
+------------------
+
+Specify a different class name for embedded associations when the class cannot
+be inferred from the association name:
+
+.. code-block:: ruby
+
+  class User < CouchbaseOrm::Base
+    embeds_one :bio, class_name: 'Profile'
+    embeds_many :locations, class_name: 'Address'
+  end
+
+Key Differences from Referenced Associations
+---------------------------------------------
+
+Embedded associations differ from referenced associations in several ways:
+
+- **Storage**: Embedded documents are stored within the parent document, not as
+  separate documents in the database.
+
+- **Lifecycle**: Embedded documents cannot be saved, updated, or destroyed
+  independently. They are always saved as part of the parent document.
+
+- **Performance**: Reading a parent document also loads all embedded documents
+  in a single operation, which can be more efficient than separate queries.
+
+- **Querying**: Embedded documents cannot be queried independently. You must
+  query the parent document and then access the embedded documents.
+
+- **Identity**: Embedded documents do not have their own document ID by default
+  (the ``id`` field is removed when embedding).
+
 Referenced Associations
 =======================
 

From 886b51bbb4b40d9d3f684955e960fc5bd7eef5c9 Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 14:16:06 +0000
Subject: [PATCH 04/10] add hash mode

---
 docs/reference/associations.txt            |  20 +++-
 lib/couchbase-orm/utilities/embeds_many.rb |  26 +++--
 lib/couchbase-orm/utilities/embeds_one.rb  |  16 ++-
 spec/embeds_many_spec.rb                   | 107 +++++++++++++++++++--
 spec/embeds_one_spec.rb                    |  43 +++++++++
 5 files changed, 196 insertions(+), 16 deletions(-)

diff --git a/docs/reference/associations.txt b/docs/reference/associations.txt
index 37ab0486..80b741d4 100644
--- a/docs/reference/associations.txt
+++ b/docs/reference/associations.txt
@@ -127,11 +127,14 @@ allowing you to embed different types of documents in the same association:
     embeds_one :media, polymorphic: true
   end
 
-  # Embed an image
+  # Embed an image using an object
   post = Post.create!(media: Image.new(url: 'photo.jpg', caption: 'Sunset'))
   post.media
   # => #<Image url: "photo.jpg", caption: "Sunset">
 
+  # Or use a hash with type key (snake_case class name)
+  post = Post.create!(media: { type: 'image', url: 'photo.jpg', caption: 'Sunset' })
+
   # Switch to a video
   post.media = Video.new(url: 'clip.mp4', duration: 120)
   post.save!
@@ -144,6 +147,7 @@ For ``embeds_many`` with polymorphism:
     embeds_many :attachments, polymorphic: true
   end
 
+  # Using objects
   article = Article.create!(
     attachments: [
       Image.new(url: 'diagram.png', caption: 'Architecture'),
@@ -151,6 +155,14 @@ For ``embeds_many`` with polymorphism:
     ]
   )
 
+  # Or using hashes with type key (snake_case class names)
+  article = Article.create!(
+    attachments: [
+      { type: 'image', url: 'diagram.png', caption: 'Architecture' },
+      { type: 'video', url: 'demo.mp4', duration: 90 }
+    ]
+  )
+
   article.attachments
   # => [#<Image ...>, #<Video ...>]
 
@@ -158,6 +170,12 @@ When using polymorphic embedded associations, the type information is stored
 in a separate attribute (``<name>_type`` for ``embeds_one`` and
 ``<name>_types`` for ``embeds_many``).
 
+**Note**: When using hashes with polymorphic associations, you must include
+the ``type`` key (either as a symbol ``:type`` or string ``'type'``) with
+the snake_case version of the class name. For example, use ``'image'`` for
+the ``Image`` class or ``'video_attachment'`` for the ``VideoAttachment`` class.
+Without it, an ``ArgumentError`` will be raised.
+
 Custom Storage Keys
 -------------------
 
diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index c81dde9e..4541fecb 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -56,18 +56,28 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
             if v.nil?
               next
             elsif v.is_a?(Hash)
-              raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many"
+              # Extract type from hash
+              type_name = v[:type] || v['type']
+              raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name." unless type_name.present?
+              
+              klass = type_name.to_s.camelize.constantize
+              # Remove type from attributes before creating object
+              attrs = v.dup
+              attrs.delete(:type)
+              attrs.delete('type')
+              obj = klass.new(attrs)
             else
               obj = v
-              obj.embedded = true
+            end
+            
+            obj.embedded = true
 
-              raw = obj.serialized_attributes
-              raw.delete('id') if raw['id'].blank?
+            raw = obj.serialized_attributes
+            raw.delete('id') if raw['id'].blank?
 
-              embedded_objects << obj
-              serialized << raw
-              types << obj.class.name
-            end
+            embedded_objects << obj
+            serialized << raw
+            types << obj.class.name
           end
 
           write_attribute(storage_key, serialized)
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index 79c5fee5..c2c69002 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -48,7 +48,21 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
             next
           end
 
-          obj = val.is_a?(Hash) ? raise(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one") : val
+          if val.is_a?(Hash)
+            # Extract type from hash
+            type_name = val[:type] || val['type']
+            raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name." unless type_name.present?
+            
+            klass = type_name.to_s.camelize.constantize
+            # Remove type from attributes before creating object
+            attrs = val.dup
+            attrs.delete(:type)
+            attrs.delete('type')
+            obj = klass.new(attrs)
+          else
+            obj = val
+          end
+          
           obj.embedded = true
 
           raw = obj.serialized_attributes
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index 4dc4bee3..4966ee17 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -40,16 +40,16 @@ class BasePerson < CouchbaseOrm::Base
 class ChildPerson < BasePerson
 end
 
-class AddressBook < CouchbaseOrm::Base
-  attribute :label, :string
-  has_many :contacts, type: :n1ql, class_name: 'Contact'
-end
-
 class Contact < CouchbaseOrm::Base
   attribute :name, :string
   belongs_to :address_book
 end
 
+class AddressBook < CouchbaseOrm::Base
+  attribute :label, :string
+  has_many :contacts, type: :n1ql, class_name: 'Contact'
+end
+
 class PersonWithBook < CouchbaseOrm::Base
   embeds_many :address_books, class_name: 'AddressBook'
 end
@@ -498,7 +498,7 @@ class Article < CouchbaseOrm::Base
 
       expect {
         article.attachments = [{ url: 'https://example.com/test.jpg', caption: 'Test' }]
-      }.to raise_error(ArgumentError, 'Cannot infer type from Hash for polymorphic embeds_many')
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.")
     end
 
     it 'skips nil values in polymorphic embedded collection' do
@@ -571,5 +571,100 @@ class Article < CouchbaseOrm::Base
     ensure
       article.destroy! if article&.persisted?
     end
+
+    it 'accepts hashes with type key for polymorphic embeds_many' do
+      article = Article.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/hash1.jpg', caption: 'First' },
+          { type: 'video_attachment', url: 'https://example.com/hash2.mp4', duration: 45 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/hash1.jpg')
+      expect(article.attachments[0].caption).to eq('First')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].url).to eq('https://example.com/hash2.mp4')
+      expect(article.attachments[1].duration).to eq(45)
+      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'VideoAttachment'])
+    end
+
+    it 'accepts hashes with string type key for polymorphic embeds_many' do
+      article = Article.new(
+        attachments: [
+          { 'type' => 'document_attachment', 'filename' => 'doc.pdf', 'size' => 1024 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(DocumentAttachment)
+      expect(article.attachments.first.filename).to eq('doc.pdf')
+      expect(article.attachments.first.size).to eq(1024)
+    end
+
+    it 'raises error when hash is missing type key for polymorphic embeds_many' do
+      expect {
+        Article.new(attachments: [{ url: 'https://example.com/no-type.jpg', caption: 'Missing Type' }])
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.")
+    end
+
+    it 'can mix objects and hashes with type key' do
+      image_obj = ImageAttachment.new(url: 'https://example.com/obj.jpg', caption: 'Object')
+      article = Article.new(
+        attachments: [
+          image_obj,
+          { type: 'video_attachment', url: 'https://example.com/hash.mp4', duration: 60 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/obj.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].duration).to eq(60)
+    end
+
+    it 'persists and retrieves polymorphic embedded from hashes' do
+      article = Article.create!(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/persist.jpg', caption: 'Persisted' },
+          { type: 'video_attachment', url: 'https://example.com/persist.mp4', duration: 90 }
+        ]
+      )
+
+      loaded = Article.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments[0]).to be_a(ImageAttachment)
+      expect(loaded.attachments[0].url).to eq('https://example.com/persist.jpg')
+      expect(loaded.attachments[1]).to be_a(VideoAttachment)
+      expect(loaded.attachments[1].duration).to eq(90)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'does not include type in serialized attributes' do
+      article = Article.new(
+        attachments: [{ type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' }]
+      )
+      
+      serialized = article.send(:serialized_attributes)
+      expect(serialized['attachments'].first).not_to have_key('type')
+      expect(serialized['attachments'].first).not_to have_key(:type)
+    end
+
+    it 'handles mixed valid and nil values with hashes' do
+      article = Article.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' },
+          nil,
+          { type: 'video_attachment', url: 'https://example.com/test.mp4', duration: 30 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+    end
   end
 end
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index 65bd7365..c8457c97 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -472,5 +472,48 @@ class Post < CouchbaseOrm::Base
       # But demonstrates the structure for validation testing
       expect(post.media).to be_a(Image)
     end
+
+    it 'accepts hash with type key for polymorphic embeds_one' do
+      post = Post.new(media: { type: 'image', url: 'https://example.com/hash.jpg', caption: 'From Hash' })
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/hash.jpg')
+      expect(post.media.caption).to eq('From Hash')
+      expect(post.attributes['media_type']).to eq('Image')
+    end
+
+    it 'accepts hash with string type key for polymorphic embeds_one' do
+      post = Post.new(media: { 'type' => 'video', 'url' => 'https://example.com/hash.mp4', 'duration' => 75 })
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/hash.mp4')
+      expect(post.media.duration).to eq(75)
+      expect(post.attributes['media_type']).to eq('Video')
+    end
+
+    it 'raises error when hash is missing type key for polymorphic embeds_one' do
+      expect {
+        Post.new(media: { url: 'https://example.com/no-type.jpg', caption: 'Missing Type' })
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.")
+    end
+
+    it 'persists and retrieves polymorphic embedded from hash' do
+      post = Post.create!(media: { type: 'image', url: 'https://example.com/persist.jpg', caption: 'Persisted' })
+
+      loaded = Post.find(post.id)
+      expect(loaded.media).to be_a(Image)
+      expect(loaded.media.url).to eq('https://example.com/persist.jpg')
+      expect(loaded.media.caption).to eq('Persisted')
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'does not include type in serialized attributes' do
+      post = Post.new(media: { type: 'video', url: 'https://example.com/test.mp4', duration: 100 })
+      
+      serialized = post.send(:serialized_attributes)
+      expect(serialized['media']).not_to have_key('type')
+      expect(serialized['media']).not_to have_key(:type)
+    end
   end
 end

From 126338ebcb684f43c1aa33adb028a2c4a4888cb0 Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 14:39:25 +0000
Subject: [PATCH 05/10] fix type polymorphic

---
 docs/reference/associations.txt            | 48 +++++++++++++++-
 lib/couchbase-orm/utilities/embeds_many.rb | 42 +++++++++-----
 lib/couchbase-orm/utilities/embeds_one.rb  | 38 +++++++++----
 spec/embeds_many_spec.rb                   | 24 +++++---
 spec/embeds_one_spec.rb                    | 64 +++++++++++++++++++---
 5 files changed, 174 insertions(+), 42 deletions(-)

diff --git a/docs/reference/associations.txt b/docs/reference/associations.txt
index 80b741d4..b9c8aeba 100644
--- a/docs/reference/associations.txt
+++ b/docs/reference/associations.txt
@@ -167,8 +167,18 @@ For ``embeds_many`` with polymorphism:
   # => [#<Image ...>, #<Video ...>]
 
 When using polymorphic embedded associations, the type information is stored
-in a separate attribute (``<name>_type`` for ``embeds_one`` and
-``<name>_types`` for ``embeds_many``).
+inside each embedded document as a ``type`` field. For example:
+
+.. code-block:: json
+
+  {
+    "_id": "post::123",
+    "media": {
+      "type": "Image",
+      "url": "photo.jpg",
+      "caption": "Sunset"
+    }
+  }
 
 **Note**: When using hashes with polymorphic associations, you must include
 the ``type`` key (either as a symbol ``:type`` or string ``'type'``) with
@@ -176,6 +186,40 @@ the snake_case version of the class name. For example, use ``'image'`` for
 the ``Image`` class or ``'video_attachment'`` for the ``VideoAttachment`` class.
 Without it, an ``ArgumentError`` will be raised.
 
+Restricting Polymorphic Types
+------------------------------
+
+You can restrict which types are allowed in a polymorphic association by
+passing an array of allowed class names to the ``polymorphic`` parameter:
+
+.. code-block:: ruby
+
+  class Post < CouchbaseOrm::Base
+    # Only Image and Video are allowed
+    embeds_one :media, polymorphic: ['Image', 'Video']
+  end
+
+  class Article < CouchbaseOrm::Base
+    # Only specific attachment types allowed
+    embeds_many :attachments, polymorphic: ['ImageAttachment', 'VideoAttachment']
+  end
+
+  # This works
+  post = Post.new(media: Image.new(url: 'photo.jpg'))
+
+  # This raises an error
+  post = Post.new(media: Audio.new(url: 'song.mp3'))
+  # => ArgumentError: Audio is not an allowed type for media. Allowed types: Image, Video
+
+You can use snake_case names in the array, which will be automatically
+converted to CamelCase class names:
+
+.. code-block:: ruby
+
+  class Post < CouchbaseOrm::Base
+    embeds_one :media, polymorphic: [:image, 'video']  # Same as ['Image', 'Video']
+  end
+
 Custom Storage Keys
 -------------------
 
diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index 4541fecb..fe13778b 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -9,36 +9,46 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
       instance_var = "@__assoc_#{name}"
       klass_name = (class_name || name.to_s.singularize.camelize)
 
+      # Handle polymorphic parameter: can be true, false, or array of allowed types
+      is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
+      allowed_types = if polymorphic.is_a?(Array)
+        polymorphic.map { |t| t.to_s.camelize }
+      else
+        nil
+      end
+
       set_embedded(name, {
         type: :many,
         class_name: klass_name, # store as string, resolve later
         key: storage_key,
         name: name,
         instance_var: instance_var,
-        polymorphic: polymorphic,
+        polymorphic: is_polymorphic,
+        allowed_types: allowed_types,
       })
 
       validates_embedded(name) if validate
 
-      if polymorphic
-        # Add types attribute for polymorphic associations
-        types_key = :"#{name}_types"
-        attribute types_key, :array, type: :string, default: []
-
+      if is_polymorphic
         # Polymorphic reader
         define_method(name) do
           return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
 
           raw_array = read_attribute(storage_key)
-          types_array = read_attribute(types_key)
 
           embedded_objects = []
-          raw_array.each_with_index do |raw, index|
-            type = types_array[index]
-            next unless raw.present? && type.present?
+          raw_array.each do |raw|
+            next unless raw.present?
+            
+            type = raw['type'] || raw[:type]
+            next unless type.present?
 
             klass = type.constantize
-            obj = klass.new(raw)
+            # Remove type from attributes before creating object
+            attrs = raw.dup
+            attrs.delete('type')
+            attrs.delete(:type)
+            obj = klass.new(attrs)
             obj.embedded = true
             embedded_objects << obj
           end
@@ -50,7 +60,6 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
         define_method("#{name}=") do |val|
           embedded_objects = []
           serialized = []
-          types = []
 
           Array(val).each do |v|
             if v.nil?
@@ -70,18 +79,23 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
               obj = v
             end
             
+            # Validate against allowed types if specified
+            if allowed_types.present? && !allowed_types.include?(obj.class.name)
+              raise ArgumentError, "#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}"
+            end
+            
             obj.embedded = true
 
             raw = obj.serialized_attributes
             raw.delete('id') if raw['id'].blank?
+            # Store type inside each object
+            raw['type'] = obj.class.name
 
             embedded_objects << obj
             serialized << raw
-            types << obj.class.name
           end
 
           write_attribute(storage_key, serialized)
-          write_attribute(types_key, types)
           instance_variable_set(instance_var, embedded_objects)
         end
       else
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index c2c69002..ecf22ee4 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -9,32 +9,43 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
       instance_var = "@__assoc_#{name}"
       klass_name = (class_name || name.to_s.camelize)
 
+      # Handle polymorphic parameter: can be true, false, or array of allowed types
+      is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
+      allowed_types = if polymorphic.is_a?(Array)
+        polymorphic.map { |t| t.to_s.camelize }
+      else
+        nil
+      end
+
       set_embedded(name, {
         type: :one,
         class_name: klass_name, # keep as string to delay resolution
         key: storage_key,
         name: name,
         instance_var: instance_var,
-        polymorphic: polymorphic,
+        polymorphic: is_polymorphic,
+        allowed_types: allowed_types,
       })
 
       validates_embedded(name) if validate
 
-      if polymorphic
-        # Add type attribute for polymorphic associations
-        type_key = :"#{name}_type"
-        attribute type_key, :string, default: nil
-
+      if is_polymorphic
         # Polymorphic reader
         define_method(name) do
           return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
 
           raw = read_attribute(storage_key)
-          type = read_attribute(type_key)
-          return instance_variable_set(instance_var, nil) unless raw.present? && type.present?
+          return instance_variable_set(instance_var, nil) unless raw.present?
+          
+          type = raw['type'] || raw[:type]
+          return instance_variable_set(instance_var, nil) unless type.present?
 
           klass = type.constantize
-          obj = klass.new(raw)
+          # Remove type from attributes before creating object
+          attrs = raw.dup
+          attrs.delete('type')
+          attrs.delete(:type)
+          obj = klass.new(attrs)
           obj.embedded = true
           instance_variable_set(instance_var, obj)
         end
@@ -43,7 +54,6 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
         define_method("#{name}=") do |val|
           if val.nil?
             write_attribute(storage_key, nil)
-            write_attribute(type_key, nil)
             instance_variable_set(instance_var, nil)
             next
           end
@@ -63,13 +73,19 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
             obj = val
           end
           
+          # Validate against allowed types if specified
+          if allowed_types.present? && !allowed_types.include?(obj.class.name)
+            raise ArgumentError, "#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}"
+          end
+          
           obj.embedded = true
 
           raw = obj.serialized_attributes
           raw.delete('id') if raw['id'].blank?
+          # Store type inside the object
+          raw['type'] = obj.class.name
 
           write_attribute(storage_key, raw)
-          write_attribute(type_key, obj.class.name)
           instance_variable_set(instance_var, obj)
         end
       else
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index 4966ee17..57441950 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -82,10 +82,19 @@ class DocumentAttachment < CouchbaseOrm::Base
   attribute :size, :integer
 end
 
+class AudioAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :bitrate, :integer
+end
+
 class Article < CouchbaseOrm::Base
   embeds_many :attachments, polymorphic: true
 end
 
+class RestrictedArticle < CouchbaseOrm::Base
+  embeds_many :attachments, polymorphic: ['ImageAttachment', 'VideoAttachment']
+end
+
 describe CouchbaseOrm::EmbedsMany do
   let(:raw_data) { [{ street: '123 Main St' }, { street: '456 Elm St' }] }
 
@@ -387,7 +396,8 @@ class Article < CouchbaseOrm::Base
       expect(article.attachments.last).to be_a(VideoAttachment)
       expect(article.attachments.last.url).to eq('https://example.com/video.mp4')
       expect(article.attachments.last.duration).to eq(120)
-      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'VideoAttachment'])
+      expect(article.attributes['attachments'].first['type']).to eq('ImageAttachment')
+      expect(article.attributes['attachments'].last['type']).to eq('VideoAttachment')
     end
 
     it 'can embed multiple items of the same polymorphic type' do
@@ -399,7 +409,7 @@ class Article < CouchbaseOrm::Base
       expect(article.attachments).to all(be_a(ImageAttachment))
       expect(article.attachments.first.caption).to eq('First')
       expect(article.attachments.last.caption).to eq('Second')
-      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'ImageAttachment'])
+      expect(article.attributes['attachments'].map { |a| a['type'] }).to eq(['ImageAttachment', 'ImageAttachment'])
     end
 
     it 'can embed mixed polymorphic types' do
@@ -480,7 +490,6 @@ class Article < CouchbaseOrm::Base
       article.attachments = []
       expect(article.attachments).to eq([])
       expect(article.attributes['attachments']).to eq([])
-      expect(article.attributes['attachments_types']).to eq([])
     end
 
     it 'can set polymorphic embedded collection to nil' do
@@ -490,7 +499,6 @@ class Article < CouchbaseOrm::Base
       article.attachments = nil
       expect(article.attachments).to eq([])
       expect(article.attributes['attachments']).to eq([])
-      expect(article.attributes['attachments_types']).to eq([])
     end
 
     it 'raises error when trying to assign Hash to polymorphic embeds_many' do
@@ -587,7 +595,7 @@ class Article < CouchbaseOrm::Base
       expect(article.attachments[1]).to be_a(VideoAttachment)
       expect(article.attachments[1].url).to eq('https://example.com/hash2.mp4')
       expect(article.attachments[1].duration).to eq(45)
-      expect(article.attributes['attachments_types']).to eq(['ImageAttachment', 'VideoAttachment'])
+      expect(article.attributes['attachments'].map { |a| a['type'] }).to eq(['ImageAttachment', 'VideoAttachment'])
     end
 
     it 'accepts hashes with string type key for polymorphic embeds_many' do
@@ -643,14 +651,14 @@ class Article < CouchbaseOrm::Base
       article.destroy! if article&.persisted?
     end
 
-    it 'does not include type in serialized attributes' do
+    it 'includes type in serialized attributes' do
       article = Article.new(
         attachments: [{ type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' }]
       )
       
       serialized = article.send(:serialized_attributes)
-      expect(serialized['attachments'].first).not_to have_key('type')
-      expect(serialized['attachments'].first).not_to have_key(:type)
+      expect(serialized['attachments'].first).to have_key('type')
+      expect(serialized['attachments'].first['type']).to eq('ImageAttachment')
     end
 
     it 'handles mixed valid and nil values with hashes' do
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index c8457c97..a16cf15b 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -83,10 +83,19 @@ class Video < CouchbaseOrm::Base
   attribute :duration, :integer
 end
 
+class Audio < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :bitrate, :integer
+end
+
 class Post < CouchbaseOrm::Base
   embeds_one :media, polymorphic: true
 end
 
+class RestrictedPost < CouchbaseOrm::Base
+  embeds_one :media, polymorphic: ['Image', 'Video']
+end
+
 describe CouchbaseOrm::EmbedsOne do
   let(:raw_data) { { bio: 'Software Engineer' } }
 
@@ -407,7 +416,7 @@ class Post < CouchbaseOrm::Base
       expect(post.media).to be_a(Image)
       expect(post.media.url).to eq('https://example.com/image.jpg')
       expect(post.media.caption).to eq('A beautiful sunset')
-      expect(post.attributes['media_type']).to eq('Image')
+      expect(post.attributes['media']['type']).to eq('Image')
     end
 
     it 'can embed a different polymorphic type' do
@@ -417,7 +426,7 @@ class Post < CouchbaseOrm::Base
       expect(post.media).to be_a(Video)
       expect(post.media.url).to eq('https://example.com/video.mp4')
       expect(post.media.duration).to eq(120)
-      expect(post.attributes['media_type']).to eq('Video')
+      expect(post.attributes['media']['type']).to eq('Video')
     end
 
     it 'persists and retrieves polymorphic embedded objects correctly' do
@@ -479,7 +488,7 @@ class Post < CouchbaseOrm::Base
       expect(post.media).to be_a(Image)
       expect(post.media.url).to eq('https://example.com/hash.jpg')
       expect(post.media.caption).to eq('From Hash')
-      expect(post.attributes['media_type']).to eq('Image')
+      expect(post.attributes['media']['type']).to eq('Image')
     end
 
     it 'accepts hash with string type key for polymorphic embeds_one' do
@@ -488,7 +497,7 @@ class Post < CouchbaseOrm::Base
       expect(post.media).to be_a(Video)
       expect(post.media.url).to eq('https://example.com/hash.mp4')
       expect(post.media.duration).to eq(75)
-      expect(post.attributes['media_type']).to eq('Video')
+      expect(post.attributes['media']['type']).to eq('Video')
     end
 
     it 'raises error when hash is missing type key for polymorphic embeds_one' do
@@ -508,12 +517,53 @@ class Post < CouchbaseOrm::Base
       post.destroy! if post&.persisted?
     end
 
-    it 'does not include type in serialized attributes' do
+    it 'includes type in serialized attributes' do
       post = Post.new(media: { type: 'video', url: 'https://example.com/test.mp4', duration: 100 })
       
       serialized = post.send(:serialized_attributes)
-      expect(serialized['media']).not_to have_key('type')
-      expect(serialized['media']).not_to have_key(:type)
+      expect(serialized['media']).to have_key('type')
+      expect(serialized['media']['type']).to eq('Video')
+    end
+  end
+
+  describe 'polymorphic embeds_one with types restriction' do
+    it 'accepts allowed types with objects' do
+      image = Image.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      post = RestrictedPost.new(media: image)
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/allowed.jpg')
+    end
+
+    it 'accepts allowed types with hashes' do
+      post = RestrictedPost.new(media: { type: 'video', url: 'https://example.com/allowed.mp4', duration: 60 })
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/allowed.mp4')
+    end
+
+    it 'rejects disallowed types with objects' do
+      audio = Audio.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+
+      expect {
+        RestrictedPost.new(media: audio)
+      }.to raise_error(ArgumentError, 'Audio is not an allowed type for media. Allowed types: Image, Video')
+    end
+
+    it 'rejects disallowed types with hashes' do
+      expect {
+        RestrictedPost.new(media: { type: 'audio', url: 'https://example.com/denied.mp3', bitrate: 128 })
+      }.to raise_error(ArgumentError, 'Audio is not an allowed type for media. Allowed types: Image, Video')
+    end
+
+    it 'persists and retrieves with type restrictions' do
+      post = RestrictedPost.create!(media: { type: 'image', url: 'https://example.com/restricted.jpg', caption: 'Restricted' })
+
+      loaded = RestrictedPost.find(post.id)
+      expect(loaded.media).to be_a(Image)
+      expect(loaded.media.url).to eq('https://example.com/restricted.jpg')
+    ensure
+      post.destroy! if post&.persisted?
     end
   end
 end

From cb5c036076d0b18ef159dc388ef2e11bf67a0d8d Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 14:43:05 +0000
Subject: [PATCH 06/10] fix rubocop

---
 lib/couchbase-orm/utilities/embeds_many.rb | 18 ++++++++----------
 lib/couchbase-orm/utilities/embeds_one.rb  | 18 ++++++++----------
 spec/embeds_many_spec.rb                   |  8 ++++----
 spec/embeds_one_spec.rb                    |  2 +-
 4 files changed, 21 insertions(+), 25 deletions(-)

diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index fe13778b..6db388ae 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -12,10 +12,8 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
       # Handle polymorphic parameter: can be true, false, or array of allowed types
       is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
       allowed_types = if polymorphic.is_a?(Array)
-        polymorphic.map { |t| t.to_s.camelize }
-      else
-        nil
-      end
+                        polymorphic.map { |t| t.to_s.camelize }
+                      end
 
       set_embedded(name, {
         type: :many,
@@ -39,7 +37,7 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
           embedded_objects = []
           raw_array.each do |raw|
             next unless raw.present?
-            
+
             type = raw['type'] || raw[:type]
             next unless type.present?
 
@@ -67,8 +65,8 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
             elsif v.is_a?(Hash)
               # Extract type from hash
               type_name = v[:type] || v['type']
-              raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name." unless type_name.present?
-              
+              raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.") unless type_name.present?
+
               klass = type_name.to_s.camelize.constantize
               # Remove type from attributes before creating object
               attrs = v.dup
@@ -78,12 +76,12 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
             else
               obj = v
             end
-            
+
             # Validate against allowed types if specified
             if allowed_types.present? && !allowed_types.include?(obj.class.name)
-              raise ArgumentError, "#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}"
+              raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
             end
-            
+
             obj.embedded = true
 
             raw = obj.serialized_attributes
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index ecf22ee4..571b4b0b 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -12,10 +12,8 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
       # Handle polymorphic parameter: can be true, false, or array of allowed types
       is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
       allowed_types = if polymorphic.is_a?(Array)
-        polymorphic.map { |t| t.to_s.camelize }
-      else
-        nil
-      end
+                        polymorphic.map { |t| t.to_s.camelize }
+                      end
 
       set_embedded(name, {
         type: :one,
@@ -36,7 +34,7 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
 
           raw = read_attribute(storage_key)
           return instance_variable_set(instance_var, nil) unless raw.present?
-          
+
           type = raw['type'] || raw[:type]
           return instance_variable_set(instance_var, nil) unless type.present?
 
@@ -61,8 +59,8 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
           if val.is_a?(Hash)
             # Extract type from hash
             type_name = val[:type] || val['type']
-            raise ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name." unless type_name.present?
-            
+            raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.") unless type_name.present?
+
             klass = type_name.to_s.camelize.constantize
             # Remove type from attributes before creating object
             attrs = val.dup
@@ -72,12 +70,12 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
           else
             obj = val
           end
-          
+
           # Validate against allowed types if specified
           if allowed_types.present? && !allowed_types.include?(obj.class.name)
-            raise ArgumentError, "#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}"
+            raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
           end
-          
+
           obj.embedded = true
 
           raw = obj.serialized_attributes
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index 57441950..d152fb36 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -520,7 +520,7 @@ class RestrictedArticle < CouchbaseOrm::Base
     it 'memoizes polymorphic embedded collection after first access' do
       image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
       article = Article.new(attachments: [image])
-      
+
       first_call = article.attachments
       second_call = article.attachments
 
@@ -544,7 +544,7 @@ class RestrictedArticle < CouchbaseOrm::Base
     it 'supports reset for polymorphic embedded collection' do
       image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
       article = Article.new(attachments: [image])
-      
+
       original = article.attachments
       article.attachments_reset
 
@@ -569,7 +569,7 @@ class RestrictedArticle < CouchbaseOrm::Base
       video = VideoAttachment.new(url: 'https://example.com/first.mp4', duration: 30)
       image = ImageAttachment.new(url: 'https://example.com/second.jpg', caption: 'Second')
       doc = DocumentAttachment.new(filename: 'third.pdf', size: 2048)
-      
+
       article = Article.create!(attachments: [video, image, doc])
       article.reload
 
@@ -655,7 +655,7 @@ class RestrictedArticle < CouchbaseOrm::Base
       article = Article.new(
         attachments: [{ type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' }]
       )
-      
+
       serialized = article.send(:serialized_attributes)
       expect(serialized['attachments'].first).to have_key('type')
       expect(serialized['attachments'].first['type']).to eq('ImageAttachment')
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index a16cf15b..31038e2e 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -519,7 +519,7 @@ class RestrictedPost < CouchbaseOrm::Base
 
     it 'includes type in serialized attributes' do
       post = Post.new(media: { type: 'video', url: 'https://example.com/test.mp4', duration: 100 })
-      
+
       serialized = post.send(:serialized_attributes)
       expect(serialized['media']).to have_key('type')
       expect(serialized['media']['type']).to eq('Video')

From a155dc9874dc2295412d2cc8564984dbf4fda684 Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Tue, 3 Feb 2026 14:50:33 +0000
Subject: [PATCH 07/10] fix rubocop

---
 lib/couchbase-orm/utilities/embeds_many.rb | 211 +++++++++++----------
 lib/couchbase-orm/utilities/embeds_one.rb  | 193 ++++++++++---------
 2 files changed, 206 insertions(+), 198 deletions(-)

diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index 6db388ae..cb81516c 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -11,13 +11,11 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
 
       # Handle polymorphic parameter: can be true, false, or array of allowed types
       is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
-      allowed_types = if polymorphic.is_a?(Array)
-                        polymorphic.map { |t| t.to_s.camelize }
-                      end
+      allowed_types = polymorphic.is_a?(Array) ? polymorphic.map { |t| t.to_s.camelize } : nil
 
       set_embedded(name, {
         type: :many,
-        class_name: klass_name, # store as string, resolve later
+        class_name: klass_name,
         key: storage_key,
         name: name,
         instance_var: instance_var,
@@ -28,121 +26,126 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
       validates_embedded(name) if validate
 
       if is_polymorphic
-        # Polymorphic reader
-        define_method(name) do
-          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
-
-          raw_array = read_attribute(storage_key)
-
-          embedded_objects = []
-          raw_array.each do |raw|
-            next unless raw.present?
-
-            type = raw['type'] || raw[:type]
-            next unless type.present?
-
-            klass = type.constantize
-            # Remove type from attributes before creating object
-            attrs = raw.dup
-            attrs.delete('type')
-            attrs.delete(:type)
-            obj = klass.new(attrs)
-            obj.embedded = true
-            embedded_objects << obj
-          end
+        define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
+        define_polymorphic_embeds_many_writer(name, storage_key, instance_var, allowed_types)
+      else
+        define_standard_embeds_many_reader(name, storage_key, instance_var, klass_name)
+        define_standard_embeds_many_writer(name, storage_key, instance_var, klass_name)
+      end
 
-          instance_variable_set(instance_var, embedded_objects)
-        end
+      define_method(:"#{name}_reset") do
+        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+      end
+    end
 
-        # Polymorphic writer
-        define_method("#{name}=") do |val|
-          embedded_objects = []
-          serialized = []
-
-          Array(val).each do |v|
-            if v.nil?
-              next
-            elsif v.is_a?(Hash)
-              # Extract type from hash
-              type_name = v[:type] || v['type']
-              raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.") unless type_name.present?
-
-              klass = type_name.to_s.camelize.constantize
-              # Remove type from attributes before creating object
-              attrs = v.dup
-              attrs.delete(:type)
-              attrs.delete('type')
-              obj = klass.new(attrs)
-            else
-              obj = v
-            end
-
-            # Validate against allowed types if specified
-            if allowed_types.present? && !allowed_types.include?(obj.class.name)
-              raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
-            end
-
-            obj.embedded = true
-
-            raw = obj.serialized_attributes
-            raw.delete('id') if raw['id'].blank?
-            # Store type inside each object
-            raw['type'] = obj.class.name
-
-            embedded_objects << obj
-            serialized << raw
-          end
+    private
 
-          write_attribute(storage_key, serialized)
-          instance_variable_set(instance_var, embedded_objects)
-        end
-      else
-        # Lazy class resolution method
-        define_method("_resolve_embedded_class_for_#{name}") do
-          @__resolved_classes ||= {}
-          @__resolved_classes[name] ||= begin
-            klass_name.constantize
-          rescue NameError => e
-            warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
-            raise
-          end
-        end
+    def define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+        raw_array = read_attribute(storage_key)
+        embedded_objects = raw_array.map do |raw|
+          next unless raw.present?
+
+          type = raw['type'] || raw[:type]
+          next unless type.present?
+
+          klass = type.constantize
+          attrs = raw.dup
+          attrs.delete('type')
+          attrs.delete(:type)
+          obj = klass.new(attrs)
+          obj.embedded = true
+          obj
+        end.compact
 
-        define_method(name) do
-          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+        instance_variable_set(instance_var, embedded_objects)
+      end
+    end
 
-          klass = send("_resolve_embedded_class_for_#{name}")
-          embedded_objects = read_attribute(storage_key).map do |raw|
-            obj = klass.new(raw)
-            obj.embedded = true
-            obj
+    def define_polymorphic_embeds_many_writer(name, storage_key, instance_var, allowed_types)
+      define_method("#{name}=") do |val|
+        embedded_objects = []
+        serialized = []
+
+        Array(val).each do |v|
+          next if v.nil?
+
+          obj = if v.is_a?(Hash)
+                  type_name = v[:type] || v['type']
+                  raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.") unless type_name.present?
+
+                  klass = type_name.to_s.camelize.constantize
+                  attrs = v.dup
+                  attrs.delete(:type)
+                  attrs.delete('type')
+                  klass.new(attrs)
+                else
+                  v
+                end
+
+          if allowed_types.present? && !allowed_types.include?(obj.class.name)
+            raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
           end
 
-          instance_variable_set(instance_var, embedded_objects)
+          obj.embedded = true
+          raw = obj.serialized_attributes
+          raw.delete('id') if raw['id'].blank?
+          raw['type'] = obj.class.name
+
+          embedded_objects << obj
+          serialized << raw
         end
 
-        define_method("#{name}=") do |val|
-          klass = send("_resolve_embedded_class_for_#{name}")
+        write_attribute(storage_key, serialized)
+        instance_variable_set(instance_var, embedded_objects)
+      end
+    end
 
-          embedded_objects = []
-          serialized = []
+    def define_standard_embeds_many_reader(name, storage_key, instance_var, klass_name)
+      define_method("_resolve_embedded_class_for_#{name}") do
+        @__resolved_classes ||= {}
+        @__resolved_classes[name] ||= begin
+          klass_name.constantize
+        rescue NameError => e
+          warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
+          raise
+        end
+      end
 
-          Array(val).each do |v|
-            obj = v.is_a?(klass) ? v : klass.new(v)
-            obj.embedded = true
-            raw = obj.serialized_attributes
-            raw.delete('id') if raw['id'].blank?
-            embedded_objects << obj
-            serialized << raw
-          end
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
 
-          write_attribute(storage_key, serialized)
-          instance_variable_set(instance_var, embedded_objects)
+        klass = send("_resolve_embedded_class_for_#{name}")
+        embedded_objects = read_attribute(storage_key).map do |raw|
+          obj = klass.new(raw)
+          obj.embedded = true
+          obj
         end
+
+        instance_variable_set(instance_var, embedded_objects)
       end
+    end
 
-      define_method(:"#{name}_reset") do
-        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+    def define_standard_embeds_many_writer(name, storage_key, instance_var, _klass_name)
+      define_method("#{name}=") do |val|
+        klass = send("_resolve_embedded_class_for_#{name}")
+
+        embedded_objects = []
+        serialized = []
+
+        Array(val).each do |v|
+          obj = v.is_a?(klass) ? v : klass.new(v)
+          obj.embedded = true
+          raw = obj.serialized_attributes
+          raw.delete('id') if raw['id'].blank?
+          embedded_objects << obj
+          serialized << raw
+        end
+
+        write_attribute(storage_key, serialized)
+        instance_variable_set(instance_var, embedded_objects)
       end
     end
   end
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index 571b4b0b..9cd0f80b 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -11,13 +11,11 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
 
       # Handle polymorphic parameter: can be true, false, or array of allowed types
       is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
-      allowed_types = if polymorphic.is_a?(Array)
-                        polymorphic.map { |t| t.to_s.camelize }
-                      end
+      allowed_types = polymorphic.is_a?(Array) ? polymorphic.map { |t| t.to_s.camelize } : nil
 
       set_embedded(name, {
         type: :one,
-        class_name: klass_name, # keep as string to delay resolution
+        class_name: klass_name,
         key: storage_key,
         name: name,
         instance_var: instance_var,
@@ -28,109 +26,116 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
       validates_embedded(name) if validate
 
       if is_polymorphic
-        # Polymorphic reader
-        define_method(name) do
-          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
-
-          raw = read_attribute(storage_key)
-          return instance_variable_set(instance_var, nil) unless raw.present?
-
-          type = raw['type'] || raw[:type]
-          return instance_variable_set(instance_var, nil) unless type.present?
-
-          klass = type.constantize
-          # Remove type from attributes before creating object
-          attrs = raw.dup
-          attrs.delete('type')
-          attrs.delete(:type)
-          obj = klass.new(attrs)
-          obj.embedded = true
-          instance_variable_set(instance_var, obj)
-        end
+        define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
+        define_polymorphic_embeds_one_writer(name, storage_key, instance_var, allowed_types)
+      else
+        define_standard_embeds_one_reader(name, storage_key, instance_var, klass_name)
+        define_standard_embeds_one_writer(name, storage_key, instance_var, klass_name)
+      end
+
+      define_method(:"#{name}_reset") do
+        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+      end
+    end
+
+    private
+
+    def define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+        raw = read_attribute(storage_key)
+        return instance_variable_set(instance_var, nil) unless raw.present?
 
-        # Polymorphic writer
-        define_method("#{name}=") do |val|
-          if val.nil?
-            write_attribute(storage_key, nil)
-            instance_variable_set(instance_var, nil)
-            next
-          end
-
-          if val.is_a?(Hash)
-            # Extract type from hash
-            type_name = val[:type] || val['type']
-            raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.") unless type_name.present?
-
-            klass = type_name.to_s.camelize.constantize
-            # Remove type from attributes before creating object
-            attrs = val.dup
-            attrs.delete(:type)
-            attrs.delete('type')
-            obj = klass.new(attrs)
-          else
-            obj = val
-          end
-
-          # Validate against allowed types if specified
-          if allowed_types.present? && !allowed_types.include?(obj.class.name)
-            raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
-          end
-
-          obj.embedded = true
-
-          raw = obj.serialized_attributes
-          raw.delete('id') if raw['id'].blank?
-          # Store type inside the object
-          raw['type'] = obj.class.name
-
-          write_attribute(storage_key, raw)
-          instance_variable_set(instance_var, obj)
+        type = raw['type'] || raw[:type]
+        return instance_variable_set(instance_var, nil) unless type.present?
+
+        klass = type.constantize
+        attrs = raw.dup
+        attrs.delete('type')
+        attrs.delete(:type)
+        obj = klass.new(attrs)
+        obj.embedded = true
+        instance_variable_set(instance_var, obj)
+      end
+    end
+
+    def define_polymorphic_embeds_one_writer(name, storage_key, instance_var, allowed_types)
+      define_method("#{name}=") do |val|
+        if val.nil?
+          write_attribute(storage_key, nil)
+          instance_variable_set(instance_var, nil)
+          return
         end
-      else
-        # Helper to lazy-resolve class when needed
-        define_method("_resolve_embedded_class_for_#{name}") do
-          @__resolved_classes ||= {}
-          @__resolved_classes[name] ||= begin
-            klass_name.constantize
-          rescue NameError => e
-            warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
-            raise
-          end
+
+        obj = if val.is_a?(Hash)
+                type_name = val[:type] || val['type']
+                raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.") unless type_name.present?
+
+                klass = type_name.to_s.camelize.constantize
+                attrs = val.dup
+                attrs.delete(:type)
+                attrs.delete('type')
+                klass.new(attrs)
+              else
+                val
+              end
+
+        if allowed_types.present? && !allowed_types.include?(obj.class.name)
+          raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
         end
 
-        define_method(name) do
-          return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+        obj.embedded = true
+        raw = obj.serialized_attributes
+        raw.delete('id') if raw['id'].blank?
+        raw['type'] = obj.class.name
 
-          raw = read_attribute(storage_key)
-          return instance_variable_set(instance_var, nil) unless raw.present?
+        write_attribute(storage_key, raw)
+        instance_variable_set(instance_var, obj)
+      end
+    end
 
-          klass = send("_resolve_embedded_class_for_#{name}")
-          obj = klass.new(raw)
-          obj.embedded = true
-          instance_variable_set(instance_var, obj)
+    def define_standard_embeds_one_reader(name, storage_key, instance_var, klass_name)
+      define_method("_resolve_embedded_class_for_#{name}") do
+        @__resolved_classes ||= {}
+        @__resolved_classes[name] ||= begin
+          klass_name.constantize
+        rescue NameError => e
+          warn "WARNING: #{klass_name} could not be resolved in #{self.class.name}: #{e.message}"
+          raise
         end
+      end
 
-        define_method("#{name}=") do |val|
-          if val.nil?
-            write_attribute(storage_key, nil)
-            instance_variable_set(instance_var, nil)
-            next
-          end
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
 
-          klass = send("_resolve_embedded_class_for_#{name}")
-          obj = val.is_a?(klass) ? val : klass.new(val)
-          obj.embedded = true
+        raw = read_attribute(storage_key)
+        return instance_variable_set(instance_var, nil) unless raw.present?
 
-          raw = obj.serialized_attributes
-          raw.delete('id') if raw['id'].blank?
+        klass = send("_resolve_embedded_class_for_#{name}")
+        obj = klass.new(raw)
+        obj.embedded = true
+        instance_variable_set(instance_var, obj)
+      end
+    end
 
-          write_attribute(storage_key, raw)
-          instance_variable_set(instance_var, obj)
+    def define_standard_embeds_one_writer(name, storage_key, instance_var, _klass_name)
+      define_method("#{name}=") do |val|
+        if val.nil?
+          write_attribute(storage_key, nil)
+          instance_variable_set(instance_var, nil)
+          return
         end
-      end
 
-      define_method(:"#{name}_reset") do
-        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+        klass = send("_resolve_embedded_class_for_#{name}")
+        obj = val.is_a?(klass) ? val : klass.new(val)
+        obj.embedded = true
+
+        raw = obj.serialized_attributes
+        raw.delete('id') if raw['id'].blank?
+
+        write_attribute(storage_key, raw)
+        instance_variable_set(instance_var, obj)
       end
     end
   end

From 60b1141efac608474b6a5b891fadb84cb7dd4e7f Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Thu, 5 Feb 2026 13:15:40 +0000
Subject: [PATCH 08/10] move safe polymorphic to validator

---
 lib/couchbase-orm.rb                          |  1 +
 lib/couchbase-orm/utilities/embeds_many.rb    |  5 +-
 lib/couchbase-orm/utilities/embeds_one.rb     |  5 +-
 .../validators/polymorphic_type_validator.rb  | 32 ++++++++
 spec/embeds_many_spec.rb                      | 73 +++++++++++++++++++
 spec/embeds_one_spec.rb                       | 13 ++--
 6 files changed, 115 insertions(+), 14 deletions(-)
 create mode 100644 lib/couchbase-orm/validators/polymorphic_type_validator.rb

diff --git a/lib/couchbase-orm.rb b/lib/couchbase-orm.rb
index 71d0fd12..310bfc79 100644
--- a/lib/couchbase-orm.rb
+++ b/lib/couchbase-orm.rb
@@ -22,6 +22,7 @@ module CouchbaseOrm
   autoload :EmbedsOne, 'couchbase-orm/utilities/embeds_one'
   autoload :EmbedsMany, 'couchbase-orm/utilities/embeds_many'
   autoload :EmbeddedAssociatedValidator, 'couchbase-orm/validators/embedded_associated_validator'
+  autoload :PolymorphicTypeValidator, 'couchbase-orm/validators/polymorphic_type_validator'
 
   # if COUCHBASE_ORM_DEBUG environement variable exist then logger is set to Logger::DEBUG level
   # else logger is set to Logger::INFO level
diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index cb81516c..4abf04ad 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -24,6 +24,7 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
       })
 
       validates_embedded(name) if validate
+      validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
 
       if is_polymorphic
         define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
@@ -85,10 +86,6 @@ def define_polymorphic_embeds_many_writer(name, storage_key, instance_var, allow
                   v
                 end
 
-          if allowed_types.present? && !allowed_types.include?(obj.class.name)
-            raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
-          end
-
           obj.embedded = true
           raw = obj.serialized_attributes
           raw.delete('id') if raw['id'].blank?
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index 9cd0f80b..575c430a 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -24,6 +24,7 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
       })
 
       validates_embedded(name) if validate
+      validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
 
       if is_polymorphic
         define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
@@ -81,10 +82,6 @@ def define_polymorphic_embeds_one_writer(name, storage_key, instance_var, allowe
                 val
               end
 
-        if allowed_types.present? && !allowed_types.include?(obj.class.name)
-          raise ArgumentError.new("#{obj.class.name} is not an allowed type for #{name}. Allowed types: #{allowed_types.join(', ')}")
-        end
-
         obj.embedded = true
         raw = obj.serialized_attributes
         raw.delete('id') if raw['id'].blank?
diff --git a/lib/couchbase-orm/validators/polymorphic_type_validator.rb b/lib/couchbase-orm/validators/polymorphic_type_validator.rb
new file mode 100644
index 00000000..521b76d5
--- /dev/null
+++ b/lib/couchbase-orm/validators/polymorphic_type_validator.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CouchbaseOrm
+  class PolymorphicTypeValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      allowed_types = options[:allowed_types]
+      return if allowed_types.blank?
+      return if value.nil?
+
+      # Handle array of embedded objects
+      if value.is_a?(Array)
+        value.each_with_index do |obj, i|
+          next if obj.nil?
+          next if allowed_types.include?(obj.class.name)
+
+          record.errors.add(
+            attribute,
+            "item ##{i} (#{obj.class.name}) is not an allowed type. Allowed types: #{allowed_types.join(', ')}"
+          )
+        end
+      else
+        # Handle single embedded object
+        return if allowed_types.include?(value.class.name)
+
+        record.errors.add(
+          attribute,
+          "#{value.class.name} is not an allowed type. Allowed types: #{allowed_types.join(', ')}"
+        )
+      end
+    end
+  end
+end
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index d152fb36..7fc13591 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -675,4 +675,77 @@ class RestrictedArticle < CouchbaseOrm::Base
       expect(article.attachments[1]).to be_a(VideoAttachment)
     end
   end
+
+  describe 'polymorphic embeds_many with types restriction' do
+    it 'accepts allowed types with objects' do
+      image = ImageAttachment.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      video = VideoAttachment.new(url: 'https://example.com/allowed.mp4', duration: 60)
+      article = RestrictedArticle.new(attachments: [image, video])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/allowed.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].url).to eq('https://example.com/allowed.mp4')
+    end
+
+    it 'accepts allowed types with hashes' do
+      article = RestrictedArticle.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/hash.jpg', caption: 'Hash' },
+          { type: 'video_attachment', url: 'https://example.com/hash.mp4', duration: 90 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/hash.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].duration).to eq(90)
+    end
+
+    it 'rejects disallowed types with objects' do
+      audio = AudioAttachment.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      article = RestrictedArticle.new(attachments: [audio])
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #0 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'rejects disallowed types with hashes' do
+      article = RestrictedArticle.new(
+        attachments: [{ type: 'audio_attachment', url: 'https://example.com/denied.mp3', bitrate: 128 }]
+      )
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #0 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'rejects disallowed types mixed with allowed types' do
+      image = ImageAttachment.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      audio = AudioAttachment.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      article = RestrictedArticle.new(attachments: [image, audio])
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #1 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'persists and retrieves with type restrictions' do
+      article = RestrictedArticle.create!(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/restricted.jpg', caption: 'Restricted' },
+          { type: 'video_attachment', url: 'https://example.com/restricted.mp4', duration: 120 }
+        ]
+      )
+
+      loaded = RestrictedArticle.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments[0]).to be_a(ImageAttachment)
+      expect(loaded.attachments[0].url).to eq('https://example.com/restricted.jpg')
+      expect(loaded.attachments[1]).to be_a(VideoAttachment)
+      expect(loaded.attachments[1].duration).to eq(120)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+  end
 end
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index 31038e2e..04595767 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -544,16 +544,17 @@ class RestrictedPost < CouchbaseOrm::Base
 
     it 'rejects disallowed types with objects' do
       audio = Audio.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      post = RestrictedPost.new(media: audio)
 
-      expect {
-        RestrictedPost.new(media: audio)
-      }.to raise_error(ArgumentError, 'Audio is not an allowed type for media. Allowed types: Image, Video')
+      expect(post).not_to be_valid
+      expect(post.errors[:media]).to include('Audio is not an allowed type. Allowed types: Image, Video')
     end
 
     it 'rejects disallowed types with hashes' do
-      expect {
-        RestrictedPost.new(media: { type: 'audio', url: 'https://example.com/denied.mp3', bitrate: 128 })
-      }.to raise_error(ArgumentError, 'Audio is not an allowed type for media. Allowed types: Image, Video')
+      post = RestrictedPost.new(media: { type: 'audio', url: 'https://example.com/denied.mp3', bitrate: 128 })
+
+      expect(post).not_to be_valid
+      expect(post.errors[:media]).to include('Audio is not an allowed type. Allowed types: Image, Video')
     end
 
     it 'persists and retrieves with type restrictions' do

From df79afe26d4522398f67ccab2092b211118de735 Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Thu, 5 Feb 2026 14:22:04 +0100
Subject: [PATCH 09/10] update docs

---
 docs/reference/associations.txt | 39 +++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/docs/reference/associations.txt b/docs/reference/associations.txt
index b9c8aeba..9aedbeed 100644
--- a/docs/reference/associations.txt
+++ b/docs/reference/associations.txt
@@ -206,10 +206,15 @@ passing an array of allowed class names to the ``polymorphic`` parameter:
 
   # This works
   post = Post.new(media: Image.new(url: 'photo.jpg'))
+  post.valid?
+  # => true
 
-  # This raises an error
+  # This raises a validation error
   post = Post.new(media: Audio.new(url: 'song.mp3'))
-  # => ArgumentError: Audio is not an allowed type for media. Allowed types: Image, Video
+  post.valid?
+  # => false
+  post.errors[:media]
+  # => ["Audio is not an allowed type. Allowed types: Image, Video"]
 
 You can use snake_case names in the array, which will be automatically
 converted to CamelCase class names:
@@ -220,6 +225,36 @@ converted to CamelCase class names:
     embeds_one :media, polymorphic: [:image, 'video']  # Same as ['Image', 'Video']
   end
 
+**Polymorphic Type Validator**: When type restrictions are specified, CouchbaseOrm
+automatically adds a ``PolymorphicTypeValidator`` to ensure that only allowed types
+can be assigned to the association. The validator:
+
+- Validates both single objects (``embeds_one``) and arrays (``embeds_many``)
+- Provides clear error messages listing the allowed types
+- Skips validation when no type restrictions are set or the value is nil
+- Runs during normal model validation (``valid?``, ``save``, ``create``, etc.)
+
+For ``embeds_many`` associations with type restrictions, each item in the array
+is validated individually:
+
+.. code-block:: ruby
+
+  class Article < CouchbaseOrm::Base
+    embeds_many :attachments, polymorphic: ['Image', 'Video']
+  end
+
+  article = Article.new(
+    attachments: [
+      Image.new(url: 'photo.jpg'),
+      Audio.new(url: 'song.mp3')  # Not allowed!
+    ]
+  )
+  
+  article.valid?
+  # => false
+  article.errors[:attachments]
+  # => ["item #1 (Audio) is not an allowed type. Allowed types: Image, Video"]
+
 Custom Storage Keys
 -------------------
 

From 878bda22c96b926ca22d68b802c01c814cb15bfd Mon Sep 17 00:00:00 2001
From: Giallombardo Nathan <nathangiallombardo@melting-point.fr>
Date: Thu, 5 Feb 2026 13:32:23 +0000
Subject: [PATCH 10/10] fix rubocop and respect validate option

---
 lib/couchbase-orm/utilities/embeds_many.rb | 10 ++++++----
 lib/couchbase-orm/utilities/embeds_one.rb  | 10 ++++++----
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index 4abf04ad..f0527aba 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -23,12 +23,14 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphi
         allowed_types: allowed_types,
       })
 
-      validates_embedded(name) if validate
-      validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      if validate
+        validates_embedded(name)
+        validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      end
 
       if is_polymorphic
         define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
-        define_polymorphic_embeds_many_writer(name, storage_key, instance_var, allowed_types)
+        define_polymorphic_embeds_many_writer(name, storage_key, instance_var)
       else
         define_standard_embeds_many_reader(name, storage_key, instance_var, klass_name)
         define_standard_embeds_many_writer(name, storage_key, instance_var, klass_name)
@@ -65,7 +67,7 @@ def define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
       end
     end
 
-    def define_polymorphic_embeds_many_writer(name, storage_key, instance_var, allowed_types)
+    def define_polymorphic_embeds_many_writer(name, storage_key, instance_var)
       define_method("#{name}=") do |val|
         embedded_objects = []
         serialized = []
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index 575c430a..dbf1b3fc 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -23,12 +23,14 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic
         allowed_types: allowed_types,
       })
 
-      validates_embedded(name) if validate
-      validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      if validate
+        validates_embedded(name)
+        validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      end
 
       if is_polymorphic
         define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
-        define_polymorphic_embeds_one_writer(name, storage_key, instance_var, allowed_types)
+        define_polymorphic_embeds_one_writer(name, storage_key, instance_var)
       else
         define_standard_embeds_one_reader(name, storage_key, instance_var, klass_name)
         define_standard_embeds_one_writer(name, storage_key, instance_var, klass_name)
@@ -61,7 +63,7 @@ def define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
       end
     end
 
-    def define_polymorphic_embeds_one_writer(name, storage_key, instance_var, allowed_types)
+    def define_polymorphic_embeds_one_writer(name, storage_key, instance_var)
       define_method("#{name}=") do |val|
         if val.nil?
           write_attribute(storage_key, nil)