active_record_compose 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76bd8c66869f7b24c2938ecb72cf2c3b9f47cdcc34a8e1c87f57329f50880ecd
-  data.tar.gz: f6efc5ec40f5e870064dec9928e56a3ee8a3ca07ea00bd5dcbe86f0855d440ce
+  metadata.gz: 491f46737a3744c5c5d3e0319de3ee9f64ae21a9adfab39f36cedc478bfa0e7c
+  data.tar.gz: 406f4c471e0d7c40ec7b3a0d492f8e7e6c96d93fd4b43204a128bf52c1f7ed4c
 SHA512:
-  metadata.gz: c0361c3c95394e550e8571ea4880545dd8e566e9a6d4c829eb494db90226c009487361ca7eed8e3691d6dbf59674e7fc2fa782b2db006b79113c95c5b229f95c
-  data.tar.gz: 2a2ac6e1d86640c8d7df1448fc362e459790561a8223066351cadd7ea297e456bc093a015fb8a765e755deccbd5071e342fe035180a4c222ce81584305388085
+  metadata.gz: 9ff0e91cfb0ca22322d1b9ca47c32f09372afa206e9fa6690c1dfe5ca30d221269ccc55fe17556627234ea8a7019118ddec8a46ad24a52c47239e694dbcac323
+  data.tar.gz: 925001a566ee81600ce91862c0c95f241dba2cd735f6ecbc3e987e83e6cd6f59d217e67afa4bed0a981f35c16645661ef7eeb00adb18df92999f9127e22116e0

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [1.1.1] - 2025-12-04
+
+* fix: the save method would return nil instead of false.
+* doc: We've simplified the documentation comment yard.
+
 ## [1.1.0] - 2025-11-19
 
 * Implemented ActiveRecord-like #inspect

data/lib/active_record_compose/attributes.rb

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

data/lib/active_record_compose/callbacks.rb

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

data/lib/active_record_compose/inspectable.rb

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

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

data/lib/active_record_compose/validations.rb

@@ -5,7 +5,6 @@ require_relative "composed_collection"
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
 
-  # @private
   module Validations
     extend ActiveSupport::Concern
     include ActiveModel::Validations::Callbacks
@@ -22,27 +21,86 @@ module ActiveRecordCompose
       perform_validations(options) ? super : raise_validation_error
     end
 
+    # Runs all the validations and returns the result as true or false.
+    #
+    # @param context Validation context.
+    # @return [Boolean] true on success, false on failure.
     def valid?(context = nil) = context_for_override_validation.with_override(context) { super }
 
+    # @!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]
+
     private
 
+    # @private
     def validate_models
       context = override_validation_context
       models.__wrapped_models.lazy.select { _1.invalid?(context) }.each { errors.merge!(_1) }
     end
 
+    # @private
     def perform_validations(options)
       options[:validate] == false || valid?(options[:context])
     end
 
+    # @private
     def raise_validation_error = raise ActiveRecord::RecordInvalid, self
 
+    # @private
     def context_for_override_validation
       @context_for_override_validation ||= OverrideValidationContext.new
     end
 
+    # @private
     def override_validation_context = context_for_override_validation.context
 
+    # @private
     class OverrideValidationContext
       attr_reader :context
 

data/lib/active_record_compose/version.rb

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

data/sig/_internal/package_private.rbs

@@ -4,19 +4,13 @@ module ActiveRecordCompose
     include ActiveModel::Attributes
     include Querying
 
+    def self.delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: bool) -> untyped
+    def self.delegated_attributes: () -> Array[Delegation]
+    def self.delegated_attributes=: (Array[Delegation]) -> untyped
     def delegated_attributes: () -> Array[Delegation]
 
     @attributes: untyped
 
-    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 AttributePredicate
       def initialize: (untyped value) -> void
       def call: -> bool
@@ -88,31 +82,20 @@ module ActiveRecordCompose
   module Inspectable
     extend ActiveSupport::Concern
     include Attributes
-    extend Inspectable::ClassMethods
 
+    def self.inspection_filter: () -> ActiveSupport::ParameterFilter
+    def self.filter_attributes: () -> Array[untyped]
+    def self.filter_attributes=: (Array[untyped]) -> void
     def inspect: () -> String
     def pretty_print: (untyped q) -> void
 
     private
     def format_for_inspect: (String name, untyped value) -> String
-
-    module ClassMethods
-      FILTERED_MASK: String
-
-      def inspection_filter: () -> ActiveSupport::ParameterFilter
-      def filter_attributes: () -> Array[untyped]
-      def filter_attributes=: (Array[untyped]) -> void
-
-      @inspection_filter: ActiveSupport::ParameterFilter?
-      @filter_attributes: untyped
-    end
   end
 
   class Model
     include Attributes
-    extend Attributes::ClassMethods
     include TransactionSupport
-    extend TransactionSupport::ClassMethods
     include Callbacks
 
     @__models: ComposedCollection
@@ -125,19 +108,12 @@ module ActiveRecordCompose
   module TransactionSupport
     extend ActiveSupport::Concern
     include ActiveRecord::Transactions
-    extend TransactionSupport::ClassMethods
-
-    module ClassMethods
-      include ActiveSupport::Callbacks::ClassMethods
-
-      def before_commit: (*untyped) -> untyped
-      def after_commit: (*untyped) -> untyped
-      def after_rollback: (*untyped) -> untyped
+    include ActiveSupport::Callbacks
+    extend ActiveSupport::Callbacks::ClassMethods
 
-      private
-      def prepend_option: -> ({ prepend: true } | {})
-      def set_options_for_callbacks!: (untyped, ?({ prepend: true } | {})) -> untyped
-    end
+    def self.before_commit: (*untyped) -> untyped
+    def self.after_commit: (*untyped) -> untyped
+    def self.after_rollback: (*untyped) -> untyped
 
     def save: (**untyped options) -> bool
     def save!: (**untyped options) -> untyped
@@ -154,7 +130,6 @@ module ActiveRecordCompose
   module Persistence
     include Callbacks
     include TransactionSupport
-    extend TransactionSupport::ClassMethods
 
     def save: (**untyped options) -> bool
     def save!: (**untyped options) -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - hamajyotan