active_record_compose 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 491f46737a3744c5c5d3e0319de3ee9f64ae21a9adfab39f36cedc478bfa0e7c
-  data.tar.gz: 406f4c471e0d7c40ec7b3a0d492f8e7e6c96d93fd4b43204a128bf52c1f7ed4c
+  metadata.gz: 810feb87760ff992aa21ca019081e6072ec43c99387ea0ee013f767d4d2c875c
+  data.tar.gz: 7077c4d5b79d12c6c5f5a0297d0d2837c3d3c79a3b8e74a13c12e05a3511c078
 SHA512:
-  metadata.gz: 9ff0e91cfb0ca22322d1b9ca47c32f09372afa206e9fa6690c1dfe5ca30d221269ccc55fe17556627234ea8a7019118ddec8a46ad24a52c47239e694dbcac323
-  data.tar.gz: 925001a566ee81600ce91862c0c95f241dba2cd735f6ecbc3e987e83e6cd6f59d217e67afa4bed0a981f35c16645661ef7eeb00adb18df92999f9127e22116e0
+  metadata.gz: 283b3beaab24fb19d30e134dbe543a25c730bf0d331bdd5114ae89747d0a247b8b572d7e6f2578c06d80f2f7cb4b8c6023f2640518c5b0dc21d335401e45ab5c
+  data.tar.gz: 6f55ebeb0bd4379d206f55b8dc8dc618beca9d281f0d425c0cc8d96078d60ed74fd26c67b92b2bb8c26f9cb6dd4634557ef1064990c4a7ca91bb15e99d6c381e

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [1.2.1] - 2026-03-21
+
+* Improved clarity of error when accessing uninitialized attributes.
+  (https://github.com/hamajyotan/active_record_compose/pull/71)
+* doc: Minor document adjustments, etc.
+
+## [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.

data/README.md

@@ -1,7 +1,7 @@
 # ActiveRecordCompose
 
 ActiveRecordCompose lets you build form objects that combine multiple ActiveRecord models into a single, unified interface.
-More than just a simple form object, it is designed as a **business-oriented composed model** that encapsulates complex operations-such as user registration spanning multiple tables-making them easier to write, validate, and maintain.
+More than a simple form object, ActiveRecordCompose is designed as a **business-oriented composed model** that encapsulates complex operations, such as user registration spanning multiple tables, making them easier to write, validate, and maintain.
 
 [![Gem Version](https://badge.fury.io/rb/active_record_compose.svg)](https://badge.fury.io/rb/active_record_compose)
 ![CI](https://github.com/hamajyotan/active_record_compose/workflows/CI/badge.svg)
@@ -29,15 +29,14 @@ More than just a simple form object, it is designed as a **business-oriented com
 
 ## Motivation
 
-In Rails, `ActiveRecord::Base` is responsible for persisting data to the database.
-By defining validations and callbacks, you can model use cases effectively.
+In Rails, `ActiveRecord::Base` is responsible for persisting data to the database and modeling application behavior through validations and callbacks.
 
 However, when a single model must serve multiple different use cases, you often end up with conditional validations (`on: :context`) or workarounds like `save(validate: false)`.
 This mixes unrelated concerns into one model, leading to unnecessary complexity.
 
-`ActiveModel::Model` helps here — it provides the familiar API (`attribute`, `errors`, validations, callbacks) without persistence, so you can isolate logic per use case.
+`ActiveModel::Model` helps address this by providing a familiar API (`attribute`, `errors`, validations, callbacks) without persistence, allowing you to isolate logic per use case.
 
-**ActiveRecordCompose** builds on `ActiveModel::Model` and is a powerful **business object** that acts as a first-class model within Rails.
+**ActiveRecordCompose** builds on `ActiveModel::Model` and provides a powerful **business object** that acts as a first-class model within Rails.
 - Transparently accesses attributes across multiple models
 - Saves all associated models atomically in a transaction
 - Collects and exposes error information consistently
@@ -106,7 +105,7 @@ class UserRegistration < ActiveRecordCompose::Model
 end
 ```
 
-Usage:
+Example usage:
 
 ```ruby
 # === Standalone script ===
@@ -174,7 +173,7 @@ registration.attributes
 
 ### Unified Error Handling
 
-Validation errors from inner models are collected into the composed model:
+Validation errors from the inner models are collected into the composed object:
 
 ```ruby
 user_registration = UserRegistration.new(
@@ -274,7 +273,7 @@ model.save
 
 ### Notes on adding models dynamically
 
-Avoid adding `models` to the models array **after validation has already run**
+Avoid adding models to the `models` array **after validation has already run**
 (for example, inside `after_validation` or `before_save` callbacks).
 
 ```ruby
@@ -323,5 +322,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the ActiveRecord::Compose project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hamajyotan/active_record_compose/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the ActiveRecordCompose project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hamajyotan/active_record_compose/blob/main/CODE_OF_CONDUCT.md).
 

data/lib/active_record_compose/attributes.rb

@@ -3,6 +3,7 @@
 require_relative "attributes/attribute_predicate"
 require_relative "attributes/delegation"
 require_relative "attributes/querying"
+require_relative "exceptions"
 
 module ActiveRecordCompose
   # Provides attribute-related functionality for use within ActiveRecordCompose::Model.
@@ -127,7 +128,11 @@ module ActiveRecordCompose
     #
     # @see #attributes
     # @return [Array<String>] array of attribute name.
-    def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
+    def attribute_names
+      _require_attributes_initialized do
+        super + delegated_attributes.to_a.map { _1.attribute_name }
+      end
+    end
 
     # Returns a hash with the attribute name as key and the attribute value as value.
     # Attributes declared with {.delegate_attribute} are also merged.
@@ -155,7 +160,24 @@ module ActiveRecordCompose
     #
     # @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) })
+      _require_attributes_initialized do
+        super.merge(*delegated_attributes.to_a.map { _1.attribute_hash(self) })
+      end
+    end
+
+    private
+
+    def _write_attribute(...) = _require_attributes_initialized { super } # steep:ignore
+
+    def attribute(...) = _require_attributes_initialized { super }
+
+    def _require_attributes_initialized
+      unless @attributes
+        raise ActiveRecordCompose::UninitializedAttribute,
+              "No attributes have been set. Is proper initialization performed, such as calling `super` in `initialize`?"
+      end
+
+      yield
     end
   end
 end

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,44 @@
+# 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
+
+  # Occurs when accessing Attributes without initializing it.
+  #
+  # @example
+  #     class Model < ActiveRecordCompose::Model
+  #       def initialize
+  #         # Intentionally not calling super...
+  #       end
+  #
+  #       attribute :foo
+  #     end
+  #     model = Model.new
+  #     model.foo = 1  #=> raises ActiveRecordCompose::UninitializedAttribute
+  #
+  class UninitializedAttribute < StandardError; end
+end

data/lib/active_record_compose/transaction_support.rb

@@ -113,7 +113,7 @@ module ActiveRecordCompose
           ensure_finalize = !connection.transaction_open?
 
           connection.transaction do
-            connection.add_transaction_record(self, ensure_finalize || has_transactional_callbacks?) # steep:ignore
+            connection.add_transaction_record(self, ensure_finalize || has_transactional_callbacks?)
 
             yield.tap { raise ActiveRecord::Rollback unless _1 }
           end || false

data/lib/active_record_compose/validations.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "composed_collection"
+require_relative "exceptions"
 
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
@@ -44,7 +45,7 @@ module ActiveRecordCompose
     #   Returns the `ActiveModel::Errors` object that holds all information about attribute error messages.
     #
     #   The `ActiveModel::Base` implementation itself,
-    #   but also aggregates error information for objects stored in {#models} when validation is performed.
+    #   but also aggregates error information for objects stored in {ActiveRecordCompose::Model#models} when validation is performed.
     #
     #       class Account < ActiveRecord::Base
     #         validates :name, :email, presence: true
@@ -76,10 +77,24 @@ module ActiveRecordCompose
     #
     #   @return [ActiveModel::Errors]
 
+    # @private
+    def detect_circular_reference(targets = [])
+      raise CircularReferenceDetected if targets.include?(object_id)
+
+      targets += [ object_id ]
+      # steep:ignore:start
+      models.select { _1.respond_to?(:detect_circular_reference) }.each do |m|
+        m.detect_circular_reference(targets)
+      end
+      # steep:ignore:end
+    end
+
     private
 
     # @private
     def validate_models
+      detect_circular_reference
+
       context = override_validation_context
       models.__wrapped_models.lazy.select { _1.invalid?(context) }.each { errors.merge!(_1) }
     end

data/lib/active_record_compose/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
-  VERSION = "1.1.1"
+  VERSION = "1.2.1"
 end

data/lib/active_record_compose/wrapped_model.rb

@@ -104,19 +104,28 @@ module ActiveRecordCompose
     # @param [Object] other
     # @return [Boolean]
     def ==(other)
+      return true if equal?(other)
       return false unless self.class == other.class
-      return false unless model == other.model
 
-      true
+      equality_key == other.equality_key
     end
 
+    def eql?(other)
+      return true if equal?(other)
+      return false unless self.class == other.class
+
+      equality_key.eql?(other.equality_key)
+    end
+
+    def hash = equality_key.hash
+
     protected
 
-    attr_reader :model
+    def equality_key = [ model, destroy_context_type, if_option ]
 
     private
 
-    attr_reader :destroy_context_type, :if_option
+    attr_reader :model, :destroy_context_type, :if_option
 
     # @private
     module PackagePrivate

data/lib/active_record_compose.rb

@@ -3,6 +3,7 @@
 require "active_record"
 
 require_relative "active_record_compose/version"
+require_relative "active_record_compose/exceptions"
 require_relative "active_record_compose/model"
 
 # namespaces in gem `active_record_compose`.

data/sig/_internal/package_private.rbs

@@ -11,6 +11,9 @@ module ActiveRecordCompose
 
     @attributes: untyped
 
+    private
+    def _require_attributes_initialized: [T] () { () -> T } -> T
+
     class AttributePredicate
       def initialize: (untyped value) -> void
       def call: -> bool
@@ -64,16 +67,20 @@ module ActiveRecordCompose
   class ComposedCollection
     def initialize: (Model) -> void
 
+    @symbol_proc_map: Hash[Symbol, (destroy_context_type | condition_type)]
+
     private
     attr_reader owner: Model
-    attr_reader models: Array[WrappedModel]
+    attr_reader models: Set[WrappedModel]
     def wrap: (ar_like, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> WrappedModel
+    def symbol_proc_map: () -> Hash[Symbol, (destroy_context_type | condition_type)]
+    def instance_variables_to_inspect: () -> Array[Symbol]
 
     module PackagePrivate
-      def __wrapped_models: () -> Array[WrappedModel]
+      def __wrapped_models: () -> Enumerable[WrappedModel]
 
       private
-      def models: () -> Array[WrappedModel]
+      def models: () -> Set[WrappedModel]
     end
 
     include PackagePrivate
@@ -143,10 +150,6 @@ module ActiveRecordCompose
     def raise_on_save_error_message: -> String
   end
 
-  class Railtie < Rails::Railtie
-    extend Rails::Initializable::ClassMethods
-  end
-
   module Validations : Model
     extend ActiveSupport::Concern
     extend ActiveModel::Validations::ClassMethods
@@ -154,6 +157,7 @@ module ActiveRecordCompose
     def save: (**untyped options) -> bool
     def save!: (**untyped options) -> untyped
     def valid?: (?validation_context context) -> bool
+    def detect_circular_reference: (?Array[Integer])-> untyped
 
     @context_for_override_validation: OverrideValidationContext
 
@@ -187,6 +191,7 @@ module ActiveRecordCompose
     attr_reader model: ar_like
     attr_reader destroy_context_type: (bool | destroy_context_type)
     attr_reader if_option: (nil | condition_type)
+    def equality_key: () -> [ar_like, (bool | destroy_context_type), (nil | condition_type)]
 
     module PackagePrivate
       def __raw_model: () -> ar_like

data/sig/active_record_compose.rbs

@@ -47,6 +47,9 @@ module ActiveRecordCompose
     def delete: (ar_like) -> ComposedCollection?
   end
 
+  class CircularReferenceDetected < StandardError
+  end
+
   class Model
     include ActiveModel::Model
     include ActiveModel::Validations::Callbacks
@@ -68,6 +71,7 @@ module ActiveRecordCompose
     def self.around_update: (*around_callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
     def self.after_update: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
 
+    def self.before_commit: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
     def self.after_commit: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
     def self.after_rollback: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
 
@@ -90,4 +94,11 @@ module ActiveRecordCompose
     private
     def models: -> ComposedCollection
   end
+
+  class Railtie < Rails::Railtie
+    extend Rails::Initializable::ClassMethods
+  end
+
+  class UninitializedAttribute < StandardError
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - hamajyotan
@@ -50,6 +50,7 @@ files:
 - lib/active_record_compose/attributes/querying.rb
 - lib/active_record_compose/callbacks.rb
 - lib/active_record_compose/composed_collection.rb
+- lib/active_record_compose/exceptions.rb
 - lib/active_record_compose/inspectable.rb
 - lib/active_record_compose/model.rb
 - lib/active_record_compose/persistence.rb
@@ -83,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []