active_record_compose 1.1.0 → 1.2.0

data/lib/active_record_compose/model.rb

@@ -89,315 +89,6 @@ module ActiveRecordCompose
     include ActiveRecordCompose::TransactionSupport
     include ActiveRecordCompose::Inspectable
 
-    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.
-      #
-      #   @param options [Hash] 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
-
-      # @!method inspect
-      #   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
-
-      # @!method self.filter_attributes
-      #   Returns columns not to expose when invoking {#inspect}.
-      #   @return [Array<Symbol>]
-      #   @see #inspect
-
-      # @!method self.filter_attributes=(value)
-      #   Specify columns not to expose when invoking {#inspect}.
-      #   @param [Array<Symbol>] value
-      #   @see #inspect
-    end
-
     def initialize(attributes = {})
       super
     end
@@ -425,8 +116,6 @@ module ActiveRecordCompose
     #
     def id = nil
 
-    # @group Model Core
-
     private
 
     # Returns a collection of model elements to encapsulate.
@@ -439,7 +128,5 @@ module ActiveRecordCompose
     # @return [ActiveRecordCompose::ComposedCollection]
     #
     def models = @__models ||= ActiveRecordCompose::ComposedCollection.new(self)
-
-    # @endgroup
   end
 end

data/lib/active_record_compose/persistence.rb

@@ -6,7 +6,6 @@ require_relative "composed_collection"
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
 
-  # @private
   module Persistence
     extend ActiveSupport::Concern
     include ActiveRecordCompose::Callbacks
@@ -22,6 +21,11 @@ module ActiveRecordCompose
     # 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.
     #
+    # @param options [Hash] 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.
     def save(**options)
       with_callbacks { save_models(**options, bang: false) }
@@ -29,38 +33,80 @@ module ActiveRecordCompose
       false
     end
 
-    # Save the models that exist in models.
-    # Unlike #save, an exception is raises on failure.
-    #
-    # Saving, like `#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.
+    # Behavior is same to {#save}, but raises an exception prematurely on failure.
     #
+    # @see #save
+    # @raise ActiveRecord::RecordInvalid
+    # @raise ActiveRecord::RecordNotSaved
     def save!(**options)
       with_callbacks { save_models(**options, bang: true) } || raise_on_save_error
     end
 
-    # Assign attributes and save.
+    # Assign attributes and {#save}.
     #
+    # @param [Hash<String, Object>] attributes
+    #   new attributes.
+    # @see #save
     # @return [Boolean] returns true on success, false on failure.
     def update(attributes)
       assign_attributes(attributes)
       save
     end
 
-    # Behavior is same to `#update`, but raises an exception prematurely on failure.
+    # 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
     def update!(attributes)
       assign_attributes(attributes)
       save!
     end
 
+    # @!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
+
     private
 
+    # @private
     def save_models(bang:, **options)
       models.__wrapped_models.all? do |model|
         if bang
@@ -71,8 +117,10 @@ module ActiveRecordCompose
       end
     end
 
+    # @private
     def raise_on_save_error = raise ActiveRecord::RecordNotSaved.new(raise_on_save_error_message, self)
 
+    # @private
     def raise_on_save_error_message = "Failed to save the model."
   end
 end

data/lib/active_record_compose/transaction_support.rb

@@ -3,7 +3,6 @@
 require "active_support/core_ext/module"
 
 module ActiveRecordCompose
-  # @private
   module TransactionSupport
     extend ActiveSupport::Concern
 
@@ -11,82 +10,103 @@ module ActiveRecordCompose
       define_callbacks :commit, :rollback, :before_commit, scope: [ :kind, :name ]
     end
 
-    module ClassMethods
-      # steep:ignore:start
+    # steep:ignore:start
 
+    class_methods do
+      # @private
       # @deprecated
       def with_connection(...)
         ActiveRecord.deprecator.warn("`with_connection` is deprecated. Use `ActiveRecord::Base.with_connection` instead.")
         ActiveRecord::Base.with_connection(...)
       end
 
+      # @private
       # @deprecated
       def lease_connection(...)
         ActiveRecord.deprecator.warn("`lease_connection` is deprecated. Use `ActiveRecord::Base.lease_connection` instead.")
         ActiveRecord::Base.lease_connection(...)
       end
 
+      # @private
       # @deprecated
       def connection(...)
         ActiveRecord.deprecator.warn("`connection` is deprecated. Use `ActiveRecord::Base.connection` instead.")
         ActiveRecord::Base.connection(...)
       end
+    end
+
+    # steep:ignore:end
 
-      # steep:ignore:end
+    # steep:ignore:start
 
+    class_methods do
+      # @private
       def before_commit(*args, &block)
         set_options_for_callbacks!(args)
-        set_callback(:before_commit, :before, *args, &block) # steep:ignore
+        set_callback(:before_commit, :before, *args, &block)
       end
 
+      # Registers a block to be called after the transaction is fully committed.
+      #
       def after_commit(*args, &block)
         set_options_for_callbacks!(args, prepend_option)
-        set_callback(:commit, :after, *args, &block) # steep:ignore
+        set_callback(:commit, :after, *args, &block)
       end
 
+      # Registers a block to be called after the transaction is rolled back.
+      #
       def after_rollback(*args, &block)
         set_options_for_callbacks!(args, prepend_option)
-        set_callback(:rollback, :after, *args, &block) # steep:ignore
+        set_callback(:rollback, :after, *args, &block)
       end
 
       private
 
+      # @private
       def prepend_option
-        if ActiveRecord.run_after_transaction_callbacks_in_order_defined # steep:ignore
+        if ActiveRecord.run_after_transaction_callbacks_in_order_defined
           { prepend: true }
         else
           {}
         end
       end
 
+      # @private
       def set_options_for_callbacks!(args, enforced_options = {})
         options = args.extract_options!.merge!(enforced_options)
         args << options
       end
     end
 
-    def save(**options) = with_transaction_returning_status { super }
-
-    def save!(**options) = with_transaction_returning_status { super }
+    # steep:ignore:end
 
     concerning :SupportForActiveRecordConnectionAdaptersTransaction do
+      # @private
       def trigger_transactional_callbacks? = true
 
+      # @private
       def before_committed!
         _run_before_commit_callbacks
       end
 
+      # @private
       def committed!(should_run_callbacks: true)
         _run_commit_callbacks if should_run_callbacks
       end
 
+      # @private
       def rolledback!(force_restore_state: false, should_run_callbacks: true)
         _run_rollback_callbacks if should_run_callbacks
       end
     end
 
+    def save(**options) = with_transaction_returning_status { super }
+
+    def save!(**options) = with_transaction_returning_status { super }
+
     private
 
+    # @private
     def with_transaction_returning_status
       connection_pool.with_connection do |connection|
         with_pool_transaction_isolation_level(connection) do
@@ -96,13 +116,15 @@ module ActiveRecordCompose
             connection.add_transaction_record(self, ensure_finalize || has_transactional_callbacks?) # steep:ignore
 
             yield.tap { raise ActiveRecord::Rollback unless _1 }
-          end
+          end || false
         end
       end
     end
 
+    # @private
     def default_ar_class = ActiveRecord::Base
 
+    # @private
     def connection_pool(ar_class: default_ar_class)
       connection_specification_name = ar_class.connection_specification_name
       role = ar_class.current_role
@@ -114,6 +136,7 @@ module ActiveRecordCompose
       connection_handler.retrieve_connection_pool(connection_specification_name, **retrieve_options)
     end
 
+    # @private
     def with_pool_transaction_isolation_level(connection, &block)
       if ActiveRecord.gem_version.release >= Gem::Version.new("8.1.0")
         isolation_level = ActiveRecord.default_transaction_isolation_level # steep:ignore
@@ -123,6 +146,7 @@ module ActiveRecordCompose
       end
     end
 
+    # @private
     def has_transactional_callbacks?
       _rollback_callbacks.present? || _commit_callbacks.present? || _before_commit_callbacks.present? # steep:ignore
     end