event_sourcery 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5a53861c6b78ba25db797887cbb523bec700832a
-  data.tar.gz: 2cc44cb2db162bf4b1f35e356e24eab1c213534d
+  metadata.gz: a6cabf34f27962b52571d80fb0a505186cef6e69
+  data.tar.gz: 3f07fcaf03c74190b2531099f1b4ca10d8312355
 SHA512:
-  metadata.gz: 77e1852829109a6fcab8e4c2efb930de89b88dfa45eccbecf761484c7a19f6ab8825fd9179c9112002e6c82ab281033106dc0da60fad2f8be76dd97e0c42d782
-  data.tar.gz: e0c6879eb49868144c628b6649c37d6577637f3514ef2653606a47d342cd820c9ed38f44588f77acd145f7b528a98b314a3c9189e27cd8f2971391c9ffe2978c
+  metadata.gz: 0a25a29c4d626ae5a179668b4663dc20dc81799948ee38506ce26b3e7b10d7c31e483baf8978507e9cb199b7eda616051b7d8c90e05b5d6af99713430a4fcb83
+  data.tar.gz: 334f2eb26deba53e6459c00caffec74403ee039fdee14d68c45243f889f64690d20082fb98e1006e50ceefaa647d8770090f9d25785b39ddbe9efe97bca01a67

data/CHANGELOG.md

@@ -5,6 +5,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+
+## [0.14.0] - 2016-6-21
+### Added
+- Added `Event#to_h` method. This returns a hash of the event attributes.
+- Added `Event#with` method. This provides a way to create a new event
+  identical to the old event except for the provided changes.
+- `Event#initialize` accepts `aggregate_id` parameter that either is
+  a strings or responds to `to_str`.
+
+## [0.13.0] - 2016-6-16
 ### Added
 - The core Event class accepts `causation_id` to allow event stores to
   add support for tracking causation ids with events.

data/README.md

@@ -8,7 +8,8 @@ A framework for building event sourced, CQRS applications.
 
 - [Development Status](#development-status)
 - [Goals](#goals)
-- [Getting Started Guide](#getting-started-guide)
+- [Related Repositories](#related-repositories)
+- [Getting Started](#getting-started)
 - [Configuration](#configuration)
 - [Development](#development)
     - [Dependencies](#dependencies)
@@ -26,7 +27,7 @@ A framework for building event sourced, CQRS applications.
         - [Projectors](#projectors)
         - [Reactors](#reactors)
         - [Running Multiple ESPs](#running-multiple-esps)
-    - [Typical Flow of State in an Event Sourcery Application](#typical-flow-of-state-in-an-event-sourcery-application)
+    - [Typical Flow of State in an EventSourcery Application](#typical-flow-of-state-in-an-eventsourcery-application)
         - [1. Handling a Command](#1-handling-a-command)
         - [2. Updating a Projection](#2-updating-a-projection)
         - [3. Handling a Query](#3-handling-a-query)
@@ -43,15 +44,21 @@ The goal of EventSourcery is to make it easier to build event sourced, CQRS appl
 
 The hope is that by using EventSourcery you can focus on modeling your domain with aggregates, commands, and events; and not worry about stitching together application plumbing.
 
-## Getting Started Guide
+## Related Repositories
 
-EventSourcery currently supports a Postgres-based event store via the [event_sourcery-postgres](https://github.com/envato/event_sourcery-postgres) gem.
+- EventSourcery's Postgres-based event store implementation: [event_sourcery-postgres](https://github.com/envato/event_sourcery-postgres).
+- Example EventSourcery application: [event_sourcery_todo_app](https://github.com/envato/event_sourcery_todo_app).
+- An opinionated CLI tool for building event sourced Ruby services with EventSourcery: [event_sourcery_generators](https://github.com/envato/event_sourcery_generators).
 
-**TODO**
+## Getting Started
+
+The [example EventSourcery application](https://github.com/envato/event_sourcery_todo_app) is intended to illustrate concepts in EventSourcery, how they relate to each other, and how to use them in practice. If you'd like a succinct look at the library in practice take a look at that.
+
+Otherwise you will generally need to add both event_sourcery and [event_sourcery-postgres](https://github.com/envato/event_sourcery-postgres) to your application.
 
 ## Configuration
 
-There are several ways to configure Event Sourcery to your liking. The following presents some examples:
+There are several ways to configure EventSourcery to your liking. The following presents some examples:
 
 ```ruby
 EventSourcery.configure do |config|
@@ -59,7 +66,7 @@ EventSourcery.configure do |config|
   # One might set up Rollbar here.
   config.on_event_processor_error = proc { |exception, processor_name| … }
 
-  # Enable Event Sourcery logging.
+  # Enable EventSourcery logging.
   config.logger = Logger.new('logs/my_event_sourcery_app.log')
 
   # Customize how event body attributes are serialized
@@ -162,7 +169,7 @@ Below is a high level view of a CQRS, event-sourced web application built using
 
 ### Events
 
-Events are value objects that record something of meaning in the domain. Think of a sequence of events as a time series of immutable domain facts.
+Events are value objects that record something of meaning in the domain. Think of a sequence of events as a time series of immutable domain facts. Together they form the source of truth for our application's state.
 
 Events are targeted at an aggregate via an `aggregate_id` and have the following attributes.
 
@@ -235,7 +242,7 @@ A typical EventSourcery application will have one or more aggregate roots with m
 
 ### Event Processing
 
-A central part of EventSourcery is the processing of events in the store. Event Sourcery provides the Event Stream Processor abstraction to support this.
+A central part of EventSourcery is the processing of events in the store. EventSourcery provides the Event Stream Processor abstraction to support this.
 
 ```
                                            ┌─────────────┐          Subscribe to the event store
@@ -255,7 +262,7 @@ store and/or triggering side      └─────────────┘
     effects in the world.
 ```
 
-A typical Event Sourcery application will have multiple projectors and reactors running as background processes.
+A typical EventSourcery application will have multiple projectors and reactors running as background processes.
 
 #### Event Stream Processors
 
@@ -279,15 +286,17 @@ A Reactor is an EventStreamProcessor that listens to events and emits events bac
 
 They typically record any external side effects they've triggered as events in the store.
 
+Reactors can be used to build [process managers or sagas](https://msdn.microsoft.com/en-us/library/jj591569.aspx).
+
 #### Running Multiple ESPs
 
 An EventSourcery application will typically have multiple ESPs running. EventSourcery provides a class called [ESPRunner](lib/event_sourcery/event_processing/esp_runner.rb) which can be used to run ESPs. It runs each ESP in a forked child process so each ESP can process the event store independently. You can find an example in [event_sourcery_todo_app](https://github.com/envato/event_sourcery_todo_app/blob/master/Rakefile).
 
 Note that you may instead choose to run each ESP in their own process directly. The coordination of this is not currently provided by EventSourcery.
 
-### Typical Flow of State in an Event Sourcery Application
+### Typical Flow of State in an EventSourcery Application
 
-Below we see the typical flow of state in an Event Sourcery application (arrows indicate data flow). Note that steps 1 and 2 are not synchronous. This means Event Sourcery applications need to embrace [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency).
+Below we see the typical flow of state in an EventSourcery application (arrows indicate data flow). Note that steps 1 and 2 are not synchronous. This means EventSourcery applications need to embrace [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency).
 
 ```
 
@@ -351,7 +360,9 @@ end
 
 #### 2. Updating a Projection
 
-Projecting is process of converting (or collecting) a stream of events into a structural representation. You can think of the process as a fold over a sequence of events. You can think of a projection as a read model that is generally persisted somewhere like a database table.
+You can think of projections as read-only models. They are created and updated by projectors and show different views over the events that are the source of truth for our application state. Projections are typically stored as database tables.
+
+Projecting is process of converting (or collecting) a stream of events into these database tables. You can think of this process as a fold over a sequence of events.
 
 A projector is a process that listens for new events in the event store. When it sees a new event it cares about it updates its projection.
 
@@ -361,14 +372,14 @@ class OutstandingTodosProjector
 
   projector_name :outstanding_todos
 
-  # Define our database table projection
+  # Database table that forms the projection.
   table :outstanding_todos do
     column :todo_id, 'UUID NOT NULL'
     column :title, :text
     column :description, :text
   end
 
-  # Handle TodoAdded events by adding the todo to our projection
+  # Handle TodoAdded events by adding the todo to our projection.
   project TodoAdded do |event|
     table.insert(
       todo_id: event.aggregate_id,
@@ -377,7 +388,7 @@ class OutstandingTodosProjector
     )
   end
 
-  # Handle TodoCompleted events by removing the todo from our projection
+  # Handle TodoCompleted events by removing the todo from our projection.
   project TodoCompleted, TodoAbandoned do |event|
     table.where(todo_id: event.aggregate_id).delete
   end
@@ -390,6 +401,7 @@ A query comes into the application and is routed to a query handler. The query h
 
 ```ruby
 module OutstandingTodos
+  # Query handler that queries the projection table.
   class QueryHandler
     def handle
       EventSourceryTodoApp.projections_database[:outstanding_todos].all

data/event_sourcery.gemspec

@@ -6,14 +6,14 @@ require 'event_sourcery/version'
 Gem::Specification.new do |spec|
   spec.name          = 'event_sourcery'
   spec.version       = EventSourcery::VERSION
-  spec.authors     = ['Steve Hodgkiss', 'Tao Guo', 'Sebastian von Conrad']
-  spec.email       = ['steve@hodgkiss.me', 'tao.guo@envato.com', 'sebastian.von.conrad@envato.com']
+  spec.authors     = ['Envato']
+  spec.email       = ['rubygems@envato.com']
 
   spec.summary       = 'Event Sourcing Library'
   spec.description   = ''
   spec.homepage      = 'https://github.com/envato/event_sourcery'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(\.|Gemfile|Rakefile|bin/|script/|spec/)}) }
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

data/lib/event_sourcery/event.rb

@@ -21,7 +21,7 @@ module EventSourcery
                    causation_id: nil)
       @id = id
       @uuid = uuid && uuid.downcase
-      @aggregate_id = aggregate_id
+      @aggregate_id = aggregate_id && aggregate_id.to_str
       @type = self.class.type || type.to_s
       @body = body ? EventSourcery::EventBodySerializer.serialize(body) : {}
       @version = version ? Integer(version) : nil
@@ -45,5 +45,23 @@ module EventSourcery
     def <=>(other)
       id <=> other.id if other.is_a? Event
     end
+
+    def with(**attributes)
+      self.class.new(**to_h.merge!(attributes))
+    end
+
+    def to_h
+      {
+        id:             id,
+        uuid:           uuid,
+        aggregate_id:   aggregate_id,
+        type:           type,
+        body:           body,
+        version:        version,
+        created_at:     created_at,
+        correlation_id: correlation_id,
+        causation_id:   causation_id,
+      }
+    end
   end
 end

data/lib/event_sourcery/rspec/event_store_shared_examples.rb

@@ -188,7 +188,7 @@ RSpec.shared_examples 'an event store' do
     RSpec.shared_examples 'gets events for a specific aggregate id' do
       before do
         event_store.sink(new_event(aggregate_id: aggregate_id, type: 'item_added', body: { 'my' => 'body' }))
-        event_store.sink(new_event(aggregate_id: aggregate_id))
+        event_store.sink(new_event(aggregate_id: double(to_str: aggregate_id)))
         event_store.sink(new_event(aggregate_id: SecureRandom.uuid))
       end
 

data/lib/event_sourcery/version.rb

@@ -1,3 +1,3 @@
 module EventSourcery
-  VERSION = '0.13.0'.freeze
+  VERSION = '0.14.0'.freeze
 end

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_sourcery
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
-- Steve Hodgkiss
-- Tao Guo
-- Sebastian von Conrad
+- Envato
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-16 00:00:00.000000000 Z
+date: 2017-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,24 +82,15 @@ dependencies:
         version: '0'
 description: ''
 email:
-- steve@hodgkiss.me
-- tao.guo@envato.com
-- sebastian.von.conrad@envato.com
+- rubygems@envato.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
 - event_sourcery.gemspec
 - lib/event_sourcery.rb
 - lib/event_sourcery/aggregate_root.rb

data/.gitignore

@@ -1,37 +0,0 @@
-# Created by .ignore support plugin (hsz.mobi)
-### Ruby template
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-
-# Used by dotenv library to load environment variables.
-# .env
-
-## Documentation cache and generated files:
-/.yardoc/
-/_yardoc/
-/doc/
-/rdoc/
-
-## Environment normalization:
-/.bundle/
-/vendor/bundle
-/lib/bundler/man/
-
-# for a library or gem, you might want to ignore these files since the code is
-# intended to run in multiple environments; otherwise, check them in:
-Gemfile.lock
-.ruby-version
-.ruby-gemset
-
-# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
-.rvmrc
-

data/.rspec

@@ -1,3 +0,0 @@
---require spec_helper
---format documentation
---color

data/.travis.yml

@@ -1,8 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.2
-  - 2.3
-  - 2.4
-before_install:
-  - gem install bundler

data/Gemfile

@@ -1,5 +0,0 @@
-source 'https://rubygems.org'
-
-ruby '>= 2.2.0'
-
-gemspec

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/bin/console

@@ -1,6 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "event_sourcery"
-require "pry"
-Pry.start

data/bin/setup

@@ -1,15 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-IFS=$'\n\t'
-
-echo
-echo "--- Bundling"
-echo
-
-bundle install
-
-echo
-echo "--- Preparing databases"
-echo
-
-createdb event_sourcery_test