active_record_compose 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2622aa32a886a2c21fcc7836254285cb92f1ce7745674297c3e7fe46bcbe556a
-  data.tar.gz: 747acd3e97cb78aba78b9d3f2c87ab4d9bd34b0727aaf2a1c94d9520ea9eaa08
+  metadata.gz: 148413ab669022c937e7f4775cff13dc018c9ba190014b130c10b9ca7e767a3f
+  data.tar.gz: 51ec332dcf2decf04dfb7f3bf8f0d38bf791d36d960d0d19c388608ef3f33a32
 SHA512:
-  metadata.gz: e6002732e8e6fa09269ccb4a7635af4ef683d06af14e829aa062846c6dbb90c2942d5b3cc2b4d715eeef2182498e732d33b5ae004836ff703f8d8235fec12c70
-  data.tar.gz: 18d3f9a635d3f4bf940eeb4020824fa7fc7d91cf27b0a99aa253af53e31fdca6bebd69d402537bea29749de26eba3f5a261e10a3ef2ebf079294e7fc3dbd5127
+  metadata.gz: 7db6b03f1a56d9d9d1ef0427362b65966bcfca997a465c4ce843d5dad9c4237e43b443ce0620629c665ab09163bf46fd362976009c2e426ae40849c1a41d18bd
+  data.tar.gz: 43ecb29b976c4136650e2152f1533af7e06de40afeba68f7265e97ba6eff208165271c338b4348d44127d850ebe75de2908eea60a18e986ef47e181d95d6e784

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [1.3.0] - 2026-08-09
+
+* Support secondary and multiple database
+  (https://github.com/hamajyotan/active_record_compose/pull/74)
+  - When models connecting to different databases are used together, the system behaves in a manner simulating a two-phase commit.
+  - Due to the nature of the ActiveRecord API supported by Rails, a true two-phase commit is not implemented; instead, transactions are nested when multiple database connections are involved.
+  - Note that operations remain unchanged when all models belong to a single primary database.
+
+## [1.2.1] - 2026-03-21
+
+* Improved clarity of error when accessing uninitialized attributes.
+  (https://github.com/hamajyotan/active_record_compose/pull/71)
+* doc: Minor document adjustments, etc.
+
 ## [1.2.0] - 2026-01-05
 
 * Avoid issuing multiple saves on the same object.

data/README.md

@@ -1,7 +1,7 @@
 # ActiveRecordCompose
 
 ActiveRecordCompose lets you build form objects that combine multiple ActiveRecord models into a single, unified interface.
-More than just a simple form object, it is designed as a **business-oriented composed model** that encapsulates complex operations-such as user registration spanning multiple tables-making them easier to write, validate, and maintain.
+More than a simple form object, ActiveRecordCompose is designed as a **business-oriented composed model** that encapsulates complex operations, such as user registration spanning multiple tables, making them easier to write, validate, and maintain.
 
 [![Gem Version](https://badge.fury.io/rb/active_record_compose.svg)](https://badge.fury.io/rb/active_record_compose)
 ![CI](https://github.com/hamajyotan/active_record_compose/workflows/CI/badge.svg)
@@ -29,15 +29,14 @@ More than just a simple form object, it is designed as a **business-oriented com
 
 ## Motivation
 
-In Rails, `ActiveRecord::Base` is responsible for persisting data to the database.
-By defining validations and callbacks, you can model use cases effectively.
+In Rails, `ActiveRecord::Base` is responsible for persisting data to the database and modeling application behavior through validations and callbacks.
 
 However, when a single model must serve multiple different use cases, you often end up with conditional validations (`on: :context`) or workarounds like `save(validate: false)`.
 This mixes unrelated concerns into one model, leading to unnecessary complexity.
 
-`ActiveModel::Model` helps here — it provides the familiar API (`attribute`, `errors`, validations, callbacks) without persistence, so you can isolate logic per use case.
+`ActiveModel::Model` helps address this by providing a familiar API (`attribute`, `errors`, validations, callbacks) without persistence, allowing you to isolate logic per use case.
 
-**ActiveRecordCompose** builds on `ActiveModel::Model` and is a powerful **business object** that acts as a first-class model within Rails.
+**ActiveRecordCompose** builds on `ActiveModel::Model` and provides a powerful **business object** that acts as a first-class model within Rails.
 - Transparently accesses attributes across multiple models
 - Saves all associated models atomically in a transaction
 - Collects and exposes error information consistently
@@ -60,6 +59,10 @@ $ bundle
 
 ## Quick Start
 
+For a complete runnable application, see the Sample Application section below.
+
+The examples in this section focus on ActiveRecordCompose itself and intentionally omit surrounding application code such as migrations, routes, views, and jobs.
+
 ### Basic Example
 
 Suppose you have two models:
@@ -106,7 +109,7 @@ class UserRegistration < ActiveRecordCompose::Model
 end
 ```
 
-Usage:
+Example usage:
 
 ```ruby
 # === Standalone script ===
@@ -174,7 +177,7 @@ registration.attributes
 
 ### Unified Error Handling
 
-Validation errors from inner models are collected into the composed model:
+Validation errors from the inner models are collected into the composed object:
 
 ```ruby
 user_registration = UserRegistration.new(
@@ -274,7 +277,7 @@ model.save
 
 ### Notes on adding models dynamically
 
-Avoid adding `models` to the models array **after validation has already run**
+Avoid adding models to the `models` array **after validation has already run**
 (for example, inside `after_validation` or `before_save` callbacks).
 
 ```ruby
@@ -323,5 +326,5 @@ 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).
+Everyone interacting in the ActiveRecordCompose 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/attributes.rb

@@ -3,6 +3,7 @@
 require_relative "attributes/attribute_predicate"
 require_relative "attributes/delegation"
 require_relative "attributes/querying"
+require_relative "exceptions"
 
 module ActiveRecordCompose
   # Provides attribute-related functionality for use within ActiveRecordCompose::Model.
@@ -127,7 +128,11 @@ module ActiveRecordCompose
     #
     # @see #attributes
     # @return [Array<String>] array of attribute name.
-    def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
+    def attribute_names
+      _require_attributes_initialized do
+        super + delegated_attributes.to_a.map { _1.attribute_name }
+      end
+    end
 
     # Returns a hash with the attribute name as key and the attribute value as value.
     # Attributes declared with {.delegate_attribute} are also merged.
@@ -155,7 +160,24 @@ module ActiveRecordCompose
     #
     # @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) })
+      _require_attributes_initialized do
+        super.merge(*delegated_attributes.to_a.map { _1.attribute_hash(self) })
+      end
+    end
+
+    private
+
+    def _write_attribute(...) = _require_attributes_initialized { super } # steep:ignore
+
+    def attribute(...) = _require_attributes_initialized { super }
+
+    def _require_attributes_initialized
+      unless @attributes
+        raise ActiveRecordCompose::UninitializedAttribute,
+              "No attributes have been set. Is proper initialization performed, such as calling `super` in `initialize`?"
+      end
+
+      yield
     end
   end
 end

data/lib/active_record_compose/composed_collection.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "set"
 require_relative "wrapped_model"
 
 module ActiveRecordCompose
@@ -117,7 +118,7 @@ module ActiveRecordCompose
     def symbol_proc_map
       @symbol_proc_map ||=
         Hash.new do |h, k|
-          h[k] = -> { owner.__send__(k) }
+          h[k] = -> { owner.__send__(k) } # steep:ignore
         end
     end
 

data/lib/active_record_compose/exceptions.rb

@@ -26,4 +26,19 @@ module ActiveRecordCompose
   #     outer.save  #=> raises ActiveRecordCompose::CircularReferenceDetected
   #
   class CircularReferenceDetected < StandardError; end
+
+  # Occurs when accessing Attributes without initializing it.
+  #
+  # @example
+  #     class Model < ActiveRecordCompose::Model
+  #       def initialize
+  #         # Intentionally not calling super...
+  #       end
+  #
+  #       attribute :foo
+  #     end
+  #     model = Model.new
+  #     model.foo = 1  #=> raises ActiveRecordCompose::UninitializedAttribute
+  #
+  class UninitializedAttribute < StandardError; end
 end

data/lib/active_record_compose/transaction_support/active_transaction.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ActiveRecordCompose
+  module TransactionSupport
+    # @private
+    # steep:ignore:start
+
+    # In older versions, the ActiveRecord::Transaction object is not passed to the block argument of #transaction.
+    # So instead, we define a transaction object that can be evaluated equivalently.
+    # This follow-up will no longer be necessary when support for Rails 7.1 is dropped.
+    #
+    class ActiveTransaction
+      def initialize(transaction)
+        @real_transaction = transaction
+      end
+
+      attr_reader :real_transaction
+
+      def open? = !closed?
+
+      def closed? = real_transaction&.state&.completed?
+
+      def ==(other)
+        return true if equal?(other)
+        return false unless self.class == other.class
+
+        real_transaction == other.real_transaction
+      end
+
+      def eql?(other)
+        return true if equal?(other)
+        return false unless self.class == other.class
+
+        real_transaction.eql?(other.real_transaction)
+      end
+
+      def hash = real_transaction.hash
+    end
+
+    # steep:ignore:end
+  end
+end

data/lib/active_record_compose/transaction_support/transaction_coordinator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "set"
+
+module ActiveRecordCompose
+  module TransactionSupport
+    # @private
+    class TransactionCoordinator
+      def add_transaction(active_transaction)
+        transactions << active_transaction
+      end
+
+      # The before_commit callback is controlled so that
+      # it runs just before the outermost transaction commits,
+      # but not just before any inner transactions commit.
+      #
+      def on_before_comitted
+        return if @_before_committed_called
+
+        yield
+        @_before_committed_called = true
+      end
+
+      # It processes after_commit/after_rollback only immediately
+      # after all transactions are closed.
+      #
+      def on_after_transaction
+        return unless all_finished?
+
+        with_transaction_cleanup { yield }
+      end
+
+      private
+
+      def with_transaction_cleanup
+        yield
+      ensure
+        @_before_committed_called = false
+        transactions.reject! { _1.closed? }
+      end
+
+      def all_finished? = transactions.all? { _1.closed? }
+
+      def transactions = @transactions ||= Set.new
+    end
+  end
+end

data/lib/active_record_compose/transaction_support.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/module"
+require_relative "transaction_support/active_transaction"
+require_relative "transaction_support/transaction_coordinator"
 
 module ActiveRecordCompose
   module TransactionSupport
@@ -86,17 +88,17 @@ module ActiveRecordCompose
 
       # @private
       def before_committed!
-        _run_before_commit_callbacks
+        transaction_coordinator.on_before_comitted { _run_before_commit_callbacks }
       end
 
       # @private
       def committed!(should_run_callbacks: true)
-        _run_commit_callbacks if should_run_callbacks
+        transaction_coordinator.on_after_transaction { _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
+        transaction_coordinator.on_after_transaction { _run_rollback_callbacks if should_run_callbacks }
       end
     end
 
@@ -104,23 +106,49 @@ module ActiveRecordCompose
 
     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
-          ensure_finalize = !connection.transaction_open?
+    def connection_pools
+      pools =
+        models.compact.flat_map do |model|
+          if model.is_a?(ActiveRecordCompose::TransactionSupport)
+            model.connection_pools
+          elsif model.is_a?(ActiveRecord::Base)
+            connection_pool(ar_class: model.class)
+          else
+            [] # : Array[ActiveRecord::ConnectionAdapters::ConnectionPool]
+          end
+        end
+      pools << connection_pool if pools.blank?
+      pools.uniq
+    end
 
-          connection.transaction do
-            connection.add_transaction_record(self, ensure_finalize || has_transactional_callbacks?) # steep:ignore
+    private
 
-            yield.tap { raise ActiveRecord::Rollback unless _1 }
-          end || false
+    # @private
+    def with_transaction_returning_status(&block)
+      procs = connection_pools.inject(block) do |inner_proc, pool|
+        -> do
+          pool.with_connection do |connection|
+            with_pool_transaction_isolation_level(connection) do
+              ensure_finalize = !connection.transaction_open?
+
+              connection.transaction do |tran|
+                tran ||= ActiveTransaction.new(connection.current_transaction) # steep:ignore
+                transaction_coordinator.add_transaction(tran)
+                connection.add_transaction_record(self, ensure_finalize || has_transactional_callbacks?)
+
+                inner_proc.call.tap { raise ActiveRecord::Rollback unless _1 }
+              end
+            end
+          end
         end
       end
+      procs.call || false
     end
 
+    # @private
+    def transaction_coordinator = @transaction_coordinator ||= TransactionCoordinator.new
+
     # @private
     def default_ar_class = ActiveRecord::Base
 

data/lib/active_record_compose/validations.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "composed_collection"
+require_relative "exceptions"
 
 module ActiveRecordCompose
   using ComposedCollection::PackagePrivate
@@ -44,7 +45,7 @@ module ActiveRecordCompose
     #   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.
+    #   but also aggregates error information for objects stored in {ActiveRecordCompose::Model#models} when validation is performed.
     #
     #       class Account < ActiveRecord::Base
     #         validates :name, :email, presence: true

data/lib/active_record_compose/version.rb

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

data/sig/_internal/package_private.rbs

@@ -11,6 +11,9 @@ module ActiveRecordCompose
 
     @attributes: untyped
 
+    private
+    def _require_attributes_initialized: [T] () { () -> T } -> T
+
     class AttributePredicate
       def initialize: (untyped value) -> void
       def call: -> bool
@@ -115,6 +118,8 @@ module ActiveRecordCompose
     include ActiveSupport::Callbacks
     extend ActiveSupport::Callbacks::ClassMethods
 
+    @transaction_coordinator: ActiveRecordCompose::TransactionSupport::TransactionCoordinator
+
     def self.before_commit: (*untyped) -> untyped
     def self.after_commit: (*untyped) -> untyped
     def self.after_rollback: (*untyped) -> untyped
@@ -124,11 +129,28 @@ module ActiveRecordCompose
     def _run_before_commit_callbacks: () -> untyped
     def _run_commit_callbacks: () -> untyped
     def _run_rollback_callbacks: () -> untyped
+    def connection_pools: () -> Array[ActiveRecord::ConnectionAdapters::ConnectionPool]
 
     private
+    def models: -> ComposedCollection
     def default_ar_class: -> singleton(ActiveRecord::Base)
     def connection_pool: (?ar_class: singleton(ActiveRecord::Base)) -> ActiveRecord::ConnectionAdapters::ConnectionPool
     def with_pool_transaction_isolation_level: [T] (ActiveRecord::ConnectionAdapters::AbstractAdapter) { () -> T } -> T
+    def transaction_coordinator: () -> ActiveRecordCompose::TransactionSupport::TransactionCoordinator
+
+    class TransactionCoordinator
+      @_before_committed_called: bool
+      @transactions: Set[ActiveRecord::ConnectionAdapters::Transaction]
+
+      def add_transaction: (ActiveRecord::ConnectionAdapters::Transaction) -> void
+      def on_after_transaction: () { () -> void } -> void
+      def on_before_comitted: () { () -> void } -> void
+
+      private
+      def all_finished?: -> bool
+      def transactions: () -> Set[ActiveRecord::ConnectionAdapters::Transaction]
+      def with_transaction_cleanup: () { () -> void } -> void
+    end
   end
 
   module Persistence

data/sig/active_record_compose.rbs

@@ -98,4 +98,7 @@ module ActiveRecordCompose
   class Railtie < Rails::Railtie
     extend Rails::Initializable::ClassMethods
   end
+
+  class UninitializedAttribute < StandardError
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - hamajyotan
@@ -56,6 +56,8 @@ files:
 - lib/active_record_compose/persistence.rb
 - lib/active_record_compose/railtie.rb
 - lib/active_record_compose/transaction_support.rb
+- lib/active_record_compose/transaction_support/active_transaction.rb
+- lib/active_record_compose/transaction_support/transaction_coordinator.rb
 - lib/active_record_compose/validations.rb
 - lib/active_record_compose/version.rb
 - lib/active_record_compose/wrapped_model.rb
@@ -84,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.16
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []