active_interaction-extras 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 355913c4e3805b1373112d39fe9e686d6f1ae8b1cd7f2bca289443fd0cd37f63
-  data.tar.gz: f0e1a1611ca60b7199db6e18dc8152aa36fa76dde81cacfba1a6290a143ae544
+  metadata.gz: 0475c2d5f3660b0b545a444835c4cbcac60c5379fb352f43a427e9e3f12a5496
+  data.tar.gz: 4a70441a2ee4f40a01ab49bbcf2473007affbf5049db891c8d69a51462321338
 SHA512:
-  metadata.gz: 256a1e71cd64571c76418ab9a4688d827ca2f98d589610af9445ea084ef018646a28ad095b32df776163530a6c544c85d9a22e9732aaa8de85829d47c841306f
-  data.tar.gz: 38cea9d7580d1c9966b9f4b70168e10cd8f7f8548605d040f4ded80ee70040032f6e9bbca9c6ed1b22f2896ed9056192a7df003eac1e6dd299a5cfcbeafbfffe
+  metadata.gz: be224738bce179d169ef765122691eecf957a333ce5798094f3d0d31b431fafef253759bc64a1b23f09224e59f576cb0abdb4512b619de5ed326d67281b1d740
+  data.tar.gz: f947b78e59b9f047b6ac8fe913cfa9ed90280d4136cf03b9a6731689609e03b03badd94d6d2b30c191d77068a30d75b19756191ace663b665107f9fa415e368d

data/.github/workflows/ci.yml

@@ -19,10 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.7', '3.0', '3.1', '3.2']
+        ruby-version: ['3.2', '3.3', '3.4', '4.0']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
     # change this to (see https://github.com/ruby/setup-ruby#versioning):
@@ -31,5 +31,6 @@ jobs:
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+        cache-version: 3
     - name: Run tests
       run: bundle exec rake

data/CHANGELOG.md

@@ -4,6 +4,30 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-13
+
+- Add the `ar_relation` filter for `ActiveRecord::Relation` inputs without forcing relation loading when checking defaults
+- Extend the `uuid` filter to accept UUID versions 5 and 7.
+- Add Rails-style `NestedAttributes` for single and collection inputs, including `allow_destroy` and `reject_if`. Nested attributes now require explicit `permit:` rules.
+- Extend `StrongParams` to support object filters and custom permit lists for scalar, hash, object, array, and nested-attribute inputs.
+- Add `FormFor` to delegate form identity and routing to a model input, and `ModelNames` to derive route keys for namespaced forms.
+- Add an `AfterInitialize` callback hook plus `InitializeWith` and `AppendInputs` for post-initialization defaults that do not overwrite explicitly supplied inputs; allow `initialize_with` blocks to return `nil` and ensure defaults run after model-field initialization.
+- Add `InstanceRunnable` with one-shot instance execution and `save`/`save!` methods for form-style usage.
+- Add `IncludeErrors` to merge model validation errors into interaction errors and halt when the model is invalid.
+- Extend `ModelFields` with `assign_model_fields`, `assign_model_changes`, `save_model!`, and `save_model_changes!`; improve change detection for new records and plain objects, and preserve custom filter blocks.
+- Add `NamedCallbacks` for before, after, and around filter, validation, and execution callbacks.
+- Extend transaction helpers to allow disabling transactions and add `force_explicit_transactions!` and `list_missing_transaction_definition` for enforcing and auditing transaction choices.
+- Add ActiveJob inline execution and the `Current` context for the running job; avoid redundant job dispatch during GoodJob batch completion.
+- Add GoodJob batch and concurrency support, including current batch/event context, and `AddToBatch` for joining the current batch.
+- Add `AllRunner` to run an interaction for every record in its object scope, synchronously or through GoodJob bulk enqueueing.
+- Add `FileBlobs` helpers for working with ActiveStorage blobs, attachments, and signed IDs in form objects.
+- Refactor extensions for Zeitwerk autoloading; require Ruby 3.0+, ActiveModel and ActiveSupport 7.1+, and Zeitwerk 2+. Update CI to cover Ruby 3.2 through 4.0.
+
+## [1.1.0] - 2023-03-08
+
+- Add support for active_interaction v5
+- Fix `model_fields` helper
+
 ## [1.0.4] - 2022-06-08
 
 - Improve halt's robustness (https://github.com/antulik/active_interaction-extras/pull/13)

data/README.md

@@ -9,9 +9,11 @@ This gem contains the collection of useful extensions to [active_interaction](ht
 - [Filters](#filters)
     - [Anything](#anything)
     - [UUID](#uuid)
+    - [ActiveRecord Relation](#activerecord-relation)
 - [Filter Extensions](#filter-extensions)
     - [Hash: auto strip](#hash-auto-strip)
     - [Object: multiple classes](#object-multiple-classes)
+    - [Timezone support](#timezone-support)
 - [Extensions](#extensions)
   - [Filter alias](#filter-alias)
   - [Halt](#halt)
@@ -19,9 +21,22 @@ This gem contains the collection of useful extensions to [active_interaction](ht
   - [RunCallback](#runcallback)
   - [StrongParams](#strongparams)
   - [Transaction](#transaction)
+  - [NamedCallbacks](#namedcallbacks)
+  - [ModelNames](#modelnames)
+  - [FormFor](#formfor)
+  - [NestedAttributes](#nestedattributes)
+  - [InitializeWith](#initializewith)
+  - [AppendInputs](#appendinputs)
+  - [IncludeErrors](#includeerrors)
+  - [InstanceRunnable](#instancerunnable)
+  - [Current](#current)
+  - [AddToBatch](#addtobatch)
+  - [AllRunner](#allrunner)
+  - [FileBlobs](#fileblobs)
 - [Jobs](#jobs)
   - [ActiveJob](#activejob)
   - [Sidekiq](#sidekiq)
+  - [GoodJob](#goodjob)
 - [RSpec](#rspec)
 
 ## Installation
@@ -61,6 +76,20 @@ class Service < ActiveInteraction::Base
 end
 ```
 
+### ActiveRecord Relation
+
+```ruby
+class Service < ActiveInteraction::Base
+  ar_relation :users
+
+  def execute
+    users.where(active: true)
+  end
+end
+
+Service.run!(users: User.all) # accepts any ActiveRecord::Relation
+```
+
 ## Filter Extensions
 
 You can load all filter extensions with:
@@ -96,6 +125,27 @@ class Service < ActiveInteraction::Base
 end
 ```
 
+### Timezone support
+
+Parses time strings in the configured timezone. Requires a separate require:
+
+```ruby
+require 'active_interaction/extras/filter_extensions/timezone_support'
+
+class Service < ActiveInteraction::Base
+  time :epoch
+
+  def execute
+    epoch.iso8601
+  end
+end
+
+Time.use_zone('Bangkok') do
+  Service.run!(epoch: '2000-12-11 10:30')
+  # => '2000-12-11T10:30:00+07:00'
+end
+```
+
 
 ## Extensions
 
@@ -237,6 +287,248 @@ UpdateUserForm.run
 Comment.count # => 0
 ```
 
+### NamedCallbacks
+
+Provides friendly method names for ActiveInteraction's internal callbacks.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::NamedCallbacks
+
+  before_filter :normalize_inputs
+  after_validate :log_validation
+  before_execute :setup_context
+  after_execute :send_notification
+
+  def execute
+  end
+end
+```
+
+### ModelNames
+
+Note: This module is currently NOT included in `ActiveInteraction::Extras::All`.
+Sets up automatic ActiveModel naming for forms based on their class name for URL helpers.
+
+```ruby
+class ApplicationForm < ActiveInteraction::Base
+  include ActiveInteraction::Extras::ModelNames
+end
+
+class User::SignUpForm < ApplicationForm
+  # route_key is auto-set to :user_sign_up_forms
+end
+
+class User::UpdateForm < ApplicationForm
+  singular_resource_route_key! # route_key becomes :user_update_form
+end
+```
+
+### FormFor
+
+Makes form objects work with Rails URL helpers by delegating routing to a model field.
+
+```ruby
+class User::Form < ActiveInteraction::Base
+  include ActiveInteraction::Extras::FormFor
+
+  object :user
+  form_for :user # delegates routing to user
+
+  # url_for(form) => "/users/1"
+end
+```
+
+### NestedAttributes
+
+Rails-style `accepts_nested_attributes_for` for interactions.
+
+```ruby
+class Form < ActiveInteraction::Base
+  include ActiveInteraction::Extras::NestedAttributes
+
+  array :items
+
+  accepts_nested_attributes_for :items,
+    permit: [:name, :quantity]
+
+  def execute
+    # items_attributes automatically mapped to items
+  end
+end
+```
+
+### InitializeWith
+
+Lazily sets input values after initialization, only for inputs not explicitly given.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::InitializeWith
+
+  anything :current_user
+
+  initialize_with do
+    { current_user: User.current }
+  end
+
+  def execute
+  end
+end
+
+Service.run! # current_user => User.current
+Service.run!(current_user: other_user) # current_user => other_user
+```
+
+### AppendInputs
+
+Set input defaults after initialization without overwriting explicitly given inputs.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::AppendInputs
+
+  string :tenant_name
+
+  default_inputs do
+    { tenant_name: Current.tenant.name }
+  end
+
+  # Or single default:
+  default_input :tenant_name do
+    Current.tenant.name
+  end
+end
+```
+
+### IncludeErrors
+
+Merges a model's errors into the interaction's errors and halts if invalid.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::IncludeErrors
+
+  def execute
+    model = User.new(params)
+    model.save
+    include_errors!(model) # merges model errors and halts if invalid
+  end
+end
+```
+
+### InstanceRunnable
+
+Allows running interactions from an already-instantiated object. Useful for controller-style usage with `save`/`save!` aliases.
+
+```ruby
+class Form < ActiveInteraction::Base
+  include ActiveInteraction::Extras::InstanceRunnable
+
+  string :name
+
+  def execute
+  end
+end
+
+# Controller-style:
+def create
+  if form.save
+    redirect_to record_path
+  else
+    render :new
+  end
+end
+
+def form
+  @form ||= Form.new(params:)
+end
+```
+
+### Current
+
+Provides `ActiveSupport::CurrentAttributes` context accessible via `current`.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::Current
+
+  def execute
+    current.job   # the current job (if running in background)
+    current.batch # the current GoodJob batch (if applicable)
+  end
+end
+```
+
+### AddToBatch
+
+Conditionally runs a block within a GoodJob batch if currently in a batch context.
+
+```ruby
+class Service < ActiveInteraction::Base
+  include ActiveInteraction::Extras::AddToBatch
+
+  def execute
+    add_to_batch do
+      SomeOtherService.delay.run(some_param: value)
+    end
+  end
+end
+```
+
+### AllRunner
+
+Runs the service for every record in the default scope of the object filter.
+
+```ruby
+class NotifyUsers < ActiveInteraction::Base
+  include ActiveInteraction::Extras::AllRunner
+
+  object :user
+
+  def execute
+    # process each user
+  end
+end
+
+# Run synchronously for all users:
+NotifyUsers.all.run!
+
+# Run async via GoodJob batches:
+NotifyUsers.all.delay.run!
+
+# With custom scope:
+NotifyUsers.all(user: User.active).delay(wait: 5.minutes).run!
+```
+
+### FileBlobs
+
+Helper for working with ActiveStorage attachments in form objects.
+
+```ruby
+class Doc::Form < ActiveInteraction::Base
+  include ActiveInteraction::Extras::FileBlobs
+
+  object :doc
+
+  model_fields(:doc) do
+    array :files
+  end
+  
+  def execute
+    save_model!(:doc)
+  end
+end
+```
+
+```slim
+/ _form.html.slim 
+= form.blobs_for(:files).each do |blob|
+  = f.hidden_field :files, value: blob.signed_id
+
+= f.file_field :files, multiple: true, direct_upload: true
+```
+
 ## Jobs
 
 You no longer need to create a separate Job class for the each interaction. This Job extension automatically converts interactions to background jobs. By convention each interaction will have a nested `Job` class which will be inherited from the parent interaction `Job` class (e.g. `ApplicationInteraction::Job`). 
@@ -339,6 +631,39 @@ DoubleService.run # => RuntimeError
 DoubleService.delay.perform_now(x: 2) # => returns 2
 ```
 
+### GoodJob
+
+Extends the ActiveJob integration with GoodJob batch support and concurrency keys.
+
+```ruby
+class ApplicationInteraction < ActiveInteraction::Base
+  include ActiveInteraction::Extras::GoodJob
+
+  class Job < ActiveJob::Base
+    include GoodJob::ActiveJobExtensions::Concurrency
+    include ActiveInteraction::Extras::GoodJob::Perform
+  end
+end
+
+class ProcessUser < ApplicationInteraction
+  object :user
+  def execute
+  end
+end
+
+class ProcessUserFinished < ApplicationInteraction
+  def execute
+  end
+end
+
+# Create and enqueue a GoodJob batch:
+batch = ProcessUserFinished.batch_job
+batch.add do
+  ProcessUser.delay.run!(user: User.last)
+end
+batch.enqueue
+```
+
 ## Rspec
 
 ```ruby

data/active_interaction-extras.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
     "changelog_uri" => "https://github.com/antulik/active_interaction-extras/blob/master/CHANGELOG.md",
   }
 
-  spec.required_ruby_version = '>= 2.7'
+  spec.required_ruby_version = '>= 3.0'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
@@ -27,14 +27,15 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "active_interaction", ">= 5.0", "< 6.0"
-  spec.add_dependency "activemodel", ">= 6.0"
-  spec.add_dependency "activesupport", ">= 6.0"
+  spec.add_dependency "activemodel", ">= 7.1"
+  spec.add_dependency "activesupport", ">= 7.1"
+  spec.add_dependency "zeitwerk", ">= 2"
 
-  spec.add_development_dependency "bundler", "~> 2.2"
+  spec.add_development_dependency "bundler", ">= 2.2"
   spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.7"
   spec.add_development_dependency "pry"
-  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "sqlite3", ">= 2"
   spec.add_development_dependency "activerecord"
   spec.add_development_dependency "activejob"
   spec.add_development_dependency "actionpack"

data/lib/active_interaction/extras/active_job.rb

@@ -2,34 +2,65 @@ require 'active_job'
 
 module ActiveInteraction::Extras::ActiveJob
   extend ActiveSupport::Concern
-
   include ActiveInteraction::Extras::Jobs::Core
 
   class_methods do
     def configured_job_class
       ConfiguredJob
     end
+
+    def perform_now(&block)
+      job_class.perform_now(&block)
+    end
   end
 
   module Perform
     extend ActiveSupport::Concern
 
     def perform(*args)
+      ActiveInteraction::Extras::Current::CurrentContext.set(job: self) do
+        parent_class.run!(*args)
+      end
+    end
+
+    def parent_class
       if self.class.respond_to?(:module_parent)
-        self.class.module_parent.run!(*args)
+        self.class.module_parent
       else
-        self.class.parent.run!(*args)
+        self.class.parent
+      end
+    end
+
+    class_methods do
+      def perform_now
+        Thread.current[name] ||= []
+        Thread.current[name].push true
+        yield
+      ensure
+        if Thread.current[name].size == 1
+          Thread.current[name] = nil
+        else
+          Thread.current[name].pop
+        end
+      end
+
+      def perform_now?
+        Thread.current[name]
       end
     end
   end
 
   class ConfiguredJob < ::ActiveJob::ConfiguredJob
     def run(*args)
-      perform_later(*args)
+      run!(*args)
     end
 
     def run!(*args)
-      perform_later(*args)
+      if @job_class.perform_now?
+        perform_now(*args)
+      else
+        perform_later(*args)
+      end
     end
   end
 end

data/lib/active_interaction/extras/add_to_batch.rb

@@ -0,0 +1,13 @@
+module ActiveInteraction::Extras::AddToBatch
+  extend ActiveSupport::Concern
+
+  include ActiveInteraction::Extras::Current
+
+  def add_to_batch(&block)
+    if current.batch
+      current.batch.add(&block)
+    else
+      block.call
+    end
+  end
+end

data/lib/active_interaction/extras/after_initialize.rb

@@ -0,0 +1,20 @@
+module ActiveInteraction::Extras::AfterInitialize
+  extend ActiveSupport::Concern
+
+  include ActiveSupport::Callbacks
+
+  included do
+    define_callbacks :initialize
+  end
+
+  class_methods do
+    def after_initialize(...)
+      set_callback(:initialize, :after, ...)
+    end
+  end
+
+  def initialize(...)
+    super
+    run_callbacks :initialize, :after
+  end
+end

data/lib/active_interaction/extras/all.rb

@@ -2,11 +2,26 @@ module ActiveInteraction::Extras::All
   extend ActiveSupport::Concern
 
   # order dependant, include first so around callback includes other modules
+  include ActiveInteraction::Extras::NamedCallbacks
+  include ActiveInteraction::Extras::AfterInitialize
   include ActiveInteraction::Extras::Transaction
 
   include ActiveInteraction::Extras::FilterAlias
   include ActiveInteraction::Extras::Halt
   include ActiveInteraction::Extras::ModelFields
-  include ActiveInteraction::Extras::RunCallback
+  include ActiveInteraction::Extras::NestedAttributes
+
   include ActiveInteraction::Extras::StrongParams
+  include ActiveInteraction::Extras::Current
+
+  include ActiveInteraction::Extras::AddToBatch
+  include ActiveInteraction::Extras::FormFor
+  include ActiveInteraction::Extras::InstanceRunnable
+  include ActiveInteraction::Extras::InitializeWith
+  include ActiveInteraction::Extras::IncludeErrors
+  include ActiveInteraction::Extras::AllRunner
+  include ActiveInteraction::Extras::AppendInputs
+  include ActiveInteraction::Extras::FileBlobs
+
+  include ActiveInteraction::Extras::RunCallback
 end

data/lib/active_interaction/extras/all_runner.rb

@@ -0,0 +1,91 @@
+module ActiveInteraction::Extras::AllRunner
+  extend ActiveSupport::Concern
+
+  class AllExecution
+    attr_reader :klass, :params
+
+    def initialize(klass:, params:)
+      @klass = klass
+      @params = params
+    end
+
+    def run(opts = {})
+      execute(opts) { klass.run(_1) }
+    end
+
+    def run!(opts = {})
+      execute(opts) { klass.run!(_1) }
+    end
+
+    def delay(**delay_opts)
+      DelayedExecution.new(klass:, params:, delay_opts:)
+    end
+
+    private
+
+    def noop
+      yield
+    end
+
+    def default_params
+      object_filters = klass.filters
+        .reject { _2.default? }
+        .select { _2.is_a?(ActiveInteraction::ObjectFilter) }
+      raise "only one object input allowed" if object_filters.size > 1
+      name, _ = object_filters.first
+
+      {
+        name => name.to_s.classify.constantize.all,
+      }
+    end
+
+    def execute(opts, around: method(:noop))
+      params = self.params.dup.reverse_merge(default_params)
+
+      name, scope = params.find { _2.is_a?(ActiveRecord::Relation) }
+      params.delete(name)
+
+      scope.find_in_batches do |batch|
+        around.call do
+          batch.each do |record|
+            yield(opts.merge(name => record, **params))
+          end
+        end
+      end
+    end
+  end
+
+  class DelayedExecution < AllExecution
+    attr_reader :delay_opts
+    def initialize(delay_opts: {}, **kw)
+      super(**kw)
+      @delay_opts = delay_opts
+    end
+
+    def run(opts = {})
+      require 'good_job'
+      around = ::GoodJob::Bulk.method(:enqueue)
+      execute(opts, around:) { klass.delay(delay_opts).run(_1) }
+    end
+
+    def run!(opts = {})
+      run(opts)
+    end
+  end
+
+  class_methods do
+    # class Service < ActiveInteraction::Base
+    #   object :user
+    #   def execute; end
+    # end
+    #
+    # @example
+    #   Service.all.run!
+    #   Service.all.run
+    #   Service.all.delay.run!
+    #   Service.all(user: User.all).delay(wait: 5.minutes).run!
+    def all(params = {})
+      AllExecution.new(klass: self, params:)
+    end
+  end
+end