eventusha

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.