active_record_compose 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e574f327847973e3b931ee6663de0d395fa6ff26de5830f92ac21d1445fe20
-  data.tar.gz: bb50aa19e200f15c3b16d6b7fe65dc4e94afc7e44eec3c94ef37ab18fc610b88
+  metadata.gz: ab0bb2d4ff8813ad8fb9a4830c2b1d3887aaa29702f11561c9c8624719a5082f
+  data.tar.gz: a3fcfb870aaf5a0825a218556423cc1af16644b41ec22f0b4d656cb42cd33790
 SHA512:
-  metadata.gz: 77a492aea1e8c5aec20bea84dbbd242c2f94d9d5674a705cacea4ad4b8b3991b54630009fb78ed425a6dee5f10d28dd5f473b7b581a92711701de07472d7a88f
-  data.tar.gz: a8386a77e58cb7db6c2478137af7bf24e606448987009257b151c695b746be9818de2d963b65672cc60e23b9a8dc7d0b29790087ea3a8271152c0115d2212bdf
+  metadata.gz: d5a1ea42bd83a986437faac38b2543ee48aff7f2003afa6267a7adcd325db1bbb0506f4f1f25e2aaa13b733df7956ebd820627821f19101fc36dd4f046a51c43
+  data.tar.gz: 4a9cc98fddbcf1068720387207469cb527b96e536a9f109a6174b5a439daa383f54a1625e916c731d01883cf360c6e01281858a238796b5cb64b92665c2405c3

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.7.0] - 2025-02-12
+
+- rename ActiveRecordCompose::InnerModel to ActiveRecordCompose::WrappedModel
+- rename ActiveRecordCompose::InnerModelCollection to ActiveRecordCompose::ComposedCollection
+- A new callback control flag, `persisted_flag_callback_control`, has been defined.
+  Currently, the default value is false, which does not change the existing behavior, but it will be deprecated in the future.
+  When the flag is set to true, the behavior will be almost the same as the callback sequence in ActiveRecord.
+  (https://github.com/hamajyotan/active_record_compose/issues/11)
+
+## [0.6.3] - 2025-01-31
+
+- fix: type error in `ActiveRecordCompose::Model` subclass definitions.
+- fixed type errors in subclass callback definitions, etc.
+- doc: more detailed gem desciption.
+- rewrite readme.
+
 ## [0.6.2] - 2025-01-04
 
 - fix: `delegate_attribute` defined in a subclass had an unintended side effect on the superclass.

data/README.md

@@ -1,9 +1,35 @@
 # ActiveRecordCompose
 
-activermodel (activerecord) form object pattern.
+activemodel (activerecord) form object pattern. it embraces multiple AR models and provides a transparent interface as if they were a single model.
 
 ![CI](https://github.com/hamajyotan/active_record_compose/workflows/CI/badge.svg)
 
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic usage](#basic-usage)
+    - [`delegate_attribute`](#delegate_attribute)
+    - [Promotion to model from AR-model errors](#promotion-to-model-from-ar-model-errors)
+  - [I18n](#i18n)
+- [Advanced Usage](#advanced-usage)
+  - [`destroy` option](#destroy-option)
+  - [Callback ordering by `#save`, `#create` and `#update`](#callback-ordering-by-save-create-and-update)
+- [Links](#links)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
+## Motivation
+
+`ActiveRecord::Base` is responsible for persisting data to the database, and by defining validations and callbacks, it allows you to structure your use cases effectively. This is a crucial component of Rails. However, when a specific model starts being updated by multiple different use cases, validations and callbacks may require conditions such as `on: :context` or `save(validate: false)`. As a result, the model needs to account for multiple dependent use cases, leading to increased complexity.
+
+In such cases, `ActiveModel::Model` becomes useful. It provides the same interfaces as `ActiveRecord::Base`, such as `attribute` and `errors`, allowing it to be used similarly to an ActiveRecord model. Additionally, it enables you to define validations and callbacks within a limited context, preventing conditions related to multiple contexts from being embedded in `ActiveRecord::Base` validations and callbacks. This results in simpler, more maintainable code.
+
+This gem is built on `ActiveModel::Model` and acts as a first-class model within the Rails context. It provides methods for performing batch and safe updates on 0..N encapsulated models, enables transparent attribute access, and facilitates access to error information.
+
 ## Installation
 
 To install `active_record_compose`, just put this line in your Gemfile:
@@ -20,149 +46,186 @@ $ bundle
 
 ## Usage
 
-### ActiveRecordCompose::Model basic
+### Basic usage
 
-It wraps AR objects or equivalent models to provide unified operation.
-For example, the following cases are supported
+(Below, it is assumed that there are two AR model definitions, `Account` and `Profile`, for the sake of explanation.)
 
-#### Context-specific callbacks.
+```ruby
+class Account < ApplicationRecord
+  has_one :profile  # can work without `autosave:true`
+  validates :name, :email, presence: true
+end
+
+class Profile < ApplicationRecord
+  belongs_to :account
+  validates :firstname, :lastname, :age, presence: true
+end
+```
 
-A callback is useful to define some processing before or after a save in a particular model.
-However, if a callback is written directly in the AR model, it is necessary to consider the case where the model is updated in other contexts.
-In particular, if you frequently create with test data, previously unnecessary processing will be called at every point of creation.
-In addition to cost, the more complicated the callbacks you write, the more difficult it will be to create even a single test data.
-If the callbacks are written in a class that inherits from `ActiveRecordCompose::Model`, the AR model itself will not be polluted, and the context can be limited.
+Here is an example of designing a model that updates both Account and Profile at the same time, using `ActiveRecordCompose::Model`.
 
 ```ruby
-class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account = Account.new, attributes = {})
-    @account = account
-    super(attributes) # When overrides `#initialize`, be sure to call `super`.
+class UserRegistration < ActiveRecordCompose::Model
+  def initialize
+    @account = Account.new
+    @profile = @account.build_profile
 
-    # By including AR instance in models, AR instance itself is saved when this model is saved.
-    models.push(account)
+    super()  # Don't forget to call `super()`
+             # RuboCop's Lint/MissingSuper cop assists in addressing this.
+
+    models << account << profile
+    # Alternatively, it can also be written as follows:
+    #     models.push(account)
+    #     models.push(profile)
   end
 
-  # By delegating these to the AR instance,
-  # For example, this model itself can be given directly as an argument to form_with, and it will behave as if it were an instance of the model.
-  delegate :id, :persisted?, to: :account
+  # Attribute declarations using ActiveModel::Attributes are supported.
+  attribute :terms_of_service, :boolean
 
-  # Defines an attribute of the same name that delegates to account#name and account#email
-  delegate_attribute :name, :email, to: :account
+  # You can provide validation definitions limited to UserRegistration.
+  # Instead of directly defining validations for Account or Profile, such
+  # as `on: :create` in the context, the model itself explains the context.
+  validates :terms_of_service, presence: true
+  validates :email, confirmation: true
+
+  # You can provide callback definitions limited to UserRegistration.
+  # For example, if this is written directly in the AR model, you need to consider
+  # callback control for data generation during tests and other situations.
+  after_commit :send_email_message
 
-  # You can only define post-processing if you update through this model.
-  # If this is written directly into the AR model, for example, it would be necessary to consider a callback control for each test data generation.
-  after_commit :try_send_email_message
+  # UserRegistration behaves as if it has attributes like email, name, and age
+  # For example, `email` is delegated to `account.email`,
+  # and `email=` is delegated to `account.email=`.
+  delegate_attribute :name, :email, to: :account
+  delegate_attribute :firstname, :lastname, :age, to: :profile
 
   private
 
-  attr_reader :account
+  attr_reader :account, :profile
 
-  def try_send_email_message
+  def send_email_message
     SendEmailConfirmationJob.perform_later(account)
   end
 end
 ```
 
-#### Validation limited to a specific context.
-
-Validates are basically fired in all cases where the model is manipulated. To avoid this, use `on: :create`, etc. to make it work only in specific cases.
-and so on to work only in specific cases. This allows you to create context-sensitive validations for the same model operation.
-However, this is the first step in making the model more and more complex. You will have to go around with `update(context: :foo)`
-In some cases, you may have to go around with the context option, such as `update(context: :foo)` everywhere.
-By writing validates in a class that extends `ActiveRecordCompose::Model`, you can define context-specific validation without polluting the AR model itself.
+The above model is used as follows.
 
 ```ruby
-class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account = Account.new, attributes = {})
-    @account = account
-    super(attributes)
-    models.push(account)
-  end
+registration = UserRegistration.new
+
+# Atomically update Account and Profile.
+registration.update!(
+  name: "foo",
+  email: "bar@example.com",
+  firstname: "taro",
+  lastname: "yamada",
+  age: 18,
+  email_confirmation: "bar@example.com",
+  terms_of_service: true,
+)
+```
 
-  delegate :id, :persisted?, to: :account
-  delegate_attribute :name, :email, to: :account
+By executing `save`, you can simultaneously update multiple models added to `models`. Furthermore, the save operation is performed within a database transaction, ensuring atomic processing.
 
-  # Only if this model is used, also check the validity of the domain
-  before_validation :require_valid_domain
+```ruby
+user_registration.save  # Atomically update Account and Profile.
+                        # In case of failure, a false value is returned.
+user_registration.save! # With the bang method,
+                        # an exception is raised in case of failure.
+```
 
-  private
+### `delegate_attribute`
 
-  attr_reader :account
-
-  # Validity of the domain part of the e-mail address is also checked only when registering an account.
-  def require_valid_domain
-    e = ValidEmail2::Address.new(email.to_s)
-    unless e.valid?
-      errors.add(:email, :invalid_format)
-      return
-    end
-    unless e.valid_mx?
-      errors.add(:email, :invalid_domain)
-    end
-  end
-end
-```
+In many cases, the composed models have attributes that need to be assigned before saving. `ActiveRecordCompose::Model` provides `delegate_attribute`, allowing transparent access to those attributes."
 
 ```ruby
-account = Account.new(name: 'new account', email: 'foo@example.com')
-account.valid?  #=> true
+  # UserRegistration behaves as if it has attributes like email, name, and age
+  # For example, `email` is delegated to `account.email`,
+  # and `email=` is delegated to `account.email=`.
+  delegate_attribute :name, :email, to: :account
+  delegate_attribute :firstname, :lastname, :age, to: :profile
+```
+
+Attributes defined with `.delegate_attribute` can be accessed through `#attributes` in the same way as the original attributes defined with `.attribute`.
 
-account_registration = AccountRegistration.new(name: 'new account', email: 'foo@example.com')
-account_registration.valid?  #=> false
+```ruby
+registration = UserRegistration.new
+registration.name = "foo"
+registration.terms_of_service = true
+
+# Not only the email_confirmation defined with attribute,
+# but also the attributes defined with delegate_attribute are included.
+registration.attributes
+# => {
+#   "terms_of_service" => true,
+#   "email" => nil,
+#   "name" => "foo",
+#   "age" => nil,
+#   "firstname" => nil,
+#   "lastname" => nil
+# }
 ```
 
-#### updating multiple models at the same time.
+### Promotion to model from AR-model errors
 
-In an AR model, you can add, for example, `autosave: true` or `accepts_nested_attributes_for` to an association to update the related models at the same time.
-There are ways to update related models at the same time. The operation is safe because it is transactional.
-`ActiveRecordCompose::Model` has an internal array called models. By adding an AR object to this models array
-By adding an AR object to the models, the object stored in the models provides an atomic update operation via #save.
+When saving a composed model with `#save`, models that are not valid with `#valid?` will obviously not be saved. As a result, the #errors information can be accessed from `ActiveRecordCompose::Model`.
 
 ```ruby
-class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account = Account.new, profile = account.build_profile, attributes = {})
-    @account = account
-    @profile = profile
-    super(attributes)
-    models << account << profile
-  end
+user_registration = UserRegistration.new
+user_registration.email = "foo@example.com"
+user_registration.email_confirmation = "BAZ@example.com"
+user_registration.age = 18
+user_registration.terms_of_service = true
+
+user_registration.save
+#=> false
+
+user_registration.errors.to_a
+# => [
+#   "Name can't be blank",
+#   "Firstname can't be blank",
+#   "Lastname can't be blank",
+#   "Email confirmation doesn't match Email"
+# ]
+```
 
-  delegate :id, :persisted?, to: :account
-  delegate_attribute :name, :email, to: :account
-  delegate_attribute :firstname, :lastname, :age, to: :profile
+### I18n
 
-  private
+When the `#save!` operation raises an `ActiveRecord::RecordInvalid` exception, it is necessary to have pre-existing locale definitions in order to construct i18n information correctly.
+The specific keys required are `activemodel.errors.messages.record_invalid` or `errors.messages.record_invalid`.
 
-  attr_reader :account, :profile
-end
+(Replace `en` as appropriate in the context.)
+
+```yaml
+en:
+  activemodel:
+    errors:
+      messages:
+        record_invalid: 'Validation failed: %{errors}'
 ```
 
-```ruby
-Account.count  #=> 0
-Profile.count  #=> 0
-
-account_registration =
-  AccountRegistration.new(
-    name: 'foo',
-    email: 'foo@example.com',
-    firstname: 'bar',
-    lastname: 'baz',
-    age: 36,
-  )
-account_registration.save!
-
-Account.count  #=> 1
-Profile.count  #=> 1
+Alternatively, the following definition is also acceptable:
+
+```yaml
+en:
+  errors:
+    messages:
+      record_invalid: 'Validation failed: %{errors}'
 ```
 
-By adding to the `models` array while specifying `destroy: true`, you can perform a delete instead of a save on the model at `#save` time.
+## Advanced Usage
+
+### `destroy` option
+
+By adding to the models array while specifying destroy: true, you can perform a delete instead of a save on the model at #save time.
 
 ```ruby
 class AccountResignation < ActiveRecordCompose::Model
   def initialize(account)
     @account = account
-    @profile = account.profile  # Suppose that Account has_one Profile.
+    @profile = account.profile || account.build_profile
+    super()
     models.push(account)
     models.push(profile, destroy: true)
   end
@@ -178,7 +241,6 @@ class AccountResignation < ActiveRecordCompose::Model
   end
 end
 ```
-
 ```ruby
 account = Account.last
 
@@ -197,72 +259,44 @@ Conditional destroy (or save) can be written like this.
 
 ```ruby
 class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account, attributes = {})
+  def initialize(account)
     @account = account
     @profile = account.profile || account.build_profile
-    super(attributes)
+    super()
     models.push(account)
-    models.push(profile, destroy: :all_blank?) # destroy if all blank, otherwise save.
+
+    # destroy if all blank, otherwise save.
+    models.push(profile, destroy: :profile_field_is_blank?)
+    # Alternatively, it can also be written as follows:
+    #     models.push(profile, destroy: -> { profile_field_is_blank? })
   end
 
-  delegate_attribute :name, :email, to: :account
-  delegate_attribute :firstname, :lastname, :age, to: :profile
+  delegate_attribute :email, to: :account
+  delegate_attribute :name, :age, to: :profile
 
   private
 
   attr_reader :account, :profile
 
-  def all_blank? = firstname.blank && lastname.blank? && age.blank?
-end
-```
-
-### `delegate_attribute`
-
-It provides a macro description that expresses access to the attributes of the AR model through delegation.
-
-```ruby
-class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account, attributes = {})
-    @account = account
-    super(attributes)
-    models.push(account)
+  def profile_field_is_blank?
+    firstname.blank? && lastname.blank? && age.blank?
   end
-
-  attribute :original_attribute, :string, default: 'qux'
-  delegate_attribute :name, to: :account
-
-  private
-
-  attr_reader :account
 end
 ```
 
-```ruby
-account = Account.new
-account.name = 'foo'
-
-registration = AccountRegistration.new(account)
-registration.name  #=> 'foo'
-
-registration.name = 'bar'
-account.name  #=> 'bar'
-```
-
-Overrides `#attributes`, merging attributes defined with `delegate_attribute` in addition to the original attributes.
-
-```
-account.attributes  #=> {'original_attribute' => 'qux', 'name' => 'bar'}
-```
-
 ### Callback ordering by `#save`, `#create` and `#update`.
 
-Sometimes, multiple AR objects are passed to the models in the arguments.
-It is not strictly possible to distinguish between create and update operations, regardless of the state of `#persisted?`.
-Therefore, control measures such as separating callbacks with `after_create` and `after_update` based on the `#persisted?` of AR objects are left to the discretion of the user,
-rather than being determined by the state of the AR objects themselves.
+The behavior of `(before|after|around)_create` and `(before|after|around)_update` hooks depends on
+the state of the `persisted_flag_callback_control` setting.
+
+When `persisted_flag_callback_control` is set to false,
+the execution of `#create`, `#update`, or `#save` determines which callbacks will be triggered.
+Currently, the default value is `false`, but it will no longer be supported in the future.
 
 ```ruby
 class ComposedModel < ActiveRecordCompose::Model
+  self.persisted_flag_callback_control = false # Currently defaults to false, but will no longer be supported in the future.
+
   # ...
 
   before_save { puts 'before_save called!' }
@@ -294,30 +328,70 @@ model.update
 # after_save called!
 ```
 
-### I18n
+When `persisted_flag_callback_control` is set to `true`, it behaves almost like callback control in ActiveRecord.
+This behavior will be the default in the future.
 
-When the `#save!` operation raises an `ActiveRecord::RecordInvalid` exception, it is necessary to have pre-existing locale definitions in order to construct i18n information correctly.
-The specific keys required are `activemodel.errors.messages.record_invalid` or `errors.messages.record_invalid`.
+```ruby
+class ComposedModel < ActiveRecordCompose::Model
+  self.persisted_flag_callback_control = true # In the future, true will be the default and false will no longer be supported.
 
-(Replace `en` as appropriate in the context.)
+  # ...
 
-```yaml
-en:
-  activemodel:
-    errors:
-      messages:
-        record_invalid: 'Validation failed: %{errors}'
+  before_save { puts 'before_save called!' }
+  before_create { puts 'before_create called!' }
+  before_update { puts 'before_update called!' }
+  after_save { puts 'after_save called!' }
+  after_create { puts 'after_create called!' }
+  after_update { puts 'after_update called!' }
+
+  def persisted?
+    # Override and return a boolish value depending on the state of the inner model.
+    # For example, it could be transferred to the primary model to be manipulated.
+    #
+    #       # ex.)
+    #       def persisted? = the_model.persisted?
+    #
+    true
+  end
+end
 ```
 
-Alternatively, the following definition is also acceptable:
+```ruby
+# when `model.persisted?` returns `true`
 
-```yaml
-en:
-  errors:
-    messages:
-      record_invalid: 'Validation failed: %{errors}'
+model = ComposedModel.new
+
+model.save # or `model.update` (the same callbacks will be triggered in all cases).
+
+# before_save called!
+# before_update called! # when persisted? is false, before_create hook is fired here instead.
+# after_update called! # when persisted? is false, after_create hook is fired here instead.
+# after_save called!
 ```
 
+```ruby
+# when `model.persisted?` returns `false`
+
+model = ComposedModel.new
+
+model.save # or `model.update` (the same callbacks will be triggered in all cases).
+
+# before_save called!
+# before_create called!
+# after_create called!
+# after_save called!
+```
+
+When `persisted_flag_callback_control` is `true`, `#create` is not supported.
+
+```ruby
+model.create  # => raises RuntimeError
+```
+
+## Links
+
+- [Smart way to update multiple models simultaneously in Rails](https://dev.to/hamajyotan/smart-way-to-update-multiple-models-simultaneously-in-rails-51b6)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -335,3 +409,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the ActiveRecord::Compose project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hamajyotan/active_record_compose/blob/main/CODE_OF_CONDUCT.md).
+

data/lib/active_record_compose/{inner_model_collection.rb → composed_collection.rb}

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'active_record_compose/inner_model'
+require 'active_record_compose/wrapped_model'
 
 module ActiveRecordCompose
-  using InnerModel::PackagePrivate
+  using WrappedModel::PackagePrivate
 
-  class InnerModelCollection
+  class ComposedCollection
     include Enumerable
 
     def initialize(owner)
@@ -79,30 +79,25 @@ module ActiveRecordCompose
     attr_reader :owner, :models
 
     def wrap(model, destroy: false, if: nil)
-      if model.is_a?(ActiveRecordCompose::InnerModel)
-        # @type var model: ActiveRecordCompose::InnerModel
-        model
-      else
-        if destroy.is_a?(Symbol)
-          method = destroy
-          destroy = -> { owner.__send__(method) }
-        end
-        if_option = binding.local_variable_get(:if)
-        if if_option.is_a?(Symbol)
-          method = if_option
-          if_option = -> { owner.__send__(method) }
-        end
-        ActiveRecordCompose::InnerModel.new(model, destroy:, if: if_option)
+      if destroy.is_a?(Symbol)
+        method = destroy
+        destroy = -> { owner.__send__(method) }
       end
+      if_option = binding.local_variable_get(:if)
+      if if_option.is_a?(Symbol)
+        method = if_option
+        if_option = -> { owner.__send__(method) }
+      end
+      ActiveRecordCompose::WrappedModel.new(model, destroy:, if: if_option)
     end
 
     # @private
     module PackagePrivate
-      refine InnerModelCollection do
+      refine ComposedCollection do
         # Returns array of wrapped model instance.
         #
         # @private
-        # @return [Array[InnerModel] array of wrapped model instance.
+        # @return [Array[WrappedModel]] array of wrapped model instance.
         def __wrapped_models = models.reject { _1.ignore? }.select { _1.__raw_model }
       end
     end

data/lib/active_record_compose/model.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'active_record_compose/composed_collection'
 require 'active_record_compose/delegate_attribute'
-require 'active_record_compose/inner_model_collection'
 require 'active_record_compose/transaction_support'
 
 module ActiveRecordCompose
-  using InnerModelCollection::PackagePrivate
+  using ComposedCollection::PackagePrivate
 
   class Model
     include ActiveModel::Model
@@ -15,6 +15,46 @@ module ActiveRecordCompose
     include ActiveRecordCompose::DelegateAttribute
     include ActiveRecordCompose::TransactionSupport
 
+    # This flag controls the callback sequence for models.
+    # The current default value is `false`, but support for `false` is planned to be discontinued in the future.
+    #
+    # When `persisted_flag_callback_control` is set to `true`,
+    # the occurrence of callbacks depends on the evaluation result of `#persisted?`.
+    # Additionally, the definition of `#persisted?` itself can be appropriately overridden in subclasses.
+    #
+    # if `#persisted?` returns `false`:
+    # * before_save
+    # * before_create
+    # * after_create
+    # * after_save
+    #
+    # if `#persisted?` returns `true`:
+    # * before_save
+    # * before_update
+    # * after_update
+    # * after_save
+    #
+    # On the other hand, when `persisted_flag_callback_control` is set to `false`,
+    # the invoked methods during saving operations vary depending on the method used.
+    #
+    # when performing `#save` or `#save!`:
+    # * before_save
+    # * after_save
+    #
+    # when performing `#update` or `#update!`:
+    # * before_save
+    # * before_update
+    # * after_update
+    # * after_save
+    #
+    # when performing `#create` or `#create!`:
+    # * before_save
+    # * before_create
+    # * after_create
+    # * after_save
+    #
+    class_attribute :persisted_flag_callback_control, instance_accessor: false, default: false
+
     define_model_callbacks :save
     define_model_callbacks :create
     define_model_callbacks :update
@@ -35,7 +75,11 @@ module ActiveRecordCompose
       return false if invalid?
 
       with_transaction_returning_status do
-        run_callbacks(:save) { save_models(bang: false) }
+        if self.class.persisted_flag_callback_control
+          with_callbacks { save_models(bang: false) }
+        else
+          run_callbacks(:save) { save_models(bang: false) }
+        end
       rescue ActiveRecord::RecordInvalid
         false
       end
@@ -50,7 +94,11 @@ module ActiveRecordCompose
       valid? || raise_validation_error
 
       with_transaction_returning_status do
-        run_callbacks(:save) { save_models(bang: true) }
+        if self.class.persisted_flag_callback_control
+          with_callbacks { save_models(bang: true) }
+        else
+          run_callbacks(:save) { save_models(bang: true) }
+        end
       end || raise_on_save_error
     end
 
@@ -80,11 +128,15 @@ module ActiveRecordCompose
     #   # after_save called!
     #
     def create(attributes = {})
+      if self.class.persisted_flag_callback_control
+        raise '`#create` cannot be called. The context for creation or update is determined by the `#persisted` flag.'
+      end
+
       assign_attributes(attributes)
       return false if invalid?
 
       with_transaction_returning_status do
-        run_callbacks(:save) { run_callbacks(:create) { save_models(bang: false) } }
+        with_callbacks(context: :create) { save_models(bang: false) }
       rescue ActiveRecord::RecordInvalid
         false
       end
@@ -93,11 +145,15 @@ module ActiveRecordCompose
     # Behavior is same to `#create`, but raises an exception prematurely on failure.
     #
     def create!(attributes = {})
+      if self.class.persisted_flag_callback_control
+        raise '`#create` cannot be called. The context for creation or update is determined by the `#persisted` flag.'
+      end
+
       assign_attributes(attributes)
       valid? || raise_validation_error
 
       with_transaction_returning_status do
-        run_callbacks(:save) { run_callbacks(:create) { save_models(bang: true) } }
+        with_callbacks(context: :create) { save_models(bang: true) }
       end || raise_on_save_error
     end
 
@@ -131,7 +187,11 @@ module ActiveRecordCompose
       return false if invalid?
 
       with_transaction_returning_status do
-        run_callbacks(:save) { run_callbacks(:update) { save_models(bang: false) } }
+        if self.class.persisted_flag_callback_control
+          with_callbacks { save_models(bang: false) }
+        else
+          with_callbacks(context: :update) { save_models(bang: false) }
+        end
       rescue ActiveRecord::RecordInvalid
         false
       end
@@ -144,22 +204,29 @@ module ActiveRecordCompose
       valid? || raise_validation_error
 
       with_transaction_returning_status do
-        run_callbacks(:save) { run_callbacks(:update) { save_models(bang: true) } }
+        if self.class.persisted_flag_callback_control
+          with_callbacks { save_models(bang: true) }
+        else
+          with_callbacks(context: :update) { save_models(bang: true) }
+        end
       end || raise_on_save_error
     end
 
     private
 
-    def models = @__models ||= ActiveRecordCompose::InnerModelCollection.new(self)
+    def models = @__models ||= ActiveRecordCompose::ComposedCollection.new(self)
 
     def validate_models
-      wms = models.__wrapped_models
-      wms.select { _1.invalid? }.each { errors.merge!(_1) }
+      models.__wrapped_models.select { _1.invalid? }.each { errors.merge!(_1) }
+    end
+
+    def with_callbacks(context: nil, &block)
+      context ||= persisted? ? :update : :create
+      run_callbacks(:save) { run_callbacks(context, &block) }
     end
 
     def save_models(bang:)
-      wms = models.__wrapped_models
-      wms.all? { bang ? _1.save! : _1.save }
+      models.__wrapped_models.all? { bang ? _1.save! : _1.save }
     end
 
     def raise_validation_error = raise ActiveRecord::RecordInvalid, self

data/lib/active_record_compose/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/lib/active_record_compose/{inner_model.rb → wrapped_model.rb}

@@ -3,7 +3,7 @@
 require 'active_support/core_ext/object'
 
 module ActiveRecordCompose
-  class InnerModel
+  class WrappedModel
     # @param model [Object] the model instance.
     # @param destroy [Boolean] given true, destroy model.
     # @param destroy [Proc] when proc returning true, destroy model.
@@ -17,7 +17,7 @@ module ActiveRecordCompose
     delegate :errors, to: :model
 
     # Determines whether to save or delete the target object.
-    # Depends on the `destroy` value of the InnerModel object initialization option.
+    # Depends on the `destroy` value of the WrappedModel object initialization option.
     #
     # On the other hand, there are values `mark_for_destruction` and `marked_for_destruction?` in ActiveRecord.
     # However, these values are not substituted here.
@@ -60,12 +60,36 @@ module ActiveRecordCompose
     # Whether save or destroy is executed depends on the value of `#destroy_context?`.
     #
     # @return [Boolean] returns true on success, false on failure.
-    def save = destroy_context? ? model.destroy : model.save
+    def save
+      # While errors caused by the type check are avoided,
+      # it is important to note that an error can still occur
+      # if `#destroy_context?` returns true but ar_like does not implement `#destroy`.
+      m = model
+      if destroy_context?
+        # @type var m: ActiveRecordCompose::_ARLikeWithDestroy
+        m.destroy
+      else
+        # @type var m: ActiveRecordCompose::_ARLike
+        m.save
+      end
+    end
 
     # Execute save or destroy. Unlike #save, an exception is raises on failure.
     # Whether save or destroy is executed depends on the value of `#destroy_context?`.
     #
-    def save! = destroy_context? ? model.destroy! : model.save!
+    def save!
+      # While errors caused by the type check are avoided,
+      # it is important to note that an error can still occur
+      # if `#destroy_context?` returns true but ar_like does not implement `#destroy`.
+      m = model
+      if destroy_context?
+        # @type var m: ActiveRecordCompose::_ARLikeWithDestroy
+        m.destroy!
+      else
+        # @type var model: ActiveRecordCompose::_ARLike
+        m.save!
+      end
+    end
 
     # @return [Boolean]
     def invalid? = destroy_context? ? false : model.invalid?
@@ -94,7 +118,7 @@ module ActiveRecordCompose
 
     # @private
     module PackagePrivate
-      refine InnerModel do
+      refine WrappedModel do
         # @private
         # Returns a model instance of raw, but it should
         # be noted that application developers are not expected to use this interface.

data/sig/_internal/package_private.rbs

@@ -1,59 +1,33 @@
 module ActiveRecordCompose
-  module DelegateAttribute : ActiveModel::Attributes
-    extend ActiveSupport::Concern
-
-    def attributes: -> Hash[String, untyped]
-    def delegated_attributes: () -> Array[String]
-
-    module ClassMethods : Module
-      def delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: untyped?, ?private: untyped?) -> untyped
-      def delegated_attributes: () -> Array[String]
-      def delegated_attributes=: (Array[String]) -> untyped
-    end
-  end
-
-  class InnerModelCollection
+  class ComposedCollection
     def initialize: (Model) -> void
 
     private
     attr_reader owner: Model
-    attr_reader models: Array[InnerModel]
-    def wrap: (_ARLike | InnerModel, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> InnerModel
+    attr_reader models: Array[WrappedModel]
+    def wrap: (ar_like, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> WrappedModel
 
     module PackagePrivate
-      def __wrapped_models: () -> Array[InnerModel]
+      def __wrapped_models: () -> Array[WrappedModel]
 
       private
-      def models: () -> Array[InnerModel]
+      def models: () -> Array[WrappedModel]
     end
 
     include PackagePrivate
   end
 
-  class InnerModel
-    def initialize: (_ARLike, ?destroy: (bool | destroy_context_type), ?if: (nil | condition_type)) -> void
-    def destroy_context?: -> bool
-    def ignore?: -> bool
-    def save: -> bool
-    def save!: -> untyped
-    def invalid?: -> bool
-    def valid?: -> bool
-    def is_a?: (untyped) -> bool
-    def ==: (untyped) -> bool
-
-    private
-    attr_reader model: _ARLike
-    attr_reader destroy_context_type: (bool | destroy_context_type)
-    attr_reader if_option: (nil | condition_type)
+  module DelegateAttribute : ActiveModel::Attributes
+    extend ActiveSupport::Concern
 
-    module PackagePrivate
-      def __raw_model: () -> _ARLike
+    def attributes: -> Hash[String, untyped]
+    def delegated_attributes: () -> Array[String]
 
-      private
-      def model: () -> _ARLike
+    module ClassMethods : Module
+      def delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: untyped?, ?private: untyped?) -> untyped
+      def delegated_attributes: () -> Array[String]
+      def delegated_attributes=: (Array[String]) -> untyped
     end
-
-    include PackagePrivate
   end
 
   class Model
@@ -62,7 +36,7 @@ module ActiveRecordCompose
     include TransactionSupport
     extend TransactionSupport::ClassMethods
 
-    @__models: InnerModelCollection
+    @__models: ComposedCollection
   end
 
   module TransactionSupport
@@ -79,4 +53,30 @@ module ActiveRecordCompose
       def ar_class: -> singleton(ActiveRecord::Base)
     end
   end
+
+  class WrappedModel
+    def initialize: (ar_like, ?destroy: (bool | destroy_context_type), ?if: (nil | condition_type)) -> void
+    def destroy_context?: -> bool
+    def ignore?: -> bool
+    def save: -> bool
+    def save!: -> untyped
+    def invalid?: -> bool
+    def valid?: -> bool
+    def is_a?: (untyped) -> bool
+    def ==: (untyped) -> bool
+
+    private
+    attr_reader model: ar_like
+    attr_reader destroy_context_type: (bool | destroy_context_type)
+    attr_reader if_option: (nil | condition_type)
+
+    module PackagePrivate
+      def __raw_model: () -> ar_like
+
+      private
+      def model: () -> ar_like
+    end
+
+    include PackagePrivate
+  end
 end

data/sig/active_record_compose.rbs

@@ -5,6 +5,15 @@ module ActiveRecordCompose
   VERSION: String
 
   interface _ARLike
+    def save: -> bool
+    def save!: -> untyped
+    def invalid?: -> bool
+    def valid?: -> bool
+    def errors: -> untyped
+    def is_a?: (untyped) -> bool
+    def ==: (untyped) -> bool
+  end
+  interface _ARLikeWithDestroy
     def save: -> bool
     def save!: -> untyped
     def destroy: -> bool
@@ -15,28 +24,53 @@ module ActiveRecordCompose
     def is_a?: (untyped) -> bool
     def ==: (untyped) -> bool
   end
+  type ar_like = (_ARLike | _ARLikeWithDestroy)
+
+  type condition[T] = Symbol | ^(T) [self: T] -> boolish
+  type callback[T] = Symbol | ^(T) [self: T] -> void
+  type around_callback[T] = Symbol | ^(T, Proc) [self: T] -> void
 
   type attribute_name = (String | Symbol)
-  type destroy_context_type = ((^() -> boolish) | (^(_ARLike) -> boolish))
-  type condition_type = ((^() -> boolish) | (^(_ARLike) -> boolish))
+  type destroy_context_type = ((^() -> boolish) | (^(ar_like) -> boolish))
+  type condition_type = ((^() -> boolish) | (^(ar_like) -> boolish))
 
-  class InnerModelCollection
-    include ::Enumerable[_ARLike]
+  class ComposedCollection
+    include ::Enumerable[ar_like]
 
-    def each: () { (_ARLike) -> void } -> InnerModelCollection | () -> Enumerator[_ARLike, self]
-    def <<: (_ARLike) -> self
-    def push: (_ARLike, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> self
+    def each: () { (ar_like) -> void } -> ComposedCollection | () -> Enumerator[ar_like, self]
+    def <<: (ar_like) -> self
+    def push: (ar_like, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> self
     def empty?: -> bool
     def clear: -> self
-    def delete: (_ARLike) -> InnerModelCollection?
+    def delete: (ar_like) -> ComposedCollection?
   end
 
   class Model
-    extend ActiveModel::Callbacks
     include ActiveModel::Model
     include ActiveModel::Validations::Callbacks
-    extend ActiveModel::Validations::ClassMethods
     include ActiveModel::Attributes
+    extend ActiveModel::Callbacks
+    extend ActiveModel::Validations::ClassMethods
+    extend ActiveModel::Validations::Callbacks::ClassMethods
+    extend ActiveModel::Attributes::ClassMethods
+
+    def self.before_save: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.around_save: (*around_callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.after_save: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+
+    def self.before_create: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.around_create: (*around_callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.after_create: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+
+    def self.before_update: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.around_update: (*around_callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+    def self.after_update: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
+
+    def self.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.persisted_flag_callback_control: () -> boolish
+    def self.persisted_flag_callback_control=: (boolish) -> untyped
 
     def self.delegate_attribute: (*untyped methods, to: untyped, ?allow_nil: untyped?, ?private: untyped?) -> untyped
     def self.connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
@@ -53,7 +87,8 @@ module ActiveRecordCompose
     def id: -> untyped
 
     private
-    def models: -> InnerModelCollection
+    def models: -> ComposedCollection
+    def with_callbacks: (?context: (nil | :create | :update)) { () -> bool } -> bool
     def validate_models: -> void
     def save_models: (bang: bool) -> bool
     def raise_validation_error: -> bot

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - hamajyotan
 bindir: bin
 cert_chain: []
-date: 2025-01-04 00:00:00.000000000 Z
+date: 2025-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -23,7 +23,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description: activemodel form object pattern
+description: activemodel form object pattern. it embraces multiple AR models and provides
+  a transparent interface as if they were a single model.
 email:
 - hamajyotan@gmail.com
 executables: []
@@ -36,12 +37,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/active_record_compose.rb
+- lib/active_record_compose/composed_collection.rb
 - lib/active_record_compose/delegate_attribute.rb
-- lib/active_record_compose/inner_model.rb
-- lib/active_record_compose/inner_model_collection.rb
 - lib/active_record_compose/model.rb
 - lib/active_record_compose/transaction_support.rb
 - lib/active_record_compose/version.rb
+- lib/active_record_compose/wrapped_model.rb
 - sig/_internal/package_private.rbs
 - sig/active_record_compose.rbs
 homepage: https://github.com/hamajyotan/active_record_compose
@@ -51,7 +52,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.6.2
+  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.7.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: