active_record_compose 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab0bb2d4ff8813ad8fb9a4830c2b1d3887aaa29702f11561c9c8624719a5082f
-  data.tar.gz: a3fcfb870aaf5a0825a218556423cc1af16644b41ec22f0b4d656cb42cd33790
+  metadata.gz: 9b1f795843fd29ef6dcd9cf17e897938ea97fc8f32db35f0b444b36455e619a3
+  data.tar.gz: 584e44a2c49c6861ad232f0c52c75b6d73abb550f39165fabe14690a71575c81
 SHA512:
-  metadata.gz: d5a1ea42bd83a986437faac38b2543ee48aff7f2003afa6267a7adcd325db1bbb0506f4f1f25e2aaa13b733df7956ebd820627821f19101fc36dd4f046a51c43
-  data.tar.gz: 4a9cc98fddbcf1068720387207469cb527b96e536a9f109a6174b5a439daa383f54a1625e916c731d01883cf360c6e01281858a238796b5cb64b92665c2405c3
+  metadata.gz: 04bc96e1479134c02ad09ae5d014ad5ad93c6d6ae6914a39724d42152f691120ccfaa76c681e3790bb1b436b49cc39d57eb8bfe7f6fc73d064818e22738ce1c9
+  data.tar.gz: e757a94164248e188c46413a706ec2418eb99c97f28bc5631305620c064b8fd7b04a6621d4809e405f95ac4d2228c22509700169f0049b581a1998ceba364acd

data/.rubocop.yml

@@ -21,6 +21,9 @@ Style/DoubleNegation:
 Style/NumericPredicate:
   Enabled: false
 
+Style/OptionalBooleanParameter:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
 
@@ -48,6 +51,9 @@ Layout/LeadingCommentSpace:
 Layout/LineLength:
   Max: 120
 
+Lint/UselessMethodDefinition:
+  Enabled: false
+
 Metrics/AbcSize:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.8.1] - 2025-06-21
+
+- Add migration guide message.
+- Add upper version.
+
+## [0.8.0] - 2025-02-22
+
+- changed `persisted_flag_callback_control` default from `false` to `true`.
+- adjusted to save errors as soon as an invalid is found.
+- drop support rails 6.1.x.
+
 ## [0.7.0] - 2025-02-12
 
 - rename ActiveRecordCompose::InnerModel to ActiveRecordCompose::WrappedModel

data/README.md

@@ -15,7 +15,7 @@ activemodel (activerecord) form object pattern. it embraces multiple AR models a
   - [I18n](#i18n)
 - [Advanced Usage](#advanced-usage)
   - [`destroy` option](#destroy-option)
-  - [Callback ordering by `#save`, `#create` and `#update`](#callback-ordering-by-save-create-and-update)
+  - [Callback ordering by `#persisted?`](#callback-ordering-by-persisted)
 - [Links](#links)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -284,52 +284,15 @@ class AccountRegistration < ActiveRecordCompose::Model
 end
 ```
 
-### Callback ordering by `#save`, `#create` and `#update`.
+### Callback ordering by `#persisted?`
 
 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!' }
-  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!' }
-end
-```
-
-```ruby
-model = ComposedModel.new
-
-model.save
-# before_save called!
-# after_save called!
-
-model.create
-# before_save called!
-# before_create called!
-# after_create called!
-# after_save called!
-
-model.update
-# before_save called!
-# before_update called!
-# after_update called!
-# after_save called!
-```
+default value is `true`, behavior when set to `false` will be removed in the next release.
 
 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.
+Depending on the evaluation result of `#persisted?`,
+either the create-related callbacks or the update-related callbacks will be triggered.
 
 ```ruby
 class ComposedModel < ActiveRecordCompose::Model
@@ -382,10 +345,43 @@ model.save # or `model.update` (the same callbacks will be triggered in all case
 # after_save called!
 ```
 
-When `persisted_flag_callback_control` is `true`, `#create` is not supported.
+When `persisted_flag_callback_control` is set to false,
+the execution of `#create`, `#update`, or `#save` determines which callbacks will be triggered.
+This behavior will no longer be supported in the next release.
+
+```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!' }
+  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!' }
+end
+```
 
 ```ruby
-model.create  # => raises RuntimeError
+model = ComposedModel.new
+
+model.save
+# before_save called!
+# after_save called!
+
+model.create
+# before_save called!
+# before_create called!
+# after_create called!
+# after_save called!
+
+model.update
+# before_save called!
+# before_update called!
+# after_update called!
+# after_save called!
 ```
 
 ## Links

data/UPGRADE.md

@@ -0,0 +1,113 @@
+# Migration Guide: `active_record_compose` 0.8.x to 0.9.0+
+
+⚠️ **Breaking Change**
+
+This guide explains how to migrate from version **0.8.x** to **0.9.0 or later**, assuming that your codebase includes:
+
+```ruby
+self.persisted_flag_callback_control = false
+```
+
+This setting was officially **deprecated** in 0.9.0 and is **no longer supported**. Migration is required to adopt the current default behavior.
+
+## Background
+
+In version **0.7.x**, the default value of `persisted_flag_callback_control` was `false`.
+
+In **0.8.x**, the default was changed to `true`.
+If you are still using `false` in your models, it means you have **explicitly overridden the default**, likely to preserve backward-compatible behavior.
+
+This guide helps you safely migrate to the new behavior while preserving intended callback semantics.
+
+## Goal of the Migration
+
+- Remove any use of `persisted_flag_callback_control = false`
+- Adjust callback definitions to align with the semantics of `#persisted?`
+
+## Step 1 – Remove Deprecated Flag
+
+Find and remove all instances of:
+
+```diff
+-self.persisted_flag_callback_control = false
+```
+
+## Step 2 – Understand Callback Behavior Changes
+
+With `persisted_flag_callback_control = true`, whether a callback is fired depends on the return value of `#persisted?`, not the method used (`create` or `update`).
+
+### When saving with `#update`:
+
+If `persisted?` returns `false`, then:
+
+- `before_update`
+- `after_update`
+- `around_update`
+
+will **not** be triggered.
+
+✅ Recommended fix:
+
+If you don’t differentiate between creation and update phases, switch to `*_save` callbacks:
+
+```diff
+- before_update :track_change
++ before_save :track_change
+```
+
+### When saving with `#create`:
+
+If `persisted?` returns `true`, then:
+
+- `before_create`
+- `after_create`
+- `around_create`
+
+will **not** be triggered.
+
+✅ Recommended fix:
+
+Again, prefer `*_save` if you're using shared logic across creation and update:
+
+```diff
+- after_create :send_notification
++ after_save :send_notification
+```
+
+## Step 3 – Override `#persisted?` if Needed
+
+If your composed model wraps an ActiveRecord instance and delegates its persistence logic, be sure to override `#persisted?` to reflect the correct state:
+
+```ruby
+class Foo < ActiveRecordCompose::Model
+  def initialize(bar = Bar.new)
+    super()
+    @bar = bar
+  end
+
+  def persisted? = bar.persisted?
+
+  private
+
+  attr_reader :bar
+end
+```
+
+## Migration Checklist ✅
+
+- [ ] All models now `persisted_flag_callback_control` omit it entirely
+- [ ] All callback definitions have been reviewed and updated
+- [ ] Any `*_create` or `*_update` callbacks have been replaced with `*_save` where applicable
+- [ ] `#persisted?` is correctly overridden where needed
+- [ ] All tests pass and expected callbacks are fired
+
+## Why This Change?
+
+By aligning callback behavior with `persisted?`, you gain:
+
+- Clearer intent and semantics
+- More accurate behavior when composing or wrapping persisted models
+- Improved compatibility with Rails conventions
+- Less surprising callback triggering
+
+If you have questions or run into edge cases, feel free to [open an issue](https://github.com/hamajyotan/active_record_compose/issues) or start a discussion.

data/lib/active_record_compose/model.rb

@@ -16,7 +16,7 @@ module ActiveRecordCompose
     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.
+    # The current default value is `true`, behavior when set to `false` will be removed in the next release.
     #
     # When `persisted_flag_callback_control` is set to `true`,
     # the occurrence of callbacks depends on the evaluation result of `#persisted?`.
@@ -53,7 +53,7 @@ module ActiveRecordCompose
     # * after_create
     # * after_save
     #
-    class_attribute :persisted_flag_callback_control, instance_accessor: false, default: false
+    class_attribute :persisted_flag_callback_control, instance_accessor: false, default: true
 
     define_model_callbacks :save
     define_model_callbacks :create
@@ -78,6 +78,14 @@ module ActiveRecordCompose
         if self.class.persisted_flag_callback_control
           with_callbacks { save_models(bang: false) }
         else
+          # steep:ignore:start
+          deprecator.warn(
+            'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+            'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+          )
+          # steep:ignore:end
           run_callbacks(:save) { save_models(bang: false) }
         end
       rescue ActiveRecord::RecordInvalid
@@ -97,6 +105,14 @@ module ActiveRecordCompose
         if self.class.persisted_flag_callback_control
           with_callbacks { save_models(bang: true) }
         else
+          # steep:ignore:start
+          deprecator.warn(
+            'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+            'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+          )
+          # steep:ignore:end
           run_callbacks(:save) { save_models(bang: true) }
         end
       end || raise_on_save_error
@@ -127,11 +143,21 @@ module ActiveRecordCompose
     #   # after_create called!
     #   # after_save called!
     #
+    # @deprecated
     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
 
+      # steep:ignore:start
+      deprecator.warn(
+        'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+        'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+        '(Alternatively, exclude statements that set `false`) ' \
+        'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+      )
+      # steep:ignore:end
+
       assign_attributes(attributes)
       return false if invalid?
 
@@ -144,11 +170,21 @@ module ActiveRecordCompose
 
     # Behavior is same to `#create`, but raises an exception prematurely on failure.
     #
+    # @deprecated
     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
 
+      # steep:ignore:start
+      deprecator.warn(
+        'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+        'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+        '(Alternatively, exclude statements that set `false`) ' \
+        'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+      )
+      # steep:ignore:end
+
       assign_attributes(attributes)
       valid? || raise_validation_error
 
@@ -190,6 +226,14 @@ module ActiveRecordCompose
         if self.class.persisted_flag_callback_control
           with_callbacks { save_models(bang: false) }
         else
+          # steep:ignore:start
+          deprecator.warn(
+            'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+            'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+          )
+          # steep:ignore:end
           with_callbacks(context: :update) { save_models(bang: false) }
         end
       rescue ActiveRecord::RecordInvalid
@@ -207,22 +251,42 @@ module ActiveRecordCompose
         if self.class.persisted_flag_callback_control
           with_callbacks { save_models(bang: true) }
         else
+          # steep:ignore:start
+          deprecator.warn(
+            'The behavior with `persisted_flag_callback_control` set to `false` will be removed in 0.9.0. ' \
+            'Use `self.persisted_flag_callback_control = true` set to `true`. ' \
+            '(Alternatively, exclude statements that set `false`) ' \
+            'cf. https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md ',
+          )
+          # steep:ignore:end
           with_callbacks(context: :update) { save_models(bang: true) }
         end
       end || raise_on_save_error
     end
 
+    # 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.
+    def persisted? = super
+
     private
 
     def models = @__models ||= ActiveRecordCompose::ComposedCollection.new(self)
 
     def validate_models
-      models.__wrapped_models.select { _1.invalid? }.each { errors.merge!(_1) }
+      models.__wrapped_models.lazy.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) }
+      run_callbacks(:save) { run_callbacks(callback_context(context:), &block) }
+    end
+
+    def callback_context(context: nil)
+      context || (persisted? ? :update : :create)
     end
 
     def save_models(bang:)
@@ -234,5 +298,15 @@ module ActiveRecordCompose
     def raise_on_save_error = raise ActiveRecord::RecordNotSaved.new(raise_on_save_error_message, self)
 
     def raise_on_save_error_message = 'Failed to save the model.'
+
+    # steep:ignore:start
+    def deprecator
+      if ActiveRecord.respond_to?(:deprecator)
+        ActiveRecord.deprecator
+      else # for rails 7.0.x or lower
+        ActiveSupport::Deprecation
+      end
+    end
+    # steep:ignore:end
   end
 end

data/lib/active_record_compose/transaction_support.rb

@@ -18,7 +18,7 @@ module ActiveRecordCompose
 
       def with_connection(&) = ar_class.with_connection(&) # steep:ignore
 
-      def composite_primary_key? = false
+      def composite_primary_key? = false # steep:ignore
 
       private
 
@@ -28,6 +28,6 @@ module ActiveRecordCompose
     def id = nil
 
     def trigger_transactional_callbacks? = true
-    def restore_transaction_record_state(_force_restore_state = false) = nil # rubocop:disable Style/OptionalBooleanParameter
+    def restore_transaction_record_state(_force_restore_state = false) = nil
   end
 end

data/lib/active_record_compose/version.rb

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

data/lib/active_record_compose.rb

@@ -7,3 +7,15 @@ require_relative 'active_record_compose/model'
 
 module ActiveRecordCompose
 end
+
+if ActiveRecordCompose::VERSION == '0.8.1'
+  unless ENV['ACTIVE_RECORD_COMPOSE_SILENCE_DEPRECATION'] # rubocop:disable Style/SoleNestedConditional
+    warn <<~WARN
+
+      [DEPRECATION] You are using active_record_compose version 0.8.1, which is deprecated.
+      Please upgrade to the latest version.
+      See: https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md
+
+    WARN
+  end
+end

data/sig/active_record_compose.rbs

@@ -89,6 +89,7 @@ module ActiveRecordCompose
     private
     def models: -> ComposedCollection
     def with_callbacks: (?context: (nil | :create | :update)) { () -> bool } -> bool
+    def callback_context: (?context: (nil | :create | :update)) -> (:create | :update)
     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.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - hamajyotan
 bindir: bin
 cert_chain: []
-date: 2025-02-12 00:00:00.000000000 Z
+date: 2025-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -15,14 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
 description: activemodel form object pattern. it embraces multiple AR models and provides
   a transparent interface as if they were a single model.
 email:
@@ -36,6 +42,7 @@ files:
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
+- UPGRADE.md
 - lib/active_record_compose.rb
 - lib/active_record_compose/composed_collection.rb
 - lib/active_record_compose/delegate_attribute.rb
@@ -52,8 +59,17 @@ 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.7.0
+  documentation_uri: https://www.rubydoc.info/gems/active_record_compose/0.8.1
   rubygems_mfa_required: 'true'
+post_install_message: |2+
+
+  Notice: This version (0.8.1) is deprecated.
+
+  Please upgrade to the latest version of `active_record_compose` as soon as possible.
+  Future releases will not support this version.
+
+  See https://github.com/hamajyotan/active_record_compose/blob/v0.8.1/UPGRADE.md for migration steps.
+
 rdoc_options: []
 require_paths:
 - lib
@@ -72,3 +88,4 @@ rubygems_version: 3.6.2
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []
+...