dexkit 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6f6f437fc7f7726b58232820e6f1afd65c5adf674f51c4be07944a43d92a58b
-  data.tar.gz: 13046423e606ff6e000b6d557ce468efa94d0f13d8aa36530dc5ae69a688e097
+  metadata.gz: f8d7274727e727937b55704faa81e4da8a54bb3af7758b11e9144e59fb2dba14
+  data.tar.gz: cb899ee88b5e83ec57a913f0173036ac228f672c7850d88e95209f4804218f96
 SHA512:
-  metadata.gz: d48748c521d0e0c298ab78230797f7a22e45ae194fee6669f0f99669ea0ac1333b59158a8068211319694cbd073660f298babdb0a784b251444b579b898ba1c0
-  data.tar.gz: 4a574717aa7d2f5f5de9d192b86d7a6151d5b1a8cd2bba04c79e933cb2768e5c4d7cd05d91e22cf3ca9973cfca59467cd1a6972df8626ce90971ca9fec2a365d
+  metadata.gz: 7758fe2c0d5b9cdd2bcf62aa510c4146ef29898335ddffb118abb35409367d5f7cbd1aeba6365f865bb36d4011b1030f136cfb9b6eee27fb3aa3d06d11eeb21e
+  data.tar.gz: e437a4af9b4aa0c121245de966775cd3be0bad5ceb5918f139cfaf059545159631797b630a9b21f3add8855308c832f5846efb78f97f36141042f40d28b32341

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-03-07
+
+### Added
+
+- **Handler callbacks** — `Dex::Event::Handler` now supports `before`, `after`, and `around` callbacks, same DSL as operations
+- **Handler transactions** — `Dex::Event::Handler` supports `transaction` and `after_commit` DSL. Transactions are disabled by default on handlers (opt in with `transaction`)
+- **Handler pipeline** — `Dex::Event::Handler` supports `use` for adding custom wrapper modules, same as operations
+- **`Dex::Executable`** — shared execution skeleton (Settings, Pipeline, `use` DSL) extracted from Operation and used by both Operation and Handler
+
+### Breaking
+
+- **`transaction false` fully opts out** — operations with `transaction false` no longer route `after_commit` through the database adapter. Previously, `after_commit` on a non-transactional operation would still detect and defer to ambient database transactions (e.g., `ActiveRecord::Base.transaction { op.call }`); now it fires callbacks directly after the pipeline completes. To restore ambient transaction awareness, remove `transaction false` or use `transaction` (enabled)
+
+## 0.5.0 - 2026-03-05
+
+### Added
+
+- **Verified Mongoid support** — operations (transactions, recording, async) and queries now have dedicated Mongoid test coverage running against a MongoDB replica set
+- **CI workflow for Mongoid** — GitHub Actions matrix includes a MongoDB replica-set job that runs Mongoid-specific tests
+
+### Breaking
+
+- **`after_commit` now always defers** — non-transactional operations queue callbacks in memory and flush them after the operation pipeline succeeds, matching the behavior of transactional operations. Previously, `after_commit` fired immediately inline when no transaction was active — code that relied on immediate execution (e.g., reading side effects of the callback later in `perform`) must account for the new deferred timing. Callbacks are discarded on `error!` or exception. Nested operations flush once at the outermost successful boundary. Ambient database transactions (e.g., `ActiveRecord::Base.transaction { op.call }`) are still respected via the adapter.
+
+### Fixed
+
+- **Mongoid async recording** — `record_id` is now serialized with `.to_s` so BSON::ObjectId values pass through ActiveJob correctly
+- **Mongoid transaction adapter** — simplified nesting logic; the outermost `Mongoid.transaction` block now reliably owns callback flushing, fixing edge cases where nested rollbacks could leak callbacks
+
+## [0.4.1] - 2026-03-04
+
+### Added
+
+- **`after_commit` in operations** — `after_commit { ... }` defers a block until the surrounding database transaction commits
+  - ActiveRecord adapter uses `ActiveRecord.after_all_transactions_commit` (requires Rails 7.2+)
+  - Mongoid adapter manually tracks callbacks and fires them after the outermost `Mongoid.transaction` commits
+  - If called outside a transaction, the block executes immediately
+
+## [0.4.0] - 2026-03-04
+
+### Added
+
+- **Query objects** — `Dex::Query` base class for encapsulating database queries with filtering, sorting, and parameter binding
+  - Typed properties via `prop`/`prop?` DSL (same as Operation and Event)
+  - `scope { Model.all }` DSL for declaring the base scope
+  - **Filter DSL** — `filter :name, :strategy` with built-in strategies: `eq`, `not_eq`, `contains`, `starts_with`, `ends_with`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`
+  - Custom filter blocks: `filter(:name) { |scope, value| ... }`
+  - Optional filters (nilable props) are automatically skipped when `nil`
+  - **Sort DSL** — `sort :col1, :col2` for column sorts with automatic `asc`/`desc` via `"-col"` prefix convention
+  - Custom sort blocks: `sort(:name) { |scope| ... }`
+  - Default sort: `sort :name, default: "-created_at"`
+  - **Backend adapters** for both ActiveRecord and Mongoid (auto-detected from scope)
+  - `scope:` injection for pre-scoping (e.g., `current_user.posts`)
+  - `from_params` for binding from controller params with automatic type coercion and sort validation
+  - `to_params` for round-tripping query state back to URL params
+  - `param_key` DSL for customizing the params namespace
+  - ActiveModel::Naming / ActiveModel::Conversion for Rails form compatibility
+  - Convenience class methods: `.call`, `.count`, `.exists?`, `.any?`
+  - Inheritance support — filters, sorts, and scope are inherited by subclasses
+- `Dex::Match` is now included in `Dex::Form` — `Ok`/`Err` are available without prefix inside forms
+
 ## [0.3.0] - 2026-03-03
 
 ### Added

data/README.md

@@ -1,4 +1,4 @@
-# Dexkit
+# dexkit
 
 Rails patterns toolbelt. Equip to gain +4 DEX.
 
@@ -9,26 +9,28 @@ Rails patterns toolbelt. Equip to gain +4 DEX.
 Service objects with typed properties, transactions, error handling, and more.
 
 ```ruby
-class CreateUser < Dex::Operation
-  prop :name,  String
-  prop :email, String
+class Order::Place < Dex::Operation
+  prop :customer, _Ref(Customer)
+  prop :product, _Ref(Product)
+  prop :quantity, _Integer(1..)
+  prop? :note, String
 
-  success _Ref(User)
-  error   :email_taken
+  success _Ref(Order)
+  error :out_of_stock
 
   def perform
-    error!(:email_taken) if User.exists?(email: email)
+    error!(:out_of_stock) unless product.in_stock?
 
-    user = User.create!(name: name, email: email)
+    order = Order.create!(customer: customer, product: product, quantity: quantity, note: note)
 
-    after_commit { WelcomeMailer.with(user: user).deliver_later }
+    after_commit { Order::Placed.publish(order_id: order.id, total: order.total) }
 
-    user
+    order
   end
 end
 
-user = CreateUser.call(name: "Alice", email: "alice@example.com")
-user.name  # => "Alice"
+order = Order::Place.call(customer: 42, product: 7, quantity: 2)
+order.id  # => 1
 ```
 
 ### What you get out of the box
@@ -36,35 +38,35 @@ user.name  # => "Alice"
 **Typed properties** – powered by [literal](https://github.com/joeldrapper/literal). Plain classes, ranges, unions, arrays, nilable, and model references with auto-find:
 
 ```ruby
-prop :amount,   _Integer(1..)
+prop :quantity, _Integer(1..)
 prop :currency, _Union("USD", "EUR", "GBP")
-prop :user,     _Ref(User)           # accepts User instance or ID
-prop? :note,    String               # optional (nil by default)
+prop :customer, _Ref(Customer)        # accepts Customer instance or ID
+prop? :note, String                    # optional (nil by default)
 ```
 
 **Structured errors** with `error!`, `assert!`, and `rescue_from`:
 
 ```ruby
-user = assert!(:not_found) { User.find_by(id: user_id) }
+product = assert!(:not_found) { Product.find_by(id: product_id) }
 
-rescue_from Stripe::CardError, as: :card_declined
+rescue_from Stripe::CardError, as: :payment_declined
 ```
 
 **Ok / Err** – pattern match on operation outcomes with `.safe.call`:
 
 ```ruby
-case CreateUser.new(email: email).safe.call
-in Ok(name:)
-  puts "Welcome, #{name}!"
-in Err(code: :email_taken)
-  puts "Already registered"
+case Order::Place.new(customer: 42, product: 7, quantity: 2).safe.call
+in Ok => result
+  redirect_to order_path(result.id)
+in Err(code: :out_of_stock)
+  flash[:error] = "Product is out of stock"
 end
 ```
 
 **Async execution** via ActiveJob:
 
 ```ruby
-SendWelcomeEmail.new(user_id: 123).async(queue: "mailers").call
+Order::Fulfill.new(order_id: 123).async(queue: "fulfillment").call
 ```
 
 **Transactions** on by default, **advisory locking**, **recording** to database, **callbacks**, and a customizable **pipeline** – all composable, all optional.
@@ -74,15 +76,16 @@ SendWelcomeEmail.new(user_id: 123).async(queue: "mailers").call
 First-class test helpers for Minitest:
 
 ```ruby
-class CreateUserTest < Minitest::Test
-  testing CreateUser
+class PlaceOrderTest < Minitest::Test
+  testing Order::Place
 
-  def test_creates_user
-    assert_operation(name: "Alice", email: "alice@example.com")
+  def test_places_order
+    assert_operation(customer: customer.id, product: product.id, quantity: 2)
   end
 
-  def test_rejects_duplicate_email
-    assert_operation_error(:email_taken, name: "Alice", email: "taken@example.com")
+  def test_rejects_out_of_stock
+    assert_operation_error(:out_of_stock, customer: customer.id,
+      product: out_of_stock_product.id, quantity: 1)
   end
 end
 ```
@@ -92,14 +95,14 @@ end
 Typed, immutable event objects with publish/subscribe, async dispatch, and causality tracing.
 
 ```ruby
-class OrderPlaced < Dex::Event
+class Order::Placed < Dex::Event
   prop :order_id, Integer
   prop :total, BigDecimal
   prop? :coupon_code, String
 end
 
 class NotifyWarehouse < Dex::Event::Handler
-  on OrderPlaced
+  on Order::Placed
   retries 3
 
   def perform
@@ -107,7 +110,7 @@ class NotifyWarehouse < Dex::Event::Handler
   end
 end
 
-OrderPlaced.publish(order_id: 1, total: 99.99)
+Order::Placed.publish(order_id: 1, total: 99.99)
 ```
 
 ### What you get out of the box
@@ -120,22 +123,26 @@ OrderPlaced.publish(order_id: 1, total: 99.99)
 
 ```ruby
 order_placed.trace do
-  InventoryReserved.publish(order_id: 1)
+  Shipment::Reserved.publish(order_id: 1)
 end
 ```
 
+**Callbacks** — `before`, `after`, `around` hooks on handlers, same DSL as operations.
+
+**Transactions** — opt-in `transaction` and `after_commit` for handlers that write to the database.
+
 **Suppression**, optional **persistence**, **context capture**, and **retries** with exponential backoff.
 
 ### Testing
 
 ```ruby
-class CreateOrderTest < Minitest::Test
+class PlaceOrderTest < Minitest::Test
   include Dex::Event::TestHelpers
 
   def test_publishes_order_placed
     capture_events do
-      CreateOrder.call(item_id: 1)
-      assert_event_published(OrderPlaced, order_id: 1)
+      Order::Place.call(customer: customer.id, product: product.id, quantity: 2)
+      assert_event_published(Order::Placed)
     end
   end
 end
@@ -146,8 +153,8 @@ end
 Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
 
 ```ruby
-class OnboardingForm < Dex::Form
-  model User
+class Employee::Form < Dex::Form
+  model Employee
 
   attribute :first_name, :string
   attribute :last_name, :string
@@ -165,7 +172,7 @@ class OnboardingForm < Dex::Form
   end
 end
 
-form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ", first_name: "Alice", last_name: "Smith")
+form = Employee::Form.new(email: "  ALICE@EXAMPLE.COM  ", first_name: "Alice", last_name: "Smith")
 form.email  # => "alice@example.com"
 form.valid?
 ```
@@ -177,10 +184,10 @@ form.valid?
 **Nested forms** — `nested_one` and `nested_many` with automatic Hash coercion, `_destroy` support, and error propagation:
 
 ```ruby
-nested_many :documents do
-  attribute :document_type, :string
-  attribute :document_number, :string
-  validates :document_type, :document_number, presence: true
+nested_many :emergency_contacts do
+  attribute :name, :string
+  attribute :phone, :string
+  validates :name, :phone, presence: true
 end
 ```
 
@@ -188,7 +195,7 @@ end
 
 **Uniqueness validation** against the database, with scope, case-sensitivity, and current-record exclusion.
 
-**Multi-model forms** — when a form spans User, Employee, and Address, define a `.for` convention method to map records and a `#save` method that delegates to a `Dex::Operation`:
+**Multi-model forms** — when a form spans Employee, Department, and Address, define a `.for` convention method to map records and a `#save` method that delegates to a `Dex::Operation`:
 
 ```ruby
 def save
@@ -203,24 +210,24 @@ end
 
 ## Queries
 
-Declarative query objects for filtering and sorting ActiveRecord relations.
+Declarative query objects for filtering and sorting ActiveRecord relations and Mongoid criteria.
 
 ```ruby
-class UserSearch < Dex::Query
-  scope { User.all }
+class Order::Query < Dex::Query
+  scope { Order.all }
 
-  prop? :name,   String
-  prop? :role,   _Array(String)
-  prop? :age_min, Integer
+  prop? :status, String
+  prop? :customer, _Ref(Customer)
+  prop? :total_min, Integer
 
-  filter :name,    :contains
-  filter :role,    :in
-  filter :age_min, :gte, column: :age
+  filter :status
+  filter :customer
+  filter :total_min, :gte, column: :total
 
-  sort :name, :created_at, default: "-created_at"
+  sort :created_at, :total, default: "-created_at"
 end
 
-users = UserSearch.call(name: "ali", role: %w[admin], sort: "name")
+orders = Order::Query.call(status: "pending", sort: "-total")
 ```
 
 ### What you get out of the box
@@ -232,10 +239,10 @@ users = UserSearch.call(name: "ali", role: %w[admin], sort: "name")
 **`from_params`** — HTTP boundary handling with automatic coercion, blank stripping, and invalid value fallback:
 
 ```ruby
-class UsersController < ApplicationController
+class OrdersController < ApplicationController
   def index
-    query = UserSearch.from_params(params, scope: policy_scope(User))
-    @users = pagy(query.resolve)
+    query = Order::Query.from_params(params, scope: policy_scope(Order))
+    @orders = pagy(query.resolve)
   end
 end
 ```
@@ -256,7 +263,7 @@ Full documentation at **[dex.razorjack.net](https://dex.razorjack.net)**.
 
 ## AI Coding Assistant Setup
 
-Dexkit ships LLM-optimized guides. Copy them into your project so AI agents automatically know the API:
+dexkit ships LLM-optimized guides. Copy them into your project so AI agents automatically know the API:
 
 ```bash
 cp $(bundle show dexkit)/guides/llm/OPERATION.md app/operations/CLAUDE.md

data/guides/llm/EVENT.md

@@ -111,6 +111,70 @@ end
 
 When retries exhausted, exception propagates normally.
 
+### Callbacks
+
+Same `before`/`after`/`around` DSL as operations:
+
+```ruby
+class ProcessPayment < Dex::Event::Handler
+  on PaymentReceived
+
+  before :log_start
+  after :log_end
+
+  around ->(cont) {
+    Instrumentation.measure("payment") { cont.call }
+  }
+
+  def perform
+    PaymentGateway.charge(event.amount)
+  end
+
+  private
+
+  def log_start = Rails.logger.info("Processing payment...")
+  def log_end = Rails.logger.info("Payment processed")
+end
+```
+
+Callbacks are inherited. Child handlers run parent callbacks first.
+
+### Transactions
+
+Handlers can opt into database transactions and deferred `after_commit`:
+
+```ruby
+class FulfillOrder < Dex::Event::Handler
+  on OrderPlaced
+  transaction
+
+  def perform
+    order = Order.find(event.order_id)
+    order.update!(status: "fulfilled")
+
+    after_commit { Shipment::Ship.new(order_id: order.id).async.call }
+  end
+end
+```
+
+Transactions are **disabled by default** on handlers (unlike operations). Opt in with `transaction`. The `after_commit` block defers until the transaction commits; on exception, deferred blocks are discarded.
+
+### Custom Pipeline
+
+Handlers support the same `use` DSL as operations for adding custom wrappers:
+
+```ruby
+class Monitored < Dex::Event::Handler
+  use MetricsWrapper, as: :metrics
+
+  def perform
+    # ...
+  end
+end
+```
+
+Default handler pipeline: `[:transaction, :callback]`.
+
 ---
 
 ## Tracing (Causality)

data/guides/llm/OPERATION.md

@@ -273,11 +273,18 @@ def perform
 end
 ```
 
-On rollback (`error!` or exception), callbacks are discarded. When no transaction is open anywhere, executes immediately. Multiple blocks run in registration order.
+Callbacks are always deferred — they run after the outermost operation boundary succeeds:
 
-**ActiveRecord:** fully nesting-aware — callbacks are deferred until the outermost transaction commits, even across nested operations or ambient `ActiveRecord::Base.transaction` blocks. Requires Rails 7.2+.
+- **Transactional operations:** deferred until the DB transaction commits.
+- **Non-transactional operations:** queued in memory, flushed after the operation pipeline completes successfully.
+- **Nested operations:** callbacks queue up and flush once at the outermost successful boundary.
+- **On error (`error!` or exception):** queued callbacks are discarded.
 
-**Mongoid:** callbacks are deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
+Multiple blocks run in registration order.
+
+**ActiveRecord:** requires Rails 7.2+ (`after_all_transactions_commit`).
+
+**Mongoid:** deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
 
 ---
 
@@ -340,7 +347,7 @@ record params: false      # response only
 
 Recording happens inside the transaction — rolled back on `error!`/`assert!`. Missing columns silently skipped.
 
-When both async and recording are enabled, Dexkit automatically stores only the record ID in the job payload instead of full params. The record tracks `status` (pending → running → done/failed) and `error` (code or exception class name).
+When both async and recording are enabled, dexkit automatically stores only the record ID in the job payload instead of full params. The record tracks `status` (pending → running → done/failed) and `error` (code or exception class name).
 
 ---
 
@@ -371,6 +378,8 @@ end
 
 Not autoloaded — stays out of production. TestLog and stubs are auto-cleared in `setup`.
 
+For Mongoid-backed operation tests, run against a MongoDB replica set (MongoDB transactions require it).
+
 ### Subject & Execution
 
 ```ruby

data/guides/llm/QUERY.md

@@ -159,7 +159,7 @@ Only one default per class. Applied when no sort is provided.
 
 ### `.call`
 
-Returns an ActiveRecord relation:
+Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`):
 
 ```ruby
 users = UserSearch.call(name: "ali", role: %w[admin], sort: "-name")
@@ -295,7 +295,7 @@ end
 
 ## Testing
 
-Queries return standard ActiveRecord relations. Test them with plain Minitest:
+Queries return standard scopes (`ActiveRecord::Relation` or `Mongoid::Criteria`). Test them with plain Minitest:
 
 ```ruby
 class UserSearchTest < Minitest::Test

data/lib/dex/event/handler.rb

@@ -3,6 +3,8 @@
 module Dex
   class Event
     class Handler
+      include Dex::Executable
+
       attr_reader :event
 
       def self.on(*event_classes)
@@ -36,7 +38,7 @@ module Dex
       def self._event_handle(event)
         instance = new
         instance.instance_variable_set(:@event, event)
-        instance.perform
+        instance.send(:call)
       end
 
       def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
@@ -69,6 +71,23 @@ module Dex
         end
       end
 
+      use TransactionWrapper
+      use CallbackWrapper
+
+      transaction false
+      private :call
+
+      # Guard must be defined after `include Executable` (which defines #call).
+      def self.method_added(method_name)
+        super
+
+        if method_name == :call
+          raise ArgumentError, "#{name || "Handler"} must not define #call — define #perform instead"
+        end
+
+        private :perform if method_name == :perform
+      end
+
       def perform
         raise NotImplementedError, "#{self.class.name} must implement #perform"
       end

data/lib/dex/event.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 # Modules loaded before class body (no reference to Dex::Event needed)
 require_relative "event/execution_state"
 require_relative "event/metadata"

data/lib/dex/executable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Dex
+  module Executable
+    def self.included(base)
+      base.include(Dex::Settings)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        subclass.instance_variable_set(:@_pipeline, pipeline.dup)
+        super
+      end
+
+      def pipeline
+        @_pipeline ||= Pipeline.new
+      end
+
+      def use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
+        step_name = as || _derive_step_name(mod)
+        wrap_method = wrap || :"_#{step_name}_wrap"
+        pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
+        include mod
+      end
+
+      private
+
+      def _derive_step_name(mod)
+        base = mod.name&.split("::")&.last
+        raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
+
+        base.sub(/Wrapper\z/, "")
+          .gsub(/([a-z])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
+    end
+
+    def call
+      self.class.pipeline.execute(self) { perform }
+    end
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -32,7 +32,7 @@ module Dex
         )
         begin
           job = apply_options(Operation::RecordJob)
-          job.perform_later(class_name: operation_class_name, record_id: record.id)
+          job.perform_later(class_name: operation_class_name, record_id: record.id.to_s)
         rescue => e
           begin
             record.destroy

data/lib/dex/operation/transaction_adapter.rb

@@ -53,10 +53,23 @@ module Dex
             raise LoadError, "Mongoid is required for transactions"
           end
 
-          outermost = !Thread.current[AFTER_COMMIT_KEY]
-          Thread.current[AFTER_COMMIT_KEY] ||= []
-          snapshot = Thread.current[AFTER_COMMIT_KEY].length
+          callbacks = Thread.current[AFTER_COMMIT_KEY]
+          outermost = callbacks.nil?
+
+          unless outermost
+            snapshot = callbacks.length
+            begin
+              return block.call
+            rescue rollback_exception_class
+              callbacks.slice!(snapshot..)
+              return nil
+            rescue StandardError # rubocop:disable Style/RescueStandardError
+              callbacks.slice!(snapshot..)
+              raise
+            end
+          end
 
+          Thread.current[AFTER_COMMIT_KEY] = []
           block_completed = false
           result = Mongoid.transaction do
             value = block.call
@@ -64,17 +77,11 @@ module Dex
             value
           end
 
-          if outermost && block_completed
+          if block_completed
             Thread.current[AFTER_COMMIT_KEY].each(&:call)
-          elsif !block_completed
-            # Mongoid swallowed a Rollback exception — discard callbacks from this level
-            Thread.current[AFTER_COMMIT_KEY].slice!(snapshot..)
           end
 
           result
-        rescue StandardError # rubocop:disable Style/RescueStandardError
-          Thread.current[AFTER_COMMIT_KEY]&.slice!(snapshot..) unless outermost
-          raise
         ensure
           Thread.current[AFTER_COMMIT_KEY] = nil if outermost
         end

data/lib/dex/operation/transaction_wrapper.rb

@@ -4,26 +4,37 @@ module Dex
   module TransactionWrapper
     extend Dex::Concern
 
+    DEFERRED_CALLBACKS_KEY = :_dex_after_commit_queue
+
     def _transaction_wrap
-      return yield unless _transaction_enabled?
+      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      outermost = deferred.nil?
+      Thread.current[DEFERRED_CALLBACKS_KEY] = [] if outermost
+      snapshot = Thread.current[DEFERRED_CALLBACKS_KEY].length
 
-      interceptor = nil
-      result = _transaction_execute do
-        interceptor = Operation::HaltInterceptor.new { yield }
-        raise _transaction_adapter.rollback_exception_class if interceptor.error?
-        interceptor.result
+      result, interceptor = if _transaction_enabled?
+        _transaction_run_adapter(snapshot) { yield }
+      else
+        _transaction_run_deferred(snapshot) { yield }
       end
 
+      _transaction_flush_deferred if outermost
+
       interceptor&.rethrow!
       result
+    rescue # rubocop:disable Style/RescueStandardError -- explicit for clarity
+      Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+      raise
+    ensure
+      Thread.current[DEFERRED_CALLBACKS_KEY] = nil if outermost
     end
 
     def after_commit(&block)
       raise ArgumentError, "after_commit requires a block" unless block
 
-      adapter = _transaction_adapter
-      if adapter
-        adapter.after_commit(&block)
+      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      if deferred
+        deferred << block
       else
         block.call
       end
@@ -65,6 +76,33 @@ module Dex
 
     private
 
+    def _transaction_run_adapter(snapshot)
+      interceptor = nil
+      result = _transaction_execute do
+        interceptor = Operation::HaltInterceptor.new { yield }
+        raise _transaction_adapter.rollback_exception_class if interceptor.error?
+        interceptor.result
+      end
+
+      if interceptor&.error?
+        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        interceptor.rethrow!
+      end
+
+      [result, interceptor]
+    end
+
+    def _transaction_run_deferred(snapshot)
+      interceptor = Operation::HaltInterceptor.new { yield }
+
+      if interceptor.error?
+        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        interceptor.rethrow!
+      end
+
+      [interceptor.result, interceptor]
+    end
+
     def _transaction_enabled?
       settings = self.class.settings_for(:transaction)
       return false unless settings.fetch(:enabled, true)
@@ -78,6 +116,20 @@ module Dex
       Operation::TransactionAdapter.for(adapter_name)
     end
 
+    def _transaction_flush_deferred
+      callbacks = Thread.current[DEFERRED_CALLBACKS_KEY]
+      return if callbacks.empty?
+
+      flush = -> { callbacks.each(&:call) }
+      enabled = self.class.settings_for(:transaction).fetch(:enabled, true)
+      adapter = enabled && _transaction_adapter
+      if adapter
+        adapter.after_commit(&flush)
+      else
+        flush.call
+      end
+    end
+
     def _transaction_execute(&block)
       _transaction_adapter.wrap(&block)
     end

data/lib/dex/operation.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 # Wrapper modules (loaded before class body so `include`/`use` can find them)
-require_relative "operation/settings"
 require_relative "operation/result_wrapper"
 require_relative "operation/record_wrapper"
 require_relative "operation/transaction_wrapper"
@@ -11,9 +10,6 @@ require_relative "operation/safe_wrapper"
 require_relative "operation/rescue_wrapper"
 require_relative "operation/callback_wrapper"
 
-# Pipeline (referenced inside class body)
-require_relative "operation/pipeline"
-
 module Dex
   class Operation
     Halt = Struct.new(:type, :value, :error_code, :error_message, :error_details, keyword_init: true) do
@@ -46,6 +42,7 @@ module Dex
 
     RESERVED_PROP_NAMES = %i[call perform async safe initialize].to_set.freeze
 
+    include Executable
     include PropsSetup
     include TypeCoercion
 
@@ -60,22 +57,6 @@ module Dex
         )
       end
 
-      def inherited(subclass)
-        subclass.instance_variable_set(:@_pipeline, pipeline.dup)
-        super
-      end
-
-      def pipeline
-        @_pipeline ||= Pipeline.new
-      end
-
-      def use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
-        step_name = as || _derive_step_name(mod)
-        wrap_method = wrap || :"_#{step_name}_wrap"
-        pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
-        include mod
-      end
-
       private
 
       def _contract_params
@@ -85,25 +66,11 @@ module Dex
           hash[prop.name] = prop.type
         end
       end
-
-      def _derive_step_name(mod)
-        base = mod.name&.split("::")&.last
-        raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
-
-        base.sub(/Wrapper\z/, "")
-          .gsub(/([a-z])([A-Z])/, '\1_\2')
-          .downcase
-          .to_sym
-      end
     end
 
     def perform(*, **)
     end
 
-    def call
-      self.class.pipeline.execute(self) { perform }
-    end
-
     def self.method_added(method_name)
       super
       return unless method_name == :perform
@@ -117,7 +84,6 @@ module Dex
       new(**kwargs).call
     end
 
-    include Settings
     include AsyncWrapper
     include SafeWrapper
 

data/lib/dex/pipeline.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dex
+  class Pipeline
+    Step = Data.define(:name, :method)
+
+    def initialize(steps = [])
+      @steps = steps.dup
+    end
+
+    def dup
+      self.class.new(@steps)
+    end
+
+    def steps
+      @steps.dup.freeze
+    end
+
+    def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
+      validate_positioning!(before, after, at)
+      step = Step.new(name: name, method: method)
+
+      if at == :outer then @steps.unshift(step)
+      elsif at == :inner then @steps.push(step)
+      elsif before then @steps.insert(find_index!(before), step)
+      elsif after then @steps.insert(find_index!(after) + 1, step)
+      else @steps.push(step)
+      end
+      self
+    end
+
+    def remove(name)
+      @steps.reject! { |s| s.name == name }
+      self
+    end
+
+    def execute(target)
+      chain = @steps.reverse_each.reduce(-> { yield }) do |next_step, step|
+        -> { target.send(step.method, &next_step) }
+      end
+      chain.call
+    end
+
+    private
+
+    def validate_positioning!(before, after, at)
+      count = [before, after, at].count { |v| !v.nil? }
+      raise ArgumentError, "specify only one of before:, after:, at:" if count > 1
+      raise ArgumentError, "at: must be :outer or :inner" if at && !%i[outer inner].include?(at)
+    end
+
+    def find_index!(name)
+      idx = @steps.index { |s| s.name == name }
+      raise ArgumentError, "pipeline step :#{name} not found" unless idx
+      idx
+    end
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end

data/lib/dexkit.rb

@@ -15,6 +15,9 @@ require_relative "dex/ref_type"
 require_relative "dex/type_coercion"
 require_relative "dex/props_setup"
 require_relative "dex/error"
+require_relative "dex/settings"
+require_relative "dex/pipeline"
+require_relative "dex/executable"
 require_relative "dex/operation"
 require_relative "dex/event"
 require_relative "dex/form"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +121,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -149,6 +177,7 @@ files:
 - lib/dex/event/trace.rb
 - lib/dex/event_test_helpers.rb
 - lib/dex/event_test_helpers/assertions.rb
+- lib/dex/executable.rb
 - lib/dex/form.rb
 - lib/dex/form/nesting.rb
 - lib/dex/form/uniqueness_validator.rb
@@ -160,21 +189,21 @@ files:
 - lib/dex/operation/jobs.rb
 - lib/dex/operation/lock_wrapper.rb
 - lib/dex/operation/outcome.rb
-- lib/dex/operation/pipeline.rb
 - lib/dex/operation/record_backend.rb
 - lib/dex/operation/record_wrapper.rb
 - lib/dex/operation/rescue_wrapper.rb
 - lib/dex/operation/result_wrapper.rb
 - lib/dex/operation/safe_wrapper.rb
-- lib/dex/operation/settings.rb
 - lib/dex/operation/transaction_adapter.rb
 - lib/dex/operation/transaction_wrapper.rb
+- lib/dex/pipeline.rb
 - lib/dex/props_setup.rb
 - lib/dex/query.rb
 - lib/dex/query/backend.rb
 - lib/dex/query/filtering.rb
 - lib/dex/query/sorting.rb
 - lib/dex/ref_type.rb
+- lib/dex/settings.rb
 - lib/dex/test_helpers.rb
 - lib/dex/test_helpers/assertions.rb
 - lib/dex/test_helpers/execution.rb
@@ -183,14 +212,15 @@ files:
 - lib/dex/type_coercion.rb
 - lib/dex/version.rb
 - lib/dexkit.rb
-homepage: https://github.com/razorjack/dexkit
+homepage: https://dex.razorjack.net/
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/razorjack/dexkit
+  homepage_uri: https://dex.razorjack.net/
   source_code_uri: https://github.com/razorjack/dexkit
   changelog_uri: https://github.com/razorjack/dexkit/blob/master/CHANGELOG.md
+  documentation_uri: https://dex.razorjack.net/
 rdoc_options: []
 require_paths:
 - lib
@@ -207,5 +237,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: 'Dexkit: Rails Patterns Toolbelt. Equip to gain +4 DEX'
+summary: 'dexkit: Rails Patterns Toolbelt. Equip to gain +4 DEX'
 test_files: []

data/lib/dex/operation/pipeline.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module Dex
-  class Operation
-    class Pipeline
-      Step = Data.define(:name, :method)
-
-      def initialize(steps = [])
-        @steps = steps.dup
-      end
-
-      def dup
-        self.class.new(@steps)
-      end
-
-      def steps
-        @steps.dup.freeze
-      end
-
-      def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
-        validate_positioning!(before, after, at)
-        step = Step.new(name: name, method: method)
-
-        if at == :outer then @steps.unshift(step)
-        elsif at == :inner then @steps.push(step)
-        elsif before then @steps.insert(find_index!(before), step)
-        elsif after then @steps.insert(find_index!(after) + 1, step)
-        else @steps.push(step)
-        end
-        self
-      end
-
-      def remove(name)
-        @steps.reject! { |s| s.name == name }
-        self
-      end
-
-      def execute(operation)
-        chain = @steps.reverse_each.reduce(-> { yield }) do |next_step, step|
-          -> { operation.send(step.method, &next_step) }
-        end
-        chain.call
-      end
-
-      private
-
-      def validate_positioning!(before, after, at)
-        count = [before, after, at].count { |v| !v.nil? }
-        raise ArgumentError, "specify only one of before:, after:, at:" if count > 1
-        raise ArgumentError, "at: must be :outer or :inner" if at && !%i[outer inner].include?(at)
-      end
-
-      def find_index!(name)
-        idx = @steps.index { |s| s.name == name }
-        raise ArgumentError, "pipeline step :#{name} not found" unless idx
-        idx
-      end
-    end
-  end
-end