funes-rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f475c7d974c06b8ea3700459a6275484b805cab6b5e5ca1822eb33a09bb5b92e
-  data.tar.gz: 1ee86eb626084ddf73cfb3921abf3e4a68ab823ad87ff09fd890788ced2063fc
+  metadata.gz: cc100a1d70358da39c0ae079d3cc028644b205b39d031299deab2e6a0486f1da
+  data.tar.gz: cc3a1cb99e508e2094cf9a10bc7dd184100fbfc3d688211f46624c3960b8be71
 SHA512:
-  metadata.gz: 5bc8898e1014eee4e865c6b1747f640a70f5cbf9336d5356eaa52ef9a557845764ac831ad54d1c5e3e777104c14b44aa5d737be3fb9f12597e5550e4280c4481
-  data.tar.gz: bbee4693d75aa24d31133e3738876d6ee0906cbde3fef4eb915d47d0ae74dad5ec91f8787d0eb2293660b9a52d632fa5af44b973a3b22ddcdd685dee7875d9dc
+  metadata.gz: c11d561ee5735da822aac0cb302b325c0ee9e803f175304cc6ce4885d795affbc33264b094b0ac8d497a3f5f4a674166a5b44055017c82e0477d1238b2cfeb77
+  data.tar.gz: f321c1ec7ce53e2f2e36795a6716bbbe51d979e777ec969bd052dc9cc4dee2b467c5899b5cabf790dfffbf491e91e760c79e8ffe2aafe8c31c7213164587b09c

data/README.md

@@ -1,17 +1,15 @@
 # Funes
 
-Event sourcing for Ruby on Rails — append-only events as your source of truth, with flexible projections for reads.
+An event sourcing meta-framework designed to provide a frictionless experience for RoR developers to build and operate systems where history is as important as the present. Built with the one-person framework philosophy in mind, it honors the Rails doctrine by providing deep **conceptual compression** over what is usually a complex architectural pattern.
 
-## Event Sourcing?
+By distilling the mechanics of event sourcing into just three core concepts — **Events**, **Streams**, and **Projections** — Funes handles the underlying complexity of persistence and state reconstruction for you. It feels like the Rails you already know, giving you the power of a permanent source of truth with the same ease of use as a standard ActiveRecord model.
 
-Traditional Rails apps update state in place. You `update!` a record and the previous value is gone. Event sourcing takes a different approach: store *what happened* as immutable events, then derive current state by replaying them.
+Unlike traditional event sourcing frameworks that require a total shift in how you build, Funes is designed for **progressive adoption**. It is a _"good neighbor"_ that coexists seamlessly with your existing ActiveRecord models and standard controllers. You can use Funes for a single mission-critical feature — like a single complex state machine — while keeping the rest of your app in "plain old Rails."
 
-This gives you:
+> [!WARNING]
+> **Not Production Ready:** Funes is currently under active development and is not yet ready for production use. The API may change without notice, and features may be incomplete or unstable. Use at your own risk in development and testing environments only.
 
-- **Complete audit trail** — every state change is recorded, forever
-- **Temporal queries** — "what was the balance on December 1st?"
-- **Multiple read models** — same events, different projections for different use cases
-- **Safer refactoring** — rebuild any projection from the event log
+> Named after Funes the Memorious, the Borges character who could forget nothing, this framework embodies the principle that in some systems, remembering everything matters.
 
 ## Installation
 
@@ -29,152 +27,34 @@ $ bin/rails generate funes:install
 $ bin/rails db:migrate
 ```
 
-## Three-Tier Consistency Model
+## Core concepts
 
-Funes gives you fine-grained control over when and how projections run:
+Funes bridges the gap between event sourcing theory and the Rails tools you already know (`ActiveModel`, `ActiveRecord`, `ActiveJob`).
 
-| Tier                      | When it runs                 | Use case                                        |
-|:--------------------------|:-----------------------------|:------------------------------------------------|
-| Consistency Projection    | Before event is persisted    | Validate business rules against resulting state |
-| Transactional Projections | Same DB transaction as event | Critical read models needing strong consistency |
-| Async Projections         | Background job (ActiveJob)   | Reports, analytics, non-critical read models    |
+![core concepts](https://raw.github.com/funes-org/funes/main/concepts.png)
 
-### Consistency Projection
+- **Events** — immutable `ActiveModel` objects that record what happened, with built-in validation and no schema migrations
+- **Projections** — transform a stream of events into a materialized state, either in-memory (`ActiveModel`) or persisted (`ActiveRecord`)
+- **Event Streams** — orchestrate writes, run double validation, and control when projections update (synchronously or via `ActiveJob`)
 
-Runs before the event is saved. If the resulting state is invalid, the event is rejected:
+For a full walkthrough of each concept, see the [guides](https://docs.funes.org).
 
-```ruby
-class InventoryEventStream < Funes::EventStream
-  consistency_projection InventorySnapshotProjection
-end
-
-class InventorySnapshot
-  include ActiveModel::Model
-  include ActiveModel::Attributes
-
-  attribute :quantity_on_hand, :integer, default: 0
-
-  validates :quantity_on_hand, numericality: { greater_than_or_equal_to: 0 }
-end
-```
-
-Now if someone tries to ship more than available:
-
-```ruby
-
-event = stream.append!(Inventory::ItemShipped.new(quantity: 9999))
-event.valid? # => false
-event.errors[:quantity_on_hand] # => ["must be greater than or equal to 0"]
-```
-
-The event is never persisted. Your invariants are protected.
-
-### Transactional Projections
-
-Update read models in the same database transaction. If anything fails, everything rolls back:
-
-```ruby
-add_transactional_projection InventoryLedgerProjection
-```
-
-### Async Projections
-
-Schedule background jobs with full ActiveJob options:
-
-```ruby
-add_async_projection ReportingProjection, queue: :low, wait: 5.minutes
-add_async_projection AnalyticsProjection, wait_until: Date.tomorrow.midnight
-```
-
-#### Controlling the `as_of` Timestamp
-
-By default, async projections use the creation time of the last event. You can customize this behavior:
-
-```ruby
-# Use job execution time instead of event time
-add_async_projection RealtimeProjection, as_of: :job_time
-
-# Custom logic with a proc
-add_async_projection EndOfDayProjection,
-  as_of: ->(last_event) { last_event.created_at.beginning_of_day }
-```
-
-Available `as_of` strategies:
-- `:last_event_time` (default) — Uses the creation time of the last event
-- `:job_time` — Uses `Time.current` when the job executes
-- `Proc/Lambda` — Custom logic that receives the last event and returns a `Time` object
-
-## Temporal Queries
-
-Every event is timestamped. Query your stream at any point in time:
-
-### Current state
-```ruby
-stream = InventoryEventStream.for("sku-12345")
-stream.events # => all events
-```
-
-### State as of last month
-```ruby
-stream = InventoryEventStream.for("sku-12345", 1.month.ago)
-stream.events # => events up to that timestamp
-```
-
-Projections receive the as_of parameter, so you can build point-in-time snapshots:
-
-```ruby
-# in your projection
-interpretation_for(Inventory::ItemReceived) do |state, event, as_of|
-  # as_of is available if you need temporal logic
-  state.quantity_on_hand += event.quantity
-  state
-end
-```
-
-## Concurrency
+## Optimistic concurrency control
 
 Funes uses optimistic concurrency control. Each event in a stream gets an incrementing version number with a unique constraint on (idx, version).
 
-If two processes try to append to the same stream simultaneously, one succeeds and the other gets a validation error — no locks, no blocking:
+If two processes try to append to the same stream simultaneously, one succeeds and the other gets a validation error — no locks, no blocking.
 
-```ruby
-event = stream.append!(SomeEvent.new)
-unless event.valid?
-  event.errors[:version] # => ["has already been taken"]
-  # Reload and retry your business logic
-end
-```
+## Documentation
 
-## Testing
+Guides and full API documentation are available at [docs.funes.org](https://docs.funes.org).
 
-Funes provides helpers for testing projections in isolation:
+## Compatibility
 
-```ruby
-class InventorySnapshotProjectionTest < ActiveSupport::TestCase
-  include Funes::ProjectionTestHelper
+- **Ruby:** 3.1, 3.2, 3.3, 3.4
+- **Rails:** 7.1, 7.2, 8.0, 8.1
 
-  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
-```
-
-## Strict Mode
-
-By default, projections ignore events they don't have interpretations for. Enable strict mode to catch missing handlers:
-
-```ruby
-class StrictProjection < Funes::Projection
-  raise_on_unknown_events
-
-  # Now forgetting to handle an event type raises Funes::UnknownEvent
-end
-```
+Rails 8.0+ requires Ruby 3.2 or higher.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -8,68 +8,44 @@ load "rails/tasks/statistics.rake"
 require "bundler/gem_tasks"
 
 namespace :docs do
-  desc "Generate YARD documentation for current version"
+  desc "Generate YARD documentation"
   task :generate do
-    # Allow version override via environment variable (for CI)
-    version = ENV["VERSION"] || begin
-      require_relative "lib/funes/version"
-      Funes::VERSION
-    end
-    output_dir = "docs/v#{version}"
+    output_dir = "docs"
 
-    puts "Generating documentation for version #{version}..."
+    puts "Generating documentation..."
     system("yard doc --output-dir #{output_dir}") || abort("Failed to generate documentation")
 
-    # Copy assets to root docs directory
-    FileUtils.mkdir_p("docs")
-    %w[css js].each do |asset_dir|
-      if Dir.exist?("#{output_dir}/#{asset_dir}")
-        FileUtils.cp_r("#{output_dir}/#{asset_dir}", "docs/#{asset_dir}")
-      end
-    end
-
     puts "Documentation generated in #{output_dir}/"
-    Rake::Task["docs:build_index"].invoke
   end
+end
 
-  desc "Build version selector index page"
-  task :build_index do
-    require "erb"
-
-    versions = Dir.glob("docs/v*").map { |d| File.basename(d) }.sort.reverse
+namespace :guides do
+  guides_dir = File.expand_path("guides", __dir__)
 
-    if versions.empty?
-      puts "No versions found. Run 'rake docs:generate' first."
-      exit 1
+  desc "Install Jekyll dependencies for guides (one-time setup)"
+  task :setup do
+    Bundler.with_unbundled_env do
+      Dir.chdir(guides_dir) do
+        system("bundle install") || abort("Failed to install guides dependencies")
+      end
     end
-
-    latest_version = versions.first
-    template_path = File.expand_path("lib/templates/docs_index.html.erb", __dir__)
-    template = ERB.new(File.read(template_path))
-    html = template.result(binding)
-
-    File.write("docs/index.html", html)
-    puts "Version index page created at docs/index.html"
-
-    # Create CNAME file for GitHub Pages custom domain
-    File.write("docs/CNAME", "docs.funes.org\n")
-    puts "CNAME file created for docs.funes.org"
-
-    # Create .nojekyll file to bypass Jekyll processing
-    # This is required for YARD's _index.html file to work properly
-    File.write("docs/.nojekyll", "")
-    puts ".nojekyll file created to bypass Jekyll processing"
   end
 
-  desc "List all documented versions"
-  task :list do
-    versions = Dir.glob("docs/v*").map { |d| File.basename(d) }.sort.reverse
+  desc "Build the guides site into guides/_site/"
+  task :build do
+    Bundler.with_unbundled_env do
+      Dir.chdir(guides_dir) do
+        system("bundle exec jekyll build") || abort("Failed to build guides")
+      end
+    end
+  end
 
-    if versions.empty?
-      puts "No versions documented yet."
-    else
-      puts "Documented versions:"
-      versions.each { |v| puts "  - #{v}" }
+  desc "Start Jekyll dev server with live reload at localhost:4000/guides/"
+  task :serve do
+    Bundler.with_unbundled_env do
+      Dir.chdir(guides_dir) do
+        system("bundle exec jekyll serve --livereload")
+      end
     end
   end
 end