active_record_compose 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a3d2a1c6e4aac0bc387a6e0d9ba2917dafeacec4d46b2ad617d54e45ff9786f
-  data.tar.gz: d71b88c9b069eca62e49d2e5ff25c447a5e70e741d29b76f572c5a21b4994a4b
+  metadata.gz: ab0bb2d4ff8813ad8fb9a4830c2b1d3887aaa29702f11561c9c8624719a5082f
+  data.tar.gz: a3fcfb870aaf5a0825a218556423cc1af16644b41ec22f0b4d656cb42cd33790
 SHA512:
-  metadata.gz: 3579fdc36270eaaa2f9f253b247aabc5bc4aa6547df5511e81158ebbf3277b37dbbaa3e4d4376fff5c9ac0066cebbf0207db993cd20b4c8b159a6f3069ae24f1
-  data.tar.gz: 4f2e98a4158a5c19c13f5bc5d83276c7071ece19b2c969d73c24cce47231c9f272fb32620d5a31748e2bd060d72733bcd28be3d4d3eb6c1e9c8ded1bb9db0340
+  metadata.gz: d5a1ea42bd83a986437faac38b2543ee48aff7f2003afa6267a7adcd325db1bbb0506f4f1f25e2aaa13b733df7956ebd820627821f19101fc36dd4f046a51c43
+  data.tar.gz: 4a9cc98fddbcf1068720387207469cb527b96e536a9f109a6174b5a439daa383f54a1625e916c731d01883cf360c6e01281858a238796b5cb64b92665c2405c3

data/CHANGELOG.md

@@ -1,6 +1,15 @@
 ## [Unreleased]
 
-## [0.6.2] - 2025-01-31
+## [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.

data/README.md

@@ -286,13 +286,17 @@ end
 
 ### 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!' }
@@ -324,6 +328,66 @@ model.update
 # after_save called!
 ```
 
+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.
+
+```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.
+
+  # ...
+
+  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
+```
+
+```ruby
+# when `model.persisted?` returns `true`
+
+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)

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.3'
+  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.
@@ -118,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,4 +1,22 @@
 module ActiveRecordCompose
+  class ComposedCollection
+    def initialize: (Model) -> void
+
+    private
+    attr_reader owner: Model
+    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[WrappedModel]
+
+      private
+      def models: () -> Array[WrappedModel]
+    end
+
+    include PackagePrivate
+  end
+
   module DelegateAttribute : ActiveModel::Attributes
     extend ActiveSupport::Concern
 
@@ -12,25 +30,31 @@ module ActiveRecordCompose
     end
   end
 
-  class InnerModelCollection
-    def initialize: (Model) -> void
+  class Model
+    include DelegateAttribute
+    extend DelegateAttribute::ClassMethods
+    include TransactionSupport
+    extend TransactionSupport::ClassMethods
 
-    private
-    attr_reader owner: Model
-    attr_reader models: Array[InnerModel]
-    def wrap: (ar_like | InnerModel, ?destroy: (bool | Symbol | destroy_context_type), ?if: (nil | Symbol | condition_type)) -> InnerModel
+    @__models: ComposedCollection
+  end
 
-    module PackagePrivate
-      def __wrapped_models: () -> Array[InnerModel]
+  module TransactionSupport
+    include ActiveRecord::Transactions
+
+    def id: -> untyped
+
+    module ClassMethods
+      def connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
+      def lease_connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
+      def with_connection: [T] () { () -> T } -> T
 
       private
-      def models: () -> Array[InnerModel]
+      def ar_class: -> singleton(ActiveRecord::Base)
     end
-
-    include PackagePrivate
   end
 
-  class InnerModel
+  class WrappedModel
     def initialize: (ar_like, ?destroy: (bool | destroy_context_type), ?if: (nil | condition_type)) -> void
     def destroy_context?: -> bool
     def ignore?: -> bool
@@ -55,28 +79,4 @@ module ActiveRecordCompose
 
     include PackagePrivate
   end
-
-  class Model
-    include DelegateAttribute
-    extend DelegateAttribute::ClassMethods
-    include TransactionSupport
-    extend TransactionSupport::ClassMethods
-
-    @__models: InnerModelCollection
-  end
-
-  module TransactionSupport
-    include ActiveRecord::Transactions
-
-    def id: -> untyped
-
-    module ClassMethods
-      def connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
-      def lease_connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
-      def with_connection: [T] () { () -> T } -> T
-
-      private
-      def ar_class: -> singleton(ActiveRecord::Base)
-    end
-  end
 end

data/sig/active_record_compose.rbs

@@ -34,15 +34,15 @@ module ActiveRecordCompose
   type destroy_context_type = ((^() -> boolish) | (^(ar_like) -> boolish))
   type condition_type = ((^() -> boolish) | (^(ar_like) -> boolish))
 
-  class InnerModelCollection
+  class ComposedCollection
     include ::Enumerable[ar_like]
 
-    def each: () { (ar_like) -> void } -> InnerModelCollection | () -> Enumerator[ar_like, 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: (ar_like) -> InnerModelCollection?
+    def delete: (ar_like) -> ComposedCollection?
   end
 
   class Model
@@ -69,6 +69,9 @@ module ActiveRecordCompose
     def self.after_commit: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
     def self.after_rollback: (*callback[instance], ?if: condition[instance], ?unless: condition[instance], **untyped) ?{ () [self: instance] -> void } -> void
 
+    def self.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
     def self.lease_connection: -> ActiveRecord::ConnectionAdapters::AbstractAdapter
@@ -84,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.3
+  version: 0.7.0
 platform: ruby
 authors:
 - hamajyotan
 bindir: bin
 cert_chain: []
-date: 2025-01-31 00:00:00.000000000 Z
+date: 2025-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -37,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
@@ -52,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.3
+  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.7.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: