dexkit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc994e44218cf9063af69ad1d01929d86b91fe35b6f30769dd068832fb04fc37
-  data.tar.gz: b4a078fb25780824cd2a876f5d668196ba2f3a2094ce63a1b9731dfeab1c7aa6
+  metadata.gz: 4a120052500fd0c1889117f87d0d4260b40eecbc82b31ad50b9e6fc97f99efd9
+  data.tar.gz: f140a685dd0825fbd675f5575d1a44d5679598ad7a2d302a65a3f22bae268ce0
 SHA512:
-  metadata.gz: b4bb8dbbe3c9acd66e5c3ed6a6b203408f66c7455544c36de4e60e755a9cfa9a2fa3405a39648e77e5bd42b2593a053d5d517e16ce1cd5236225083bd24891b3
-  data.tar.gz: c050bd2dc477e19efcebbe6bfa6fe7d46dbfa4dea5367f38c098b6c82750439211d1b4a28224c21fd66e98c8971b9532f341f4e17b4d2e836383470ccf778913
+  metadata.gz: f2186829d67bb0c19d71e9a81021a94efc56cb90dc943d11ad62a9306833ed08183691eb3196fc8dec950dcd3e7a624be5e67eda00abb3e74a444404b7947267
+  data.tar.gz: 5314488039b706abbbf68bc3ca7fb3e2445718286a2b21ce7346dfae60f8cdb5ca68f89369b3b54fe1a756826e95a76f22bac973d75494a10c4605e8210e1d94

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## [Unreleased]
 
+## 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

@@ -9,21 +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)
-    User.create!(name: name, email: email)
+    error!(:out_of_stock) unless product.in_stock?
+
+    order = Order.create!(customer: customer, product: product, quantity: quantity, note: note)
+
+    after_commit { Order::Placed.publish(order_id: order.id, total: order.total) }
+
+    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
@@ -31,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.
@@ -69,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
 ```
@@ -87,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
@@ -102,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
@@ -115,7 +123,7 @@ 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
 ```
 
@@ -124,13 +132,13 @@ end
 ### 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
@@ -141,8 +149,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
@@ -160,7 +168,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?
 ```
@@ -172,10 +180,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
 ```
 
@@ -183,7 +191,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
@@ -198,24 +206,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
@@ -227,10 +235,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
 ```

data/guides/llm/OPERATION.md

@@ -20,7 +20,12 @@ class CreateUser < Dex::Operation
   def perform
     error!(:invalid_email) unless email.include?("@")
     error!(:email_taken) if User.exists?(email: email)
-    User.create!(email: email, name: name, role: role)
+
+    user = User.create!(email: email, name: name, role: role)
+
+    after_commit { WelcomeMailer.with(user: user).deliver_later }
+
+    user
   end
 end
 ```
@@ -255,6 +260,32 @@ transaction :mongoid     # adapter override (default: auto-detect AR → Mongoid
 
 Child classes can re-enable: `transaction true`.
 
+### after_commit
+
+Register blocks to run after the transaction commits. Use for side effects that should only happen on success (emails, webhooks, cache invalidation):
+
+```ruby
+def perform
+  user = User.create!(name: name, email: email)
+  after_commit { WelcomeMailer.with(user: user).deliver_later }
+  after_commit { Analytics.track(:user_created, user_id: user.id) }
+  user
+end
+```
+
+Callbacks are always deferred — they run after the outermost operation boundary succeeds:
+
+- **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.
+
+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.
+
 ---
 
 ## Advisory Locking
@@ -347,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/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

@@ -32,17 +32,70 @@ module Dex
           ActiveRecord::Base.transaction(&block)
         end
 
+        def self.after_commit(&block)
+          unless defined?(ActiveRecord) && ActiveRecord.respond_to?(:after_all_transactions_commit)
+            raise LoadError, "after_commit requires Rails 7.2+"
+          end
+
+          ActiveRecord.after_all_transactions_commit(&block)
+        end
+
         def self.rollback_exception_class
           ActiveRecord::Rollback
         end
       end
 
       module MongoidAdapter
+        AFTER_COMMIT_KEY = :_dex_mongoid_after_commit
+
         def self.wrap(&block)
           unless defined?(Mongoid)
             raise LoadError, "Mongoid is required for transactions"
           end
-          Mongoid.transaction(&block)
+
+          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
+            block_completed = true
+            value
+          end
+
+          if block_completed
+            Thread.current[AFTER_COMMIT_KEY].each(&:call)
+          end
+
+          result
+        ensure
+          Thread.current[AFTER_COMMIT_KEY] = nil if outermost
+        end
+
+        # NOTE: Only detects transactions opened via MongoidAdapter.wrap (i.e. Dex operations).
+        # Ambient Mongoid.transaction blocks opened outside Dex are invisible here —
+        # the callback will fire immediately instead of deferring to the outer commit.
+        def self.after_commit(&block)
+          callbacks = Thread.current[AFTER_COMMIT_KEY]
+          if callbacks
+            callbacks << block
+          else
+            block.call
+          end
         end
 
         def self.rollback_exception_class

data/lib/dex/operation/transaction_wrapper.rb

@@ -4,18 +4,40 @@ 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
+
+      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      if deferred
+        deferred << block
+      else
+        block.call
+      end
     end
 
     TRANSACTION_KNOWN_ADAPTERS = %i[active_record mongoid].freeze
@@ -54,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)
@@ -67,6 +116,19 @@ 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) }
+      adapter = _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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.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