frp-eventsourcing 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b89e010d2caf9f64fc4a66718e79111e0e0d3a30
+  data.tar.gz: cf6ce8fbc999d409ae9a454cf06c9e843f24fc8d
+SHA512:
+  metadata.gz: 8d097c4b0c2813a039ed35815c3ee3d837eb15b7722120617393131e7b5c0ea035473d0e25fdab5034d013aa8ff644f9f6f91b440519b96463b907ff8230ad66
+  data.tar.gz: 7e78cc3362d3b8d8b2003cf8553bf362455ebf85b3b3a01c7b40707fdddded9011b59f54ca3092afd6e05333b1b79960c5ba1ab007623d4a7e226e8282eebaa2

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Mac files
+.DS_Store

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.15.1

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in frp-eventsourcing.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2017 Žilvinas Kučinskas
+
+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,187 @@
+[![Build Status](https://travis-ci.org/ZilvinasKucinskas/FRP-EventSourcing.svg?branch=master)](https://travis-ci.org/ZilvinasKucinskas/FRP-EventSourcing)
+
+Will be released soon (2017 June) after testing out in sample application.
+
+# Frp-Eventsourcing
+
+EventSourcing describes current state as series of events that occurred in a system. Events hold all information that is needed to recreate current state. This method allows to achieve high volume of transactions, and enables efficient replication. Whereas reactive programming lets implement reactive systems in declarative style, decomposing logic into smaller, easier to understand components. The goal is to create reactive programming program interface, incorporating both principles. Applying reactive programming in event-sourcing systems enables modelling not only instantaneous events, but also have their history. Furthermore, it enables focus on the solvable problem, regardless of low level realization details. Reactive operators enable read model creation without exposing realization details of operations with data storage.
+
+## Sources to learn more about
+
+### (Functional) Reactive programming
+
+* [The introduction to Reactive Programming you've been missing](https://gist.github.com/staltz/868e7e9bc2a7b8c1f754)
+(by [@andrestaltz](https://twitter.com/andrestaltz))
+* [Lambda Jam 2015 - Conal Elliott - The Essence and Origins of Functional Reactive Programming](https://youtu.be/j3Q32brCUAI)
+* More [here](https://github.com/ZilvinasKucinskas/FRP-EventSourcing/tree/master/sources)
+
+### EventSourcing
+
+* [Martin Fowler - EventSourcing](http://martinfowler.com/eaaDev/EventSourcing.html)
+* [Greg Young - CQRS documents](https://github.com/ZilvinasKucinskas/FRP-EventSourcing/blob/master/sources/cqrs_documents.pdf)
+* GetEventStore - The open-source, functional database with Complex Event Processing in JavaScript. [Event Sourcing Basics](http://docs.geteventstore.com/introduction/3.9.0/event-sourcing-basics/)
+* [Martin Fowler - Retroactive Event](https://martinfowler.com/eaaDev/RetroactiveEvent.html)
+* [Akka Persistence module uses EventSourcing](http://doc.akka.io/docs/akka/snapshot/scala/persistence.html#event-sourcing)
+* More [here](https://github.com/ZilvinasKucinskas/FRP-EventSourcing/tree/master/sources)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'frp-eventsourcing'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install frp-eventsourcing
+
+## Usage
+
+### Generate EventStore event model
+
+Use provided task to generate a table to store events in your database.
+
+```
+rails generate frp_eventsourcing:migration
+rake db:migrate
+```
+
+### Event definitions
+
+```
+# Define events
+AccountCreated = Class.new(FrpEventsourcing::Event)
+MoneyDeposited = Class.new(FrpEventsourcing::Event)
+MoneyWithdrawn = Class.new(FrpEventsourcing::Event)
+```
+
+Alternative definition:
+
+```
+class AccountCreated < FrpEventsourcing::Event; end
+class MoneyDeposited < FrpEventsourcing::Event; end
+class MoneyWithdrawn < FrpEventsourcing::Event; end
+```
+
+### Create stream
+
+We can define stream that is creating read model once in our app. Keep in mind that no database operations are present here.
+
+```
+account_stream = FrpEventsourcing::Stream.new(AccountCreated, MoneyDeposited, MoneyWithdrawn).
+  as_persistent_type(Account, %i(account_id)).
+  init(-> (state) { state.balance = 0 }).
+  when(MoneyDeposited, -> (state, event) { state.balance += event[:data][:amount] }).
+  when(MoneyWithdrawn, -> (state, event) { state.balance -= event[:data][:amount] })
+```
+
+Instead of passing `lambda` directly, we can also use a variable to save and reuse `lambda`:
+
+```
+account_initial_state_change_function = -> (state) { state.balance = 0 }
+```
+
+or even use a class that implements `call` method. We can structure our code with some kind of denormalizer for example:
+
+```
+class Denormalizers::ReadModelType::InitialState::Account
+  def call(state)
+    state.balance = 0
+  end
+end
+```
+
+### Publish events
+
+We can create an account:
+
+```
+stream_name = "account"
+event = AccountCreated.new(data: {
+          account_id: 'LT121000011101001000'
+        })
+FrpEventsourcing::EventRepository.new.create(event, stream_name)
+```
+
+Transfer some money (100$ for example) to the account:
+
+```
+stream_name = "account"
+event = MoneyDeposited.new(data: {
+          account_id: 'LT121000011101001000',
+          amount: 100
+        })
+FrpEventsourcing::EventRepository.new.create(event, stream_name)
+```
+
+Withdraw some money (25$ for example) from the account:
+
+```
+stream_name = "account"
+event = MoneyWithdrawn.new(data: {
+          account_id: 'LT121000011101001000',
+          amount: 25
+        })
+FrpEventsourcing::EventRepository.new.create(event, stream_name)
+```
+
+Now we can query read model like:
+
+```
+account = Account.find_by(account_id: 'LT121000011101001000')
+puts account.balance # prints 75
+```
+
+## Available reactive operators
+
+* `merge(another_stream)` - merge one stream to another.
+* `filter(predicate_function)` - if predicate function returns false, event won't get propogated through the chain any more.
+* `map(transform_function)` - applies transformation function and propogates event through the chain.
+* `init(initial_state_change_function)` - applies initial state change function for the first event.
+* `when(event_type, state_change_function)` - if event matches event type, record is being created or loaded, state change function is being applied for the record and transition state saved to database.
+* `each(state_change_function)` - same as `when` operator, just does not check event type and applies state change function for each event.
+
+## Implementation
+
+Reactive operators were implemented using Observer design pattern, object oriented programming principles and introspection.
+
+Transition state is being solved by applying metaprogramming (introspection, reflection) and using method chaining.
+
+## 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](https://rubygems.org).
+
+## Possible improvements
+
+Easy-medium difficulty:
+
+* Make demo application with UI. Controller should publish events. Event types and streams should be defined in some kind of initializer file for example.
+* Improve error handling - could be bugs, because it's just prototype version.
+* Refactor event publishing mechanics. We can borrow optimistic locking from [RailsEventStore](https://github.com/arkency/rails_event_store)
+* More tests
+
+Challenging:
+
+* Make mechanics for recreating read models after changes. We should reapply all associated events.
+* Use custom events repository + instructions how to change adapter for `FrpEventsourcing::EventRepository`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ZilvinasKucinskas/FRP-EventSourcing.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "frp-eventsourcing"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/frp-eventsourcing.gemspec

@@ -0,0 +1,43 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'frp-eventsourcing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'frp-eventsourcing'
+  spec.version       = FrpEventsourcing::VERSION
+  spec.authors       = ['Zilvinas']
+  spec.email         = ['zil.kucinskas@gmail.com']
+
+  spec.summary       = 'A library to do Functional Reactive Programming with EventSourcing in Ruby'
+  spec.description   = 'Functional Reactive Programming with EventSourcing in Ruby'
+  spec.homepage      = 'https://github.com/ZilvinasKucinskas/FRP-EventSourcing'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+      'public gem pushes.'
+  end
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'activerecord', '>= 4.0.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rails', '~> 4.2'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'activerecord', '~> 4.0'
+  spec.add_development_dependency 'sqlite3', '~> 1.3'
+  spec.add_development_dependency 'database_cleaner', '~> 1.6'
+end

data/lib/frp-eventsourcing.rb

@@ -0,0 +1,12 @@
+require 'frp-eventsourcing/version'
+require 'frp-eventsourcing/generators/migration_generator'
+require 'frp-eventsourcing/event'
+require 'frp-eventsourcing/event_repository'
+require 'frp-eventsourcing/stream'
+
+class EventStoreEvent < ::ActiveRecord::Base
+  self.primary_key = :id
+
+  serialize :metadata
+  serialize :data
+end

data/lib/frp-eventsourcing/event.rb

@@ -0,0 +1,37 @@
+require 'securerandom'
+require 'observer'
+
+module FrpEventsourcing
+  class Event
+    extend Observable
+
+    def initialize(event_id: SecureRandom.uuid, metadata: nil, data: nil)
+      @event_id = event_id.to_s
+      @metadata = metadata.to_h
+      @data     = data.to_h
+    end
+    attr_reader :event_id, :metadata, :data
+
+    def to_h
+      {
+          event_id:   event_id,
+          event_type: self.class,
+          metadata:   metadata,
+          data:       data
+      }
+    end
+
+    def ==(other_event)
+      other_event.instance_of?(self.class) &&
+        other_event.event_id.eql?(event_id) &&
+        other_event.data.eql?(data)
+    end
+
+    alias_method :eql?, :==
+
+    def emit
+      self.class.changed
+      self.class.notify_observers(self.to_h)
+    end
+  end
+end

data/lib/frp-eventsourcing/event_repository.rb

@@ -0,0 +1,95 @@
+module FrpEventsourcing
+  class EventRepository
+    def initialize(adapter: ::EventStoreEvent)
+      @adapter = adapter
+    end
+    attr_reader :adapter
+
+    def create(event, stream_name)
+      data = event.to_h.merge!(stream: stream_name)
+      adapter.create(data)
+
+      event.emit if event.respond_to?(:emit)
+
+      event
+    end
+
+    def delete_stream(stream_name)
+      condition = {stream: stream_name}
+      adapter.destroy_all condition
+    end
+
+    def has_event?(event_id)
+      adapter.exists?(event_id: event_id)
+    end
+
+    def last_stream_event(stream_name)
+      build_event_entity(adapter.where(stream: stream_name).last)
+    end
+
+    def read_events_forward(stream_name, start_event_id, count)
+      stream = adapter.where(stream: stream_name)
+      unless start_event_id.equal?(:head)
+        starting_event = adapter.find_by(event_id: start_event_id)
+        stream = stream.where('id > ?', starting_event)
+      end
+
+      stream.limit(count)
+        .map(&method(:build_event_entity))
+    end
+
+    def read_events_backward(stream_name, start_event_id, count)
+      stream = adapter.where(stream: stream_name)
+      unless start_event_id.equal?(:head)
+        starting_event = adapter.find_by(event_id: start_event_id)
+        stream = stream.where('id < ?', starting_event)
+      end
+
+      stream.order('id DESC').limit(count)
+        .map(&method(:build_event_entity))
+    end
+
+    def read_stream_events_forward(stream_name)
+      adapter.where(stream: stream_name)
+        .map(&method(:build_event_entity))
+    end
+
+    def read_stream_events_backward(stream_name)
+      adapter.where(stream: stream_name).order('id DESC')
+        .map(&method(:build_event_entity))
+    end
+
+    def read_all_streams_forward(start_event_id, count)
+      stream = adapter
+      unless start_event_id.equal?(:head)
+        starting_event = adapter.find_by(event_id: start_event_id)
+        stream = stream.where('id > ?', starting_event)
+      end
+
+      stream.limit(count)
+        .map(&method(:build_event_entity))
+    end
+
+    def read_all_streams_backward(start_event_id, count)
+      stream = adapter
+      unless start_event_id.equal?(:head)
+        starting_event = adapter.find_by(event_id: start_event_id)
+        stream = stream.where('id < ?', starting_event)
+      end
+
+      stream.order('id DESC').limit(count)
+        .map(&method(:build_event_entity))
+    end
+
+    private
+
+    def build_event_entity(record)
+      return nil unless record
+      record.event_type.constantize.new(
+        event_id: record.event_id,
+        metadata: record.metadata,
+        data: record.data
+      )
+    end
+  end
+end