Eventusha

Eventusha is an Event Sourcing framework for Ruby.

Installation

Add this line to your application's Gemfile:

gem 'eventusha'

Execute:

$ bundle install

And then:

$ rails generate eventusha:install
$ rake db:migrate

Usage

Event Sourcing and CQRS consist of a few different elements. Recommended folder structure inside app folder:

app
──cqrs
    ──aggregates
    ──command_handlers
    ──commands
    ──event_handlers
    ──events

Controller

Inside controllers you need to execute commands.

class BankAccountsController < ApplicationController
  def new
    @command = Commands::CreateBankAccount.new
  end

  def create
    @command = Commands::CreateBankAccount.new(bank_account_params)

    if @command.execute
      redirect_to [:bank_accounts]
    else
      render :new
    end
  end

  private

  def bank_account_params
    params.require(:bank_account)
          .permit(:first_name, :last_name)
  end
end

Commands

Commands are instructions that are usually initiated by users, e.g. CreateBankAccount. Commands are defined inside app/cqrs/commands folder. User actions are validated inside commands using the ActiveModel::Model.

attributes

Use attributes method to define command attributes. These attributes are going to be saved as serialized event data.

module Commands
    class CreateBankAccount < Eventusha::Command
      attributes :first_name, :last_name

      validates :first_name, presence: true
      validates :last_name, presence: true
    end
end

Command Handlers

Command handlers are used for handling commands. They load defined aggregate and execute corresponding action on it. For each command you must define a command handler with the same name inside app/cqrs/command_handlers folder

aggregate

Use aggregate method to define which aggregate is going to be used. Selected aggregate must be defined in app/cqrs/aggregates folder. These attributes are going to be saved as serialized event data.

aggregate :bank_account will use Aggregates::BankAccount aggregate.

module CommandHandlers
    class CreateBankAccount < Eventusha::CommandHandler
      aggregate :bank_account

      def execute
        bank_account = aggregate.new

        bank_account.create_bank_account(command.attributes)
      end
    end
end

You can create a new aggregate with aggregate.new or build by replaying all events with that aggregate_id using aggregate.find(command.aggregate_id)

module CommandHandlers
    class PerformDeposit < Eventusha::CommandHandler
      aggregate :bank_account

      def execute
        bank_account = aggregate.find(command.aggregate_id)

        bank_account.perform_deposit(command.attributes)
      end
    end
end

Aggregates

Aggregate is a main domain model. It is build by replaying events and it represents current state of a domain object.

When an action initiated from command handler is executed on an aggregate, one or more events are created and applied on current aggregate.

Define what happens on an aggregate when you replay an event.

    on EventClass do |event|
        #define what happens on aggregate when you replay this event
    end

module Aggregates
    class BankAccount < Eventusha::Aggregate
      def initialize
        @aggregate_id = SecureRandom.uuid
        @amount = 0
      end

      def create_bank_account(attributes)
        apply Events::BankAccountCreated.prepare(aggregate_id, attributes)
      end

      def perform_deposit(attributes)
        apply Events::DepositPerformed.prepare(aggregate_id, attributes)
      end

      private

      on Events::BankAccountCreated do |event|
        @aggregate_id = event.aggregate_id
        @amount = 0
        @first_name = event.first_name
        @last_name = event.last_name
      end

      on Events::DepositPerformed do |event|
        @amount += event.amount.to_i
      end
    end
end

Events

Events describe what happened as a consequence of executing a command. Attributes defined on a command that was executed are saved as a data json object.

event_handler

Using event handler define which event handler is going to be used when this event is created. Selected event handler must be defined in app/cqrs/event_handlers folder.

event_handler :bank_account will use EventHandlers::BankAccount event handler.

store_accessor

You need to define accessors for data attributes saved in JSON.

module Events
    class BankAccountCreated < Eventusha::Event
      event_handler :bank_account

      store_accessor :data, :first_name, :last_name
    end
end

Event Handlers

Event handlers are usually updating view models after event is created. You need to define which event handler is going to be used for each event.

module EventHandlers
    class BankAccount < Eventusha::EventHandler
      on Events::BankAccountCreated do |event|
        ::BankAccount.create(
          aggregate_id: event.aggregate_id,
          first_name: event.first_name,
          last_name: event.last_name,
          amount: 0
        )
      end

      on Events::DepositPerformed do |event|
        bank_account = ::BankAccount.find_by(aggregate_id: event.aggregate_id)
        bank_account.amount += event.amount.to_i
        bank_account.save
      end
    end
end

Usage

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/eventusha. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.