active_record_compose 0.11.2 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e0428468971c6a369fd86cfae9b5413acddf18a252a1f502498e11a55e23b92
-  data.tar.gz: fea23f0f94a09d84b462e27af4feb01c1e40f0c8ff4ba306a9dd391f89eeb9f7
+  metadata.gz: 154ee35310ede836e5d89ecd703efadbbc2b7fba0a6229797e9b38b5288eba47
+  data.tar.gz: 42c565c5093680ae089bac356541561dc83ff73759941f268af22365338126db
 SHA512:
-  metadata.gz: f293d9167fe2a1f879df2f3936e784a2f6f33b1df20160606a5ef65a23f2e4a81040ada14ed7d42aa1ed289899db278880945f75d8a792f369a02f5301e31a5f
-  data.tar.gz: b7db34b71359f1f7d90bb6bbb25b5139595742b202c29b8f009e506dd2244a485f80151fd74edf5245aca224ef6a58bf9c507ade5b95bc69b84963bf3203f9a9
+  metadata.gz: a5a9f0a46534ea0dbb3423275a68b521543c67074d8fcd7c637d46f86fcc42f93ac6792b2d80f83b6a0aae367f6dd461e6fb4d0e06730f40da3aefd0751393e9
+  data.tar.gz: c5bb3aaae6e84b23bc264ce5a1ad7b369f248c1fb1f1494b2753a1a82681ecc3df8c5f10a6b68854cda319c65da59e69435dd1c4381f44ff585d81a2400b5bac

data/.yardopts

@@ -0,0 +1,4 @@
+--private
+--markup markdown
+--markup-provider redcarpet
+--default-return void

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.11.3] - 2025-07-13
+
+- refactor: Aggregation attribute module.
+  (https://github.com/hamajyotan/active_record_compose/pull/24)
+- Warn against specifying instance variables, etc. directly in the `:to` option of `delegate_attribute`.
+  - Deprecated:
+    ```ruby
+    delegate_attribute :foo, to: :@model
+    ```
+  - Recommended:
+    ```ruby
+    delegate_attribute :foo, to: :model
+    private
+    attr_reader :model
+    ```
+- doc: Expansion of yard documentation comments.
+
 ## [0.11.2] - 2025-06-29
 
 - `ActiveModel::Attributes.attribute_names` now takes into account attributes declared in `.delegate_attribute`

data/README.md

@@ -381,20 +381,20 @@ end
 ```ruby
 r = Registration.new(name: 'foo', email: 'example@example.com', accept: false)
 r.valid?
-=> true
+#=> true
 
 r.valid?(:education)
-=> false
+#=> false
 r.errors.map { [_1.attribute, _1.type] }
-=> [[:email, :invalid], [:accept, :blank]]
+#=> [[:email, :invalid], [:accept, :blank]]
 
 r.email = 'example@example.edu'
 r.accept = true
 
 r.valid?(:education)
-=> true
+#=> true
 r.save(context: :education)
-=> true
+#=> true
 ```
 
 ## Sample application as an example
@@ -405,6 +405,7 @@ With Github Codespaces, it can also be run directly in the browser. Naturally, a
 
 ## Links
 
+- [Document from YARD](https://hamajyotan.github.io/active_record_compose/)
 - [Smart way to update multiple models simultaneously in Rails](https://dev.to/hamajyotan/smart-way-to-update-multiple-models-simultaneously-in-rails-51b6)
 
 ## Development

data/lib/active_record_compose/attributes/delegation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveRecordCompose
+  module Attributes
+    # @private
+    class Delegation
+      # @return [Symbol] The attribute name as symbol
+      attr_reader :attribute
+
+      def initialize(attribute:, to:, allow_nil: false)
+        @attribute = attribute.to_sym
+        @to = to.to_sym
+        @allow_nil = !!allow_nil
+
+        freeze
+      end
+
+      def define_delegated_attribute(klass)
+        klass.delegate(reader, writer, to:, allow_nil:)
+        klass.define_attribute_methods(attribute)
+      end
+
+      # @return [String] The attribute name as string
+      def attribute_name = attribute.to_s
+
+      # @return [Hash<String, Object>]
+      def attribute_hash(model)
+        { attribute_name => model.public_send(attribute) }
+      end
+
+      private
+
+      attr_reader :to, :allow_nil
+
+      def reader = attribute.to_s
+
+      def writer = "#{attribute}="
+    end
+  end
+end

data/lib/active_record_compose/attributes/querying.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ActiveRecordCompose
+  module Attributes
+    # @private
+    # This provides predicate methods based on the attributes.
+    #
+    # @example
+    #   class AccountRegistration < ActiveRecordCompose::Model
+    #     def initialize
+    #       @account = Account.new
+    #       super()
+    #       models << account
+    #     end
+    #
+    #     attribute :original_attr
+    #     delegate_attribute :name, :email, to: :account
+    #
+    #     private
+    #
+    #     attr_reader :account
+    #   end
+    #
+    #   model = AccountRegistration.new
+    #
+    #   model.name                    #=> nil
+    #   model.name?                   #=> false
+    #   model.name = "Alice"
+    #   model.name?                   #=> true
+    #
+    #   model.original_attr = "Bob"
+    #   model.original_attr?          #=> true
+    #   model.original_attr = ""
+    #   model.original_attr?          #=> false
+    #
+    #   # If the value is numeric, it returns the result of checking whether it is zero or not.
+    #   # This behavior is consistent with `ActiveRecord::AttributeMethods::Query`.
+    #   model.original_attr = 123
+    #   model.original_attr?          #=> true
+    #   model.original_attr = 0
+    #   model.original_attr?          #=> false
+    #
+    module Querying
+      extend ActiveSupport::Concern
+      include ActiveModel::AttributeMethods
+
+      included do
+        attribute_method_suffix "?", parameters: false
+      end
+
+      private
+
+      def attribute?(attr_name)
+        value = public_send(attr_name)
+
+        case value
+        when true then true
+        when false, nil then false
+        else
+          if value.respond_to?(:zero?)
+            !value.zero?
+          else
+            value.present?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record_compose/attributes.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+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
+  # for query methods (e.g., `#attribute?`) and delegation of attributes to underlying
+  # ActiveRecord instances via macros.
+  #
+  # For example, `.delegate_attribute` defines attribute accessors that delegate to
+  # a specific model, similar to:
+  #
+  #     delegate :name, :name=, to: :account
+  #
+  # Additionally, delegated attributes are included in the composed model's `#attributes`
+  # hash.
+  #
+  # @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
+  #
+  #   registration.attributes
+  #   # => { "original_attribute" => "qux", "name" => "bar" }
+  #
+  module Attributes
+    extend ActiveSupport::Concern
+    include ActiveModel::Attributes
+
+    included do
+      include Querying
+
+      # @type self: Class
+      class_attribute :delegated_attributes, instance_writer: false
+    end
+
+    module ClassMethods
+      ALLOW_NIL_DEFAULT = Object.new.freeze # steep:ignore
+      private_constant :ALLOW_NIL_DEFAULT
+
+      # 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
+      #
+      #   registration.attributes
+      #   # => { "original_attribute" => "qux", "name" => "bar" }
+      #
+      def delegate_attribute(*attributes, to:, allow_nil: ALLOW_NIL_DEFAULT) # steep:ignore
+        # steep:ignore:start
+        if to.start_with?("@")
+          suggested_reader_name = to.to_s.sub(/^@+/, "")
+          suggested_method =
+            if to.start_with?("@@")
+              "def #{suggested_reader_name} = #{to}"
+            else
+              "attr_reader :#{suggested_reader_name}"
+            end
+
+          message = <<~MSG
+            Direct use of instance or class variables in `to:` will be removed in the next minor version.
+            Please define a reader method (private is fine) and refer to it by name instead.
+
+            For example,
+                delegate_attribute #{attributes.map { ":#{_1}" }.join(", ")}, to: :#{to}#{", allow_nil: #{allow_nil}" if allow_nil != ALLOW_NIL_DEFAULT}
+
+            Instead of the above, use the following
+                delegate_attribute #{attributes.map { ":#{_1}" }.join(", ")}, to: :#{suggested_reader_name}#{", allow_nil: #{allow_nil}" if allow_nil != ALLOW_NIL_DEFAULT}
+                private
+                #{suggested_method}
+
+          MSG
+          (ActiveRecord.respond_to?(:deprecator) ? ActiveRecord.deprecator : ActiveSupport::Deprecation).warn(message)
+        end
+        allow_nil = false if allow_nil == ALLOW_NIL_DEFAULT
+        # steep:ignore:end
+
+        delegations = attributes.map { Delegation.new(attribute: _1, to:, allow_nil:) }
+        delegations.each { _1.define_delegated_attribute(self) }
+
+        self.delegated_attributes = (delegated_attributes.to_a + delegations).reverse.uniq { _1.attribute }.reverse
+      end
+
+      # Returns a array of attribute name.
+      # Attributes declared with `delegate_attribute` are also merged.
+      #
+      # @return [Array<String>] array of attribute name.
+      def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
+    end
+
+    # Returns a array of attribute name.
+    # Attributes declared with `delegate_attribute` are also merged.
+    #
+    # @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.
+    #
+    # @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
+    #
+    #     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.attributes # => { "original_attribute" => "qux", "name" => "bar" }
+    #
+    def attributes
+      super.merge(*delegated_attributes.to_a.map { _1.attribute_hash(self) })
+    end
+  end
+end

data/lib/active_record_compose/callbacks.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
+require_relative "validations"
+
 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.
+  #
+  # The callback flow generally follows the same structure as Active Record:
+  #
+  # * `before_validation`
+  # * `after_validation`
+  # * `before_save`
+  # * `before_create` (or `before_update` for update operations)
+  # * `after_create` (or `after_update` for update operations)
+  # * `after_save`
+  # * `after_commit` (or `after_rollback` when the transaction is rolled back)
+  #
   module Callbacks
     extend ActiveSupport::Concern
     include ActiveModel::Validations::Callbacks
 
     included do
+      include ActiveRecordCompose::Validations
+
       define_model_callbacks :save
       define_model_callbacks :create
       define_model_callbacks :update
@@ -13,8 +32,15 @@ module ActiveRecordCompose
 
     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) }
 
+    # Returns the symbol representing the callback context, which is `:create` if the record
+    # is new, or `:update` if it has been persisted.
+    #
+    # @return [:create, :update] either `:create` if not persisted, or `:update` if persisted
     def callback_context = persisted? ? :update : :create
   end
 end

data/lib/active_record_compose/composed_collection.rb

@@ -5,6 +5,9 @@ require_relative "wrapped_model"
 module ActiveRecordCompose
   using WrappedModel::PackagePrivate
 
+  # Object obtained by {ActiveRecordCompose::Model#models}.
+  #
+  # It functions as a collection that contains the object to be saved.
   class ComposedCollection
     include Enumerable
 
@@ -15,7 +18,7 @@ module ActiveRecordCompose
 
     # Enumerates model objects.
     #
-    # @yieldparam [Object] the model instance
+    # @yieldparam [Object] model model instance
     # @return [Enumerator] when not block given.
     # @return [self] when block given, returns itself.
     def each
@@ -27,7 +30,7 @@ module ActiveRecordCompose
 
     # Appends model to collection.
     #
-    # @param model [Object] the model instance
+    # @param model [Object] model instance
     # @return [self] returns itself.
     def <<(model)
       models << wrap(model, destroy: false)
@@ -36,12 +39,14 @@ module ActiveRecordCompose
 
     # Appends model to collection.
     #
-    # @param model [Object] the model instance
-    # @param destroy [Boolean] given true, destroy model.
-    # @param destroy [Proc] when proc returning true, destroy model.
-    # @param destroy [Symbol] applies boolean value of result of sending a message to `owner` to evaluation.
-    # @param if [Proc] evaluation result is false, it will not be included in the renewal.
-    # @param if [Symbol] applies boolean value of result of sending a message to `owner` to evaluation.
+    # @param model [Object] model instance
+    # @param destroy [Boolean, Proc, Symbol] Controls whether the model should be destroyed.
+    #   - Boolean: if `true`, the model will be destroyed.
+    #   - Proc: the model will be destroyed if the proc returns `true`.
+    #   - Symbol: sends the symbol as a method to `owner`; if the result is truthy, the model will be destroyed.
+    # @param if [Proc, Symbol] Controls conditional inclusion in renewal.
+    #   - Proc: the proc is called, and if it returns `false`, the model is excluded.
+    #   - Symbol: sends the symbol as a method to `owner`; if the result is falsy, the model is excluded.
     # @return [self] returns itself.
     def push(model, destroy: false, if: nil)
       models << wrap(model, destroy:, if:)
@@ -64,7 +69,7 @@ module ActiveRecordCompose
     # Removes the specified model from the collection.
     # Returns nil if the deletion fails, self if it succeeds.
     #
-    # @param model [Object] the model instance
+    # @param model [Object] model instance
     # @return [self] Successful deletion
     # @return [nil] If deletion fails
     def delete(model)
@@ -76,8 +81,10 @@ module ActiveRecordCompose
 
     private
 
+    # @private
     attr_reader :owner, :models
 
+    # @private
     def wrap(model, destroy: false, if: nil)
       if destroy.is_a?(Symbol)
         method = destroy

data/lib/active_record_compose/model.rb

@@ -1,39 +1,375 @@
 # frozen_string_literal: true
 
+require_relative "attributes"
 require_relative "callbacks"
-require_relative "attribute_querying"
 require_relative "composed_collection"
-require_relative "delegate_attribute"
-require_relative "transaction_support"
 require_relative "persistence"
-require_relative "validations"
 
 module ActiveRecordCompose
+  # This is the core class of {ActiveRecordCompose}.
+  #
+  # By defining subclasses of this model, you can use ActiveRecordCompose functionality in your application.
+  # It has the basic functionality of `ActiveModel::Model` and `ActiveModel::Attributes`,
+  # and also provides aggregation of multiple models and atomic updates through transaction control.
+  # @example Example of model registration.
+  #     class AccountRegistration < ActiveRecordCompose::Model
+  #       def initialize(account = Account.new, attributes = {})
+  #         @account = account
+  #         @profile = @account.build_profile
+  #         models << account << profile
+  #         super(attributes)
+  #       end
+  #
+  #       attribute :register_confirmation, :boolean, default: false
+  #       delegate_attribute :name, :email, to: :account
+  #       delegate_attribute :firstname, :lastname, :age, to: :profile
+  #
+  #       validates :register_confirmation, presence: true
+  #
+  #       private
+  #
+  #       attr_reader :account, :profile
+  #     end
+  # @example Multiple model update once.
+  #     registration = AccountRegistration.new
+  #     registration.assign_attributes(
+  #       name: "alice-in-wonderland",
+  #       email: "alice@example.com",
+  #       firstname: "Alice",
+  #       lastname: "Smith",
+  #       age: 24,
+  #       register_confirmation: true
+  #     )
+  #
+  #     registration.save!      # Register Account and Profile models at the same time.
+  #     Account.count           # => (0 ->) 1
+  #     Profile.count           # => (0 ->) 1
+  # @example Attribute delegation.
+  #     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
+  #
+  #     registration.attributes   # => { "original_attribute" => "qux", "name" => "bar" }
+  # @example Aggregate errors on invalid.
+  #     registration = AccountRegistration.new
+  #
+  #     registration.name = "alice-in-wonderland"
+  #     registration.firstname = "Alice"
+  #     registration.age = 18
+  #
+  #     registration.valid?
+  #     #=> false
+  #
+  #     # The error contents of the objects stored in models are aggregated.
+  #     # For example, direct access to errors in Account#email.
+  #     registration.errors[:email].to_a  # Account#email
+  #     #=> ["can't be blank"]
+  #
+  #     # Of course, the validation defined for itself is also working.
+  #     registration.errors[:register_confirmation].to_a
+  #     #=> ["can't be blank"]
+  #
+  #     registration.errors.to_a
+  #     #=> ["Email can't be blank", "Lastname can't be blank", "Register confirmation can't be blank"]
   class Model
     include ActiveModel::Model
-    include ActiveModel::Attributes
 
-    include ActiveRecordCompose::AttributeQuerying
-    include ActiveRecordCompose::Callbacks
-    include ActiveRecordCompose::DelegateAttribute
+    include ActiveRecordCompose::Attributes
     include ActiveRecordCompose::Persistence
-    include ActiveRecordCompose::Validations
+    include ActiveRecordCompose::Callbacks
+
+    begin
+      # @group Model Core
+
+      # @!method self.delegate_attribute(*attributes, to:, allow_nil: false)
+      #   Provides a method of attribute access to the encapsulated model.
+      #
+      #   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
+
+      # @!method self.attribute_names
+      #   Returns a array of attribute name.
+      #   Attributes declared with {.delegate_attribute} are also merged.
+      #
+      #   @see #attribute_names
+      #   @return [Array<String>] array of attribute name.
+
+      # @!method attribute_names
+      #   Returns a array of attribute name.
+      #   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.
+
+      # @!method attributes
+      #   Returns a hash with the attribute name as key and the attribute value as value.
+      #   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 = Foo.new
+      #       foo.name = "Alice"
+      #       foo.confirmation = true
+      #
+      #       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.
+
+      # @!method persisted?
+      #   Returns true if model is persisted.
+      #
+      #   By overriding this definition, you can control the callbacks that are triggered when a save is made.
+      #   For example, returning false will trigger before_create, around_create and after_create,
+      #   and returning true will trigger {.before_update}, {.around_update} and {.after_update}.
+      #
+      #   @return [Boolean] returns true if model is persisted.
+      #   @example
+      #       # A model where persistence is always false
+      #       class Foo < ActiveRecordCompose::Model
+      #         before_save { puts "before_save called" }
+      #         before_create { puts "before_create called" }
+      #         before_update { puts "before_update called" }
+      #         after_update { puts "after_update called" }
+      #         after_create { puts "after_create called" }
+      #         after_save { puts "after_save called" }
+      #
+      #         def persisted? = false
+      #       end
+      #
+      #       # A model where persistence is always true
+      #       class Bar < Foo
+      #         def persisted? = true
+      #       end
+      #
+      #       Foo.new.save!
+      #       # before_save called
+      #       # before_create called
+      #       # after_create called
+      #       # after_save called
+      #
+      #       Bar.new.save!
+      #       # before_save called
+      #       # before_update called
+      #       # after_update called
+      #       # after_save called
+
+      # @endgroup
+
+      # @group Validations
+
+      # @!method valid?(context = nil)
+      #   Runs all the validations and returns the result as true or false.
+      #   @param context Validation context.
+      #   @return [Boolean] true on success, false on failure.
+
+      # @!method validate(context = nil)
+      #   Alias for {#valid?}
+      #   @see #valid? Validation context.
+      #   @param context
+      #   @return [Boolean] true on success, false on failure.
+
+      # @!method validate!(context = nil)
+      #   @see #valid?
+      #   Runs all the validations within the specified context.
+      #   no errors are found, raises `ActiveRecord::RecordInvalid` otherwise.
+      #   @param context Validation context.
+      #   @raise ActiveRecord::RecordInvalid
+
+      # @!method errors
+      #   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.
+      #
+      #       class Account < ActiveRecord::Base
+      #         validates :name, :email, presence: true
+      #       end
+      #
+      #       class AccountRegistration < ActiveRecordCompose::Model
+      #         def initialize(attributes = {})
+      #           @account = Account.new
+      #           super(attributes)
+      #           models << account
+      #         end
+      #
+      #         attribute :confirmation, :boolean, default: false
+      #         validates :confirmation, presence: true
+      #
+      #         private
+      #
+      #         attr_reader :account
+      #       end
+      #
+      #       registration = AccountRegistration
+      #       registration.valid?
+      #       #=> false
+      #
+      #       # In addition to the model's own validation error information (`confirmation`), also aggregates
+      #       # error information for objects stored in `account` (`name`, `email`) when validation is performed.
+      #
+      #       registration.errors.map { _1.attribute }  #=> [:name, :email, :confirmation]
+      #
+      #   @return [ActiveModel::Errors]
+
+      # @endgroup
+
+      # @group Persistences
+
+      # @!method save(**options)
+      #   Save the models that exist in models.
+      #   Returns false if any of the targets fail, true if all succeed.
+      #
+      #   The save is performed within a single transaction.
+      #
+      #   Only the `:validate` option takes effect as it is required internally.
+      #   However, we do not recommend explicitly specifying `validate: false` to skip validation.
+      #   Additionally, the `:context` option is not accepted.
+      #   The need for such a value indicates that operations from multiple contexts are being processed.
+      #   If the contexts differ, we recommend separating them into different model definitions.
+      #
+      #   @params [Hash] Optional parameters.
+      #   @option options [Boolean] :validate Whether to run validations.
+      #     This option is intended for internal use only.
+      #     Users should avoid explicitly passing <tt>validate: false</tt>,
+      #     as skipping validations can lead to unexpected behavior.
+      #   @return [Boolean] returns true on success, false on failure.
+
+      # @!method save!(**options)
+      #   Behavior is same to {#save}, but raises an exception prematurely on failure.
+      #   @see #save
+      #   @raise ActiveRecord::RecordInvalid
+      #   @raise ActiveRecord::RecordNotSaved
+
+      # @!method update(attributes)
+      #   Assign attributes and {#save}.
+      #
+      #   @param [Hash<String, Object>] attributes
+      #     new attributes.
+      #   @see #save
+      #   @return [Boolean] returns true on success, false on failure.
+
+      # @!method update!(attributes)
+      #   Behavior is same to {#update}, but raises an exception prematurely on failure.
+      #
+      #   @param [Hash<String, Object>] attributes
+      #     new attributes.
+      #   @see #save
+      #   @see #update
+      #   @raise ActiveRecord::RecordInvalid
+      #   @raise ActiveRecord::RecordNotSaved
+
+      # @endgroup
+
+      # @group Callbacks
+
+      # @!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.
+
+      # @!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.
+
+      # @!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.
+
+      # @!method self.after_commit(*args, &block)
+      #   Registers a block to be called after the transaction is fully committed.
+
+      # @!method self.after_rollback(*args, &block)
+      #   Registers a block to be called after the transaction is rolled back.
+
+      # @endgroup
+    end
+
+    # @group Model Core
 
     def initialize(attributes = {})
       super
     end
 
-    # Returns true if model is persisted.
-    #
-    # By overriding this definition, you can control the callbacks that are triggered when a save is made.
-    # For example, returning false will trigger before_create, around_create and after_create,
-    # and returning true will trigger before_update, around_update and after_update.
-    #
-    # @return [Boolean] returns true if model is persisted.
-    def persisted? = super
-
     private
 
+    # Returns a collection of model elements to encapsulate.
+    # @example Adding models
+    #   models << inner_model_a << inner_model_b
+    #   models.push(inner_model_c)
+    # @example `#push` can have `:destroy` `:if` options
+    #   models.push(profile, destroy: :blank_profile?)
+    #   models.push(profile, destroy: -> { blank_profile? })
+    # @return [ActiveRecordCompose::ComposedCollection]
+    #
     def models = @__models ||= ActiveRecordCompose::ComposedCollection.new(self)
+
+    # @endgroup
   end
 end

data/lib/active_record_compose/persistence.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "composed_collection"
+require_relative "transaction_support"
 
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
 
+  # @private
   module Persistence
     extend ActiveSupport::Concern
     include ActiveRecordCompose::TransactionSupport

data/lib/active_record_compose/transaction_support.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
+  # @private
   module TransactionSupport
     extend ActiveSupport::Concern
     include ActiveRecord::Transactions

data/lib/active_record_compose/validations.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "composed_collection"
+
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
 
+  # @private
   module Validations
     extend ActiveSupport::Concern
 

data/lib/active_record_compose/version.rb

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

data/lib/active_record_compose/wrapped_model.rb

@@ -3,10 +3,12 @@
 require "active_support/core_ext/object"
 
 module ActiveRecordCompose
+  # @private
   class WrappedModel
     # @param model [Object] the model instance.
-    # @param destroy [Boolean] given true, destroy model.
-    # @param destroy [Proc] when proc returning true, destroy model.
+    # @param destroy [Boolean, Proc, Symbol] Controls whether the model should be destroyed.
+    #   - Boolean: if `true`, the model will be destroyed.
+    #   - Proc: the model will be destroyed if the proc returns `true`.
     # @param if [Proc] evaluation result is false, it will not be included in the renewal.
     def initialize(model, destroy: false, if: nil)
       @model = model

data/lib/active_record_compose.rb

@@ -5,5 +5,9 @@ require "active_record"
 require_relative "active_record_compose/version"
 require_relative "active_record_compose/model"
 
+# namespaces in gem `active_record_compose`.
+#
+# Most of the functionality resides in {ActiveRecordCompose::Model}.
+#
 module ActiveRecordCompose
 end

data/sig/_internal/package_private.rbs

@@ -1,11 +1,46 @@
 module ActiveRecordCompose
-  module AttributeQuerying
-    include ActiveModel::AttributeMethods
+  module Attributes
     extend ActiveSupport::Concern
-    extend ActiveModel::AttributeMethods::ClassMethods
+    include ActiveModel::Attributes
+    include Querying
 
-    private
-    def attribute?: (attribute_name) -> untyped
+    def delegated_attributes: () -> Array[Delegation]
+
+    module ClassMethods : Module
+      include ActiveModel::Attributes::ClassMethods
+      include ActiveModel::AttributeMethods::ClassMethods
+
+      def delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: bool) -> untyped
+      def delegated_attributes: () -> Array[Delegation]
+      def delegated_attributes=: (Array[Delegation]) -> untyped
+    end
+
+    class Delegation
+      def initialize: (attribute: String, to: Symbol, ?allow_nil: bool) -> void
+      def attribute: () -> Symbol
+      def attribute_name: () -> String
+      def attribute_hash: (Object model) -> Hash[String, untyped]
+      def define_delegated_attribute: ((Module & ActiveModel::AttributeMethods::ClassMethods) klass) -> void
+
+      @attribute: Symbol
+      @to: Symbol
+      @allow_nil: bool
+
+      private
+      def to: () -> Symbol
+      def allow_nil: () -> bool
+      def reader: () -> String
+      def writer: () -> String
+    end
+
+    module Querying
+      include ActiveModel::AttributeMethods
+      extend ActiveSupport::Concern
+      extend ActiveModel::AttributeMethods::ClassMethods
+
+      private
+      def attribute?: (attribute_name) -> untyped
+    end
   end
 
   module Callbacks
@@ -37,34 +72,9 @@ module ActiveRecordCompose
     include PackagePrivate
   end
 
-  module DelegateAttribute
-    include ActiveModel::Attributes
-    extend ActiveSupport::Concern
-
-    class Delegation
-      def initialize: (attribute: String, to: Symbol, allow_nil: boolish) -> void
-      def attribute: () -> String
-      def to: () -> Symbol
-      def allow_nil: () -> boolish
-      def reader: () -> String
-      def writer: () -> String
-    end
-
-    def delegated_attributes: () -> Array[Delegation]
-
-    module ClassMethods : Module
-      include ActiveModel::Attributes::ClassMethods
-      include ActiveModel::AttributeMethods::ClassMethods
-
-      def delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: untyped?) -> untyped
-      def delegated_attributes: () -> Array[Delegation]
-      def delegated_attributes=: (Array[Delegation]) -> untyped
-    end
-  end
-
   class Model
-    include DelegateAttribute
-    extend DelegateAttribute::ClassMethods
+    include Attributes
+    extend Attributes::ClassMethods
     include TransactionSupport
     extend TransactionSupport::ClassMethods
     include Callbacks

data/sig/active_record_compose.rbs

@@ -71,7 +71,7 @@ module ActiveRecordCompose
     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
 
-    def self.delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: untyped?) -> untyped
+    def self.delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: bool) -> untyped
     def self.connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
     def self.lease_connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
     def self.with_connection: [T] () { () -> T } -> T

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.11.3
 platform: ruby
 authors:
 - hamajyotan
 bindir: bin
 cert_chain: []
-date: 2025-06-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,15 +38,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - lib/active_record_compose.rb
-- lib/active_record_compose/attribute_querying.rb
+- lib/active_record_compose/attributes.rb
+- lib/active_record_compose/attributes/delegation.rb
+- lib/active_record_compose/attributes/querying.rb
 - lib/active_record_compose/callbacks.rb
 - lib/active_record_compose/composed_collection.rb
-- lib/active_record_compose/delegate_attribute.rb
 - lib/active_record_compose/model.rb
 - lib/active_record_compose/persistence.rb
 - lib/active_record_compose/transaction_support.rb
@@ -62,7 +64,7 @@ metadata:
   homepage_uri: https://github.com/hamajyotan/active_record_compose
   source_code_uri: https://github.com/hamajyotan/active_record_compose
   changelog_uri: https://github.com/hamajyotan/active_record_compose/blob/main/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.11.2
+  documentation_uri: https://hamajyotan.github.io/active_record_compose/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -78,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []

data/lib/active_record_compose/attribute_querying.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveRecordCompose
-  # = Attribute \Querying
-  #
-  # This provides predicate methods based on the attributes.
-  #
-  #   class AccountRegistration < ActiveRecordCompose::Model
-  #     def initialize
-  #       @account = Account.new
-  #       super()
-  #       models << account
-  #     end
-  #
-  #     attribute :original_attr
-  #     delegate_attribute :name, :email, to: :account
-  #
-  #     private
-  #
-  #     attr_reader :account
-  #   end
-  #
-  #   model = AccountRegistration.new
-  #
-  #   model.name                    #=> nil
-  #   model.name?                   #=> false
-  #   model.name = 'Alice'
-  #   model.name?                   #=> true
-  #
-  #   model.original_attr = "Bob"
-  #   model.original_attr?          #=> true
-  #   model.original_attr = ""
-  #   model.original_attr?          #=> false
-  #
-  #   # If the value is numeric, it returns the result of checking whether it is zero or not.
-  #   # This behavior is consistent with `ActiveRecord::AttributeMethods::Query`.
-  #   model.original_attr = 123
-  #   model.original_attr?          #=> true
-  #   model.original_attr = 0
-  #   model.original_attr?          #=> false
-  #
-  module AttributeQuerying
-    extend ActiveSupport::Concern
-    include ActiveModel::AttributeMethods
-
-    included do
-      attribute_method_suffix "?", parameters: false
-    end
-
-    private
-
-    def attribute?(attr_name)
-      value = public_send(attr_name)
-
-      case value
-      when true then true
-      when false, nil then false
-      else
-        if value.respond_to?(:zero?)
-          !value.zero?
-        else
-          value.present?
-        end
-      end
-    end
-  end
-end

data/lib/active_record_compose/delegate_attribute.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveRecordCompose
-  # = Delegate \Attribute
-  #
-  # It provides a macro description that expresses access to the attributes of the AR model through delegation.
-  #
-  #   class AccountRegistration < ActiveRecordCompose::Model
-  #     def initialize(account, attributes = {})
-  #       @account = account
-  #       super(attributes)
-  #       models.push(account)
-  #     end
-  #
-  #     attribute :original_attribute, :string, default: 'qux'
-  #
-  #     # like a `delegate :name, :name=, to: :account`
-  #     delegate_attribute :name, to: :account
-  #
-  #     private
-  #
-  #     attr_reader :account
-  #   end
-  #
-  #   account = Account.new
-  #   account.name = 'foo'
-  #
-  #   registration = AccountRegistration.new(account)
-  #   registration.name  #=> 'foo'  # delegate to account#name
-  #
-  #   registration.name = 'bar'  # delegate to account#name=
-  #   account.name  #=> 'bar'
-  #
-  #   # Attributes defined in delegate_attribute will be included in the original `#attributes`.
-  #   registration.attributes  #=> { 'original_attribute' => 'qux', 'name' => 'bar' }
-  #
-  module DelegateAttribute
-    extend ActiveSupport::Concern
-    include ActiveModel::Attributes
-
-    # steep:ignore:start
-    if defined?(Data)
-      Delegation = Data.define(:attribute, :to, :allow_nil) do
-        def reader = attribute.to_s
-        def writer = "#{attribute}="
-      end
-    else
-      Delegation = Struct.new(:attribute, :to, :allow_nil, keyword_init: true) do
-        def reader = attribute.to_s
-        def writer = "#{attribute}="
-      end
-    end
-    # steep:ignore:end
-
-    included do
-      # @type self: Class
-      class_attribute :delegated_attributes, instance_writer: false
-    end
-
-    module ClassMethods
-      # Defines the reader and writer for the specified attribute.
-      #
-      def delegate_attribute(*attributes, to:, allow_nil: nil)
-        delegations = attributes.map { Delegation.new(attribute: _1.to_s, to:, allow_nil:) }
-
-        delegations.map do |delegation|
-          delegate delegation.reader, delegation.writer, to: delegation.to, allow_nil: delegation.allow_nil
-          define_attribute_methods delegation.attribute
-        end
-
-        self.delegated_attributes = (delegated_attributes.to_a + delegations).reverse.uniq { _1.attribute }.reverse
-      end
-
-      # Returns a array of attribute name.
-      # Attributes declared with `delegate_attribute` are also merged.
-      #
-      # @return [Array<String>] array of attribute name.
-      def attribute_names = super + delegated_attributes.to_a.map { _1.attribute }
-    end
-
-    # Returns a array of attribute name.
-    # Attributes declared with `delegate_attribute` are also merged.
-    #
-    # @return [Array<String>] array of attribute name.
-    def attribute_names = super + delegated_attributes.to_a.map { _1.attribute }
-
-    # Returns a hash with the attribute name as key and the attribute value as value.
-    # Attributes declared with `delegate_attribute` are also merged.
-    #
-    # @return [Hash] hash with the attribute name as key and the attribute value as value.
-    def attributes
-      super.merge(delegated_attributes.to_a.map { _1.attribute }.to_h { [ _1, public_send(_1) ] })
-    end
-  end
-end