Module: TypedEAV::EventDispatcher

Defined in:
lib/typed_eav/event_dispatcher.rb

Overview

In-process event-dispatch hub for Value and Field after_commit lifecycle events. Implements the contract that Phase 04 versioning and Phase 07 materialized index both depend on.

Contract surface

  • Config.on_value_change / Config.on_field_change are PUBLIC single proc slots (nil-default), backed by ActiveSupport::Configurable. Users set them via TypedEAV.configure { |c| c.on_value_change = ->(...) }.
  • register_internal_value_change(callable) / register_internal_field_change(callable) are FIRST-PARTY hooks for in-gem features (Phase 04 versioning, Phase 07 matview DDL regen). They are not private_class_method because Phase 04 lives in TypedEAV::Versioning::* and cannot reach a truly-private class method — the register_internal_* naming + this comment block signal first-party-only intent.
  • Internal subscribers fire FIRST, in registration order. User proc fires LAST. Phase 04 reserves slot 0 of value_change_internals by convention.

Error policy (split, locked at 03-CONTEXT.md §User-callback error policy)

  • Internal subscribers: exceptions PROPAGATE (fail-closed). Versioning corruption must be loud — silent failure leaves typed_eav_value_versions inconsistent with the live row. Without propagation, Phase 04 bugs would be invisible until someone audited the version table.
  • User proc: rescued via rescue StandardError, logged via Rails.logger.error, and SWALLOWED. The Value/Field row is already committed by the time the after_commit fires, so re-raising here would surface a misleading "save failed" error to the caller — the save actually succeeded.

Out of scope for this module

  • :rename detection happens in Field's after_commit callback (the model has direct access to saved_change_to_attribute?(:name)).
  • Orphan-Value handling (field.nil? because the field row was destroyed in the same transaction) is filtered at the model layer, not here. The dispatcher receives a guaranteed-non-nil object.

See .vbw-planning/phases/03-event-system/03-CONTEXT.md for the locked design decisions this module implements.

Class Method Summary collapse

Class Method Details

.dispatch_field_change(field, change_type) ⇒ Object

Dispatch a field lifecycle event. Called from Field#after_commit in plan 03-02. Same internals-first / user-last ordering and same error policy split as dispatch_value_change.

Signature: (field, change_type) — TWO args, no context. Field changes are CRUD-on-config (admin operations on field definitions), not per-entity user actions, so thread context is less relevant. Asymmetry vs dispatch_value_change is intentional and locked. change_type is one of :create | :update | :destroy | :rename.



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/typed_eav/event_dispatcher.rb', line 120

def dispatch_field_change(field, change_type)
  field_change_internals.each { |cb| cb.call(field, change_type) }

  user = TypedEAV::Config.on_field_change
  return unless user

  begin
    user.call(field, change_type)
  rescue StandardError => e
    Rails.logger.error(
      "[TypedEAV] on_field_change raised: #{e.class}: #{e.message} " \
      "(field_id=#{field.id} field_name=#{field.name} change_type=#{change_type})",
    )
  end
end

.dispatch_value_change(value, change_type) ⇒ Object

Dispatch a value lifecycle event. Called from Value#after_commit in plan 03-02. Internals fire FIRST (raises propagate), then the user proc fires LAST (errors logged + swallowed).

Signature: (value, change_type, TypedEAV.current_context) for both internals and user proc — context is injected here, not by callers. change_type is one of :create | :update | :destroy.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/typed_eav/event_dispatcher.rb', line 88

def dispatch_value_change(value, change_type)
  context = TypedEAV.current_context
  # Internals fire first, in registration order. Exceptions propagate —
  # versioning failure (Phase 04) must surface, never be silent.
  value_change_internals.each { |cb| cb.call(value, change_type, context) }

  user = TypedEAV::Config.on_value_change
  return unless user

  # User proc fires last. Wrapped in rescue because the Value row is
  # already committed — re-raising would surface a misleading "save
  # failed" error to the caller. Internal-vs-user error policy split
  # is locked at 03-CONTEXT.md §User-callback error policy.
  begin
    user.call(value, change_type, context)
  rescue StandardError => e
    Rails.logger.error(
      "[TypedEAV] on_value_change raised: #{e.class}: #{e.message} " \
      "(value_id=#{value.id} field_id=#{value.field_id} change_type=#{change_type})",
    )
  end
end

.field_change_internals ⇒ Object

Internal subscribers for Field lifecycle events. Same registration protocol as value_change_internals.



56
57
58
 
# File 'lib/typed_eav/event_dispatcher.rb', line 56

def field_change_internals
  @field_change_internals ||= []
end

.register_internal_field_change(callable) ⇒ Object

Register an in-gem field-change subscriber. Same first-party-only contract as register_internal_value_change. Field subscribers are invoked with (field, change_type) — TWO args, no context. The asymmetry vs value-change is locked at 03-CONTEXT.md §Phase Boundary.



77
78
79
 
# File 'lib/typed_eav/event_dispatcher.rb', line 77

def register_internal_field_change(callable)
  field_change_internals << callable
end

.register_internal_value_change(callable) ⇒ Object

Register an in-gem value-change subscriber. Called at engine boot by Phase 04 versioning and Phase 07 matview. Subscribers are invoked in registration order with (value, change_type, context). Exceptions raised here PROPAGATE — fail-closed because versioning corruption must be loud. See module-level comment §"Error policy".

NOT private_class_method: Phase 04 lives in TypedEAV::Versioning::* and cannot call a truly-private class method. The register_internal_* naming + this comment signal first-party-only intent.



69
70
71
 
# File 'lib/typed_eav/event_dispatcher.rb', line 69

def register_internal_value_change(callable)
  value_change_internals << callable
end

.reset! ⇒ Object

Clear ONLY the internal-subscribers arrays. Does NOT touch Config.on_value_change / Config.on_field_change — Config.reset! owns the user-proc state.

Splitting reset is load-bearing: Phase 04 versioning registers on the internal list at engine load. Calling EventDispatcher.reset! must NOT require re-running engine load to restore versioning. Test teardown that needs to clear EVERYTHING calls Config.reset! AND EventDispatcher.reset! — see 03-CONTEXT.md §"Reset split".



145
146
147
148
 
# File 'lib/typed_eav/event_dispatcher.rb', line 145

def reset!
  @value_change_internals = []
  @field_change_internals = []
end

.value_change_internals ⇒ Object

Internal subscribers for Value lifecycle events. Populated at engine boot by Phase 04 versioning (slot 0) and Phase 07 matview (subsequent slots). Exposed as a reader for test introspection — first-party registration goes through register_internal_value_change.



50
51
52
 
# File 'lib/typed_eav/event_dispatcher.rb', line 50

def value_change_internals
  @value_change_internals ||= []
end