active_record_compose 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e0428468971c6a369fd86cfae9b5413acddf18a252a1f502498e11a55e23b92
-  data.tar.gz: fea23f0f94a09d84b462e27af4feb01c1e40f0c8ff4ba306a9dd391f89eeb9f7
+  metadata.gz: 954ce34124a1c8e83a45710e104dd965c407afb5ba296b74d4a4e5f9d13d971a
+  data.tar.gz: c1bb35ef5458a804f243b886c037aff3794822477ea2aaf5a57bfb12a4001477
 SHA512:
-  metadata.gz: f293d9167fe2a1f879df2f3936e784a2f6f33b1df20160606a5ef65a23f2e4a81040ada14ed7d42aa1ed289899db278880945f75d8a792f369a02f5301e31a5f
-  data.tar.gz: b7db34b71359f1f7d90bb6bbb25b5139595742b202c29b8f009e506dd2244a485f80151fd74edf5245aca224ef6a58bf9c507ade5b95bc69b84963bf3203f9a9
+  metadata.gz: 2e7f81f304cec10420cb4f405ad8ad7f93f3811c7f43bf9952c05dbca84e651bbf0c851e648349d7e93986cf67cb177110785588a47c8951718f4d271cf53944
+  data.tar.gz: 8ac490bd69c0d51e6e89f1f198a4e052eccbeedcf1b234edfa8c9635819fe336bbe10b6b64b6b55907524543ad34eb9343892b00f54f2737a65c45c120456afa

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.12.0] - 2025-08-21
+
+- Omits default arguments for `#update` and `#update!`. It's to align I/F with ActiveRecord.
+  (https://github.com/hamajyotan/active_record_compose/pull/25)
+  - `#update(attributes = {})` to `#update(attributes)`
+  - `#update!(attributes = {})` to `#update!(attributes)`
+- Omitted Specify instance variables in the `:to` option of `delegate_attribute`.
+  (https://github.com/hamajyotan/active_record_compose/pull/29)
+- Omitted `#destroy` and `#touch` from `ActiveRecordCompose::Model`.
+  These were unintentionally provided by the `ActiveRecord::Transactions` module. The but in fact did not work correctly.
+  (https://github.com/hamajyotan/active_record_compose/pull/27)
+
+## [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/attribute_predicate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveRecordCompose
+  module Attributes
+    # @private
+    class AttributePredicate
+      def initialize(value)
+        @value = value
+      end
+
+      def call
+        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
+
+      private
+
+      attr_reader :value
+    end
+  end
+end

data/lib/active_record_compose/attributes/delegation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "attribute_predicate"
+
+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.module_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{reader}?
+            ActiveRecordCompose::Attributes::AttributePredicate.new(#{reader}).call
+          end
+        RUBY
+      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,62 @@
+# frozen_string_literal: true
+
+require_relative "attribute_predicate"
+
+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) = query?(public_send(attr_name))
+
+      def query?(value)
+        ActiveRecordCompose::Attributes::AttributePredicate.new(value).call
+      end
+    end
+  end
+end

data/lib/active_record_compose/attributes.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "attributes/attribute_predicate"
+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
+      # 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: false)
+        if to.start_with?("@")
+          raise ArgumentError, "Instance variables cannot be specified in delegate to. (#{to})"
+        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,6 +1,21 @@
 # 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.
+  #
+  # 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
@@ -13,8 +28,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