event_source 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f482b09497aecd4c9d777e9044129236d63492e4
+  data.tar.gz: cd32bd6e04351a71e77aaf1c22e51e14f437dca1
+SHA512:
+  metadata.gz: bef50c5d9b5fa8e3691da030a59cc002f1c3ea62794a5510b5c8318252d7704c6a07893077902073b02312f6ace48e2078b351dab3e009ed447847da72be7625
+  data.tar.gz: 09fb34fd611b0a9146e913f3a512cac0afb31334d744bb31024db007889debc1c72382c8f53e5729c957006428ac76751b19d2fadfbcb25bb65221b90c7d7c0e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# changes
+
+## version 0.1.0
+
+nothing yet!

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Louis P. Salin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# Event Sourcing
+
+This library is an implementation of the Event Sourcing pattern, where instead of persisting the state of your objects in a data store, it is the sequence of events that led to the objects' state that is stored. In order to rebuild objects, the events must be replayed on each object.
+
+## The event repository
+
+An event store must be initialized. Currently, only the in_memory SQLlite3 type is available.
+
+```ruby
+EventSource::EventRepository.create(in_memory: true)
+```
+
+## Your entities
+
+An entity is an object that you intend to persist. You must extend and include some class methods and instance methods. Let's create an entity called BankAccount.
+
+```ruby
+class BankAccount
+  extend EventSource::Entity::ClassMethods
+  include EventSource::Entity
+
+end
+```
+
+For each of the entity's members that you want to persist, you must create an accessor. Then you must create events for your entity. For example, 'deposit' could be an event on the bank account entity and balance would be something we want to persist.
+
+```ruby
+class BankAccount
+  extend EventSource::Entity::ClassMethods
+  include EventSource::Entity
+
+  attr_accessor :balance
+
+  on_event :deposit do |e, amount|
+  end
+end
+```
+
+Your event handler will receive at least one parameter, which is the instance of the entity being modified. It is used to set the state of your entity by calling the method 'set' on it. All the other parameters will be arguments that must be giving when calling the event. In this case, when calling the deposit event, the caller will have to supply the amount. 
+
+Here's what could go into event handler:
+
+```ruby
+  on_event :deposit do |e, amount|
+    e.set(:balance) {@balance + amount}
+  end
+```
+
+The 'set' method does more than simply set the @balance attribute. It also saves the state of your entity into the event so that when the event eventually gets replayed to rebuild this entity, it will know how to set the balance of the account.
+
+To call the event, simply call the 'deposit' method that was created for you:
+
+```ruby
+account = BankAccount.create
+account.deposit(100)
+```
+
+Note that calling the event outside the context of a Entity Repository transaction won't persist the event. (see below)
+
+### unique identifiers
+
+Each entity gets a unique identifier when created the first time. This id is important. You will need it to recreate the entity. You can access it with the 'uid' attribute.
+
+```ruby
+account.uid
+```
+
+## Creating entities
+
+Call the 'create' class method to create a new instance of your entity.
+
+```ruby
+account = BankAccount.create
+```
+
+## The Entity Repository
+
+This repository is used to store and load entities. It is also used to monitor changes to entities. When a transaction is created, all changes to all entities and all events created will be saved in the event repository.
+
+### Transactions
+
+```ruby
+EventSource::EntityRepository.transaction do
+    account.deposit(100)
+end
+```
+
+The code above will store one event in the event store: a deposit event that adds 100 to the balance of the account.
+
+### Loading an entity
+
+To load an entity, you must create an entity repository and pass it an instance of your event repository, then call 'find'. I know, this isn't the simplest thing yet. It'll improve.
+
+The 'find' method expects an entity type and the entity's unique identifier. The type, by convention, is simply a lowercase undescored string of the entity class name.
+
+```ruby
+event_repo = EventSource::EventRepository.current
+entity_repo = EventSource::EntityRepository.new(event_repo)
+entity = entity_repo.find(:bank_account, uid)
+```
+

data/lib/event_source/entity.rb

@@ -0,0 +1,71 @@
+module EventSource
+    module Entity
+        module ClassMethods
+            def create(uid = EventSource::UIDGenerator.generate_id)
+                entity = self.new
+                entity.send(:uid=, uid)
+
+                yield entity if block_given?
+                entity
+            end
+
+            def rebuild(events)
+                return self.create() if events.length == 0
+
+                entity = self.new
+
+                events.each do |e|
+                    data = JSON.parse(e.data)
+                    data.keys.each do |attr|
+                        entity.send("#{attr}=", data[attr])
+                    end
+                end
+
+                entity
+            end
+
+            def on_event(name, &block)
+                self.send(:define_method, name) do |*args|
+                    returnValue = block.call(args.unshift(self))
+                    entity_events << EventSource::Event.create(name, self)
+
+                    # if repo is nil, that's because this isn't being executed in the context of a
+                    # transaction and the result won't be saved
+                    repo = EventSource::EntityRepository.current
+                    repo.entities << self if repo
+
+                    returnValue
+                end
+            end
+        end
+
+        attr_reader :uid,
+                    :entity_changes
+
+        def set(attr_name, &block)
+            val = block.call
+            @entity_changes[attr_name.to_sym] = val
+            self.send("#{attr_name}=", val)
+        end
+
+        def entity_events
+            @events ||= Array.new
+            @events
+        end
+
+        def save
+            entity_events.each {|e| e.save}
+        end
+
+        private
+
+        def initialize
+            @entity_changes = Hash.new
+        end
+
+        def uid=(new_uid)
+            @uid = new_uid
+        end
+    end
+end
+

data/lib/event_source/entity_repository.rb

@@ -0,0 +1,57 @@
+# the repository should be thread safe. This is accomplished by forcing
+# every transaction done (anything from newing up the repo to commiting it) to 
+# create their own repo. That way, changes aren't shared.
+
+require 'set'
+require 'active_support/inflector'
+
+module EventSource
+    class EntityRepository
+        attr_reader :entities
+
+        class << self
+            @@current = nil
+
+            def transaction
+                @@current = self.new
+                yield
+                @@current.commit
+                @@current = nil
+            end
+
+            def current
+                @@current
+            end
+        end
+
+        def initialize(event_repo = nil)
+            @entities = Set.new
+            @event_repo = event_repo
+        end
+
+        def add(entity)
+            @entities << entity
+        end
+
+        def commit
+            # TODO: gather all events of all entities, maintain order and save in batch
+            @entities.each {|e| e.save}
+        end
+
+        def find(type, uid)
+            entity = @entities.select {|e| e.uid == uid}[0]
+            return entity if entity
+
+            events = @event_repo.get_events(type, uid)
+
+            entity_class = type.to_s.camelize.constantize
+            if events.count > 0
+                entity = entity_class.rebuild(events)
+            else
+                entity = entity_class.create(uid)
+            end
+
+            entity
+        end
+    end
+end

data/lib/event_source/event.rb

@@ -0,0 +1,49 @@
+require 'active_support/inflector'
+require 'json'
+
+module EventSource
+    class Event
+        attr_reader :name, :entity_type, :entity_id, :data, :created_at
+
+        class << self
+            def build_from_data(data)
+                event = self.new
+                event.send(:new_from_data, data)
+                event
+            end
+
+            def create(name, entity)
+                event = self.new
+                event.send(:new_from_entity, name, entity)
+                event
+            end
+        end
+
+        def save
+            raise CannotSaveRebuiltEvent if @is_rebuilt
+            EventSource::EventRepository.current.save(self)
+        end
+
+        private
+
+        def new_from_entity(name, entity)
+            @name = name.to_s
+            @entity_id = entity.uid
+            @data = entity.entity_changes.to_json
+            @created_at = Time.now
+            @entity_type = entity.class.to_s.underscore
+
+            @is_rebuilt = false
+        end
+
+        def new_from_data(data)
+            @name = data[:name]
+            @entity_id = data[:entity_id]
+            @data = data[:data]
+            @created_at = data[:created_at]
+            @entity_type = data[:entity_type]
+
+            @is_rebuilt = true
+        end
+    end
+end

data/lib/event_source/event_repository.rb

@@ -0,0 +1,57 @@
+require 'sequel'
+
+module EventSource
+    class EventRepository
+        attr_reader :db
+
+        class << self
+            def current
+                @@instance ||= self.new(in_memory: true)
+            end
+
+            def create(options)
+                @@instance = self.new(options)
+            end
+        end
+
+        def save(event)
+            count = @db[:events].exclude_where(entity_type: event.entity_type).
+                                 where(entity_id: event.entity_id).count
+
+            raise InvalidEntityID if count > 0
+            @db[:events].insert(name: event.name, entity_type: event.entity_type,
+                                entity_id: event.entity_id, data: event.data,
+                                created_at: event.created_at)
+        end
+
+        def get_events(type, uid)
+            data = @db[:events].where(entity_type: type.to_s, entity_id: uid).order(:created_at)
+            data.map {|d| create_event(d)}
+        end
+
+        private
+
+        def initialize(options)
+            if options[:in_memory] 
+                @db = Sequel.sqlite
+                init_in_memory_schema
+            end
+        end
+
+        def init_in_memory_schema
+            @db.create_table :events do
+                primary_key :id
+                String :name
+                String :entity_id
+                String :entity_type
+                Time :created_at
+                String :data
+            end
+        end
+
+        def create_event(data)
+            EventSource::Event.build_from_data(data)
+        end
+    end
+end
+

data/lib/event_source/exceptions.rb

@@ -0,0 +1,2 @@
+class InvalidEntityID < Exception; end
+class CannotSaveRebuiltEvent < Exception; end

data/lib/event_source/uid_generator.rb

@@ -0,0 +1,9 @@
+require 'uuidtools'
+
+module EventSource
+    class UIDGenerator
+        def self.generate_id
+            UUIDTools::UUID.timestamp_create.to_s
+        end
+    end
+end

data/lib/event_source/version.rb

@@ -0,0 +1,3 @@
+module EventSource
+    Version = '0.1.0'
+end

data/lib/event_source.rb

@@ -0,0 +1,9 @@
+require './lib/event_source/exceptions'
+require './lib/event_source/uid_generator'
+require './lib/event_source/event'
+require './lib/event_source/entity'
+require './lib/event_source/entity_repository'
+require './lib/event_source/event_repository'
+
+module EventSource
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: event_source
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Louis Salin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: uuidtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Event sourcing allows you to persist changes to your domain instead of
+  the state of your domain
+email:
+- louis.phil@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/event_source.rb
+- lib/event_source/uid_generator.rb
+- lib/event_source/event.rb
+- lib/event_source/entity.rb
+- lib/event_source/event_repository.rb
+- lib/event_source/entity_repository.rb
+- lib/event_source/version.rb
+- lib/event_source/exceptions.rb
+- LICENSE
+- README.md
+- CHANGELOG.md
+homepage: http://github.com/louissalin/event_source
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0.rc.2
+signing_key: 
+specification_version: 4
+summary: Event sourcing framework
+test_files: []