funes-rails 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa0d0b4e8fb74b347944d1cd0796b57e545a2bcd5387afb0d4c1291fd80f70db
-  data.tar.gz: 4a1ce3b83983e298c27ff627a4510ab04eaf23108a64fc4988b51c683efdd892
+  metadata.gz: fa21a99408ee10d9f9b17e06af87f2f51d099fd593fadec8672c71b15110a53e
+  data.tar.gz: 893a107d52489ffc4e7680f558dbe8dfce0c8bdf88ad05bd4a704efd0eeb97ce
 SHA512:
-  metadata.gz: 14aa532ec93bd4513e462394ba9b88043e99cacb1f903020bec50f4f9678aa9ee405640fee98e8470cc734260007b31e659608bc411843bc112f9b383480fd14
-  data.tar.gz: 97c2655d30a097463aa8549faef89763421c629bbb2a67d9c456c2a1a9d551c8ab011e9207f571419412e04659816816f11fc010c03cc90d6534f9b2082dab70
+  metadata.gz: eddd2d0d5c46fe75338a095098a5391eb3aa81b29196f4fd352458ba6e6efc75673959ac59b1b40c555ec1a2f8914524503f718017845f636b030577578dc3f6
+  data.tar.gz: c57f6bb79093b02c19abc8c5246bb741c4cf23d16c24dc2e1857e7941457e02ddd4a2e83441b767302bf6c4322bb88a087703bf2480031ac0bc7aa5e86470607

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/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.3"
 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.3
 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