tcb 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77ac348140af6f18f4416932f320bc474f3131c14903c592cf83f352a02e1297
-  data.tar.gz: 4f5462a8425eb01612a3e6ffb3b89c8c848504db97d8a2fb913c7961abbc67b2
+  metadata.gz: 3d004e21f0c4555988f0a5b84e40a4ae4710933b3e862ab964a6a4bc07cd02cf
+  data.tar.gz: 684c9a07870739ebec829c872f6c4c71d455b0919d369d0f9badd000fceb28d3
 SHA512:
-  metadata.gz: 2eed8f7a67fcef1a356262a854b707964a2d5eb15c910a5a508368fc602e7f0892742e0ff24035a26f7542ae9de14740288db7fe07655d7e13e25a444db8799e
-  data.tar.gz: d41fd603ec8b6cc729396ea7ac5b9b692bd983b080f59e8f1df23faab88976563bd460513ed0634d25fba6a3911f77e583e8508c0ce455997347ed25eef00e12
+  metadata.gz: 71b0fe98490c7a0c1d995b7eaf7612976690306c55c1ccc904f4038089f11c3f6389e03afd9474fd1a058c28de4905fdfca811cb4e88fcf77119a361cde3ff3f
+  data.tar.gz: a433451a28f9fe1bd295db4fe40e4760069d4d4915ec8807f8f35f2791df6821dd86f1e24b7c57bbb470dc9b4d618f540e26862a61461e71af9c839bc881a661

data/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.2] - 2026-05-07
+
+### Fixed
+
+- `tcb:install` generator — `TCB.domain_modules=` moved into `Rails.application.config.to_prepare` block; bare initializer runs before Zeitwerk loads application constants, causing `NameError` when domain modules reference Rails classes such as `ApplicationJob` or `ApplicationRecord`
+
 ## [0.6.1] - 2026-05-06
 
 ### Fixed

data/README.md

@@ -1,10 +1,36 @@
 # TCB
 
-A lightweight, thread-safe event and command runtime for Domain-Driven Design on Rails.
+Is your codebase using every form of coupling except the one architects actually recommend?
+How much does a feature request cost you now?
+
+TCB gives each concern its own place, a clean domain language, and a full record
+of everything that happened, so you can understand and evolve your business logic
+with confidence.
+
+Imagine the following scenario. An order is placed. Stock gets reserved. The customer is notified.
+Now imagine each piece in its own domain, reacting independently, easy to test in isolation,
+simple to evolve as your business grows, and the full picture always visible.
+
+```ruby
+PlaceOrder = Data.define(:order_id, :customer)
+def Sales.place!(order_id:, customer:) = TCB.dispatch(PlaceOrder.new(order_id:, customer:))
 
-TCB gives Rails applications a clean domain language. Events, aggregates, and handlers are plain Ruby. No framework inheritance, no infrastructure details leaking into your domain.
+correlation_id = Sales.place!(order_id: 42, customer: "Alice")
+#   Sales             → OrderPlaced        persisted, published
+#     Warehouse       → StockReserved      reacts automatically, same correlation
+#       Notifications → CustomerNotified   reacts automatically, same correlation
+
+TCB.read_correlation(correlation_id).to_a # => all three events, across all three domains, in order
+```
+
+A lightweight, thread-safe event and command runtime for Domain-Driven Design on Rails.
+Events, aggregates, and handlers are plain Ruby. No framework inheritance, no infrastructure
+details leaking into your domain.
 
-TCB uses a command and event bus as an architectural coordination mechanism. Commands are decisions routed to exactly one handler. Events are facts broadcast to any number of reactions. The goal is to isolate side-effects, allow independent evolution of behaviors, and support an increasing number of business-significant events.
+Rails can change. Your domains should change only when your business demands it.
+Clean domain code pays compound interest. It's easier to reason about, easier to test,
+and easier for AI agents to work with. TCB keeps your domain that way.
+Rails takes care of the rest.
 
 ## Installation
 
@@ -46,11 +72,11 @@ bus.publish(UserRegistered.new(id: 1, email: "alice@example.com"))
 
 ### Execution model
 
-TCB::EventBus uses a single background thread to process events. Publishing is non-blocking — the event is placed on a queue and control returns to the caller immediately. The dispatcher thread processes events in FIFO order. Handlers for a given event execute sequentially within the dispatcher thread.
+TCB::EventBus uses a single background thread to process events. Publishing is non-blocking. The event is placed on a queue and control returns to the caller immediately. The dispatcher thread processes events in FIFO order. Handlers for a given event execute sequentially within the dispatcher thread.
 
 This design favors determinism and simplicity: events are always processed in the order they were published, and handlers cannot race with each other.
 
-For tests and simple use cases, `sync: true` executes handlers in the caller thread immediately — no background thread, no queue:
+For tests and simple use cases, `sync: true` executes handlers in the caller thread immediately, no background thread, no queue:
 
 ```ruby
 bus = TCB::EventBus.new(sync: true)
@@ -77,7 +103,7 @@ The event queue is unbounded by default. If handlers are slower than the rate of
 TCB::EventBus.new(max_queue_size: 10_000)
 ```
 
-When the queue is full, `publish` blocks until space is available. The right value depends on your event volume and handler latency — measure before deciding.
+When the queue is full, `publish` blocks until space is available. The right value depends on your event volume and handler latency. Measure before deciding.
 
 ---
 
@@ -140,7 +166,7 @@ end
 Event classes can come from anywhere. Cross-module reactions are the norm, not the exception. Each handler is isolated. Ine failure does not prevent others from executing.
 
 Domain modules are declared once at the top level, before infrastructure is configured.
-This is the only place TCB needs to know about your bounded contexts — all reactions,
+This is the only place TCB needs to know about your bounded contexts. All reactions,
 persistence rules, and handler mappings live inside each module itself.
 
 ```ruby
@@ -154,7 +180,7 @@ end
 
 `TCB.domain_modules=` wires up subscriptions and command routing from all modules.
 `TCB.configure` provides the infrastructure they run on. The two are intentionally
-separate — domain modules don't change between environments, infrastructure does.
+separate. Domain modules don't change between environments, infrastructure does.
 
 ---
 
@@ -370,7 +396,7 @@ end
 
 ### Domain modules
 
-Domain modules are the bounded contexts of your application. Declare them once, at the top level — before infrastructure is configured:
+Domain modules are the bounded contexts of your application. Declare them once, at the top level, before infrastructure is configured:
 
 ```ruby
 # config/initializers/tcb.rb
@@ -425,7 +451,7 @@ Rails.application.config.after_initialize do
 end
 ```
 
-`sync: true` executes handlers in the caller thread — no background thread, no polling. `after_initialize` runs once at boot. Between tests, call `TCB.reset!` to get a fresh bus and store.
+`sync: true` executes handlers in the caller thread. No background thread, no polling. `after_initialize` runs once at boot. Between tests, call `TCB.reset!` to get a fresh bus and store.
 
 Each domain module gets its own database table. Domains stay isolated at the persistence level:
 
@@ -483,7 +509,7 @@ envelope.causation_id   # UUID string, event_id of the triggering event; nil for
 
 ## Correlation and causation tracking
 
-Every `TCB.dispatch` generates a `correlation_id` and returns it to the caller. All events produced within that dispatch chain share the same `correlation_id`, regardless of how deep the reactive chain goes. `causation_id` identifies the direct cause — the `event_id` of the envelope that triggered the handler.
+Every `TCB.dispatch` generates a `correlation_id` and returns it to the caller. All events produced within that dispatch chain share the same `correlation_id`, regardless of how deep the reactive chain goes. `causation_id` identifies the direct cause, the `event_id` of the envelope that triggered the handler.
 
 ```
 Sales.place!(order_id: 42, customer: "Alice")
@@ -529,7 +555,7 @@ TCB.read_correlation("req-abc").between(1.hour.ago, Time.now).to_a
 
 Results are ordered by `occurred_at` across all domains. Each result is a `TCB::Envelope` with `correlation_id` and `causation_id` populated.
 
-`across:` defaults to all configured domain modules that have persistence registrations. Domains without persistence — like `Notifications` in the example above — are excluded automatically.
+`across:` defaults to all configured domain modules that have persistence registrations. Domains without persistence, like `Notifications` in the example above, are excluded automatically.
 
 ---
 
@@ -598,17 +624,21 @@ Generates:
 | `--skip-migration` | Skip migration (event_store only) |
 | `--no-comments` | Generate without inline guidance comments |
 
-After generating, add your module to config/initializers/tcb.rb. Domain modules don't change between environments — infrastructure does. Keeping them separate means your bounded contexts are declared once, while the bus and store are configured per environment:
+After generating, add your module to config/initializers/tcb.rb. Domain modules don't change between environments. Infrastructure does. Keeping them separate means your bounded contexts are declared once, while the bus and store are configured per environment:
 
 ```ruby
 # config/initializers/tcb.rb
-TCB.domain_modules = [
-  Sales,
-  Warehouse,
-  Notifications
-]
+Rails.application.config.to_prepare do
+  TCB.domain_modules = [
+    Sales,
+    Warehouse,
+    Notifications
+  ]
+end
 ```
 
+`to_prepare` runs after Zeitwerk loads all application constants. Use it instead of a bare initializer. Domain modules typically reference Rails classes (ApplicationJob, ApplicationRecord, etc.) that are not yet available at initializer time.
+
 ---
 
 ## Error Handling
@@ -645,7 +675,7 @@ bus.force_shutdown
 
 Configure TCB once at boot in `config/environments/test.rb` (see Configuration above). Between tests, call `TCB.reset!` to get a fresh event bus and a clean event store.
 
-`TCB.reset!` shuts down the current bus, clears the event store, and clears all subscriptions. The next test starts with a clean slate. Domain modules do not need to be re-declared — they are set once at the top level and persist across resets.
+`TCB.reset!` shuts down the current bus, clears the event store, and clears all subscriptions. The next test starts with a clean slate. Domain modules do not need to be re-declared. They are set once at the top level and persist across resets.
 
 ### Synchronous mode
 
@@ -661,12 +691,20 @@ Rails.application.config.after_initialize do
 end
 ```
 
+`after_initialize` runs once at boot. Tests do not reload Rails, so `to_prepare` is unnecessary. Between tests, TCB.reset! shuts down the current bus and clears the store, but also wipes the configuration. Restore it in your test teardown so every test starts with a clean, fully configured bus.
+
 ### Minitest
 
 ```ruby
 class OrdersTest < Minitest::Test
   include TCB::MinitestHelpers
-  def teardown = TCB.reset!
+  def teardown
+    TCB.reset!
+    TCB.configure do |c|
+      c.event_bus   = TCB::EventBus.new(sync: true)
+      c.event_store = TCB::EventStore::InMemory.new
+    end
+  end
 
   def test_placing_order_publishes_event
     assert_published(Orders::OrderPlaced) do
@@ -687,7 +725,7 @@ assert_published(Orders::OrderPlaced, within: 0.5) { Orders.place!(...) }
 
 #### poll_assert
 
-Only needed when using an async bus. With `TCB::EventBus.new(sync: true)`, handlers execute in the caller thread and results are available immediately — no polling required.
+Only needed when using an async bus. With `TCB::EventBus.new(sync: true)`, handlers execute in the caller thread and results are available immediately. No polling required.
 
 ```ruby
 poll_assert("reserve inventory called") { CALLED.include?(:reserve_inventory) }
@@ -699,7 +737,13 @@ poll_assert("payment processed", within: 2.0) { Payment.completed? }
 ```ruby
 # spec/support/tcb.rb
 RSpec.configure do |config|
-  config.after(:each) { TCB.reset! }
+  config.after(:each) do
+    TCB.reset!
+    TCB.configure do |c|
+      c.event_bus   = TCB::EventBus.new(sync: true)
+      c.event_store = TCB::EventStore::InMemory.new
+    end
+  end
 end
 ```
 

data/lib/generators/tcb/install/templates/tcb.rb.tt

@@ -2,19 +2,27 @@
 # Add your domain modules here after generating them:
 #   rails generate tcb:event_store orders place_order:order_id,customer
 #   rails generate tcb:domain notifications send_welcome_email:user_id,email
-TCB.domain_modules = [
-  # Orders,
-  # Notifications,
-]
-
-# Infrastructure — how events are transported and stored
-# Runs on every Rails reload in development
+#
+# to_prepare runs after Zeitwerk loads all application constants.
+# Domain modules typically reference Rails classes (ApplicationJob, ApplicationRecord, etc.)
+# that are not yet available at initializer time.
 Rails.application.config.to_prepare do
-  TCB.configure do |c|
-    c.event_bus   = TCB::EventBus.new(
-      handle_signals: true,
-      shutdown_timeout: 10.0
-    )
-    c.event_store = TCB::EventStore::ActiveRecord.new
-  end
+  TCB.domain_modules = [
+    # Orders,
+    # Notifications,
+  ]
 end
+
+# Infrastructure — how events are transported and stored
+# Configure per environment in config/environments/*.rb so differences are explicit.
+# Example for development:
+#
+#   Rails.application.config.to_prepare do
+#     TCB.reset!
+#     TCB.configure do |c|
+#       c.event_bus   = TCB::EventBus.new(handle_signals: false, shutdown_timeout: 10.0)
+#       c.event_store = TCB::EventStore::ActiveRecord.new
+#     end
+#   end
+#
+# See README for production and test examples.

data/lib/tcb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TCB
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tcb
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Ljubomir Marković
@@ -192,7 +192,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Lightweight DDD runtime for Rails — events, commands, and aggregates
 test_files: []