Class: Funes::Projection

Inherits:
Object
  • Object
show all
Defined in:
app/projections/funes/projection.rb

Overview

Projections perform the necessary pattern-matching to compute and aggregate the interpretations that the system gives to a particular collection of events. A projection consists of a series of interpretations defined by the programmer and an aggregated representation of these interpretations (therefore, a representation of transient and final states) which is referenced as the materialized representation.

A projection can be virtual or persistent. In practical terms, what defines this characteristic is the type of materialized representation configured in the projection.

  • Virtual projection: has an ActiveModel instance as its materialized representation. An instance like this is not persistent, but can be calculated at runtime and has characteristics like validation that are quite valuable in the context of a projection.

  • Persistent projection: has an ActiveRecord instance as its materialized representation. A persistent projection has the same validation capabilities but can be persisted and serve the search patterns needed for the application (read model or even eager read derivation).

Temporal Queries with as_of

The as_of parameter enables temporal queries by allowing projections to be computed as they would have been at a specific point in time. When processing events, only events created before or at the as_of timestamp are included, enabling point-in-time snapshots of the system state.

All interpretation blocks (initial_state, interpretation_for, and final_state) receive the as_of parameter, allowing custom temporal logic within projections.

Class Method Summary collapse

Class Method Details

.final_state {|transient_state, as_of| ... } ⇒ void

This method returns an undefined value.

Register a final interpretation of the state.

Default behavior: when this is not defined the projection does nothing after the interpretations

Examples:

class YourProjection < Funes::Projection
  final_state do |transient_state, as_of|
    # TODO...
  end
end

Yields:

  • (transient_state, as_of) —

    Block invoked to produce the final state.

Yield Parameters:

  • transient_state (ActiveModel::Model, ActiveRecord::Base) —

    The current transient state after all interpretations.

  • as_of (Time) —

    Context or timestamp used when interpreting.

Yield Returns:

  • (ActiveModel::Model, ActiveRecord::Base) —

    the final transient state instance



88
89
90
91
 
# File 'app/projections/funes/projection.rb', line 88

def final_state(&block)
  @interpretations ||= {}
  @interpretations[:final] = block
end

.initial_state {|materialization_model, as_of| ... } ⇒ void

This method returns an undefined value.

Registers the initial transient state that will be used for the current projection's interpretations.

Default behavior: When no block is provided the initial state defaults to a new instance of the configured materialization model.

Examples:

class YourProjection < Funes::Projection
  initial_state do |materialization_model, _as_of|
    materialization_model.new(some: :specific, value: 42)
  end
end

Yields:

Yield Parameters:

  • materialization_model (Class<ActiveRecord::Base>, Class<ActiveModel::Model>) —

    The materialization model constant.

  • as_of (Time) —

    Context or timestamp used when interpreting.

Yield Returns:

  • (ActiveModel::Model, ActiveRecord::Base) —

    the new transient state



67
68
69
70
 
# File 'app/projections/funes/projection.rb', line 67

def initial_state(&block)
  @interpretations ||= {}
  @interpretations[:init] = block
end

.interpretation_for(event_type) {|state, event, as_of| ... } ⇒ void

This method returns an undefined value.

Registers an interpretation block for a given event type.

Examples:

class YourProjection < Funes::Projection
  interpretation_for Order::Placed do |transient_state, current_event, _as_of|
    transient_state.assign_attributes(total: (transient_state.total || 0) + current_event.amount)
    transient_state
  end
end

Parameters:

  • event_type (Class<Funes::Event>) —

    The event class constant that will be interpreted.

Yields:

  • (state, event, as_of) —

    Block invoked with the current state, the event and the as_of marker. It should return a new version of the transient state

Yield Parameters:

  • transient_state (ActiveModel::Model, ActiveRecord::Base) —

    The current transient state

  • event (Funes::Event) —

    Event instance.

  • as_of (Time) —

    Context or timestamp used when interpreting.

Yield Returns:

  • (ActiveModel::Model, ActiveRecord::Base) —

    the new transient state



45
46
47
48
 
# File 'app/projections/funes/projection.rb', line 45

def interpretation_for(event_type, &block)
  @interpretations ||= {}
  @interpretations[event_type] = block
end

.materialization_model(active_record_or_model) ⇒ void

This method returns an undefined value.

Register the projection's materialization model

Examples:

Virtual projection (non-persistent, ActiveModel)

class YourProjection < Funes::Projection
  materialization_model YourActiveModelClass
end

Persistent projection (persisted read model, ActiveRecord)

class YourProjection < Funes::Projection
  materialization_model YourActiveRecordClass
end

Parameters:

  • active_record_or_model (Class<ActiveRecord::Base>, Class<ActiveModel::Model>) —

    The materialization model class.



107
108
109
 
# File 'app/projections/funes/projection.rb', line 107

def materialization_model(active_record_or_model)
  @materialization_model = active_record_or_model
end

.raise_on_unknown_events ⇒ void

This method returns an undefined value.

It changes the sensibility of the projection about events that it doesn't know how to interpret

By default, a projection ignores events that it doesn't have interpretations for. This method informs the projection that in cases like that an Funes::UnknownEvent should be raised and the DB transaction should be rolled back.

Examples:

class YourProjection < Funes::Projection
  raise_on_unknown_events
end


123
124
125
 
# File 'app/projections/funes/projection.rb', line 123

def raise_on_unknown_events
  @throws_on_unknown_events = true
end