funes-rails 0.1.0

data/app/helpers/funes/projection_test_helper.rb

@@ -0,0 +1,54 @@
+module Funes
+  # Test helper for testing 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.
+  #
+  # @example Include in your test
+  #   class InventorySnapshotProjectionTest < ActiveSupport::TestCase
+  #     include Funes::ProjectionTestHelper
+  #
+  #     test "receiving items increases quantity on hand" do
+  #       initial_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)
+  #
+  #       assert_equal 15, result.quantity_on_hand
+  #     end
+  #   end
+  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, nil] as_of Optional timestamp for temporal logic. Defaults to Time.current.
+    # @return [ActiveModel::Model, ActiveRecord::Base] The new state after applying the interpretation.
+    #
+    # @example Test a single interpretation
+    #   initial_state = OrderSnapshot.new(total: 100)
+    #   event = Order::ItemAdded.new(amount: 50)
+    #
+    #   result = interpret_event_based_on(OrderSnapshotProjection, event, initial_state)
+    #
+    #   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, as_of = Time.current)
+      projection_class.instance_variable_get(:@interpretations)[event_instance.class]
+                      .call(previous_state, event_instance, as_of)
+    end
+  end
+end

data/app/jobs/funes/application_job.rb

@@ -0,0 +1,4 @@
+module Funes
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/funes/persist_projection_job.rb

@@ -0,0 +1,8 @@
+module Funes
+  class PersistProjectionJob < ApplicationJob
+    def perform(event_stream_idx, projection_class, as_of = nil)
+      event_stream = EventStream.for(event_stream_idx, as_of)
+      projection_class.materialize!(event_stream.events, event_stream.idx, as_of)
+    end
+  end
+end

data/app/mailers/funes/application_mailer.rb

@@ -0,0 +1,6 @@
+module Funes
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/funes/application_record.rb

@@ -0,0 +1,5 @@
+module Funes
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/funes/event.rb

@@ -0,0 +1,137 @@
+module Funes
+  # Base class for all events in the Funes event sourcing framework.
+  #
+  # Events are immutable facts that represent something that happened in the system. They use
+  # ActiveModel for attributes and validations, making them familiar to Rails developers.
+  #
+  # ## Event Validation
+  #
+  # Events support two types of validation:
+  #
+  # - **Own validation:** Standard ActiveModel validations defined on the event class itself.
+  # - **Adjacent state validation:** Validation errors from consistency projections that check
+  #   if the event would lead to an invalid state.
+  #
+  # The `valid?` method returns `true` only if both validations pass. The `errors` method
+  # merges both types of errors for display.
+  #
+  # ## Defining Events
+  #
+  # Events inherit from `Funes::Event` and define attributes using ActiveModel::Attributes:
+  #
+  # @example Define a simple event
+  #   class Order::Placed < Funes::Event
+  #     attribute :total, :decimal
+  #     attribute :customer_id, :string
+  #     attribute :at, :datetime, default: -> { Time.current }
+  #
+  #     validates :total, presence: true, numericality: { greater_than: 0 }
+  #     validates :customer_id, presence: true
+  #   end
+  #
+  # @example Using the event
+  #   event = Order::Placed.new(total: 99.99, customer_id: "cust-123")
+  #   stream.append!(event)
+  #
+  # @example Handling validation errors
+  #   event = stream.append!(Order::Placed.new(total: -10))
+  #   unless event.valid?
+  #     puts event.own_errors.full_messages      # => Event's own validation errors
+  #     puts event.state_errors.full_messages    # => Consistency projection errors
+  #     puts event.errors.full_messages          # => All errors merged
+  #   end
+  class Event
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # @!attribute [rw] adjacent_state_errors
+    #   @return [ActiveModel::Errors] Validation errors from consistency projections.
+    attr_accessor :adjacent_state_errors
+
+    # @!attribute [rw] event_errors
+    #   @return [ActiveModel::Errors, nil] The event's own validation errors (internal use).
+    attr_accessor :event_errors
+
+    # @!visibility private
+    def initialize(*args, **kwargs)
+      super(*args, **kwargs)
+      @adjacent_state_errors = ActiveModel::Errors.new(nil)
+    end
+
+    # @!visibility private
+    def persist!(idx, version)
+      Funes::EventEntry.create!(klass: self.class.name, idx:, version:, props: attributes)
+    end
+
+    # Custom string representation of the event.
+    #
+    # @return [String] A string showing the event class name and attributes.
+    #
+    # @example
+    #   event = Order::Placed.new(total: 99.99)
+    #   event.inspect  # => "<Order::Placed: {:total=>99.99}>"
+    def inspect
+      "<#{self.class.name}: #{attributes}>"
+    end
+
+    # Check if the event is valid.
+    #
+    # An event is valid only if both its own validations pass AND it doesn't lead to an
+    # invalid state (no adjacent_state_errors from consistency projections).
+    #
+    # @return [Boolean] `true` if the event is valid, `false` otherwise.
+    #
+    # @example
+    #   event = Order::Placed.new(total: 99.99, customer_id: "cust-123")
+    #   event.valid?  # => true or false
+    def valid?
+      super && (adjacent_state_errors.nil? || adjacent_state_errors.empty?)
+    end
+
+    # Get validation errors from consistency projections.
+    #
+    # These are errors that indicate the event would lead to an invalid state, even if
+    # the event itself is valid.
+    #
+    # @return [ActiveModel::Errors] Errors from consistency projection validation.
+    #
+    # @example
+    #   event = stream.append!(Inventory::ItemShipped.new(quantity: 9999))
+    #   event.state_errors.full_messages  # => ["Quantity on hand must be >= 0"]
+    def state_errors
+      adjacent_state_errors
+    end
+
+    # Get the event's own validation errors (excluding state errors).
+    #
+    # @return [ActiveModel::Errors] Only the event's own validation errors.
+    #
+    # @example
+    #   event = Order::Placed.new(total: -10)
+    #   event.own_errors.full_messages  # => ["Total must be greater than 0"]
+    def own_errors
+      event_errors || errors
+    end
+
+    # Get all validation errors (both event and state errors merged).
+    #
+    # This method merges the event's own validation errors with any errors from consistency
+    # projections, prefixing state errors with a localized message.
+    #
+    # @return [ActiveModel::Errors] All validation errors combined.
+    #
+    # @example
+    #   event.errors.full_messages
+    #   # => ["Total must be greater than 0", "Led to invalid state: Quantity on hand must be >= 0"]
+    def errors
+      return super if @event_errors.nil?
+
+      tmp_errors = ActiveModel::Errors.new(nil)
+      tmp_errors.merge!(event_errors)
+      adjacent_state_errors.each do |error|
+        tmp_errors.add(:base, "#{I18n.t("funes.events.led_to_invalid_state_prefix")}: #{error.full_message}")
+      end
+      tmp_errors
+    end
+  end
+end

data/app/models/funes/event_entry.rb

@@ -0,0 +1,9 @@
+module Funes
+  class EventEntry < ApplicationRecord
+    self.table_name = "event_entries"
+
+    def to_klass_instance
+      klass.constantize.new(props.symbolize_keys)
+    end
+  end
+end

data/app/projections/funes/projection.rb

@@ -0,0 +1,203 @@
+module Funes
+  # 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](https://martinfowler.com/bliki/EagerReadDerivation.html)).
+  #
+  # ## 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 Projection
+    class << self
+      # Registers an interpretation block for a given event type.
+      #
+      # @param [Class<Funes::Event>] event_type The event class constant that will be interpreted.
+      # @yield [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
+      # @yieldparam [ActiveModel::Model, ActiveRecord::Base] transient_state The current transient state
+      # @yieldparam [Funes::Event] event Event instance.
+      # @yieldparam [Time] as_of Context or timestamp used when interpreting.
+      # @yieldreturn [ActiveModel::Model, ActiveRecord::Base] the new transient state
+      # @return [void]
+      #
+      # @example
+      #   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
+      def interpretation_for(event_type, &block)
+        @interpretations ||= {}
+        @interpretations[event_type] = block
+      end
+
+      # 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.
+      #
+      # @yield [materialization_model, as_of] Block invoked to produce the initial state.
+      # @yieldparam [Class<ActiveRecord::Base>, Class<ActiveModel::Model>] materialization_model The materialization model constant.
+      # @yieldparam [Time] as_of Context or timestamp used when interpreting.
+      # @yieldreturn [ActiveModel::Model, ActiveRecord::Base] the new transient state
+      # @return [void]
+      #
+      # @example
+      #   class YourProjection < Funes::Projection
+      #     initial_state do |materialization_model, _as_of|
+      #       materialization_model.new(some: :specific, value: 42)
+      #     end
+      #   end
+      def initial_state(&block)
+        @interpretations ||= {}
+        @interpretations[:init] = block
+      end
+
+      # Register a final interpretation of the state.
+      #
+      # *Default behavior:* when this is not defined the projection does nothing after the interpretations
+      #
+      # @yield [transient_state, as_of] Block invoked to produce the final state.
+      # @yieldparam [ActiveModel::Model, ActiveRecord::Base] transient_state The current transient state after all interpretations.
+      # @yieldparam [Time] as_of Context or timestamp used when interpreting.
+      # @yieldreturn [ActiveModel::Model, ActiveRecord::Base] the final transient state instance
+      # @return [void]
+      #
+      # @example
+      #   class YourProjection < Funes::Projection
+      #     final_state do |transient_state, as_of|
+      #       # TODO...
+      #     end
+      #   end
+      def final_state(&block)
+        @interpretations ||= {}
+        @interpretations[:final] = block
+      end
+
+      # Register the projection's materialization model
+      #
+      # @param [Class<ActiveRecord::Base>, Class<ActiveModel::Model>] active_record_or_model The materialization model class.
+      # @return [void]
+      #
+      # @example Virtual projection (non-persistent, ActiveModel)
+      #   class YourProjection < Funes::Projection
+      #     materialization_model YourActiveModelClass
+      #   end
+      #
+      # @example Persistent projection (persisted read model, ActiveRecord)
+      #   class YourProjection < Funes::Projection
+      #     materialization_model YourActiveRecordClass
+      #   end
+      def materialization_model(active_record_or_model)
+        @materialization_model = active_record_or_model
+      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
+      # projection that in cases like that an Funes::UnknownEvent should be raised and the DB transaction should be
+      # rolled back.
+      #
+      # @return [void]
+      #
+      # @example
+      #   class YourProjection < Funes::Projection
+      #     raise_on_unknown_events
+      #   end
+      def raise_on_unknown_events
+        @throws_on_unknown_events = true
+      end
+
+      # @!visibility private
+      def process_events(events_collection, as_of)
+        new(self.instance_variable_get(:@interpretations),
+            self.instance_variable_get(:@materialization_model),
+            self.instance_variable_get(:@throws_on_unknown_events))
+          .process_events(events_collection, as_of)
+      end
+
+      # @!visibility private
+      def materialize!(events_collection, idx, as_of)
+        new(self.instance_variable_get(:@interpretations),
+            self.instance_variable_get(:@materialization_model),
+            self.instance_variable_get(:@throws_on_unknown_events))
+          .materialize!(events_collection, idx, as_of)
+      end
+    end
+
+    # @!visibility private
+    def initialize(interpretations, materialization_model, throws_on_unknown_events)
+      @interpretations = interpretations
+      @materialization_model = materialization_model
+      @throws_on_unknown_events = throws_on_unknown_events
+    end
+
+    # @!visibility private
+    def process_events(events_collection, as_of)
+      initial_state = interpretations[:init].present? ? interpretations[:init].call(@materialization_model, as_of) : @materialization_model.new
+      state = events_collection.inject(initial_state) do |previous_state, event|
+        fn = @interpretations[event.class]
+        if fn.nil? && throws_on_unknown_events?
+          raise Funes::UnknownEvent, "Events of the type #{event.class} are not processable"
+        end
+
+        fn.nil? ? previous_state : fn.call(previous_state, event, as_of)
+      end
+
+      state = interpretations[:final].call(state, as_of) if interpretations[:final].present?
+      state
+    end
+
+    # @!visibility private
+    def materialize!(events_collection, idx, as_of)
+      raise Funes::UnknownMaterializationModel,
+            "There is no materialization model configured on #{self.class.name}" unless @materialization_model.present?
+
+      state = process_events(events_collection, as_of)
+      materialized_model_instance = materialized_model_instance_based_on(state)
+      if materialization_model_is_persistable?
+        state.assign_attributes(idx:)
+        persist_based_on!(state)
+      end
+
+      materialized_model_instance
+    end
+
+    private
+      def throws_on_unknown_events?
+        @throws_on_unknown_events || false
+      end
+
+      def interpretations
+        @interpretations || {}
+      end
+
+      def materialized_model_instance_based_on(state)
+        @materialization_model.new(state.attributes)
+      end
+
+      def materialization_model_is_persistable?
+        @materialization_model.present? && @materialization_model <= ActiveRecord::Base
+      end
+
+      def persist_based_on!(state)
+        @materialization_model.upsert(state.attributes, unique_by: :idx)
+      end
+  end
+end

data/app/views/layouts/funes/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Funes</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "funes/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+en:
+  funes:
+    events:
+      racing_condition_on_insert: "The current event led to an invalid state"
+      led_to_invalid_state_prefix: "Led to invalid state"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Funes::Engine.routes.draw do
+end

data/lib/funes/engine.rb

@@ -0,0 +1,10 @@
+module Funes
+  class Engine < ::Rails::Engine
+    isolate_namespace Funes
+
+    initializer "funes.autoload", before: :set_autoload_paths do |app|
+      engine_root = config.root
+      app.config.autoload_paths << engine_root.join("lib")
+    end
+  end
+end

data/lib/funes/unknown_event.rb

@@ -0,0 +1,24 @@
+module Funes
+  # Raised when a projection encounters an event type it doesn't know how to interpret.
+  #
+  # By default, projections silently ignore unknown events. This error is only raised when
+  # a projection is configured with `raise_on_unknown_events`, which enforces strict event
+  # handling to catch missing interpretation blocks during development.
+  #
+  # @example Configure a projection to raise on unknown events
+  #   class StrictProjection < Funes::Projection
+  #     raise_on_unknown_events
+  #
+  #     interpretation_for OrderPlaced do |state, event, as_of|
+  #       # ...
+  #     end
+  #   end
+  #
+  # @example Handling unknown events
+  #   begin
+  #     projection.process_events(events, Time.current)
+  #   rescue Funes::UnknownEvent => e
+  #     Rails.logger.error "Missing interpretation: #{e.message}"
+  #   end
+  class UnknownEvent < StandardError; end
+end

data/lib/funes/unknown_materialization_model.rb

@@ -0,0 +1,29 @@
+module Funes
+  # Raised when attempting to materialize a projection without a configured materialization model.
+  #
+  # Projections require a materialization model (ActiveModel or ActiveRecord class) to be
+  # configured via `materialization_model` before they can be materialized or persisted.
+  # This error occurs when calling `materialize!` on a projection that hasn't been properly
+  # configured.
+  #
+  # @example Projection without materialization model (raises error)
+  #   class IncompleteProjection < Funes::Projection
+  #     interpretation_for OrderPlaced do |state, event, as_of|
+  #       # ...
+  #     end
+  #     # Missing: materialization_model SomeModel
+  #   end
+  #
+  #   # This will raise Funes::UnknownMaterializationModel
+  #   IncompleteProjection.materialize!(events, "entity-123", Time.current)
+  #
+  # @example Properly configured projection
+  #   class OrderProjection < Funes::Projection
+  #     materialization_model OrderSnapshot
+  #
+  #     interpretation_for OrderPlaced do |state, event, as_of|
+  #       # ...
+  #     end
+  #   end
+  class UnknownMaterializationModel < StandardError; end
+end

data/lib/funes/version.rb

@@ -0,0 +1,3 @@
+module Funes
+  VERSION = "0.1.0"
+end

data/lib/funes.rb

@@ -0,0 +1,72 @@
+require "funes/version"
+require "funes/engine"
+
+# Funes is an event sourcing framework for Ruby on Rails.
+#
+# Instead of updating state in place, Funes stores immutable events as the source of truth,
+# then derives current state by replaying them through projections. This provides complete
+# audit trails, temporal queries, and the ability to create multiple read models from the
+# same event stream.
+#
+# ## Core Concepts
+#
+# - **Events** ({Funes::Event}): Immutable facts representing something that happened
+# - **Event Streams** ({Funes::EventStream}): Append-only sequences of events for a specific entity
+# - **Projections** ({Funes::Projection}): Transform events into read models (state)
+#
+# ## Getting Started
+#
+# 1. Install the gem and run migrations:
+#    ```bash
+#    $ bin/rails generate funes:install
+#    $ bin/rails db:migrate
+#    ```
+#
+# 2. Define your events:
+#    ```ruby
+#    class Order::Placed < Funes::Event
+#      attribute :total, :decimal
+#      attribute :customer_id, :string
+#      validates :total, presence: true
+#    end
+#    ```
+#
+# 3. Define a projection:
+#    ```ruby
+#    class OrderProjection < Funes::Projection
+#      materialization_model OrderSnapshot
+#
+#      interpretation_for Order::Placed do |state, event, as_of|
+#        state.assign_attributes(total: event.total)
+#        state
+#      end
+#    end
+#    ```
+#
+# 4. Create an event stream:
+#    ```ruby
+#    class OrderEventStream < Funes::EventStream
+#      add_transactional_projection OrderProjection
+#    end
+#    ```
+#
+# 5. Append events:
+#    ```ruby
+#    stream = OrderEventStream.for("order-123")
+#    event = stream.append!(Order::Placed.new(total: 99.99, customer_id: "cust-1"))
+#    ```
+#
+# ## Three-Tier Consistency Model
+#
+# Funes provides fine-grained control over projection execution:
+#
+# - **Consistency Projection**: Validates business rules before persisting events
+# - **Transactional Projections**: Execute synchronously in the same database transaction
+# - **Async Projections**: Execute asynchronously via ActiveJob
+#
+# @see Funes::Event
+# @see Funes::EventStream
+# @see Funes::Projection
+# @see Funes::ProjectionTestHelper
+module Funes
+end

data/lib/generators/funes/install_generator.rb

@@ -0,0 +1,41 @@
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Funes
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Funes rules!!!"
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template("migration.rb",
+                           "db/migrate/create_funes_events_table.rb",
+                           migration_version: migration_version)
+      end
+
+      def show_readme
+        readme "README.md" if File.exist?(File.join(self.class.source_root, "README.md"))
+      end
+
+      private
+
+      def json_column_type
+        postgres? ? "jsonb" : "json"
+      end
+
+      def migration_version
+        "[#{::Rails::VERSION::MAJOR}.#{::Rails::VERSION::MINOR}]"
+      end
+
+      def postgres?
+        ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).first&.adapter == "postgresql"
+      end
+    end
+  end
+end

data/lib/generators/funes/templates/migration.rb.tt

@@ -0,0 +1,16 @@
+class CreateFunesEventsTable < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :events, id: false do |t|
+      t.column :klass, :string, null: false
+      t.column :entity_id, :string, null: false
+      t.column :props, :<%= json_column_type %>, null: false
+      t.column :version, :bigint, default: 1, null: false
+      t.column :created_at, :datetime, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :events, :entity_id
+    add_index :events, :created_at
+    add_index :events, [:entity_id, :version], unique: true
+  end
+end
+

data/lib/tasks/funes_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :funes do
+#   # Task goes here
+# end