dexkit 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7be5c6e58f2741692419cf25f9a8e76df8003036dd17139073561fe5141e3bdc
-  data.tar.gz: 28f77abedf2552c3a2f319abd175f61855f956517295e1ea435a3dbf88327735
+  metadata.gz: ec8b561633fbdf9989f8bc2476fe84ad2cd0c32177990d03380d63f59a8368a9
+  data.tar.gz: a348e6b1090374bfda6281e6a58fe16af3e285bb009fad38be60a3ba2c510720
 SHA512:
-  metadata.gz: 800756f2f2f22dc4e487794fc129ccafc57ee815b3e26aea67c1f8eef9195654106cd7ab7b91525c4e5325da1696e94069ffc78e2d1302dc1f7a5d6f6eff8e82
-  data.tar.gz: 7bf8212783439db36adb9ae04854f981d2e2e6d9db8ca7bf9cd0768faa566aec98addc56f12640b7d0c284e3a7f4ca9d8afa05ba1f90568241970214bd8307d5
+  metadata.gz: 49d44b87657f65927b88c7fc1296ccab5d5246637a1887a126b0949e11bd452ecc0deb5fea90ef7f3329051b7bc13895f8f0ef73286705de44f7d21dccc0802a
+  data.tar.gz: 43182a4b6b6c904afe87fb385cff3a42057975363b5fd53e10744264f3af8cd5d48306b0ade26fd195b0d4fca696cbd85ac6c06e4434f48c280fb42a959beb80

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-03
+
+### Added
+
+- **Form objects** — `Dex::Form` base class for user-facing input handling
+  - Typed attributes via ActiveModel (`attribute :name, :string`)
+  - Normalization on assignment (`normalizes :email, with: -> { _1&.strip&.downcase }`)
+  - Full ActiveModel validation support, including custom `uniqueness` validator with scope, case-insensitive matching, conditions, and record exclusion
+  - `model` DSL for binding a form to an ActiveRecord model class (drives `model_name`, `persisted?`, `to_key`, `to_param`)
+  - `record` reader and `with_record` chainable method for edit/update forms — record is excluded from form attributes and protected from mass assignment
+  - `nested_one` / `nested_many` DSL for nested form objects with auto-generated constants, `build_` methods, and `_attributes=` setters
+  - Hash coercion, Rails numbered hash format, and `_destroy` filtering in nested forms
+  - Validation propagation from nested forms with prefixed error keys (`address.street`, `documents[0].doc_type`)
+  - `ActionController::Parameters` support — strong parameters (`permit`) not required; the form's attribute declarations are the whitelist
+  - `to_h` / `to_hash` serialization including nested forms
+  - `ValidationError` for bang-style save patterns
+  - Full Rails `form_with` / `fields_for` compatibility
+- **Form uniqueness validator** — `validates :email, uniqueness: true`
+  - Model resolution chain: explicit `model:` option, `model` DSL, or infer from class name (`UserForm` → `User`)
+  - Options: `scope`, `case_sensitive`, `conditions` (zero-arg or form-arg lambda), `attribute` mapping, `message`
+  - Excludes current record via model's `primary_key` (not hardcoded `id`)
+  - Declaration-time validation of `model:` and `conditions:` options
+- Added `actionpack` as development dependency for testing Rails controller integration
+- Added `activemodel >= 6.1` as runtime dependency
+
+### Changed
+
+- `Dex::Match` is now included in `Dex::Operation` – `Ok`/`Err` are available without prefix inside operations. External contexts (controllers, POROs) can still use `Dex::Ok`/`Dex::Err` or `include Dex::Match`.
+
+## [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

@@ -48,8 +48,6 @@ rescue_from Stripe::CardError, as: :card_declined
 **Ok / Err** – pattern match on operation outcomes with `.safe.call`:
 
 ```ruby
-include Dex::Match
-
 case CreateUser.new(email: email).safe.call
 in Ok(name:)
   puts "Welcome, #{name}!"
@@ -84,6 +82,120 @@ 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
+```
+
+## Forms
+
+Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
+
+```ruby
+class OnboardingForm < Dex::Form
+  model User
+
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :email, :string
+
+  normalizes :email, with: -> { _1&.strip&.downcase.presence }
+
+  validates :email, presence: true, uniqueness: true
+  validates :first_name, :last_name, presence: true
+
+  nested_one :address do
+    attribute :street, :string
+    attribute :city, :string
+    validates :street, :city, presence: true
+  end
+end
+
+form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ", first_name: "Alice", last_name: "Smith")
+form.email  # => "alice@example.com"
+form.valid?
+```
+
+### What you get out of the box
+
+**ActiveModel attributes** with type casting, normalization, and full Rails validation DSL.
+
+**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
+end
+```
+
+**Rails form compatibility** — works with `form_with`, `fields_for`, and nested attributes out of the box.
+
+**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`:
+
+```ruby
+def save
+  return false unless valid?
+
+  case operation.safe.call
+  in Ok then true
+  in Err => e then errors.add(:base, e.message) and false
+  end
+end
+```
+
 ## Installation
 
 ```ruby
@@ -100,7 +212,8 @@ 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
+cp $(bundle show dexkit)/guides/llm/FORM.md app/forms/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.**