lieutenant 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b4bd4305e270917371083e9ad6138b7a45f6473
-  data.tar.gz: 5bd3c11a3945578b07e45226dc95efdd4388ba3a
+  metadata.gz: c13d7331d61d26a8ec7a9c816a25b959d2d94466
+  data.tar.gz: f26f9cf92f4a8064078859bd488a5cb15eb3954b
 SHA512:
-  metadata.gz: 11e225acbc456c2e8093eb467a1537df64c98400686d295a1ecfbd1c96f2d7463f896cc1c2363d38b8d37700a30db74f7cb731c4b967d11562a1ad0e461b9f30
-  data.tar.gz: 95136b8ad7cd14e41d4bc2eb7b2a3c8e4a76f2fad74b684574ef76d63e962422585377d2b044eb6ee1d7ec813269c5970c6ba4888ad57cf57276ffea4704e467
+  metadata.gz: 7f85b854951dd7e9556186ba9a173331cbd7cef3dd45e23e4a8e52a27508ac2d2a78a67cb2279dee7fe270fd85bb552d621d4c0d3c174b5fb6f90ec901ce22fd
+  data.tar.gz: 1ca3adbc3fb5fdc021b00f2621d1b65b722f724f7fa7dd554a650a0cef32167a64e48d1a54adddcdb6bc26d795ffa62a506d5e920de50cd7b22e20eb3b9f3b2e

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.4
+  TargetRubyVersion: 2.1
 
 Metrics/LineLength:
   Max: 120

data/.travis.yml

@@ -1,5 +1,11 @@
 sudo: false
 language: ruby
 rvm:
+  - 2.1
+  - 2.2
+  - 2.3.0
   - 2.4.1
-before_install: gem install bundler -v 1.16.0.pre.2
+  - ruby-head
+before_install: gem install bundler -v 1.16.0
+script:
+  - bundle exec rake fulltest

data/README.md

@@ -2,9 +2,15 @@
 
 ## **CQRS/ES Toolkit to command them all**
 
+[![Gem Version](https://badge.fury.io/rb/lieutenant.svg)](https://badge.fury.io/rb/lieutenant)
+[![Build Status](https://travis-ci.org/gabteles/lieutenant.svg?branch=master)](https://travis-ci.org/gabteles/lieutenant)
+[![Coverage Status](https://coveralls.io/repos/github/gabteles/lieutenant/badge.svg?branch=master)](https://coveralls.io/github/gabteles/lieutenant?branch=master)
+[![Maintainability](https://api.codeclimate.com/v1/badges/c96a6dd822547e657829/maintainability)](https://codeclimate.com/github/gabteles/lieutenant/maintainability)
+
+
 Lieutenant is a toolkit that implements various of the components of Command & Query Responsability Segregation (CQRS) and Event Sourcing (ES). It means that your application can get rid of the "current" state of the entities you choose and store all the *changes* that led them to it.
 
-This gem aims to be most independent as possible of your tecnological choices, it means that it should work with Rails, Sinatra, pure Rack apps or whatever you want.
+This gem aims to be most independent as possible of your tecnological choices: it should work with Rails, Sinatra, pure Rack apps or whatever you want.
 
 If you are not familiarized, you may check this references:
 
@@ -37,63 +43,307 @@ By now, Lieutenant offer the components listed below. With each one, there's a d
 - [Commands](#commands)
 - [Command Sender](#command-sender)
 - [Command Handlers](#command-handlers)
-- [Aggregate Repositories](#aggregate-repositories)
+- [Aggregate Repository](#aggregate-repository)
 - [Aggregates](#aggregates)
 - [Events](#events)
 - [Event Store](#event-store)
 - [Event Bus](#event-bus)
+- [Projections](#projections)
+- [Configuration](#configuration)
 
 ### Commands
 
-TODO
+Commands are the representation of the system actions. They describe a **intention** to do something (e.g. `ScheduleMeeting`, `DisableProduct`).
+
+This classes do not need any special methods, just define attributes and validations.
 
+To use define them, just include `Lieutenant::Command` module. It'll allow you to use [ActiveModel Validations](http://guides.rubyonrails.org/active_record_validations.html).
+
+```ruby
+class ScheduleMeeting
+    include Lieutenant::Command
+
+    attr_accessor :meeting_room_uuid
+    attr_accessor :description
+    attr_accessor :date_start
+    attr_accessor :date_end
+
+    validates :meeting_room_uuid, presence: true
+    validates :description, presence: true, length: { minimum: 3 }
+    validates :date_start, presence: true
+    validates :date_end, presence: true
+
+    validate do
+        date_start.is_a?(Time) && date_end.is_a?(Time) && date_start < date_end
+    end
+end
+```
+
+To instantiate commands you can use `.new` or helper method `.with`, that receives the parameters as a Hash:
+
+```ruby
+ScheduleMeeting.with(
+    meeting_room_uuid: '4bb0a8a0-9234-477d-8df4-5f10a2fb1faa',
+    description: 'Annual planning',
+    date_start: Time.mktime(2017, 12, 15, 14, 0, 0),
+    date_end: Time.mktime(2017, 12, 15, 18, 0, 0)
+)
+```
 
 ### Command Sender
 
-TODO
+Command sender is the component that receives commands and forward them to the right handlers. It also instantiate the aggregate repository's unit of work, in order to help persistence to save only the generated events in each command handling.
+
+You can access the command sender throught Lieutenant's config:
+
+```ruby
+Lieutenant.config.command_sender
+```
+
+It dependes on all the configuration components, so be sure to config them before calling it. See [Configuration](#configuration).
+
+Once with the Command Sender, dispatch events by using `#dispatch` (aliased as `#call`):
+
+```ruby
+Lieutenant.config.command_sender.dispatch(command)
+```
 
 
 ### Command Handlers
 
-TODO
+Command Handlers are orchestrators to your business logic. They will receive a command and a aggregate repository then will call the needed operations, they can load a aggregate by the identifier or add a new one to the repository.
 
+Handlers are simply objects that respond to `#call`. You can define them as [Proc's](https://ruby-doc.org/core-2.5.0/Proc.html), for example.
 
-### Aggregate Repositories
+Lieutenant also defines a syntax sugar to help definition of them:
 
-TODO
+```ruby
+module ScheduleHandler
+    include Lieutenant::CommandHandler
+
+    on(ScheduleMeeting) do |repository, command|
+        # ...
+    end
+end
+```
+
+You can also register them directly on command sender:
+
+```ruby
+Lieutenant.config.command_sender.register(ScheduleMeeting) do |repository, command|
+    # ...
+end
+```
+
+It's important that command handlers do not have side-effects, since the commands **can** be retried (and eventually they will). If you, for example, send an email inside your handler, it may be sent twice in case of command retry.
+
+### Aggregate Repository
+
+The aggregate repository is responsible to control the changes in the application state. It means that it will collect events from created or modified aggregates.
+
+It also implements the [Unit of Work Pattern](https://martinfowler.com/eaaCatalog/unitOfWork.html) for each dispatched command, meaning that it will know what new events where created when processing the command.
+
+You'll interact only with the Repository Unit of Work, that is the `repository` parameter that command handlers receive. It allows you to:
+
+#### Add an aggregate:
+```ruby
+aggregate = MeetingRoom.new
+repository.add_aggregate(aggregate)
+```
+
+#### Load an aggregate:
+```ruby
+meeting_room = repository.load(MeetingRoom, command.meeting_room_uuid)
+```
 
 
 ### Aggregates
 
-TODO
+Aggregates contain your business logic, rules between multiple entities are kept by them. Aggregates are all about the transaction consistency.
+
+To define them, include `Lieutenant::Aggregate` into your class. When defining it's initializer, you'll need to also setup the instance, calling `#setup(id)`, where `id` is the identifier of the aggregates' instance (`SecureRandom.uuid` is encouraged).
 
+```ruby
+class MeetingRoom
+    include Lieutenant::Aggregate
+
+    def initialize(name)
+        setup(SecureRandom.uuid)
+    end
+end
+```
+
+Aggregates' state should only be modified by events, that can be applied using `#apply`, that will instantiate the event with provided params and fire them to aggregate's internal handlers (registered with `.on`):
+
+```ruby
+class MeetingRoom
+    include Lieutenant::Aggregate
+
+    def initialize(name)
+        setup(SecureRandom.uuid)
+        apply(MeetingRoomCreated, name: name)
+    end
+
+    on(MeetingRoomCreated) do |event|
+        @name = event.name
+    end
+end
+```
+
+To allow command handlers to modify aggregates, you can define handlers that also handles your business logic or throw errors:
+
+```ruby
+class MeetingRoom
+    include Lieutenant::Aggregate
+
+    def initialize(name)
+        setup(SecureRandom.uuid)
+        apply(MeetingRoomCreated, name: name)
+    end
+
+    def schedule_meeting(description, date_start, date_end)
+        # Check if meeting room is available to needed dates
+
+        raise(MeetingRoomNotAvailable) unless room_available
+
+        apply(
+            MeetingScheduled,
+            description: description,
+            date_start: date_start,
+            date_end: date_end
+        )
+    end
+
+    on(MeetingRoomCreated) do |event|
+        @name = event.name
+        @meetings = []
+    end
+
+    on(MeetingScheduled) do |event|
+        # Note that we could push a PORO instead of a Hash
+        # (and it wouldn't be a Lieutenant::Aggregate)
+        @meetings.push({
+            description: event.description,
+            date_start: event.date_start,
+            date_end: event.date_end
+        })
+    end
+end
+```
+
+For the same reason of the command handlers, aggregates should not have side-effects inside them.
 
 ### Events
 
-TODO
+Events register what happened with aggregates since they were created. They have same features as `Commands`: you can use ActiveModel Validations and instantiate them using `#with` method.
+
+Events exposes `aggregate_id` and `sequence_number`, that are used to know to which aggregate each event belongs to and it's order into the event stream. You should not worry about them, we use them internally ;)
 
+```ruby
+class MeetingScheduled
+    include Lieutenant::Event
+
+    attr_accessor :description
+    attr_accessor :date_start
+    attr_accessor :date_end
+    # Implicity defined:
+    # attr_accessor :aggregate_id (Meeting room's UUID)
+    # attr_accessor :sequence_number
+end
+```
 
 ### Event Store
 
-TODO
+Event stores handles pushing and pulling events to/from the persistence. They are used by the Aggregate Repository to commit changes collected by one unit of work.
+
+You need to set what implementation will be used, them Lieutenant will do the magic. Please refer to [Configuration](#configuration).
 
 
 ### Event Bus
 
-TODO
+The event bus publishes and receives messages from the aggregates updates.
+
+You can also listen to it's events by subscribing to them:
+
+```ruby
+Lieutenant.config.event_bus.subscribe(MeetingScheduled) do |event|
+  puts "Meeting scheduled on room #{event.aggregate_id}, starts at #{event.date_start.iso8601}, ends at #{event.date_end.iso8601}"
+end
+```
+
+
+### Projections
+
+The Projections listens to events it is interested in and updates read models
+as needed. It means that they maintain the *current* state of the data.  To use
+it, just include `Lieutenant::Projection`.
 
+```ruby
+module MeetingRoomProjection
+  include Lieutenant::Projection
+
+  on(MeetingRoomCreated) do |event|
+    MeetingRoomRecord.create!(
+      uuid: event.aggregate_id,
+      name: event.name,
+      meetings: []
+    )
+  end
+
+  on(MeetingScheduled) do |event|
+    meeting_room = MeetingRoomRecord.find(event.aggregate_id)
+    meeting_room.meetings.push({
+      description: event.description,
+      date_start: event.date_start,
+      date_end: event.date_end
+    })
+    meeting_room.save!
+  end
+end
+```
+
+
+### Configuration
+
+Lieutenant's configuration can be modified by using an structured or block way. By default, it uses InMemory implementation of event store.
+
+```ruby
+Lieutenant.config do |configuration|
+    configuration.event_store(Lieutenant::EventStore::InMemory)
+end
+
+# OR
+
+Lieutenant.config.event_store(Lieutenant::EventStore::InMemory)
+```
+
+You can also access configuration the same way:
+
+```ruby
+Lieutenant.config do |configuration|
+    configuration.event_bus # => Lieutenant::EventBus
+    configuration.event_store # => Lieutenant::EventStore::InMemory
+    configuration.aggregate_repository # => Lieutentant::AggregateRepository
+    configuration.command_sender # => Lieutenant::CommandSender
+end
+
+# OR
+
+Lieutenant.config.event_bus # => Lieutenant::EventBus
+Lieutenant.config.event_store # => Lieutenant::EventStore::InMemory
+Lieutenant.config.aggregate_repository # => Lieutentant::AggregateRepository
+Lieutenant.config.command_sender # => Lieutenant::CommandSender
+```
 
 ## Roadmap
 
 In order to give some directions to the development of this gem, the roadmap below presents in a large picture of the plans to the future (more or less ordered).
 
-- Projections
-- Better documentation
-- Command filters
 - Command retry policies
-- Sagas
 - More implementations of event store
-- More implementations of event bus
+- Sagas
+- Command filters
+- Better documentation
 
 ## Development
 

data/lib/lieutenant.rb

@@ -16,6 +16,7 @@ module Lieutenant
   autoload :EventStore,          'lieutenant/event_store'
   autoload :Exception,           'lieutenant/exception'
   autoload :Message,             'lieutenant/message'
+  autoload :Projection,          'lieutenant/projection'
   autoload :VERSION,             'lieutenant/version'
 
   module_function

data/lib/lieutenant/command.rb

@@ -4,7 +4,9 @@ module Lieutenant
   # Syntax helper to define commands
   module Command
     def self.included(base)
-      base.include(Message)
+      base.instance_eval do
+        include Lieutenant::Message
+      end
     end
   end
 end

data/lib/lieutenant/config.rb

@@ -3,15 +3,14 @@
 module Lieutenant
   # Manages configuration
   class Config
-    # :reek:BooleanParameter
-    def event_bus(implementation = false)
-      return @event_bus = implementation if implementation
-      @event_bus ||= EventBus::InMemory.new
+    def event_bus
+      @event_bus ||= EventBus.new
     end
 
     # :reek:BooleanParameter
     def event_store(implementation = false)
       return @event_store_implementation = implementation if implementation
+      @event_store_implementation ||= EventStore::InMemory
       @event_store ||= EventStore.new(@event_store_implementation, event_bus)
     end
 

data/lib/lieutenant/event.rb

@@ -4,7 +4,9 @@ module Lieutenant
   # The basic interface to register the aggregates events
   module Event
     def self.included(base)
-      base.include(Message)
+      base.instance_eval do
+        include Lieutenant::Message
+      end
     end
 
     attr_reader :aggregate_id, :sequence_number

data/lib/lieutenant/event_bus.rb

@@ -2,7 +2,23 @@
 
 module Lieutenant
   # Publishes and receives messages from the aggregates updates
-  module EventBus
-    autoload :InMemory, 'lieutenant/event_bus/in_memory'
+  class EventBus
+    def initialize
+      @handlers = Hash.new { [] }
+    end
+
+    def subscribe(*event_classes, &handler)
+      event_classes.each do |event_class|
+        handlers[event_class] = handlers[event_class].push(handler)
+      end
+    end
+
+    def publish(event)
+      handlers[event.class].each { |handler| handler.call(event) }
+    end
+
+    private
+
+    attr_reader :handlers
   end
 end

data/lib/lieutenant/event_store/in_memory.rb

@@ -5,22 +5,27 @@ module Lieutenant
     # Memory implementation of the event store. Stores events while the application is running
     class InMemory
       def initialize
-        @store = {}
+        @store = []
+        @index = {}
       end
 
       def persist(events)
-        events.each { |event| (store[event.aggregate_id] ||= []).push(event) }
+        events.each do |event|
+          (index[event.aggregate_id] ||= []).push(store.size)
+          store.push(event)
+        end
       end
 
       def event_stream_for(aggregate_id)
-        events = store[aggregate_id]
-        return nil unless events
+        aggregate_stream = index[aggregate_id]
+        return nil unless aggregate_stream
+        events = aggregate_stream.lazy.map(&store.method(:[]))
         Enumerator.new { |yielder| events.each(&yielder.method(:<<)) }
       end
 
       def aggregate_sequence_number(aggregate_id)
-        return -1 unless store.key?(aggregate_id)
-        store[aggregate_id].last.sequence_number
+        return -1 unless index.key?(aggregate_id)
+        store[index[aggregate_id].last].sequence_number
       end
 
       def transaction
@@ -30,7 +35,7 @@ module Lieutenant
 
       private
 
-      attr_reader :store
+      attr_reader :store, :index
     end
   end
 end

data/lib/lieutenant/message.rb

@@ -4,8 +4,10 @@ module Lieutenant
   # Helper to define messages with validation
   module Message
     def self.included(base)
-      base.extend(ClassMethods)
-      base.include(ActiveModel::Validations)
+      base.instance_eval do
+        extend Lieutenant::Message::ClassMethods
+        include ActiveModel::Validations
+      end
     end
 
     # Define common class methods to commands

data/lib/lieutenant/projection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lieutenant
+  # Projection helper. Allows clean syntax to subscribe to events:
+  #
+  #   module FooProjection
+  #     include Lieutenant::Projection
+  #
+  #     on(CreatedBarEvent) do |event|
+  #        # ...
+  #     end
+  #   end
+  module Projection
+    def self.included(base)
+      base.class_eval do
+        extend Lieutenant::Projection
+      end
+    end
+
+    # :reek:UtilityFunction
+    def on(*event_classes, &block)
+      Lieutenant.config.event_bus.subscribe(*event_classes, &block)
+    end
+  end
+end

data/lib/lieutenant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lieutenant
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'.freeze
 end

data/lieutenant.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'coveralls'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'reek'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lieutenant
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Gabriel Teles
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-03 00:00:00.000000000 Z
+date: 2018-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -161,7 +175,6 @@ files:
 - lib/lieutenant/config.rb
 - lib/lieutenant/event.rb
 - lib/lieutenant/event_bus.rb
-- lib/lieutenant/event_bus/in_memory.rb
 - lib/lieutenant/event_store.rb
 - lib/lieutenant/event_store/in_memory.rb
 - lib/lieutenant/exception.rb
@@ -169,6 +182,7 @@ files:
 - lib/lieutenant/exception/concurrency_conflict.rb
 - lib/lieutenant/exception/no_registered_handler.rb
 - lib/lieutenant/message.rb
+- lib/lieutenant/projection.rb
 - lib/lieutenant/version.rb
 - lieutenant.gemspec
 homepage: https://github.com/gabteles/lieutenant

data/lib/lieutenant/event_bus/in_memory.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Lieutenant
-  module EventBus
-    # Memory implementation of the event bus. Publishes and notifies on the same memory space.
-    class InMemory
-      def initialize
-        @handlers = Hash.new { [] }
-      end
-
-      def subscribe(*event_classes, &handler)
-        event_classes.each do |event_class|
-          handlers[event_class] = handlers[event_class].push(handler)
-        end
-      end
-
-      def publish(event)
-        block = CALL_HANDLER_WITH_EVENT[event]
-        handlers[:all].each(&block)
-        handlers[event.class].each(&block)
-      end
-
-      private
-
-      attr_reader :handlers
-
-      CALL_HANDLER_WITH_EVENT = ->(event) { ->(handler) { handler.call(event) } }
-      private_constant :CALL_HANDLER_WITH_EVENT
-    end
-  end
-end