funes-rails 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa0d0b4e8fb74b347944d1cd0796b57e545a2bcd5387afb0d4c1291fd80f70db
-  data.tar.gz: 4a1ce3b83983e298c27ff627a4510ab04eaf23108a64fc4988b51c683efdd892
+  metadata.gz: 2c51e21ab14ee2a2a3994320929a81e9e06a5eae4247c3ef3415f4c86f901b93
+  data.tar.gz: aa84a44d6e3d9b920c55952a7fefee48d186d185a5e6718b4c22577d3bcfef02
 SHA512:
-  metadata.gz: 14aa532ec93bd4513e462394ba9b88043e99cacb1f903020bec50f4f9678aa9ee405640fee98e8470cc734260007b31e659608bc411843bc112f9b383480fd14
-  data.tar.gz: 97c2655d30a097463aa8549faef89763421c629bbb2a67d9c456c2a1a9d551c8ab011e9207f571419412e04659816816f11fc010c03cc90d6534f9b2082dab70
+  metadata.gz: a28819da667269a81dbc569f1deffdb9b1fbb2d48308106b1662f1abfddbb55d8ef7df6ca3cec4007c19088b6980559725a2f1187dcee577fd847e3dc95f811b
+  data.tar.gz: 1811203127bd94c7537355ccb974b1b7dd29dcbd40291075bcd43c5c5e9408929aa8bf4eb2b559de56b978666e05fa3baa99ba443b0498458f5f6ca9bb3417f7

data/README.md

@@ -90,25 +90,6 @@ Funes gives you fine-grained control over when and how projections run:
 * **Validation before persistence:** before upserting the materialization, Funes runs ActiveRecord validations on the materialization model. If the model is invalid, an `ActiveRecord::RecordInvalid` exception is raised, the transaction rolls back, and the event is not persisted.
 * **Fail-loud on errors:** if a projection fails with a database error (e.g., constraint violation) or a validation error, the transaction rolls back, the event is marked as not persisted (`persisted?` returns `false`), and the exception (`ActiveRecord::StatementInvalid` or `ActiveRecord::RecordInvalid`) propagates. This ensures bugs are immediately visible rather than silently hidden, while keeping the event in a consistent state for any rescue logic in your application.
 
-### Host-managed transactions with `append!`
-
-When you need to wrap `append` inside your own `ActiveRecord::Base.transaction` — for example, to keep a sibling update in lockstep with the event, or to append to two streams atomically — use `append!`. It mirrors Rails' `save` / `save!` pair: on any failure it raises `ActiveRecord::RecordInvalid`, which rolls back the enclosing transaction.
-
-```ruby
-event = Order::Placed.new(total: 99.99)
-begin
-  ActiveRecord::Base.transaction do
-    customer.update!(last_ordered_at: Time.current)
-    OrderEventStream.for(order_id).append!(event)
-  end
-rescue ActiveRecord::RecordInvalid
-  event.persisted?  # => false
-  event.errors.any? # => true
-end
-```
-
-The failed event stays queryable after the rescue (`persisted?`, `errors`), just like a record that failed `save!`. Async projections are only enqueued once the outer transaction commits, so a rolled-back transaction never schedules a job.
-
 ### Async projections
 
 * **Background processing:** these are offloaded to `ActiveJob`, ensuring that heavy computations don't slow down the write path.
@@ -122,12 +103,22 @@ The failed event stays queryable after the rescue (`persisted?`, `errors`), just
 
 Guides and full API documentation are available at [docs.funes.org](https://docs.funes.org).
 
+## Performance
+
+Precise benchmarks are notoriously hard to pin down: workloads vary, and absolute numbers depend heavily on hardware, configuration, and the shape of the data. So treat the figures we publish as directional rather than definitive.
+
+That said, our measurements consistently show that the complexity of event stream operations stays **sub-linear, comfortably within `O(n)`** as the log grows — which is an important property for medium/long-lived streams.
+
+You can browse the latest measurements and join the conversation in the [Performance Measurements](https://github.com/funes-org/funes/discussions/categories/performance-measurements) discussions.
+
 ## Compatibility
 
-- **Ruby:** 3.1+
-- **Rails:** 7.2+
+Funes supports the following runtimes:
+
+- **Ruby** 3.1 or newer
+- **Rails** 7.2 or newer
 
-Rails 8.0+ requires Ruby 3.2 or higher.
+If you're on Rails 8.0 or above, you'll need Ruby 3.2 or newer — that's a Rails 8 requirement, not a Funes one.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/helpers/funes/projection_test_helper.rb

@@ -1,112 +1,111 @@
 module Funes
-  # Test helper for testing projections in isolation.
+  # Test helper for exercising projections in isolation.
   #
-  # Include this module in your test classes to access helper methods that allow you to test
-  # individual projection interpretations without needing to process entire event streams.
+  # Include this module in your test class to access methods that interpret a
+  # single event, build the initial state, or apply the final state of a
+  # projection — without processing an entire event stream.
   #
-  # @example Include in your test
+  # Bind the projection class once with the +projection+ macro and then call
+  # {#interpret}, {#initial_state}, or {#final_state} without repeating it.
+  #
+  # @example Bind the projection at the class level
   #   class InventorySnapshotProjectionTest < ActiveSupport::TestCase
   #     include Funes::ProjectionTestHelper
+  #     projection InventorySnapshotProjection
   #
   #     test "receiving items increases quantity on hand" do
-  #       initial_state = InventorySnapshot.new(quantity_on_hand: 10)
+  #       state = InventorySnapshot.new(quantity_on_hand: 10)
   #       event = Inventory::ItemReceived.new(quantity: 5, unit_cost: 9.99)
   #
-  #       result = interpret_event_based_on(InventorySnapshotProjection, event, initial_state)
+  #       result = interpret(event, given: state)
   #
   #       assert_equal 15, result.quantity_on_hand
   #     end
   #   end
+  #
+  # @example Override the bound projection per call
+  #   interpret(event, given: state, projection: AnotherProjection)
   module ProjectionTestHelper
-    # Test a single event interpretation in isolation.
-    #
-    # This method extracts and executes a single interpretation block from a projection,
-    # allowing you to test how specific events transform state without processing entire
-    # event streams.
-    #
-    # @param [Class<Funes::Projection>] projection_class The projection class being tested.
-    # @param [Funes::Event] event_instance The event to interpret.
-    # @param [ActiveModel::Model, ActiveRecord::Base] previous_state The state before applying the event.
-    # @param [Time] at The temporal reference point. Defaults to Time.current.
-    # @return [ActiveModel::Model, ActiveRecord::Base] The new state after applying the interpretation.
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :projection_under_test, instance_accessor: false
+    end
+
+    class_methods do
+      # Binds the projection class exercised by this test class. Subclasses
+      # inherit the binding and may override it with another call to
+      # +projection+.
+      #
+      # @param [Class<Funes::Projection>] projection_class
+      # @return [void]
+      def projection(projection_class)
+        self.projection_under_test = projection_class
+      end
+    end
+
+    # Interprets a single event in isolation and returns the resulting state.
     #
-    # @example Test a single interpretation
-    #   initial_state = OrderSnapshot.new(total: 100)
-    #   event = Order::ItemAdded.new(amount: 50)
+    # If the event carries an +occurred_at+, it takes precedence over +at+ —
+    # mirroring how {Funes::Projection} replays persisted events. A +Date+
+    # passed as +at+ is coerced to its +beginning_of_day+.
     #
-    #   result = interpret_event_based_on(OrderSnapshotProjection, event, initial_state)
+    # @param [Funes::Event] event The event to interpret.
+    # @param [ActiveModel::Model, ActiveRecord::Base] given The state before applying the event.
+    # @param [Time, Date] at The temporal reference point. Defaults to +Time.current+.
+    # @param [Class<Funes::Projection>, nil] projection Overrides the class bound via +projection+.
+    # @return [ActiveModel::Model, ActiveRecord::Base] The state after the interpretation.
     #
+    # @example
+    #   result = interpret(Order::ItemAdded.new(amount: 50), given: OrderSnapshot.new(total: 100))
     #   assert_equal 150, result.total
-    #
-    # @example Test with validations
-    #   state = InventorySnapshot.new(quantity_on_hand: 5)
-    #   event = Inventory::ItemShipped.new(quantity: 10)
-    #
-    #   result = interpret_event_based_on(InventorySnapshotProjection, event, state)
-    #
-    #   assert_equal -5, result.quantity_on_hand
-    #   refute result.valid?
-    def interpret_event_based_on(projection_class, event_instance, previous_state, at = Time.current)
-      at = at.beginning_of_day if at.is_a?(Date) && !at.is_a?(Time)
-      event_at = event_instance.occurred_at || at
-      projection_class.instance_variable_get(:@interpretations)[event_instance.class]
-                      .call(previous_state, event_instance, event_at)
+    def interpret(event, given:, at: Time.current, projection: nil)
+      projection_class = resolve_projection(projection)
+      coerced_at = coerce_at(at)
+      event_at = event.occurred_at || coerced_at
+      projection_class.instance_variable_get(:@interpretations)[event.class]
+                      .call(given, event, event_at)
     end
 
-    # Test an initial_state block in isolation.
-    #
-    # This method extracts and executes the initial_state block from a projection,
-    # allowing you to test how the projection builds its starting state without
-    # processing entire event streams.
+    # Builds the initial state of the bound projection.
     #
-    # @param [Class<Funes::Projection>] projection_class The projection class being tested.
-    # @param [Time] at The temporal reference point. Defaults to Time.current.
-    # @return [ActiveModel::Model, ActiveRecord::Base] The initial state produced by the projection.
+    # @param [Time, Date] at The temporal reference point. Defaults to +Time.current+.
+    # @param [Class<Funes::Projection>, nil] projection Overrides the class bound via +projection+.
+    # @return [ActiveModel::Model, ActiveRecord::Base] The state produced by the +initial_state+ block.
     #
-    # @example Test initial state construction
-    #   result = build_initial_state_based_on(InventorySnapshotProjection)
-    #
-    #   assert_equal 0, result.quantity_on_hand
-    #
-    # @example Test with a specific timestamp
-    #   at = Time.new(2023, 5, 10)
-    #
-    #   result = build_initial_state_based_on(InventorySnapshotProjection, at)
-    #
-    #   assert_equal at, result.created_at
-    def build_initial_state_based_on(projection_class, at = Time.current)
+    # @example
+    #   assert_equal 0, initial_state.quantity_on_hand
+    def initial_state(at: Time.current, projection: nil)
+      projection_class = resolve_projection(projection)
       projection_class.instance_variable_get(:@interpretations)[:init]
-                      .call(projection_class.instance_variable_get(:@materialization_model), at)
+                      .call(projection_class.instance_variable_get(:@materialization_model), coerce_at(at))
     end
 
-    # Test a final_state block in isolation.
-    #
-    # This method extracts and executes the final_state block from a projection,
-    # allowing you to test how the projection transforms state after all event
-    # interpretations have been applied.
-    #
-    # @param [Class<Funes::Projection>] projection_class The projection class being tested.
-    # @param [ActiveModel::Model, ActiveRecord::Base] previous_state The state before applying the final transformation.
-    # @param [Time] at The temporal reference point. Defaults to Time.current.
-    # @return [ActiveModel::Model, ActiveRecord::Base] The final state after applying the transformation.
+    # Applies the final-state transformation of the bound projection.
     #
-    # @example Test final state transformation
-    #   state = OrderSnapshot.new(total: 100, item_count: 3)
+    # @param [ActiveModel::Model, ActiveRecord::Base] given The state to finalize.
+    # @param [Time, Date] at The temporal reference point. Defaults to +Time.current+.
+    # @param [Class<Funes::Projection>, nil] projection Overrides the class bound via +projection+.
+    # @return [ActiveModel::Model, ActiveRecord::Base] The state after the +final_state+ block.
     #
-    #   result = apply_final_state_based_on(OrderSnapshotProjection, state)
-    #
-    #   assert_equal 33.33, result.average_item_price
-    #
-    # @example Test with a specific timestamp
-    #   state = InventorySnapshot.new(quantity_on_hand: 10)
-    #   at = Time.new(2023, 5, 10)
-    #
-    #   result = apply_final_state_based_on(InventorySnapshotProjection, state, at)
-    #
-    #   assert_equal at, result.finalized_at
-    def apply_final_state_based_on(projection_class, previous_state, at = Time.current)
+    # @example
+    #   assert_equal 33.33, final_state(given: OrderSnapshot.new(total: 100, item_count: 3)).average_item_price
+    def final_state(given:, at: Time.current, projection: nil)
+      projection_class = resolve_projection(projection)
       projection_class.instance_variable_get(:@interpretations)[:final]
-                      .call(previous_state, at)
+                      .call(given, coerce_at(at))
     end
+
+    private
+      def resolve_projection(explicit)
+        explicit || self.class.projection_under_test ||
+          raise(ArgumentError,
+                "No projection bound. Declare `projection ProjectionClass` in your test class " \
+                "or pass `projection:` explicitly.")
+      end
+
+      def coerce_at(at)
+        at.is_a?(Date) && !at.is_a?(Time) ? at.beginning_of_day : at
+      end
   end
 end

data/app/projections/funes/projection.rb

@@ -1,5 +1,6 @@
 require "funes/unknown_event"
 require "funes/unknown_materialization_model"
+require "funes/invalid_materialization_state"
 
 module Funes
   # Projections perform the necessary pattern-matching to compute and aggregate the interpretations that the system
@@ -122,6 +123,31 @@ module Funes
         @materialization_model = active_record_or_model
       end
 
+      # Registers an instance method on the materialization model that owns the persistence step,
+      # replacing the framework's default upsert.
+      #
+      # When set, the named method is invoked on the in-memory state after all interpretations have
+      # run and +idx+ has been assigned. The method takes no arguments and is expected to raise on
+      # failure. The framework still calls +state.valid?+ and raises
+      # +Funes::InvalidMaterializationState+ before delegating, so the custom method only runs
+      # against valid state.
+      #
+      # Declaring +persist_materialization_model_with+ also lifts the requirement that the
+      # materialization model be an +ActiveRecord::Base+ subclass: a plain +ActiveModel+ class is
+      # enough as long as it exposes +assign_attributes+, +attributes+, +valid?+ and +errors+.
+      #
+      # @param [Symbol] method_name The instance method on the materialization model that performs the write.
+      # @return [void]
+      #
+      # @example Persisting a projection to a JSON file
+      #   class YourProjection < Funes::Projection
+      #     materialization_model YourMaterializationModel
+      #     persist_materialization_model_with :save_to_object_storage!
+      #   end
+      def persist_materialization_model_with(method_name)
+        @persist_method = method_name
+      end
+
       # 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
@@ -142,7 +168,8 @@ module Funes
       def process_events(events_collection, at: nil, consistency: false)
         new(self.instance_variable_get(:@interpretations),
             self.instance_variable_get(:@materialization_model),
-            self.instance_variable_get(:@throws_on_unknown_events))
+            self.instance_variable_get(:@throws_on_unknown_events),
+            self.instance_variable_get(:@persist_method))
           .process_events(events_collection, at: at, consistency: consistency)
       end
 
@@ -150,13 +177,14 @@ module Funes
       def materialize!(events_collection, idx, at: nil)
         new(self.instance_variable_get(:@interpretations),
             self.instance_variable_get(:@materialization_model),
-            self.instance_variable_get(:@throws_on_unknown_events))
+            self.instance_variable_get(:@throws_on_unknown_events),
+            self.instance_variable_get(:@persist_method))
           .materialize!(events_collection, idx, at: at)
       end
     end
 
     # @!visibility private
-    def initialize(interpretations, materialization_model, throws_on_unknown_events)
+    def initialize(interpretations, materialization_model, throws_on_unknown_events, persist_method = nil)
       @interpretations = interpretations
       @materialization_model = materialization_model
       raise Funes::UnknownMaterializationModel,
@@ -164,6 +192,7 @@ module Funes
 
 
       @throws_on_unknown_events = throws_on_unknown_events
+      @persist_method = persist_method
     end
 
     # @!visibility private
@@ -191,13 +220,13 @@ module Funes
     # @!visibility private
     def materialize!(events_collection, idx, at: nil)
       state = process_events(events_collection, at: at)
-      materialized_model_instance = materialized_model_instance_based_on(state)
-      if materialization_model_is_persistable?
+      if persistable?
         state.assign_attributes(idx:)
         persist_based_on!(state)
+        return state if @persist_method
       end
 
-      materialized_model_instance
+      materialized_model_instance_based_on(state)
     end
 
     private
@@ -213,13 +242,23 @@ module Funes
         @materialization_model.new(state.attributes)
       end
 
-      def materialization_model_is_persistable?
-        @materialization_model.present? && @materialization_model <= ActiveRecord::Base
+      def persistable?
+        return false unless @materialization_model.present?
+        return true if @persist_method
+        @materialization_model <= ActiveRecord::Base
       end
 
       def persist_based_on!(state)
-        raise ActiveRecord::RecordInvalid.new(state) unless state.valid?
-        @materialization_model.upsert(state.attributes, unique_by: :idx)
+        unless state.valid?
+          raise Funes::InvalidMaterializationState.new(state) if @persist_method
+          raise ActiveRecord::RecordInvalid.new(state)
+        end
+
+        if @persist_method
+          state.public_send(@persist_method)
+        else
+          @materialization_model.upsert(state.attributes, unique_by: :idx)
+        end
       end
 
       def warn_about_ineffective_errors(event)

data/lib/funes/invalid_materialization_state.rb

@@ -0,0 +1,31 @@
+module Funes
+  # Raised when a projection configured with `persist_materialization_model_with` produces an
+  # invalid materialization state.
+  #
+  # When a projection declares a custom persistence method via `persist_materialization_model_with`,
+  # Funes still validates the materialization (via `state.valid?`) before delegating the write.
+  # If validation fails, this exception is raised and the custom persist method is *not* invoked.
+  #
+  # The failed materialization is exposed via `#record`, mirroring the ergonomics of
+  # `ActiveRecord::RecordInvalid` — but without coupling the custom-persist path to ActiveRecord.
+  # Like any unrescued exception, it propagates out of `materialize!` and rolls back any enclosing
+  # `ActiveRecord::Base.transaction`, which is the desired behaviour for transactional projections.
+  #
+  # @example Handling an invalid materialization state
+  #   begin
+  #     YourProjection.materialize!(events, "some-id", at: Time.current)
+  #   rescue Funes::InvalidMaterializationState => e
+  #     Rails.logger.error "Invalid materialization: #{e.message}"
+  #     e.record.errors.full_messages # the validation errors on the materialization
+  #   end
+  #
+  # @see Funes::Projection.persist_materialization_model_with
+  class InvalidMaterializationState < StandardError
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+      super("Invalid materialization state: #{record.errors.full_messages.to_sentence}")
+    end
+  end
+end

data/lib/funes/version.rb

@@ -1,3 +1,3 @@
 module Funes
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

data/lib/funes.rb

@@ -5,6 +5,7 @@ require "funes/event_metainformation_builder"
 require "funes/invalid_event_metainformation"
 require "funes/conflicting_actual_time_error"
 require "funes/missing_actual_time_attribute_error"
+require "funes/invalid_materialization_state"
 require "funes/engine"
 
 # Funes is an event sourcing framework for Ruby on Rails.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: funes-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Vinícius Almeida da Silva
@@ -216,6 +216,7 @@ files:
 - lib/funes/event_metainformation_builder.rb
 - lib/funes/inspection.rb
 - lib/funes/invalid_event_metainformation.rb
+- lib/funes/invalid_materialization_state.rb
 - lib/funes/missing_actual_time_attribute_error.rb
 - lib/funes/unknown_event.rb
 - lib/funes/unknown_materialization_model.rb