dexkit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a120052500fd0c1889117f87d0d4260b40eecbc82b31ad50b9e6fc97f99efd9
-  data.tar.gz: f140a685dd0825fbd675f5575d1a44d5679598ad7a2d302a65a3f22bae268ce0
+  metadata.gz: f8d7274727e727937b55704faa81e4da8a54bb3af7758b11e9144e59fb2dba14
+  data.tar.gz: cb899ee88b5e83ec57a913f0173036ac228f672c7850d88e95209f4804218f96
 SHA512:
-  metadata.gz: f2186829d67bb0c19d71e9a81021a94efc56cb90dc943d11ad62a9306833ed08183691eb3196fc8dec950dcd3e7a624be5e67eda00abb3e74a444404b7947267
-  data.tar.gz: 5314488039b706abbbf68bc3ca7fb3e2445718286a2b21ce7346dfae60f8cdb5ca68f89369b3b54fe1a756826e95a76f22bac973d75494a10c4605e8210e1d94
+  metadata.gz: 7758fe2c0d5b9cdd2bcf62aa510c4146ef29898335ddffb118abb35409367d5f7cbd1aeba6365f865bb36d4011b1030f136cfb9b6eee27fb3aa3d06d11eeb21e
+  data.tar.gz: e437a4af9b4aa0c121245de966775cd3be0bad5ceb5918f139cfaf059545159631797b630a9b21f3add8855308c832f5846efb78f97f36141042f40d28b32341

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [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

data/README.md

@@ -1,4 +1,4 @@
-# Dexkit
+# dexkit
 
 Rails patterns toolbelt. Equip to gain +4 DEX.
 
@@ -127,6 +127,10 @@ order_placed.trace do
 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
@@ -259,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

@@ -347,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).
 
 ---
 

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/transaction_wrapper.rb

@@ -121,7 +121,8 @@ module Dex
       return if callbacks.empty?
 
       flush = -> { callbacks.each(&:call) }
-      adapter = _transaction_adapter
+      enabled = self.class.settings_for(:transaction).fetch(:enabled, true)
+      adapter = enabled && _transaction_adapter
       if adapter
         adapter.after_commit(&flush)
       else

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.5.0"
+  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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -177,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
@@ -188,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
@@ -211,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
@@ -235,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