funes-rails 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c51e21ab14ee2a2a3994320929a81e9e06a5eae4247c3ef3415f4c86f901b93
-  data.tar.gz: aa84a44d6e3d9b920c55952a7fefee48d186d185a5e6718b4c22577d3bcfef02
+  metadata.gz: a03d8c22f06c54db21f30e95b22db605a0ba5ab95f6d271d822ab1b925ea1547
+  data.tar.gz: b2a8d7a5205e0bdd508ab3cc98d28048b2d4d53508b12790751dd4e92d98c410
 SHA512:
-  metadata.gz: a28819da667269a81dbc569f1deffdb9b1fbb2d48308106b1662f1abfddbb55d8ef7df6ca3cec4007c19088b6980559725a2f1187dcee577fd847e3dc95f811b
-  data.tar.gz: 1811203127bd94c7537355ccb974b1b7dd29dcbd40291075bcd43c5c5e9408929aa8bf4eb2b559de56b978666e05fa3baa99ba443b0498458f5f6ca9bb3417f7
+  metadata.gz: 1a54c80af6790e8500449c6e71e46117da93b00fdbdc6694142ac7ae8603732d2671fe8455c1410d953e8b8538e1d6cdc188861ebddfd77bf247a40abf791baa
+  data.tar.gz: 462fae650d472c157aa75cbad863569936939ce6540e4f120d333a95a4221aea4ea59750c7bb21098d58e15e8dcbe7a74fdd8be498057eb1c291be1ed060acf2

data/README.md

@@ -103,6 +103,8 @@ Funes gives you fine-grained control over when and how projections run:
 
 Guides and full API documentation are available at [docs.funes.org](https://docs.funes.org).
 
+For a hands-on example, see the [Funes Workshop](https://github.com/viniciusalmeida/funes_workshop) — a small Rails app that models a debt lifecycle (loan issuance, daily interest accrual, and payments) to demonstrate how to use Events, Streams, and Projections in a realistic financial domain.
+
 ## 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.

data/Rakefile

@@ -7,6 +7,29 @@ load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
 
+# Safeguard against releasing from a fork. `rake release` (bundler/gem_tasks)
+# pushes the tag and commits to the remote tracked by the current branch
+# (falling back to "origin"). This guard inspects that same remote and aborts
+# before any push if it does not point at the canonical funes-org/funes repo.
+CANONICAL_RELEASE_REPO = %r{[:/]funes-org/funes(\.git)?\z}
+
+task "release:guard_canonical_remote" do
+  branch = `git rev-parse --abbrev-ref HEAD`.strip
+  remote = `git config --get branch.#{branch}.remote`.strip
+  remote = "origin" if remote.empty?
+  url = `git config --get remote.#{remote}.url`.strip
+
+  unless url.match?(CANONICAL_RELEASE_REPO)
+    abort <<~MSG
+      Refusing to release: the '#{remote}' remote is #{url.inspect}, which is
+      not funes-org/funes. Releases must be cut from the canonical repository,
+      not a fork. Check out the canonical repo (or fix the remote) and retry.
+    MSG
+  end
+end
+
+Rake::Task["release:source_control_push"].enhance([ "release:guard_canonical_remote" ])
+
 namespace :docs do
   desc "Generate YARD documentation"
   task :generate do

data/app/models/funes/event.rb

@@ -36,6 +36,24 @@ module Funes
   #   event = Order::Placed.new(total: 99.99, customer_id: "cust-123")
   #   stream.append(event)
   #
+  # ## Associating Events With Other Models
+  #
+  # Use +refers_to+ to relate an event to another model. Only the referenced record's id is stored
+  # in the event payload; the record itself is loaded lazily and is readable at interpretation time:
+  #
+  # @example Reference another model and read it in an interpretation
+  #   class Order::Placed < Funes::Event
+  #     refers_to :customer
+  #     attribute :total, :decimal
+  #   end
+  #
+  #   stream.append(Order::Placed.new(customer: customer, total: 99.99))
+  #
+  #   interpretation_for Order::Placed do |state, event, _at|
+  #     state.customer = event.customer  # loaded by id from props
+  #     state
+  #   end
+  #
   # @example Handling validation errors
   #   event = stream.append(Order::Placed.new(total: -10))
   #   unless event.valid?
@@ -47,6 +65,7 @@ module Funes
     include ActiveModel::Model
     include ActiveModel::Attributes
     include Funes::Inspection
+    include Funes::Associations
 
     # @!attribute [rw] adjacent_state_errors
     #   @return [ActiveModel::Errors] Validation errors from consistency projections.

data/app/projections/funes/projection.rb

@@ -158,41 +158,32 @@ module Funes
       #
       # @example
       #   class YourProjection < Funes::Projection
-      #     raise_on_unknown_events
+      #     strict_mode!
       #   end
-      def raise_on_unknown_events
+      def strict_mode!
         @throws_on_unknown_events = true
       end
 
       # @!visibility private
       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(:@persist_method))
-          .process_events(events_collection, at: at, consistency: consistency)
+        new.process_events(events_collection, at: at, consistency: consistency)
       end
 
       # @!visibility private
       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(:@persist_method))
-          .materialize!(events_collection, idx, at: at)
+        new.materialize!(events_collection, idx, at: at)
       end
     end
 
     # @!visibility private
-    def initialize(interpretations, materialization_model, throws_on_unknown_events, persist_method = nil)
-      @interpretations = interpretations
-      @materialization_model = materialization_model
+    def initialize
+      @interpretations = self.class.instance_variable_get(:@interpretations)
+      @materialization_model = self.class.instance_variable_get(:@materialization_model)
+      @throws_on_unknown_events = self.class.instance_variable_get(:@throws_on_unknown_events)
+      @persist_method = self.class.instance_variable_get(:@persist_method)
+
       raise Funes::UnknownMaterializationModel,
             "There is no materialization model configured on #{self.class.name}" unless @materialization_model.present?
-
-
-      @throws_on_unknown_events = throws_on_unknown_events
-      @persist_method = persist_method
     end
 
     # @!visibility private

data/lib/funes/associations.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Funes
+  # Declares references to other models, accessible at interpretation time.
+  #
+  # Events are immutable facts serialized as plain JSON in the +props+ column, so an event cannot
+  # store another model directly. The +refers_to+ macro stores only the referenced record's id as a
+  # regular event attribute (and therefore in +props+), while exposing a reader that lazily loads the
+  # record by id and a writer that accepts the record itself.
+  #
+  # The reader returns the record's *current* state (a live lookup via +find_by+), not a snapshot of
+  # how it looked when the event was recorded. A reference whose record no longer exists reads as
+  # +nil+ rather than raising. The loaded record is memoized per reference and reloaded whenever the
+  # foreign key attribute changes, matching Active Record's staleness handling.
+  #
+  # == Example
+  #
+  #   class Deposit::Created < Funes::Event
+  #     refers_to :customer
+  #   end
+  #
+  #   event = Deposit::Created.new(customer: some_customer)
+  #   event.customer_id      # => some_customer.id  (this is what gets serialized)
+  #   event.customer         # => some_customer
+  #
+  #   # Inside an interpretation block, the reference is read straight off the event:
+  #   interpretation_for Deposit::Created do |state, event, _at|
+  #     state.customer = event.customer
+  #     state
+  #   end
+  #
+  # == Options
+  #
+  # * +class_name+ - The name of the referenced class, as a string (or symbol) — passing the class
+  #   itself raises +ArgumentError+, as in Active Record. Defaults to the camelized reference name
+  #   (e.g. +refers_to :customer+ infers +"Customer"+). Resolved lazily, so it plays well with
+  #   autoloading and namespaced constants.
+  # * +foreign_key+ - The attribute that stores the id. Defaults to +"#{name}_id"+.
+  # * +required+ - When +true+, adds a presence validation on the foreign key so an event without the
+  #   reference is invalid and will not be persisted. Defaults to +false+ (ActiveRecord-style).
+  #
+  #   class Loan::Granted < Funes::Event
+  #     refers_to :borrower, class_name: "User", required: true
+  #     refers_to :account, foreign_key: :account_uuid
+  #   end
+  #
+  # == Requirements
+  #
+  # The including class must provide +ActiveModel::Attributes+, which backs the foreign key
+  # attribute. Passing <tt>required: true</tt> additionally needs +ActiveModel::Validations+.
+  # {Funes::Event} provides both.
+  #
+  # == Use on materialization models
+  #
+  # A projection's state is an instance of its materialization model, so a materialization model
+  # that declares +refers_to+ offers interpretation blocks the same API events do — the reference
+  # reads and writes identically on both sides of the block:
+  #
+  #   class CustomerSnapshot
+  #     include ActiveModel::Model
+  #     include ActiveModel::Attributes
+  #     include Funes::Associations
+  #
+  #     refers_to :customer, class_name: "Examples::Customer"
+  #   end
+  #
+  #   interpretation_for Deposit::Created do |state, event, _at|
+  #     state.customer = event.customer
+  #     state
+  #   end
+  #
+  # Only the id travels in +attributes+, so the reference survives the rebuild that +materialize!+
+  # performs. This works for both virtual materialization models and those persisted through
+  # +persist_materialization_model_with+.
+  #
+  # For an ActiveRecord-backed materialization model, declare a regular +belongs_to+ association
+  # instead. That is the idiomatic tool there, and it brings preloading and +inverse_of+ with it.
+  #
+  # +refers_to+ can work on such a model, but only when the foreign key is already a column in the
+  # database — and even then +belongs_to+ remains the better choice. Without that column the failure
+  # is late and misleading: interpretation blocks read and write the reference correctly and the
+  # foreign key is populated, then +materialize!+ feeds +attributes+ into an upsert and raises
+  #
+  #   ActiveModel::UnknownAttributeError: unknown attribute 'customer_id' for CustomerSnapshot.
+  #
+  # naming the attribute without mentioning the missing column or the +refers_to+ call that created
+  # it, so the error surfaces far from its cause.
+  #
+  # == Namespaced models
+  #
+  # +class_name+ must be fully qualified, e.g. <tt>class_name: "Examples::Customer"</tt>. It is
+  # resolved lazily, on the first load by id — assigning a record caches it directly, so a wrong
+  # +class_name+ surfaces only when a freshly built object reads the reference, not when it is
+  # assigned.
+  module Associations
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Declares a reference to another model. See {Funes::Associations} for details.
+      #
+      # @param name [Symbol] The reference name (defines +name+ / +name=+ accessors).
+      # @param class_name [String, Symbol, nil] Name of the referenced class (not the class itself).
+      #   Defaults to +name.camelize+.
+      # @param foreign_key [Symbol, String, nil] Attribute storing the id. Defaults to +"#{name}_id"+.
+      # @param required [Boolean] Whether to validate presence of the foreign key. Defaults to +false+.
+      # @return [void]
+      def refers_to(name, class_name: nil, foreign_key: nil, required: false)
+        if class_name.instance_of?(Class)
+          raise ArgumentError, "A class was passed to `:class_name` but we are expecting a string."
+        end
+
+        fk        = (foreign_key || "#{name}_id").to_sym
+        klass_str = (class_name || name.to_s.camelize).to_s
+
+        # Untyped (pass-through Value) attribute so integer and string/UUID ids both round-trip
+        # through JSON unchanged. This is what gets serialized into +props+.
+        attribute fk
+
+        define_method(name) do
+          id = public_send(fk)
+          return nil if id.nil?
+
+          # Cache entries are [id, record] pairs so a direct write to the foreign key attribute
+          # invalidates the memoized record, as in ActiveRecord's stale-target handling.
+          @__reference_cache ||= {}
+          cached_id, cached_record = @__reference_cache[name]
+          return cached_record if cached_id == id
+
+          record = klass_str.constantize.find_by(id: id)
+          @__reference_cache[name] = [ id, record ]
+          record
+        end
+
+        define_method("#{name}=") do |record|
+          @__reference_cache ||= {}
+          if record.nil?
+            public_send("#{fk}=", nil)
+            @__reference_cache.delete(name)
+          else
+            public_send("#{fk}=", record.id)
+            @__reference_cache[name] = [ record.id, record ]
+          end
+        end
+
+        validates fk, presence: true if required
+      end
+    end
+  end
+end

data/lib/funes/unknown_event.rb

@@ -2,12 +2,12 @@ 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
+  # a projection is configured with `strict_mode!`, 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
+  #     strict_mode!
   #
   #     interpretation_for OrderPlaced do |state, event, _at|
   #       # ...

data/lib/funes/version.rb

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

data/lib/funes.rb

@@ -1,6 +1,7 @@
 require "funes/version"
 require "funes/configuration"
 require "funes/inspection"
+require "funes/associations"
 require "funes/event_metainformation_builder"
 require "funes/invalid_event_metainformation"
 require "funes/conflicting_actual_time_error"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: funes-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Vinícius Almeida da Silva
@@ -210,6 +210,7 @@ files:
 - config/routes.rb
 - lib/funes-rails.rb
 - lib/funes.rb
+- lib/funes/associations.rb
 - lib/funes/configuration.rb
 - lib/funes/conflicting_actual_time_error.rb
 - lib/funes/engine.rb
@@ -234,7 +235,7 @@ licenses:
 metadata:
   homepage_uri: https://funes.org/
   source_code_uri: https://github.com/funes-org/funes
-  changelog_uri: https://github.com/funes-org/funes
+  changelog_uri: https://github.com/funes-org/funes/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib