dexkit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7be5c6e58f2741692419cf25f9a8e76df8003036dd17139073561fe5141e3bdc
-  data.tar.gz: 28f77abedf2552c3a2f319abd175f61855f956517295e1ea435a3dbf88327735
+  metadata.gz: 3adbbfa21a62c17b74b7ac6807ed7a9abdca2b02c85e06bb2d542bdbf7d39677
+  data.tar.gz: cead77e688d4c30a7256c05f73d509fefd44c7c6b6bfc52d9b0bdbfd8675954e
 SHA512:
-  metadata.gz: 800756f2f2f22dc4e487794fc129ccafc57ee815b3e26aea67c1f8eef9195654106cd7ab7b91525c4e5325da1696e94069ffc78e2d1302dc1f7a5d6f6eff8e82
-  data.tar.gz: 7bf8212783439db36adb9ae04854f981d2e2e6d9db8ca7bf9cd0768faa566aec98addc56f12640b7d0c284e3a7f4ca9d8afa05ba1f90568241970214bd8307d5
+  metadata.gz: b58aec14261efd1c679bb662b163df64f96d86239e5efe8897d7b8d007aef4cd19864a8fabc03ee4acf139379c1185e56f8a5f6e488a1f5dec00442a24223dee
+  data.tar.gz: 6009bd9567cf1fd4adacf21cfb5c6627cfce8d1d399498923ae9ff8a11c3f2b31df884549a8b3bdb0c45bede9951b672c6d50dbf2199a691e45a79c37b5c1497

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-02
+
+### Added
+
+- **Event system** — typed, immutable event value objects with publish/subscribe
+  - Typed properties via `prop`/`prop?` DSL (same as Operation)
+  - Sync and async publishing (`event.publish`, `Event.publish(sync: true)`)
+  - Handler DSL: `on` for subscription, `retries` with exponential/fixed/custom backoff
+  - Async dispatch via ActiveJob (`Dex::Event::Processor`, lazy-loaded)
+  - Causality tracing: `event.trace { ... }` and `caused_by:` link events into chains with shared `trace_id`
+  - Block-scoped suppression: `Dex::Event.suppress(SomeEvent) { ... }`
+  - Optional persistence via `event_store` configuration
+  - Context capture and restoration across async boundaries (`event_context`, `restore_event_context`)
+- **Event test helpers** — `Dex::Event::TestHelpers` module
+  - `capture_events` block for inspecting published events without dispatching
+  - `assert_event_published`, `refute_event_published`, `assert_event_count`
+  - `assert_event_trace`, `assert_same_trace` for causality assertions
+
+### Changed
+
+- Extracted shared `validate_options!` helper for DSL option validation
+- Added `Dex.warn` for unified warning logging
+- Added `Dex::Concern` to reduce module inclusion boilerplate
+- Simplified internal method names in standalone classes (AsyncProxy, Pipeline, Jobs, Processor)
+
+### Fixed
+
+- `_Array(_Ref(...))` props now serialize and deserialize correctly in both Operation and Event (array of model references was crashing on `value.id` called on Array)
+
+### Changed
+
+- Extracted `Dex::TypeCoercion` — shared module for prop serialization and coercion, used by both Operation and Event. Eliminates duplication of `_serialized_coercions`, ref type detection, and value coercion logic.
+- Extracted `Dex::PropsSetup` — shared `prop`/`prop?`/`_Ref` DSL wrapping Literal's with reserved name validation, public reader default, and automatic RefType coercion. Eliminates duplication between Operation and Event.
+
 ## [0.1.0] - 2026-03-01
 
 - Initial public release

data/README.md

@@ -84,6 +84,60 @@ class CreateUserTest < Minitest::Test
 end
 ```
 
+## Events
+
+Typed, immutable event objects with publish/subscribe, async dispatch, and causality tracing.
+
+```ruby
+class OrderPlaced < Dex::Event
+  prop :order_id, Integer
+  prop :total, BigDecimal
+  prop? :coupon_code, String
+end
+
+class NotifyWarehouse < Dex::Event::Handler
+  on OrderPlaced
+  retries 3
+
+  def perform
+    WarehouseApi.notify(event.order_id)
+  end
+end
+
+OrderPlaced.publish(order_id: 1, total: 99.99)
+```
+
+### What you get out of the box
+
+**Zero-config pub/sub** — define events and handlers, publish. No bus setup needed.
+
+**Async by default** — handlers dispatched via ActiveJob. `sync: true` for inline.
+
+**Causality tracing** — link events in chains with shared `trace_id`:
+
+```ruby
+order_placed.trace do
+  InventoryReserved.publish(order_id: 1)
+end
+```
+
+**Suppression**, optional **persistence**, **context capture**, and **retries** with exponential backoff.
+
+### Testing
+
+```ruby
+class CreateOrderTest < 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)
+    end
+  end
+end
+```
+
 ## Installation
 
 ```ruby
@@ -100,7 +154,7 @@ Dexkit ships LLM-optimized guides. Copy them into your project so AI agents auto
 
 ```bash
 cp $(bundle show dexkit)/guides/llm/OPERATION.md app/operations/CLAUDE.md
-cp $(bundle show dexkit)/guides/llm/TESTING.md test/CLAUDE.md
+cp $(bundle show dexkit)/guides/llm/EVENT.md app/event_handlers/CLAUDE.md
 ```
 
 ## License

data/guides/llm/EVENT.md

@@ -0,0 +1,300 @@
+# Dex::Event — LLM Reference
+
+Copy this to your app's event handlers directory (e.g., `app/event_handlers/AGENTS.md`) so coding agents know the full API when implementing and testing events.
+
+---
+
+## Reference Event
+
+All examples below build on this event unless noted otherwise:
+
+```ruby
+class OrderPlaced < Dex::Event
+  prop :order_id, Integer
+  prop :total, BigDecimal
+  prop? :coupon_code, String
+end
+```
+
+---
+
+## Defining Events
+
+Typed, immutable value objects. Props defined with `prop` (required) and `prop?` (optional). Same type system as `Dex::Operation`.
+
+```ruby
+class UserCreated < Dex::Event
+  prop :user_id, Integer
+  prop :email, String
+  prop? :referrer, String
+end
+```
+
+Reserved names: `id`, `timestamp`, `trace_id`, `caused_by_id`, `caused_by`, `context`, `publish`, `metadata`, `sync`.
+
+Events are frozen after creation. Each gets auto-generated `id` (UUID), `timestamp` (UTC), `trace_id`, and optional `caused_by_id`.
+
+### Literal Types Cheatsheet
+
+Same types as Operation — `String`, `Integer`, `_Integer(1..)`, `_Array(String)`, `_Union("a", "b")`, `_Nilable(String)`, `_Ref(Model)`, etc.
+
+---
+
+## Publishing
+
+```ruby
+# Class-level (most common)
+OrderPlaced.publish(order_id: 1, total: 99.99)              # async (default)
+OrderPlaced.publish(order_id: 1, total: 99.99, sync: true)   # sync
+
+# Instance-level
+event = OrderPlaced.new(order_id: 1, total: 99.99)
+event.publish                    # async
+event.publish(sync: true)        # sync
+
+# With causality
+OrderPlaced.publish(order_id: 1, total: 99.99, caused_by: parent_event)
+```
+
+**Async** (default): handlers dispatched via ActiveJob. **Sync**: handlers called inline.
+
+---
+
+## Handling
+
+Handlers are classes that subscribe to events. Subscription is automatic via `on`:
+
+```ruby
+class NotifyWarehouse < Dex::Event::Handler
+  on OrderPlaced
+  on OrderUpdated            # subscribe to multiple events
+
+  def perform
+    event                    # accessor — the event instance
+    event.order_id           # typed props
+    event.id                 # UUID
+    event.timestamp          # Time (UTC)
+    event.caused_by_id       # parent event ID (if traced)
+    event.trace_id           # shared trace ID across causal chain
+  end
+end
+```
+
+**Multi-event handlers**: A single handler can subscribe to multiple event types.
+
+### Loading Handlers (Rails)
+
+Handlers must be loaded for `on` to register. Standard pattern:
+
+```ruby
+# config/initializers/events.rb
+Rails.application.config.to_prepare do
+  Dex::Event::Bus.clear!
+  Dir.glob(Rails.root.join("app/event_handlers/**/*.rb")).each { |e| require(e) }
+end
+```
+
+### Retries
+
+```ruby
+class ProcessPayment < Dex::Event::Handler
+  on PaymentReceived
+  retries 3                              # exponential backoff (1s, 2s, 4s)
+  retries 3, wait: 10                    # fixed 10s between retries
+  retries 3, wait: ->(attempt) { attempt * 5 }  # custom delay
+
+  def perform
+    # ...
+  end
+end
+```
+
+When retries exhausted, exception propagates normally.
+
+---
+
+## Tracing (Causality)
+
+Link events in a causal chain. All events in a chain share the same `trace_id`.
+
+```ruby
+order_placed = OrderPlaced.new(order_id: 1, total: 99.99)
+
+# Option 1: trace block
+order_placed.trace do
+  InventoryReserved.publish(order_id: 1)   # caused_by_id = order_placed.id
+  ShippingRequested.publish(order_id: 1)   # same trace_id
+end
+
+# Option 2: caused_by keyword
+InventoryReserved.publish(order_id: 1, caused_by: order_placed)
+```
+
+Nesting works — each child gets the nearest parent's `id` as `caused_by_id`, and the root's `trace_id`.
+
+---
+
+## Suppression
+
+Prevent events from being published (useful in tests, migrations, bulk ops):
+
+```ruby
+Dex::Event.suppress { ... }                         # suppress all events
+Dex::Event.suppress(OrderPlaced) { ... }             # suppress specific class
+Dex::Event.suppress(OrderPlaced, UserCreated) { ... } # suppress multiple
+```
+
+Suppression is block-scoped and nestable. Child classes are suppressed when parent is.
+
+---
+
+## Persistence (Optional)
+
+Store events to database when configured:
+
+```ruby
+Dex.configure do |c|
+  c.event_store = EventRecord   # any model with create!(event_type:, payload:, metadata:)
+end
+```
+
+```ruby
+create_table :event_records do |t|
+  t.string :event_type
+  t.jsonb  :payload
+  t.jsonb  :metadata
+  t.timestamps
+end
+```
+
+Persistence failures are silently rescued — they never halt event publishing.
+
+---
+
+## Context (Optional)
+
+Capture ambient context (current user, tenant, etc.) at publish time:
+
+```ruby
+Dex.configure do |c|
+  c.event_context = -> { { user_id: Current.user&.id, tenant: Current.tenant } }
+  c.restore_event_context = ->(ctx) {
+    Current.user = User.find(ctx["user_id"]) if ctx["user_id"]
+    Current.tenant = ctx["tenant"]
+  }
+end
+```
+
+Context is stored in event metadata and restored before async handler execution.
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/dexkit.rb
+Dex.configure do |config|
+  config.event_store = nil               # model for persistence (default: nil)
+  config.event_context = nil             # -> { Hash } lambda (default: nil)
+  config.restore_event_context = nil     # ->(ctx) { ... } lambda (default: nil)
+end
+```
+
+Everything works without configuration. All three settings are optional.
+
+---
+
+## Testing
+
+```ruby
+# test/test_helper.rb
+require "dex/event_test_helpers"
+
+class Minitest::Test
+  include Dex::Event::TestHelpers
+end
+```
+
+Not autoloaded — stays out of production.
+
+### Capturing Events
+
+Captures events instead of dispatching handlers:
+
+```ruby
+def test_publishes_order_placed
+  capture_events do
+    OrderPlaced.publish(order_id: 1, total: 99.99)
+
+    assert_event_published(OrderPlaced)
+    assert_event_published(OrderPlaced, order_id: 1)
+    assert_event_count(OrderPlaced, 1)
+    refute_event_published(OrderCancelled)
+  end
+end
+```
+
+Outside `capture_events`, events are dispatched synchronously (test safety).
+
+### Assertions
+
+```ruby
+# Published
+assert_event_published(EventClass)                    # any instance
+assert_event_published(EventClass, prop: value)       # with prop match
+refute_event_published                                # nothing published
+refute_event_published(EventClass)                    # specific class not published
+
+# Count
+assert_event_count(EventClass, 3)
+
+# Tracing
+assert_event_trace(parent_event, child_event)         # caused_by_id match
+assert_same_trace(event_a, event_b, event_c)          # shared trace_id
+```
+
+### Suppression in Tests
+
+```ruby
+def test_no_side_effects
+  Dex::Event.suppress do
+    CreateOrder.call(item_id: 1)  # events suppressed
+  end
+end
+```
+
+### Complete Test Example
+
+```ruby
+class CreateOrderTest < Minitest::Test
+  include Dex::Event::TestHelpers
+
+  def test_publishes_order_placed
+    capture_events do
+      order = CreateOrder.call(item_id: 1, quantity: 2)
+
+      assert_event_published(OrderPlaced, order_id: order.id)
+      assert_event_count(OrderPlaced, 1)
+      refute_event_published(OrderCancelled)
+    end
+  end
+
+  def test_trace_chain
+    capture_events do
+      parent = OrderPlaced.new(order_id: 1, total: 99.99)
+
+      parent.trace do
+        InventoryReserved.publish(order_id: 1)
+      end
+
+      child = _dex_published_events.last
+      assert_event_trace(parent, child)
+      assert_same_trace(parent, child)
+    end
+  end
+end
+```
+
+---
+
+**End of reference.**

data/lib/dex/concern.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Dex
+  module Concern
+    def included(base)
+      base.extend(self::ClassMethods) if const_defined?(:ClassMethods, false)
+      super
+    end
+  end
+end

data/lib/dex/event/bus.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    class Bus
+      @_subscribers = {}
+      @_mutex = Mutex.new
+
+      class << self
+        def subscribe(event_class, handler_class)
+          Event.validate_event_class!(event_class)
+          unless handler_class.is_a?(Class) && handler_class < Dex::Event::Handler
+            raise ArgumentError, "#{handler_class.inspect} is not a Dex::Event::Handler subclass"
+          end
+
+          @_mutex.synchronize do
+            @_subscribers[event_class] ||= []
+            @_subscribers[event_class] |= [handler_class]
+          end
+        end
+
+        def unsubscribe(event_class, handler_class)
+          @_mutex.synchronize do
+            list = @_subscribers[event_class]
+            return unless list
+
+            list.delete(handler_class)
+            @_subscribers.delete(event_class) if list.empty?
+          end
+        end
+
+        def subscribers_for(event_class)
+          @_mutex.synchronize do
+            @_subscribers.each_with_object([]) do |(subscribed_class, handlers), result|
+              result.concat(handlers) if event_class <= subscribed_class
+            end.uniq
+          end
+        end
+
+        def subscribers
+          @_mutex.synchronize { @_subscribers.transform_values(&:dup) }
+        end
+
+        def publish(event, sync:)
+          return if Suppression.suppressed?(event.class)
+
+          persist(event)
+          handlers = subscribers_for(event.class)
+          return if handlers.empty?
+
+          event_frame = event.trace_frame
+
+          handlers.each do |handler_class|
+            if sync
+              Trace.restore(event_frame) do
+                handler_class._event_handle(event)
+              end
+            else
+              enqueue(handler_class, event, event_frame)
+            end
+          end
+        end
+
+        def clear!
+          @_mutex.synchronize { @_subscribers.clear }
+        end
+
+        private
+
+        def persist(event)
+          store = Dex.configuration.event_store
+          return unless store
+
+          store.create!(
+            event_type: event.class.name,
+            payload: event._props_as_json,
+            metadata: event.metadata.as_json
+          )
+        rescue => e
+          Event._warn("Failed to persist event: #{e.message}")
+        end
+
+        def enqueue(handler_class, event, trace_data)
+          ctx = event.context
+
+          Dex::Event::Processor.perform_later(
+            handler_class: handler_class.name,
+            event_class: event.class.name,
+            payload: event._props_as_json,
+            metadata: event.metadata.as_json,
+            trace: trace_data,
+            context: ctx
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dex/event/execution_state.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    module ExecutionState
+      private
+
+      def _execution_state
+        if defined?(ActiveSupport::IsolatedExecutionState)
+          ActiveSupport::IsolatedExecutionState
+        else
+          Thread.current
+        end
+      end
+    end
+  end
+end

data/lib/dex/event/handler.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Dex
+  class Event
+    class Handler
+      attr_reader :event
+
+      def self.on(*event_classes)
+        event_classes.each do |ec|
+          Event.validate_event_class!(ec)
+          Bus.subscribe(ec, self)
+        end
+      end
+
+      def self.retries(count, **opts)
+        raise ArgumentError, "retries count must be a positive Integer" unless count.is_a?(Integer) && count > 0
+
+        if opts.key?(:wait)
+          wait = opts[:wait]
+          unless wait.is_a?(Numeric) || wait.is_a?(Proc)
+            raise ArgumentError, "wait: must be Numeric or Proc"
+          end
+        end
+
+        @_event_handler_retries = { count: count, **opts }
+      end
+
+      def self._event_handler_retry_config
+        if defined?(@_event_handler_retries)
+          @_event_handler_retries
+        elsif superclass.respond_to?(:_event_handler_retry_config)
+          superclass._event_handler_retry_config
+        end
+      end
+
+      def self._event_handle(event)
+        instance = new
+        instance.instance_variable_set(:@event, event)
+        instance.perform
+      end
+
+      def self._event_handle_from_payload(event_class_name, payload, metadata_hash)
+        event_class = Object.const_get(event_class_name)
+        event = _event_reconstruct(event_class, payload, metadata_hash)
+        _event_handle(event)
+      end
+
+      class << self
+        private
+
+        def _event_reconstruct(event_class, payload, metadata_hash)
+          coerced = event_class.send(:_coerce_serialized_hash, payload)
+          instance = event_class.allocate
+
+          event_class.literal_properties.each do |prop|
+            instance.instance_variable_set(:"@#{prop.name}", coerced[prop.name])
+          end
+
+          metadata = Event::Metadata.new(
+            id: metadata_hash["id"],
+            timestamp: Time.parse(metadata_hash["timestamp"]),
+            trace_id: metadata_hash["trace_id"],
+            caused_by_id: metadata_hash["caused_by_id"],
+            context: metadata_hash["context"]
+          )
+          instance.instance_variable_set(:@metadata, metadata)
+          instance.freeze
+          instance
+        end
+      end
+
+      def perform
+        raise NotImplementedError, "#{self.class.name} must implement #perform"
+      end
+    end
+  end
+end

data/lib/dex/event/metadata.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dex
+  class Event
+    class Metadata
+      attr_reader :id, :timestamp, :trace_id, :caused_by_id, :context
+
+      def initialize(id:, timestamp:, trace_id:, caused_by_id:, context:)
+        @id = id
+        @timestamp = timestamp
+        @trace_id = trace_id
+        @caused_by_id = caused_by_id
+        @context = context
+        freeze
+      end
+
+      def self.build(caused_by_id: nil)
+        id = SecureRandom.uuid
+        trace_id = Trace.current_trace_id || id
+        caused = caused_by_id || Trace.current_event_id
+
+        ctx = if Dex.configuration.event_context
+          begin
+            Dex.configuration.event_context.call
+          rescue => e
+            Event._warn("event_context failed: #{e.message}")
+            nil
+          end
+        end
+
+        new(
+          id: id,
+          timestamp: Time.now.utc,
+          trace_id: trace_id,
+          caused_by_id: caused,
+          context: ctx
+        )
+      end
+
+      def as_json
+        h = {
+          "id" => @id,
+          "timestamp" => @timestamp.iso8601(6),
+          "trace_id" => @trace_id
+        }
+        h["caused_by_id"] = @caused_by_id if @caused_by_id
+        h["context"] = @context if @context
+        h
+      end
+    end
+  end
+end