active_record_compose 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 954ce34124a1c8e83a45710e104dd965c407afb5ba296b74d4a4e5f9d13d971a
-  data.tar.gz: c1bb35ef5458a804f243b886c037aff3794822477ea2aaf5a57bfb12a4001477
+  metadata.gz: 9cdfb23b1af43681e6c4af3e9fed615bc3dc64873461bdee6f49c92f706f33e9
+  data.tar.gz: 4530c0987f038605cb6dc3da229df21e8cf16af29d6ca8cf3078b1dc933cc838
 SHA512:
-  metadata.gz: 2e7f81f304cec10420cb4f405ad8ad7f93f3811c7f43bf9952c05dbca84e651bbf0c851e648349d7e93986cf67cb177110785588a47c8951718f4d271cf53944
-  data.tar.gz: 8ac490bd69c0d51e6e89f1f198a4e052eccbeedcf1b234edfa8c9635819fe336bbe10b6b64b6b55907524543ad34eb9343892b00f54f2737a65c45c120456afa
+  metadata.gz: 10c37b41ff66acd993e2f5c412ed5f48213f29344a94e0ab27d40766e11f60197808d4d1b9e97118f729b4be1d272a4bdae100c8e06489c40008ac3c92f6fe61
+  data.tar.gz: 67c4086fce4661e89188161fd6d23610bca3dcb9ad8a6e781162909d07fbf750add3ad804d8e58bd92bf4fc1305bcebd2452a4a9d924af70e56e6a0217ecf70f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [1.0.0] - 2025-09-23
+
+- drop support rails 7.0.x
+
 ## [0.12.0] - 2025-08-21
 
 - Omits default arguments for `#update` and `#update!`. It's to align I/F with ActiveRecord.

data/README.md

@@ -1,6 +1,7 @@
 # ActiveRecordCompose
 
-activemodel (activerecord) form object pattern. it embraces multiple AR models and provides a transparent interface as if they were a single model.
+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.
 
 [![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)
@@ -10,16 +11,16 @@ activemodel (activerecord) form object pattern. it embraces multiple AR models a
 
 - [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)
+- [Quick Start](#quick-start)
+  - [Basic Example](#basic-example)
+  - [Attribute Delegation](#attribute-delegation)
+  - [Unified Error Handling](#unified-error-handling)
+  - [I18n Support](#i18n-support)
 - [Advanced Usage](#advanced-usage)
-  - [`destroy` option](#destroy-option)
-  - [Callback ordering by `#persisted?`](#callback-ordering-by-persisted)
-  - [`#save` with custom context option](#save-with-custom-context-option)
-- [Sample application as an example](#sample-application-as-an-example)
+  - [Destroy Option](#destroy-option)
+  - [Callback ordering with `#persisted?`](#callback-ordering-with-persisted)
+  - [Notes on adding models dynamically](#notes-on-adding-models-dynamically)
+- [Sample Application](#sample-application)
 - [Links](#links)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -28,11 +29,20 @@ activemodel (activerecord) form object pattern. it embraces multiple AR models a
 
 ## 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 Rails, `ActiveRecord::Base` is responsible for persisting data to the database.
+By defining validations and callbacks, you can model use cases effectively.
 
-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.
+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.
 
-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.
+`ActiveModel::Model` helps here — it provides the familiar API (`attribute`, `errors`, validations, callbacks) without persistence, so you can 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.
+- Transparently accesses attributes across multiple models
+- Saves all associated models atomically in a transaction
+- Collects and exposes error information consistently
+
+This leads to cleaner domain models, better separation of concerns, and fewer surprises in validations and callbacks.
 
 ## Installation
 
@@ -48,15 +58,15 @@ Then bundle
 $ bundle
 ```
 
-## Usage
+## Quick Start
 
-### Basic usage
+### Basic Example
 
-(Below, it is assumed that there are two AR model definitions, `Account` and `Profile`, for the sake of explanation.)
+Suppose you have two models:
 
 ```ruby
 class Account < ApplicationRecord
-  has_one :profile  # can work without `autosave:true`
+  has_one :profile
   validates :name, :email, presence: true
 end
 
@@ -66,40 +76,23 @@ class Profile < ApplicationRecord
 end
 ```
 
-Here is an example of designing a model that updates both Account and Profile at the same time, using `ActiveRecordCompose::Model`.
+You can compose them into one form object:
 
 ```ruby
 class UserRegistration < ActiveRecordCompose::Model
-  def initialize
+  def initialize(attributes = {})
     @account = Account.new
     @profile = @account.build_profile
-
-    super()  # Don't forget to call `super()`
-             # RuboCop's Lint/MissingSuper cop assists in addressing this.
-
+    super(attributes)
     models << account << profile
-    # Alternatively, it can also be written as follows:
-    #     models.push(account)
-    #     models.push(profile)
   end
 
-  # Attribute declarations using ActiveModel::Attributes are supported.
   attribute :terms_of_service, :boolean
-
-  # 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
 
-  # 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
 
@@ -113,12 +106,11 @@ class UserRegistration < ActiveRecordCompose::Model
 end
 ```
 
-The above model is used as follows.
+Usage:
 
 ```ruby
+# === Standalone script ===
 registration = UserRegistration.new
-
-# Atomically update Account and Profile.
 registration.update!(
   name: "foo",
   email: "bar@example.com",
@@ -128,38 +120,41 @@ registration.update!(
   email_confirmation: "bar@example.com",
   terms_of_service: true,
 )
-```
 
-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.
+# === Or, in a Rails controller with strong parameters ===
+class UserRegistrationsController < ApplicationController
+  def create
+    @registration = UserRegistration.new(user_registration_params)
+    if @registration.save
+      redirect_to root_path, notice: "Registered!"
+    else
+      render :new
+    end
+  end
 
-```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
+  def user_registration_params
+    params.require(:user_registration).permit(
+      :name, :email, :firstname, :lastname, :age, :email_confirmation, :terms_of_service
+    )
+  end
+end
 ```
 
-### `delegate_attribute`
+Both `Account` and `Profile` will be updated **atomically in one transaction**.
+
+### Attribute Delegation
 
-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."
+`delegate_attribute` allows transparent access to attributes of inner models:
 
 ```ruby
-  # 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
+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`.
+They are also included in `#attributes`:
 
 ```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,
@@ -171,21 +166,21 @@ registration.attributes
 # }
 ```
 
-### Promotion to model from AR-model errors
+### Unified Error Handling
 
-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`.
+Validation errors from inner models are collected into the composed model:
 
 ```ruby
-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 = UserRegistration.new(
+  email: "foo@example.com",
+  email_confirmation: "BAZ@example.com",
+  age: 18,
+  terms_of_service: true,
+)
 
-user_registration.save
-#=> false
+user_registration.save # => false
 
-user_registration.errors.to_a
+user_registration.errors.full_messages
 # => [
 #   "Name can't be blank",
 #   "Firstname can't be blank",
@@ -194,12 +189,10 @@ user_registration.errors.to_a
 # ]
 ```
 
-### I18n
+### I18n Support
 
-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`.
-
-(Replace `en` as appropriate in the context.)
+When `#save!` raises `ActiveRecord::RecordInvalid`,
+make sure you have locale entries such as:
 
 ```yaml
 en:
@@ -209,204 +202,104 @@ en:
         record_invalid: 'Validation failed: %{errors}'
 ```
 
-Alternatively, the following definition is also acceptable:
-
-```yaml
-en:
-  errors:
-    messages:
-      record_invalid: 'Validation failed: %{errors}'
-```
+For more complete usage patterns, see the [Sample Application](#sample-application) below.
 
 ## Advanced Usage
 
-### `destroy` option
+### 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 || account.build_profile
-    super()
-    models.push(account)
-    models.push(profile, destroy: true)
-  end
-
-  before_save :set_resigned_at
-
-  private
-
-  attr_reader :account, :profile
-
-  def set_resigned_at
-    account.resigned_at = Time.zone.now
-  end
-end
-```
 ```ruby
-account = Account.last
-
-account.resigned_at.present?  #=> nil
-account.profile.blank?        #=> false
-
-account_resignation = AccountResignation.new(account)
-account_resignation.save!
-
-account.reload
-account.resigned_at.present?  #=> Tue, 02 Jan 2024 22:58:01.991008870 JST +09:00
-account.profile.blank?        #=> true
+models.push(profile, destroy: true)
 ```
 
-Conditional destroy (or save) can be written like this.
+This deletes the model on `#save` instead of persisting it.
+Conditional deletion is also supported:
 
 ```ruby
-class AccountRegistration < ActiveRecordCompose::Model
-  def initialize(account)
-    @account = account
-    @profile = account.profile || account.build_profile
-    super()
-    models.push(account)
-
-    # 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
+models.push(profile, destroy: -> { profile_field_is_blank? })
+```
 
-  delegate_attribute :email, to: :account
-  delegate_attribute :name, :age, to: :profile
+### Callback ordering with `#persisted?`
 
-  private
+The result of `#persisted?` determines **which callbacks are fired**:
 
-  attr_reader :account, :profile
+- `persisted? == false` -> create callbacks (`before_create`, `after_create`, ...)
+- `persisted? == true` -> update callbacks (`before_update`, `after_update`, ...)
 
-  def profile_field_is_blank?
-    firstname.blank? && lastname.blank? && age.blank?
-  end
-end
-```
-
-### Callback ordering by `#persisted?`
-
-The behavior of `(before|after|around)_create` and `(before|after|around)_update` hooks depending on the evaluation result of `#persisted?`,
-either the create-related callbacks or the update-related callbacks will be triggered.
+This matches the behavior of normal ActiveRecord models.
 
 ```ruby
 class ComposedModel < ActiveRecordCompose::Model
-  # ...
-
-  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!' }
+  before_save     { puts "before_save" }
+  before_create   { puts "before_create" }
+  before_update   { puts "before_update" }
+  after_create    { puts "after_create" }
+  after_update    { puts "after_update" }
+  after_save      { puts "after_save" }
 
   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
+    account.persisted?
   end
 end
 ```
 
-```ruby
-# when `model.persisted?` returns `true`
+Example:
 
+```ruby
+# When persisted? == false
 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.save
+# => before_save
+# => before_create
+# => after_create
+# => after_save
 
+# When persisted? == true
 model = ComposedModel.new
+def model.persisted?; true; end
 
-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!
+model.save
+# => before_save
+# => before_update
+# => after_update
+# => after_save
 ```
 
-### `#save` with custom context option
-
-The interface remains consistent with standard ActiveModel and ActiveRecord models, so the :context option works with #save.
-
-```ruby
-composed_model.valid?(:custom_context)
-
-composed_model.save(context: :custom_context)
-```
+### Notes on adding models dynamically
 
-However, this may not be ideal from a design perspective.
-If your application requires complex context-specific validations, consider separating models by context.
+Avoid adding `models` to the models array **after validation has already run**
+(for example, inside `after_validation` or `before_save` callbacks).
 
 ```ruby
-class Account < ActiveRecord::Base
-  validates :name, presence: true
-  validates :email, presence: true
-  validates :email, format: { with: /\.edu\z/ }, on: :education
+class Example < ActiveRecordCompose::Model
+  before_save { models << AnotherModel.new }
 end
+```
 
-class Registration < ActiveRecordCompose::Model
-  def initialize(attributes = {})
-    models.push(@account = Account.new)
-    super(attributes)
-  end
-
-  attribute :accept, :boolean
-  validates :accept, presence: true, on: :education
+In this case, the newly added model will **not** run validations for the current save cycle.
+This may look like a bug, but it is the expected behavior: validations are only applied
+to models that were registered before validation started.
 
-  delegate_attribute :name, :email, to: :account
-
-  private
+We intentionally do not restrict this at the framework level, since there may be valid
+advanced use cases where models are manipulated dynamically.
+Instead, this behavior is documented here so that developers can make an informed decision.
 
-  attr_reader :account
-end
-```
-```ruby
-r = Registration.new(name: 'foo', email: 'example@example.com', accept: false)
-r.valid?
-#=> true
-
-r.valid?(:education)
-#=> false
-r.errors.map { [_1.attribute, _1.type] }
-#=> [[:email, :invalid], [:accept, :blank]]
-
-r.email = 'example@example.edu'
-r.accept = true
-
-r.valid?(:education)
-#=> true
-r.save(context: :education)
-#=> true
-```
+## Sample Application
 
-## Sample application as an example
+The sample app demonstrates a more complete usage of ActiveRecordCompose
+(e.g., user registration flows involving multiple models).
+It is not meant to cover every possible pattern, but can serve as a reference
+for putting the library into practice.
 
-With Github Codespaces, it can also be run directly in the browser. Naturally, a local environment is also possible.
+Try it out in your browser with GitHub Codespaces (or locally):
 
 - https://github.com/hamajyotan/active_record_compose-example
 
 ## Links
 
-- [Document from YARD](https://hamajyotan.github.io/active_record_compose/)
-- [Smart way to update multiple models simultaneously in Rails](https://dev.to/hamajyotan/smart-way-to-update-multiple-models-simultaneously-in-rails-51b6)
+- [API Documentation (YARD)](https://hamajyotan.github.io/active_record_compose/)
+- [Blog article introducing the concept](https://dev.to/hamajyotan/smart-way-to-update-multiple-models-simultaneously-in-rails-51b6)
 
 ## Development
 

data/lib/active_record_compose/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_compose
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 1.0.0
 platform: ruby
 authors:
 - hamajyotan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.1'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.1'
@@ -81,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: activemodel form object pattern
 test_files: []