active_record_compose 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76bd8c66869f7b24c2938ecb72cf2c3b9f47cdcc34a8e1c87f57329f50880ecd
-  data.tar.gz: f6efc5ec40f5e870064dec9928e56a3ee8a3ca07ea00bd5dcbe86f0855d440ce
+  metadata.gz: 2622aa32a886a2c21fcc7836254285cb92f1ce7745674297c3e7fe46bcbe556a
+  data.tar.gz: 747acd3e97cb78aba78b9d3f2c87ab4d9bd34b0727aaf2a1c94d9520ea9eaa08
 SHA512:
-  metadata.gz: c0361c3c95394e550e8571ea4880545dd8e566e9a6d4c829eb494db90226c009487361ca7eed8e3691d6dbf59674e7fc2fa782b2db006b79113c95c5b229f95c
-  data.tar.gz: 2a2ac6e1d86640c8d7df1448fc362e459790561a8223066351cadd7ea297e456bc093a015fb8a765e755deccbd5071e342fe035180a4c222ce81584305388085
+  metadata.gz: e6002732e8e6fa09269ccb4a7635af4ef683d06af14e829aa062846c6dbb90c2942d5b3cc2b4d715eeef2182498e732d33b5ae004836ff703f8d8235fec12c70
+  data.tar.gz: 18d3f9a635d3f4bf940eeb4020824fa7fc7d91cf27b0a99aa253af53e31fdca6bebd69d402537bea29749de26eba3f5a261e10a3ef2ebf079294e7fc3dbd5127

data/.yardopts

@@ -1,4 +1,6 @@
 --private
+--no-private
 --markup markdown
 --markup-provider redcarpet
+--plugin activesupport-concern
 --default-return void

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [1.2.0] - 2026-01-05
+
+* Avoid issuing multiple saves on the same object.
+  (https://github.com/hamajyotan/active_record_compose/pull/56)
+* The storage of `#models` has been changed from an Array to a Set.
+  This prevents duplicate additions of the same object and option combinations.
+  Also, `#models#delete` now deletes the model regardless of the options used when it was added.
+  (https://github.com/hamajyotan/active_record_compose/pull/57)
+* Adding an `ActiveRecordCompose::Model` to `#models` now throws an error if there is a circular reference.
+  (https://github.com/hamajyotan/active_record_compose/pull/58)
+
+## [1.1.1] - 2025-12-04
+
+* fix: the save method would return nil instead of false.
+* doc: We've simplified the documentation comment yard.
+
 ## [1.1.0] - 2025-11-19
 
 * Implemented ActiveRecord-like #inspect

data/lib/active_record_compose/attributes.rb

@@ -5,8 +5,6 @@ require_relative "attributes/delegation"
 require_relative "attributes/querying"
 
 module ActiveRecordCompose
-  # @private
-  #
   # Provides attribute-related functionality for use within ActiveRecordCompose::Model.
   #
   # This module allows you to define attributes on your composed model, including support
@@ -56,45 +54,32 @@ module ActiveRecordCompose
     include ActiveModel::Attributes
 
     included do
+      # @type self: Class
+
       include Querying
 
-      # @type self: Class
       class_attribute :delegated_attributes, instance_writer: false
     end
 
-    module ClassMethods
-      # Defines the reader and writer for the specified attribute.
-      #
-      # @example
-      #   class AccountRegistration < ActiveRecordCompose::Model
-      #     def initialize(account, attributes = {})
-      #       @account = account
-      #       super(attributes)
-      #       models.push(account)
-      #     end
-      #
-      #     attribute :original_attribute, :string, default: "qux"
-      #     delegate_attribute :name, to: :account
-      #
-      #     private
-      #
-      #     attr_reader :account
-      #   end
-      #
-      #   account = Account.new
-      #   account.name = "foo"
-      #
-      #   registration = AccountRegistration.new(account)
-      #   registration.name         # => "foo" (delegated)
-      #   registration.name?        # => true  (delegated attribute method + `?`)
-      #
-      #   registration.name = "bar" # => updates account.name
-      #   account.name              # => "bar"
-      #   account.name?             # => true
+    # steep:ignore:start
+
+    class_methods do
+      # Provides a method of attribute access to the encapsulated model.
       #
-      #   registration.attributes
-      #   # => { "original_attribute" => "qux", "name" => "bar" }
+      # It provides a way to access the attributes of the model it encompasses,
+      # allowing transparent access as if it had those attributes itself.
       #
+      # @param [Array<Symbol, String>] attributes
+      #   attributes A variable-length list of attribute names to delegate.
+      # @param [Symbol, String] to
+      #   The target object to which attributes are delegated (keyword argument).
+      # @param [Boolean] allow_nil
+      #   allow_nil Whether to allow nil values. Defaults to false.
+      # @example Basic usage
+      #   delegate_attribute :name, :email, to: :profile
+      # @example Allowing nil
+      #   delegate_attribute :bio, to: :profile, allow_nil: true
+      # @see Module#delegate for similar behavior in ActiveSupport
       def delegate_attribute(*attributes, to:, allow_nil: false)
         if to.start_with?("@")
           raise ArgumentError, "Instance variables cannot be specified in delegate to. (#{to})"
@@ -107,45 +92,68 @@ module ActiveRecordCompose
       end
 
       # Returns a array of attribute name.
-      # Attributes declared with `delegate_attribute` are also merged.
+      # Attributes declared with {.delegate_attribute} are also merged.
       #
+      # @see #attribute_names
       # @return [Array<String>] array of attribute name.
       def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
     end
 
+    # steep:ignore:end
+
     # Returns a array of attribute name.
-    # Attributes declared with `delegate_attribute` are also merged.
+    # Attributes declared with {.delegate_attribute} are also merged.
+    #
+    #     class Foo < ActiveRecordCompose::Base
+    #       def initialize(attributes = {})
+    #         @account = Account.new
+    #         super
+    #       end
+    #
+    #       attribute :confirmation, :boolean, default: false   # plain attribute
+    #       delegate_attribute :name, to: :account              # delegated attribute
+    #
+    #       private
+    #
+    #       attr_reader :account
+    #     end
     #
+    #     Foo.attribute_names                                   # Returns the merged state of plain and delegated attributes
+    #     # => ["confirmation" ,"name"]
+    #
+    #     foo = Foo.new
+    #     foo.attribute_names                                   # Similar behavior for instance method version
+    #     # => ["confirmation", "name"]
+    #
+    # @see #attributes
     # @return [Array<String>] array of attribute name.
     def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
 
     # Returns a hash with the attribute name as key and the attribute value as value.
-    # Attributes declared with `delegate_attribute` are also merged.
+    # Attributes declared with {.delegate_attribute} are also merged.
     #
-    # @return [Hash] hash with the attribute name as key and the attribute value as value.
-    # @example
-    #   class AccountRegistration < ActiveRecordCompose::Model
-    #     def initialize(account, attributes = {})
-    #       @account = account
-    #       super(attributes)
-    #       models.push(account)
-    #     end
+    #     class Foo < ActiveRecordCompose::Base
+    #       def initialize(attributes = {})
+    #         @account = Account.new
+    #         super
+    #       end
     #
-    #     attribute :original_attribute, :string, default: "qux"
-    #     delegate_attribute :name, to: :account
+    #       attribute :confirmation, :boolean, default: false   # plain attribute
+    #       delegate_attribute :name, to: :account              # delegated attribute
     #
-    #     private
+    #       private
     #
-    #     attr_reader :account
-    #   end
-    #
-    #   account = Account.new
-    #   account.name = "foo"
+    #       attr_reader :account
+    #     end
     #
-    #   registration = AccountRegistration.new(account)
+    #     foo = Foo.new
+    #     foo.name = "Alice"
+    #     foo.confirmation = true
     #
-    #   registration.attributes # => { "original_attribute" => "qux", "name" => "bar" }
+    #     foo.attributes                                        # Returns the merged state of plain and delegated attributes
+    #     # => { "confirmation" => true, "name" => "Alice" }
     #
+    # @return [Hash<String, Object>] hash with the attribute name as key and the attribute value as value.
     def attributes
       super.merge(*delegated_attributes.to_a.map { _1.attribute_hash(self) })
     end

data/lib/active_record_compose/callbacks.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
-  # @private
-  #
   # Provides hooks into the life cycle of an ActiveRecordCompose model,
   # allowing you to insert custom logic before or after changes to the object's state.
   #
@@ -21,18 +19,48 @@ module ActiveRecordCompose
     include ActiveModel::Validations::Callbacks
 
     included do
+      # @!method self.before_save(*args, &block)
+      #   Registers a callback to be called before a model is saved.
+
+      # @!method self.around_save(*args, &block)
+      #   Registers a callback to be called around the save of a model.
+
+      # @!method self.after_save(*args, &block)
+      #   Registers a callback to be called after a model is saved.
+
       define_model_callbacks :save
+
+      # @!method self.before_create(*args, &block)
+      #   Registers a callback to be called before a model is created.
+
+      # @!method self.around_create(*args, &block)
+      #   Registers a callback to be called around the creation of a model.
+
+      # @!method self.after_create(*args, &block)
+      #   Registers a callback to be called after a model is created.
+
       define_model_callbacks :create
+
+      # @!method self.before_update(*args, &block)
+      #   Registers a callback to be called before a model is updated.
+
+      # @!method self.around_update(*args, &block)
+      #   Registers a callback to be called around the update of a model.
+
+      # @!method self.after_update(*args, &block)
+      #   Registers a callback to be called after a update is updated.
       define_model_callbacks :update
     end
 
     private
 
+    # @private
     # Evaluate while firing callbacks such as `before_save` `after_save`
     # before and after block evaluation.
     #
     def with_callbacks(&block) = run_callbacks(:save) { run_callbacks(callback_context, &block) }
 
+    # @private
     # Returns the symbol representing the callback context, which is `:create` if the record
     # is new, or `:update` if it has been persisted.
     #

data/lib/active_record_compose/composed_collection.rb

@@ -13,7 +13,7 @@ module ActiveRecordCompose
 
     def initialize(owner)
       @owner = owner
-      @models = []
+      @models = Set.new
     end
 
     # Enumerates model objects.
@@ -69,13 +69,28 @@ module ActiveRecordCompose
     # Removes the specified model from the collection.
     # Returns nil if the deletion fails, self if it succeeds.
     #
+    # The specified model instance will be deleted regardless of the options used when it was added.
+    #
+    # @example
+    #   model_a = Model.new
+    #   model_b = Model.new
+    #
+    #   collection.push(model_a, destroy: true)
+    #   collection.push(model_b)
+    #   collection.push(model_a, destroy: false)
+    #   collection.count  #=> 3
+    #
+    #   collection.delete(model_a)
+    #   collection.count  #=> 1
+    #
     # @param model [Object] model instance
     # @return [self] Successful deletion
     # @return [nil] If deletion fails
     def delete(model)
-      wrapped = wrap(model)
-      return nil unless models.delete(wrapped)
+      matched = models.select { _1.__raw_model == model }
+      return nil if matched.blank?
 
+      matched.each { models.delete(_1) }
       self
     end
 
@@ -87,17 +102,27 @@ module ActiveRecordCompose
     # @private
     def wrap(model, destroy: false, if: nil)
       if destroy.is_a?(Symbol)
-        method = destroy
-        destroy = -> { owner.__send__(method) }
+        destroy = symbol_proc_map[destroy]
       end
+
       if_option = binding.local_variable_get(:if)
       if if_option.is_a?(Symbol)
-        method = if_option
-        if_option = -> { owner.__send__(method) }
+        if_option = symbol_proc_map[if_option]
       end
+
       ActiveRecordCompose::WrappedModel.new(model, destroy:, if: if_option)
     end
 
+    # @private
+    def symbol_proc_map
+      @symbol_proc_map ||=
+        Hash.new do |h, k|
+          h[k] = -> { owner.__send__(k) }
+        end
+    end
+
+    def instance_variables_to_inspect = %i[@owner @models]
+
     # @private
     module PackagePrivate
       refine ComposedCollection do
@@ -105,7 +130,9 @@ module ActiveRecordCompose
         #
         # @private
         # @return [Array[WrappedModel]] array of wrapped model instance.
-        def __wrapped_models = models.reject { _1.ignore? }.select { _1.__raw_model }
+        def __wrapped_models
+          models.reject { _1.ignore? }.uniq { [ _1.__raw_model, !!_1.destroy_context? ] }.select { _1.__raw_model }
+        end
       end
     end
   end

data/lib/active_record_compose/exceptions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveRecordCompose
+  # Occurs when a circular reference is detected in the containing model.
+  #
+  # @example
+  #     class Model < ActiveRecordCompose::Model
+  #       def initialize
+  #         super()
+  #         models << self  # Adding itself to models creates a circular reference.
+  #       end
+  #     end
+  #     model = Model.new
+  #     model.save  #=> raises ActiveRecordCompose::CircularReferenceDetected
+  #
+  # @example
+  #     class Model < ActiveRecordCompose::Model
+  #       attribute :model
+  #       before_validation { models << model }
+  #     end
+  #     inner = Model.new
+  #     middle = Model.new(model: inner)
+  #     outer = Model.new(model: middle)
+  #
+  #     inner.model = outer  # There is a circular reference in the form outer > middle > inner > outer.
+  #     outer.save  #=> raises ActiveRecordCompose::CircularReferenceDetected
+  #
+  class CircularReferenceDetected < StandardError; end
+end

data/lib/active_record_compose/inspectable.rb

@@ -4,8 +4,6 @@ require "active_support/parameter_filter"
 require_relative "attributes"
 
 module ActiveRecordCompose
-  # @private
-  #
   # It provides #inspect behavior.
   # It tries to replicate the inspect format provided by ActiveRecord as closely as possible.
   #
@@ -39,26 +37,48 @@ module ActiveRecordCompose
     extend ActiveSupport::Concern
     include ActiveRecordCompose::Attributes
 
+    # steep:ignore:start
+
+    # @private
+    FILTERED_MASK =
+      Class.new(DelegateClass(::String)) do
+        def pretty_print(pp)
+          pp.text __getobj__
+        end
+      end.new(ActiveSupport::ParameterFilter::FILTERED).freeze
+    private_constant :FILTERED_MASK
+
+    # steep:ignore:end
+
     included do
       self.filter_attributes = []
     end
 
-    module ClassMethods
+    # steep:ignore:start
+
+    class_methods do
+      # Returns columns not to expose when invoking {#inspect}.
+      #
+      # @return [Array<Symbol>]
+      # @see #inspect
       def filter_attributes
         if @filter_attributes.nil?
-          superclass.filter_attributes # steep:ignore
+          superclass.filter_attributes
         else
           @filter_attributes
         end
       end
 
+      # Specify columns not to expose when invoking {#inspect}.
+      #
+      # @param [Array<Symbol>] value
+      # @see #inspect
       def filter_attributes=(value)
         @inspection_filter = nil
         @filter_attributes = value
       end
 
-      # steep:ignore:start
-
+      # @private
       def inspection_filter
         if @filter_attributes.nil?
           superclass.inspection_filter
@@ -77,20 +97,41 @@ module ActiveRecordCompose
           @filter_attributes ||= nil
         end
       end
-
-      FILTERED_MASK =
-        Class.new(DelegateClass(::String)) do
-          def pretty_print(pp)
-            pp.text __getobj__
-          end
-        end.new(ActiveSupport::ParameterFilter::FILTERED).freeze
-      private_constant :FILTERED_MASK
-
-      # steep:ignore:end
     end
 
+    # steep:ignore:end
+
     # Returns a formatted string representation of the record's attributes.
+    # It tries to replicate the inspect format provided by ActiveRecord as closely as possible.
+    #
+    # @example
+    #   class Model < ActiveRecordCompose::Model
+    #     def initialize(ar_model)
+    #       @ar_model = ar_model
+    #       super
+    #     end
+    #
+    #     attribute :foo, :date, default: -> { Date.today }
+    #     delegate_attribute :bar, to: :ar_model
+    #
+    #     private attr_reader :ar_model
+    #   end
+    #
+    #   m = Model.new(ar_model)
+    #   m.inspect  #=> #<Model:0x00007ff0fe75fe58 foo: "2025-11-14", bar: "bar">
+    #
+    # @example use {.filter_attributes}
+    #   class Model < ActiveRecordCompose::Model
+    #     self.filter_attributes += %i[foo]
+    #
+    #     # ...
+    #   end
+    #
+    #   m = Model.new(ar_model)
+    #   m.inspect  #=> #<Model:0x00007ff0fe75fe58 foo: [FILTERED], bar: "bar">
     #
+    # @return [String] formatted string representation of the record's attributes.
+    # @see .filter_attributes
     def inspect
       inspection =
         if @attributes
@@ -126,6 +167,7 @@ module ActiveRecordCompose
 
     private
 
+    # @private
     def format_for_inspect(name, value)
       return value.inspect if value.nil?