rails_simple_event_sourcing 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a12c3adaddba63ac71f028aa700a4c14826999551657b1cafe758d9d7c1a66f
-  data.tar.gz: 480fcef167c89edb26e9ebe04596f3a90fe9cc04e58064bcb46309abba5926f6
+  metadata.gz: 97abf701a07288f6fc66a33c3cc064810ad7a5ea5c7f798be4f85a96f839722a
+  data.tar.gz: '08c7fe14306245b4f0a3b59e5309aa9de4b4a8dd76b4f989d6f7e5cc02962f0e'
 SHA512:
-  metadata.gz: 47f6eddbbd5b4ad08e586caad344024432b716ac354b01bdd17494cff94b3b4419735a203a1425d7b3798a401685f8a8c1f28bacc50ceac3afe748fdb22c80b0
-  data.tar.gz: 4800824fd957523c51466fafe888b80541fcf1a52abab599435e32dd3a18871e4e5ea6b18acba24579c45762558952a03118157aeed4f2bb7c2a29ce49589132
+  metadata.gz: e0a8dd9298aacb9b1a5f414dc70c27f6ba657e77ec8db90f8ecff6b8b5ff085197cdca911117e73dbab3046504a0d857bbba4984f39124373920444af6ad904d
+  data.tar.gz: 64ebd4e3f398a7bee7e4e118c4d6df301dea1e85d214c139f763d4755eea69161208684c59b834a8d743bf85cf38b6d7ddc026aed5f9d113feea325bb4f227e6

data/README.md

@@ -18,6 +18,8 @@ If you need a more comprehensive solution, check out:
   - [Commands](#commands)
   - [Command Handlers](#command-handlers)
   - [Events](#events)
+  - [Model Configuration](#model-configuration)
+  - [Immutability and Read-Only Protection](#immutability-and-read-only-protection)
   - [Registering Command Handlers](#registering-command-handlers)
   - [Controller Integration](#controller-integration)
   - [Update and Delete Operations](#update-and-delete-operations)
@@ -27,6 +29,7 @@ If you need a more comprehensive solution, check out:
   - [Adding Event Sourcing to an Existing Model](#adding-event-sourcing-to-an-existing-model)
   - [Event Subscriptions](#event-subscriptions)
   - [Event Schema Versioning](#event-schema-versioning)
+  - [Snapshots](#snapshots)
 - [Testing](#testing)
 - [Limitations](#limitations)
 - [Troubleshooting](#troubleshooting)
@@ -47,12 +50,13 @@ If you need a more comprehensive solution, check out:
 - **Built-in Events Viewer** - Web UI for browsing, searching, and inspecting events
 - **Event Subscriptions** - React to events after they are committed (send emails, send webhooks, etc.)
 - **Event Schema Versioning** - Built-in upcasting to evolve event schemas without modifying stored data
+- **Snapshot Support** - Optional snapshots to speed up aggregate reconstruction for long event streams
 - **Minimal Configuration** - Convention over configuration approach
 
 ## Requirements
 
 - **Ruby**: 3.2 or higher
-- **Rails**: 7.1.2 or higher
+- **Rails**: 7.2.0 or higher
 - **Database**: PostgreSQL 9.4+ (requires JSONB support)
 
 ## Installation
@@ -98,6 +102,12 @@ RailsSimpleEventSourcing.configure do |config|
 
   # Number of events displayed per page in the Events Viewer (defaults to 25)
   config.events_per_page = 50
+
+  # Automatically create a snapshot every N events per aggregate (defaults to nil = disabled)
+  # With snapshot_interval = 50, a snapshot is written after every 50th event.
+  # EventPlayer will load the nearest snapshot and replay only the delta,
+  # instead of replaying the full event history from the beginning.
+  config.snapshot_interval = 50
 end
 ```
 
@@ -126,7 +136,7 @@ flowchart TD
 4. **Event** - Immutable record of what happened
 5. **Aggregate** - Model updated via event
 6. **EventBus** - After the transaction commits, enqueues subscriber jobs
-7. **Subscribers** - ActiveJob classes that react to events asynchronously (send emails, sync external systems, etc.)
+7. **Subscribers** - ActiveJob classes that react to events asynchronously (send emails, sync external systems, etc.). See [Event Subscriptions](#event-subscriptions) for setup details
 
 ### Directory Structure
 
@@ -407,6 +417,28 @@ end
 
 This is useful for recording domain-significant occurrences that don't map to a state change on a model.
 
+### Model Configuration
+
+Models that use event sourcing should include the `RailsSimpleEventSourcing::Events` module:
+
+```ruby
+class Customer < ApplicationRecord
+  include RailsSimpleEventSourcing::Events
+end
+```
+
+**This provides:**
+- `.events` association - Access all events for this aggregate
+- Read-only protection - Prevents accidental direct modifications
+- Event replay capability - Reconstruct state from events
+
+### Immutability and Read-Only Protection
+
+**Important Principles:**
+- **Events are immutable** - Once created, events should never be modified
+- **Models are read-only** - Aggregates should only be modified through events
+- Both have built-in protection against accidental changes
+
 ### Registering Command Handlers
 
 The recommended approach is to register command handlers explicitly using the registry. This makes the command-to-handler mapping explicit and avoids relying on naming conventions.
@@ -463,6 +495,58 @@ end
 
 **Update Example:**
 
+Command — same structure as create, but inherits `aggregate_id` from the base class:
+
+```ruby
+class Customer
+  module Commands
+    class Update < RailsSimpleEventSourcing::Commands::Base
+      attr_accessor :first_name, :last_name, :email
+
+      validates :first_name, presence: true
+      validates :last_name, presence: true
+    end
+  end
+end
+```
+
+Event:
+
+```ruby
+class Customer
+  module Events
+    class CustomerUpdated < RailsSimpleEventSourcing::Event
+      aggregate_class Customer
+      event_attributes :first_name, :last_name, :email, :updated_at
+    end
+  end
+end
+```
+
+Handler — pass `aggregate_id` to the event so it knows which aggregate to replay and update:
+
+```ruby
+class Customer
+  module CommandHandlers
+    class Update < RailsSimpleEventSourcing::CommandHandlers::Base
+      def call
+        event = Customer::Events::CustomerUpdated.create!(
+          aggregate_id: command.aggregate_id,
+          first_name: command.first_name,
+          last_name: command.last_name,
+          email: command.email,
+          updated_at: Time.zone.now
+        )
+
+        success(data: event.aggregate)
+      end
+    end
+  end
+end
+```
+
+Controller:
+
 ```ruby
 class CustomersController < ApplicationController
   def update
@@ -482,6 +566,51 @@ end
 
 **Delete Example:**
 
+Command — only `aggregate_id` is needed (inherited from base class, no extra attributes):
+
+```ruby
+class Customer
+  module Commands
+    class Delete < RailsSimpleEventSourcing::Commands::Base
+    end
+  end
+end
+```
+
+Event — uses a soft delete pattern; sets `deleted_at` instead of removing the record:
+
+```ruby
+class Customer
+  module Events
+    class CustomerDeleted < RailsSimpleEventSourcing::Event
+      aggregate_class Customer
+      event_attributes :deleted_at
+    end
+  end
+end
+```
+
+Handler:
+
+```ruby
+class Customer
+  module CommandHandlers
+    class Delete < RailsSimpleEventSourcing::CommandHandlers::Base
+      def call
+        Customer::Events::CustomerDeleted.create!(
+          aggregate_id: command.aggregate_id,
+          deleted_at: Time.zone.now
+        )
+
+        success
+      end
+    end
+  end
+end
+```
+
+Controller:
+
 ```ruby
 class CustomersController < ApplicationController
   def destroy
@@ -494,7 +623,7 @@ class CustomersController < ApplicationController
 end
 ```
 
-**Important:** For update and delete operations, you must pass `aggregate_id` to identify which record to modify. See the full examples in `test/dummy/app/domain/customer/`.
+**Important:** For update and delete operations, you must pass `aggregate_id` to identify which record to modify. The event handler receives this via `command.aggregate_id` and uses it to find and replay the correct aggregate before applying the new event.
 
 ### Testing the API
 
@@ -633,7 +762,29 @@ end
 ```
 
 **Metadata Outside HTTP Requests:**
-When events are created outside HTTP requests (background jobs, console, tests), metadata will be empty unless you manually set it using `CurrentRequest.metadata = {...}`.
+
+When events are created outside HTTP requests (background jobs, rake tasks, console), metadata will be empty unless you set it manually. `CurrentRequest` is backed by `ActiveSupport::CurrentAttributes`, which resets automatically between requests and jobs, so you must set it at the start of each execution:
+
+```ruby
+class CustomerImportJob < ApplicationJob
+  def perform(row)
+    RailsSimpleEventSourcing::CurrentRequest.metadata = {
+      job: self.class.name,
+      job_id: job_id
+    }
+
+    RailsSimpleEventSourcing.dispatch(
+      Customer::Commands::Create.new(
+        first_name: row[:first_name],
+        last_name: row[:last_name],
+        email: row[:email]
+      )
+    )
+  end
+end
+```
+
+Any events dispatched during that job execution will carry the metadata you set. You do not need to clear it afterwards — `CurrentAttributes` resets automatically when the job finishes.
 
 ### Events Viewer
 
@@ -687,37 +838,23 @@ end
 - **Filtering** - Filter events by event type or aggregate type using dropdown selectors
 - **Search** - Search by aggregate ID, or use `key:value` syntax to search within payload and metadata (e.g., `email:john@example.com`)
 
-### Model Configuration
-
-Models that use event sourcing should include the `RailsSimpleEventSourcing::Events` module:
-
-```ruby
-class Customer < ApplicationRecord
-  include RailsSimpleEventSourcing::Events
-end
-```
-
-**This provides:**
-- `.events` association - Access all events for this aggregate
-- Read-only protection - Prevents accidental direct modifications
-- Event replay capability - Reconstruct state from events
-
-### Immutability and Read-Only Protection
-
-**Important Principles:**
-- **Events are immutable** - Once created, events should never be modified
-- **Models are read-only** - Aggregates should only be modified through events
-- Both have built-in protection against accidental changes
-
 ### Soft Deletes
 
 **Recommendation:** Use soft deletes instead of hard deletes to preserve event history.
 
 **Why?**
-- Events are linked to aggregates via foreign keys
-- Hard deleting a record can orphan its events
-- Event log becomes incomplete
-- Cannot reconstruct historical state
+- Events are linked to aggregates via a polymorphic association
+- Hard deleting a record breaks the link between the aggregate and its events
+- The event log becomes incomplete and historical state cannot be reconstructed
+
+**Hard deletes are blocked by default.** The `RailsSimpleEventSourcing::Events` concern declares `dependent: :restrict_with_exception`, so calling `destroy` on an aggregate that has any events raises `ActiveRecord::DeleteRestrictionError`. This makes the "don't hard-delete" rule a runtime error rather than a silent data-integrity drift.
+
+If you genuinely need to erase an aggregate and its event history (e.g. GDPR erasure), do it explicitly:
+
+```ruby
+customer.events.delete_all
+customer.delete
+```
 
 **How to implement:**
 
@@ -738,12 +875,22 @@ class Customer < ApplicationRecord
   scope :deleted, -> { where.not(deleted_at: nil) }
 end
 
-# Event
+# Event - deleted_at is applied to the aggregate automatically via event_attributes
 class Customer::Events::CustomerDeleted < RailsSimpleEventSourcing::Event
   aggregate_class Customer
   event_attributes :deleted_at
+end
 
-  # No need to implement apply - deleted_at will be automatically set on the aggregate
+# Handler
+class Customer::CommandHandlers::Delete < RailsSimpleEventSourcing::CommandHandlers::Base
+  def call
+    Customer::Events::CustomerDeleted.create!(
+      aggregate_id: command.aggregate_id,
+      deleted_at: Time.zone.now
+    )
+
+    success
+  end
 end
 ```
 
@@ -865,6 +1012,27 @@ RailsSimpleEventSourcing::EventBus.subscribe(
 
 If you subscribe the same job to both a specific event class and `RailsSimpleEventSourcing::Event`, it will be enqueued twice — once for each subscription. This is intentional and consistent with standard pub/sub behaviour.
 
+**Delivery guarantees:**
+
+Subscribers are enqueued via `perform_later` in an `after_commit` callback. This means delivery is **at-most-once** by default — if the queue backend (Redis, SQS, etc.) is temporarily unavailable when `perform_later` is called, the job is lost. The EventBus logs these failures individually and continues enqueuing remaining subscribers, so a single failure does not block other subscribers from being dispatched.
+
+For stronger guarantees, consider using a database-backed queue adapter such as [solid_queue](https://github.com/rails/solid_queue) or [good_job](https://github.com/bensheldon/good_job). Since these adapters write job records to PostgreSQL, the enqueue is durable as soon as the transaction commits — eliminating the window where a network blip can lose a job.
+
+**Error handling:**
+
+Subscribers are dispatched as ActiveJob jobs. Use standard ActiveJob error handling to configure retries and failure behavior:
+
+```ruby
+class SendWelcomeEmailJob < ApplicationJob
+  retry_on Net::OpenError, wait: :polynomially_longer, attempts: 5
+  discard_on ActiveJob::DeserializationError
+
+  def perform(event)
+    # ...
+  end
+end
+```
+
 **Testing with EventBus:**
 
 Use `ActiveJob::TestHelper` to assert that subscriber jobs are enqueued. Call `RailsSimpleEventSourcing::EventBus.reset!` in your test `setup` to clear all subscriptions between tests:
@@ -965,6 +1133,76 @@ end
 - Upcasting is transparent to `apply` — custom or default `apply` methods receive the already-upcasted payload
 - Events without `aggregate_class` do not use schema versioning (the `schema_version` column is left `nil`)
 
+### Snapshots
+
+By default, every aggregate reconstruction replays its full event history from the beginning. For aggregates with many events this can become slow. Snapshots store the aggregate's serialized state at a given version so that `EventPlayer` only needs to replay events written after the snapshot.
+
+**Automatic snapshots:**
+
+Set `snapshot_interval` in your initializer to have a snapshot created automatically every N events:
+
+```ruby
+# config/initializers/rails_simple_event_sourcing.rb
+RailsSimpleEventSourcing.configure do |config|
+  config.snapshot_interval = 50
+end
+```
+
+With `snapshot_interval = 50`, a snapshot is written after event version 50, 100, 150, and so on. On the next reconstruction, `EventPlayer` loads the snapshot at version 100 and replays only events 101 onwards — at most 49 events instead of all 100+.
+
+**Choosing a snapshot interval:**
+
+The right interval depends on your event replay cost. A lower interval (e.g., 20) means faster reconstruction but more snapshot writes. A higher interval (e.g., 200) saves writes but replays more events. For most applications, 50–100 is a reasonable starting point.
+
+**Manual snapshots:**
+
+Call `create_snapshot!` on any aggregate to write a snapshot immediately at the current version:
+
+```ruby
+customer = Customer.find(params[:id])
+customer.create_snapshot!
+```
+
+This is useful after bulk imports or data migrations, where you want to pre-warm snapshots for all existing aggregates:
+
+```ruby
+# lib/tasks/import_customer_events.rake
+namespace :events do
+  desc "Import existing customers as CustomerCreated events and pre-warm snapshots"
+  task import_customers: :environment do
+    Customer.find_each do |customer|
+      next if customer.events.exists?
+
+      Customer::Events::CustomerCreated.create!(
+        aggregate_id: customer.id,
+        first_name: customer.first_name,
+        last_name: customer.last_name,
+        email: customer.email,
+        created_at: customer.created_at,
+        updated_at: customer.updated_at
+      )
+
+      customer.reload.create_snapshot!
+    end
+  end
+end
+```
+
+**How it works:**
+
+- Snapshots are stored in the `rails_simple_event_sourcing_snapshots` table
+- One snapshot per aggregate is kept — each new snapshot overwrites the previous one
+- `aggregate_state` (used by the Events Viewer) also benefits: when reconstructing historical state at version N, the nearest snapshot at or before version N is used
+- If no snapshot exists, `EventPlayer` falls back to a full replay — behaviour is identical, just slower
+
+**Schema fingerprinting:**
+
+Each snapshot stores a `schema_fingerprint` — a hash of the aggregate's column names at the time the snapshot was written. When `EventPlayer` loads a snapshot, it compares the stored fingerprint against the aggregate's current fingerprint. If they differ (because a column was added, removed, or renamed), the snapshot is **ignored** and a full event replay is performed instead.
+
+This protects you from a subtle class of bug: snapshots store the aggregate's raw attributes at a point in time, but upcasters only transform event payloads — there's no equivalent migration path for snapshot state. Without fingerprint validation, a schema change could leave your aggregate in an inconsistent state after a snapshot restore (e.g., a renamed column would silently drop the old value and the new column would remain `nil`).
+
+The fingerprint check makes snapshots self-invalidating: after any aggregate schema change, stale snapshots are skipped automatically and replaced with fresh ones on the next auto-snapshot or `create_snapshot!` call. No manual cleanup required.
+
 ## Testing
 
 ### Setting Up Tests with Command Handler Registry
@@ -1092,11 +1330,11 @@ end
 Be aware of these limitations when using this gem:
 
 - **PostgreSQL Only** - Requires PostgreSQL 9.4+ for JSONB support
-- **No Snapshots** - All aggregate reconstruction done by replaying all events (can be slow for aggregates with many events)
 - **No Projections** - No built-in read model or projection support
 - **Manual aggregate_id** - Must manually track and pass `aggregate_id` for updates/deletes
 - **No Saga Support** - No built-in support for long-running processes or sagas
 - **Single Database** - Events and aggregates must be in the same database
+- **Pessimistic Locking** - Concurrent updates to the same aggregate are serialized using `SELECT ... FOR UPDATE`. This guarantees correctness but may increase latency under high contention on a single aggregate. A unique database index on `(eventable_type, aggregate_id, version)` provides an additional safety net
 
 ## Troubleshooting
 

data/app/models/concerns/rails_simple_event_sourcing/aggregate_configuration.rb

@@ -12,9 +12,7 @@ module RailsSimpleEventSourcing
       end
     end
 
-    def aggregate_class
-      self.class.aggregate_class
-    end
+    delegate :aggregate_class, to: :class
 
     def aggregate_defined?
       aggregate_class.present?

data/app/models/concerns/rails_simple_event_sourcing/events.rb

@@ -6,7 +6,21 @@ module RailsSimpleEventSourcing
     include ReadOnly
 
     included do
-      has_many :events, class_name: 'RailsSimpleEventSourcing::Event', as: :eventable, dependent: :nullify
+      has_many :events, class_name: 'RailsSimpleEventSourcing::Event', as: :eventable,
+                        dependent: :restrict_with_exception
+    end
+
+    def create_snapshot!
+      latest_event = events.order(version: :desc).first
+      return unless latest_event
+
+      RailsSimpleEventSourcing::Snapshot.create_or_update!(
+        aggregate_type: self.class.name,
+        aggregate_id: id,
+        state: attributes,
+        version: latest_event.version,
+        schema_fingerprint: RailsSimpleEventSourcing::Snapshot.fingerprint_for(self.class)
+      )
     end
   end
 end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -15,13 +15,14 @@ module RailsSimpleEventSourcing
               numericality: { only_integer: true, greater_than: 0 },
               if: -> { aggregate_id.present? }
     validates :version,
-              uniqueness: { scope: :aggregate_id },
+              uniqueness: { scope: %i[eventable_type aggregate_id] },
               if: -> { aggregate_id.present? }
 
     before_validation :setup_for_create, on: :create
     before_save :persist_aggregate, if: :aggregate_defined?
     after_create :disable_write_access!
     after_commit :dispatch_to_event_bus, on: :create
+    after_commit :maybe_create_snapshot, on: :create
 
     def apply(aggregate)
       payload.each do |key, value|
@@ -67,7 +68,7 @@ module RailsSimpleEventSourcing
     end
 
     def calculate_next_version
-      max_version = Event.where(aggregate_id:).maximum(:version) || 0
+      max_version = Event.where(eventable_type: aggregate_class.name, aggregate_id:).maximum(:version) || 0
       max_version + 1
     end
 
@@ -86,5 +87,12 @@ module RailsSimpleEventSourcing
     def dispatch_to_event_bus
       EventBus.dispatch(self)
     end
+
+    def maybe_create_snapshot
+      interval = RailsSimpleEventSourcing.config.snapshot_interval
+      return unless interval && aggregate_defined? && eventable.present? && (version % interval).zero?
+
+      Snapshot.create_from_event!(self)
+    end
   end
 end

data/app/models/rails_simple_event_sourcing/snapshot.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class Snapshot < ApplicationRecord
+    validates :aggregate_type, :aggregate_id, :state, :version, presence: true
+
+    def self.create_from_event!(event)
+      create_or_update!(
+        aggregate_type: event.eventable_type,
+        aggregate_id: event.aggregate_id,
+        state: event.eventable.attributes,
+        version: event.version,
+        schema_fingerprint: fingerprint_for(event.eventable.class)
+      )
+    end
+
+    def self.create_or_update!(aggregate_type:, aggregate_id:, state:, version:, schema_fingerprint:)
+      upsert( # rubocop:disable Rails/SkipsModelValidations
+        {
+          aggregate_type: aggregate_type,
+          aggregate_id: aggregate_id.to_s,
+          state: state,
+          version: version,
+          schema_fingerprint: schema_fingerprint
+        },
+        unique_by: :index_snapshots_on_aggregate_type_and_aggregate_id
+      )
+    end
+
+    def self.fingerprint_for(aggregate_class)
+      signature = aggregate_class.columns
+                                 .map { |c| "#{c.name}:#{c.sql_type}:#{c.null}" }
+                                 .sort
+                                 .join(',')
+      Digest::SHA256.hexdigest(signature)
+    end
+  end
+end

data/db/migrate/20260328000000_create_rails_simple_event_sourcing_snapshots.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateRailsSimpleEventSourcingSnapshots < ActiveRecord::Migration[7.1]
+  def change
+    create_table :rails_simple_event_sourcing_snapshots do |t|
+      t.string :aggregate_type, null: false
+      t.string :aggregate_id, null: false
+      t.jsonb :state, null: false, default: {}
+      t.integer :version, null: false
+      t.string :schema_fingerprint
+
+      t.timestamps
+    end
+
+    add_index :rails_simple_event_sourcing_snapshots,
+              %i[aggregate_type aggregate_id],
+              unique: true,
+              name: 'index_snapshots_on_aggregate_type_and_aggregate_id'
+  end
+end

data/lib/rails_simple_event_sourcing/configuration.rb

@@ -3,10 +3,21 @@
 module RailsSimpleEventSourcing
   class Configuration
     attr_accessor :use_naming_convention_fallback, :events_per_page
+    attr_reader :snapshot_interval
 
     def initialize
       @use_naming_convention_fallback = true
       @events_per_page = 25
+      @snapshot_interval = nil
+    end
+
+    def snapshot_interval=(value)
+      if !value.nil? && !(value.is_a?(Integer) && value.positive?)
+        raise ArgumentError,
+              "snapshot_interval must be nil or a positive integer, got #{value.inspect}"
+      end
+
+      @snapshot_interval = value
     end
   end
 end

data/lib/rails_simple_event_sourcing/event_bus.rb

@@ -16,6 +16,10 @@ module RailsSimpleEventSourcing
       def dispatch(event)
         subscribers_for(event).each do |subscriber|
           subscriber.perform_later(event)
+        rescue StandardError => e
+          Rails.logger.error(
+            "[RailsSimpleEventSourcing::EventBus] Failed to enqueue #{subscriber} for event ##{event.id}: #{e.message}"
+          )
         end
       end
 

data/lib/rails_simple_event_sourcing/event_player.rb

@@ -19,11 +19,39 @@ module RailsSimpleEventSourcing
     private
 
     def load_event_stream(up_to_version:)
-      scope = @aggregate.events.order(version: :asc)
+      snapshot = load_snapshot(up_to_version:)
+
+      if snapshot
+        restore_from_snapshot(snapshot)
+        from_version = snapshot.version + 1
+      else
+        from_version = 1
+      end
+
+      scope = @aggregate.events.where(version: from_version..).order(:version)
       scope = scope.where(version: ..up_to_version) if up_to_version
       scope
     end
 
+    def load_snapshot(up_to_version:)
+      return nil if @aggregate.new_record?
+
+      snapshot = Snapshot.find_by(
+        aggregate_type: @aggregate.class.name,
+        aggregate_id: @aggregate.id.to_s
+      )
+      return nil if snapshot && up_to_version && snapshot.version > up_to_version
+      return nil if snapshot && snapshot.schema_fingerprint != Snapshot.fingerprint_for(@aggregate.class)
+
+      snapshot
+    end
+
+    def restore_from_snapshot(snapshot)
+      snapshot.state.each do |key, value|
+        @aggregate.send("#{key}=", value) if @aggregate.respond_to?("#{key}=")
+      end
+    end
+
     def apply_events(events)
       events.each do |event|
         event.apply(@aggregate)

data/lib/rails_simple_event_sourcing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsSimpleEventSourcing
-  VERSION = '1.1.0'
+  VERSION = '1.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_event_sourcing
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Damian Baćkowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.2
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.2
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -102,12 +102,14 @@ files:
 - app/models/rails_simple_event_sourcing.rb
 - app/models/rails_simple_event_sourcing/current_request.rb
 - app/models/rails_simple_event_sourcing/event.rb
+- app/models/rails_simple_event_sourcing/snapshot.rb
 - app/views/layouts/rails_simple_event_sourcing/application.html.erb
 - app/views/rails_simple_event_sourcing/events/_pagination.html.erb
 - app/views/rails_simple_event_sourcing/events/index.html.erb
 - app/views/rails_simple_event_sourcing/events/show.html.erb
 - config/routes.rb
 - db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb
+- db/migrate/20260328000000_create_rails_simple_event_sourcing_snapshots.rb
 - lib/rails_simple_event_sourcing.rb
 - lib/rails_simple_event_sourcing/aggregate_links_builder.rb
 - lib/rails_simple_event_sourcing/aggregate_repository.rb
@@ -129,6 +131,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/dbackowski/rails_simple_event_sourcing
+  source_code_uri: https://github.com/dbackowski/rails_simple_event_sourcing
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -144,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Rails engine for simple event sourcing.