aggregates 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00b1d88fe05dec5dcc22db0e1349c2dd91645b4e33755f8fbf9e3d3ea9085fab
+  data.tar.gz: ad8bd4c5cd4c1e781776ea4890f59e59d952a6cc30e4509c41e92da649b691ba
+SHA512:
+  metadata.gz: dbd3330da62e2783c4911116e266511ff5decc8f629eefbc7e671a8128fb7082f62aff6a1edac6018243ed6d1856a823dd84e3cef879edb741376f9a273ddaf8
+  data.tar.gz: c5ff7486bda8e1412cc6624db657c7deeb8f94f5d823cbdc799e9bf42c862bbc0735fa3ba589fc10c64a30275f8aa514f33ab33ff4f345807a2da244dc5438d5

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright 2021 [Resilient Vitality](https://www.resilientvitality.com).
+
+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,322 @@
+<p align="center">
+  <img src="aggregates.png" alt="Aggregates Icon"/>
+</p>
+
+# Aggregates
+
+A ruby gem for writing CQRS applications with pluggable components.
+
+_Warning:_ This Gem is in active development and probably doesn't work correctly. Tests are really light.
+
+[![Gem Version](https://badge.fury.io/rb/aggregates.svg)](http://badge.fury.io/rb/aggregates)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-community-brightgreen.svg)](https://rubystyle.guide)
+
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+  - [Features](#features)
+  - [Requirements](#requirements)
+  - [Setup](#setup)
+  - [Usage](#usage)
+    - [Defining AggregateRoots](#defining-aggregateroots)
+    - [Creating Commands](#creating-commands)
+    - [Creating Events](#creating-events)
+    - [Processing Commands](#processing-commands)
+    - [Filtering Commands](#filtering-commands)
+    - [Processing Events](#processing-events)
+    - [Executing Commands](#executing-commands)
+    - [Auditing Aggregates](#auditing-aggregates)
+    - [Configuring](#configuring)
+      - [Storage Backends](#storage-backends)
+        - [Dynamoid](#dynamoid)
+      - [Adding Command Processors](#adding-command-processors)
+      - [Adding Event Processors](#adding-event-processors)
+      - [Adding Command Filters](#adding-command-filters)
+  - [Development](#development)
+  - [Tests](#tests)
+  - [Versioning](#versioning)
+  - [Code of Conduct](#code-of-conduct)
+  - [Contributions](#contributions)
+  - [License](#license)
+  - [History](#history)
+  - [Credits](#credits)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
+## Features
+
+- Pluggable Event / Command Storage Backends
+- Tools for Command Validation, Filtering, and Execution.
+- Opinioned structure for CQRS, Domain-Driven Design, and Event Sourcing.
+
+## Requirements
+
+1. [Ruby 3.0+](https://www.ruby-lang.org)
+
+## Setup
+
+To install, run:
+
+    gem install aggregates
+
+Or Add the following to your Gemfile:
+
+    gem "aggregates"
+
+## Usage
+
+### Defining AggregateRoots
+
+An AggregateRoot is a grouping of domain object(s) that work to encapsulate
+a single part of your Domain or Business Logic. The general design of aggregate roots should be as follows:
+
+- Create functions that encapsulate different operations on your Aggregate Roots. These functions should enforce buisiness logic constraints and then capture state changes by creating events.
+- Create event handlers that actually perform the state changes captured by those events.
+
+A simple example is below:
+
+```ruby
+class Post < Aggregates::AggregateRoot
+  # Write functions that encapsulate business logic.
+  def publish(command)
+    apply EventPublished, body: command.body, category: command.category
+  end
+
+  # Modify the state of the aggregate from the emitted events.
+  on EventPublished do |event|
+    @body = event.body
+    @category = event.category
+  end
+end
+```
+
+_Note:_ the message-handling DSL (`on`) supports passing a super class of any given event
+as well. Every `on` block that applies to the event will be called in order from most specific to least specific.
+
+### Creating Commands
+
+Commands are a type of domain message that define the shape and contract of data needed to perform an action. Essentially, they provide the api for interacting with your domain. Commands should have descriptive names capturing the change they are intended to make. For instance, `ChangeUserEmail` or `AddComment`.
+
+```ruby
+class PublishPost < Aggregates::Command
+  attribute :body, Types::String
+  attribute :category, Types::String
+
+  # Input Validation Handled via dry-validation.
+  # Reference: https://dry-rb.org/gems/dry-validation/1.6/
+  class Contract < Contract
+    rule(:body) do
+      key.failure('Post not long enough') unless value.length > 10
+    end
+  end
+end
+```
+
+### Creating Events
+
+An Event describes something that happened. They are named in passed tense.
+For instance, if the user's email has changed, then you might create an event type called
+`UserEmailChanged`.
+
+```ruby
+class PublishPost < Aggregates::Command
+  attribute :body, Types::String
+  attribute :category, Types::String
+end
+```
+
+### Processing Commands
+
+The goal of a `CommandProcessor` is to route commands that have passed validation and
+filtering. They should invoke business logic on their respective aggregates. Doing so is accomplished by using the same message-handling DSL as in our `AggregateRoots`, this time for commands.
+
+A helper function, `with_aggregate`, is provided to help retrieve the appropriate aggregate
+for a given command.
+
+```ruby
+class PostCommandProcessor < Aggregates::CommandProcessor
+  on PublishPost do |command|
+    with_aggregate(Post, command) do |post|
+      post.publsh(command)
+    end
+  end
+end
+```
+
+_Note:_ the message-handling DSL (`on`) supports passing a super class of any given event
+as well. Every `on` block that applies to the event will be called in order from most specific to least specific.
+
+### Filtering Commands
+
+There are times where commands should not be executed by the domain logic. You can opt to include a condition in your command processor or aggregate. However, that is not always extensible if you have repeated logic between many commands. Additionally, it violates the single responsiblity principal.
+
+Instead, it is best to support this kind of filtering logic using `CommandFilters`. A `CommandFilter` uses the same Message Handling message-handling DSL as the rest of the `Aggregates` gem. This time, it needs to return a true/false back to the gem to determine whether or not (true/false) the command should be allowed. Many command filters can provide many blocks of the `on` DSL. If any one of the filters rejects the command then the command will not be procesed.
+
+```ruby
+class UpdatePostCommand < Aggregates::Command
+  attribute :commanding_user_id, Types::String
+end
+
+class UpdatePostBody < UpdatePostCommand
+  attribute :body, Types::String
+end
+
+class PostCommandFilter < Aggregates::CommandFilter
+  on UpdatePostCommand do |command|
+    with_aggregate(Post, command) do |post|
+      post.owner_id == command.commanding_user_id
+    end
+  end
+end
+```
+
+In this example, we are using a super class of `UpdatePostBody`.
+As with all MessageProcessors, calling `on` with a super class
+will be called when any child class is being processed. In other words,
+`on UpdatePostCommand` will be called when you call `Aggregates.execute_command`
+with an instance of `UpdatePostBody`.
+
+### Processing Events
+
+Event processors are responsible for responding to events and effecting changes on things
+that are not the aggregates themselves. Here is where the read side of your CQRS model can take
+place. Since `Aggregates` does not enforce a storage solution for any component of the application, you will likely want to provide a helper mechanism for updating projections of aggregates into your read model.
+
+Additionally, the `EventProcessor` type can be used to perform other side effects in other systems. Examples could include sending an email to welcome a user, publish the event to a webhook for a subscribing micro service, or much more.
+
+```ruby
+class RssUpdateProcessor < Aggregates::EventProcessor
+  def update_feed_for_new_post(event)
+    # ...
+  end
+
+  on EventPublished do |event|
+    update_feed_for_new_post(event)
+  end
+end
+```
+
+_Note:_ the message-handling DSL (`on`) supports passing a super class of any given event
+as well. Every `on` block that applies to the event will be called in order from most specific to least specific.
+
+### Executing Commands
+
+```ruby
+aggregate_id = Aggregates.new_aggregate_id
+command = CreateThing.new(foo: 1, bar: false, aggregate_id: aggregate_id)
+Aggregates.execute_command command
+
+increment = IncrementFooThing.new(aggregate_id: aggregate_id)
+toggle = ToggleBarThing.new(aggregate_id: aggregate_id)
+Aggregates.execute_commands increment, toggle
+```
+
+### Auditing Aggregates
+
+```ruby
+aggregate_id = Aggregates.new_aggregate_id
+# ... Commands and stuff happened.
+auditor = Aggregates.audit MyAggregateType aggregate_id
+
+# Each of these returns a list to investigate using.
+events = auditor.events # Or events_processed_by(time) or events_processed_after(time)
+commands = auditor.commands # Or commands_processed_by(time) or commands_processed_after(time)
+
+# Or....
+# View the state of an aggregate at a certain pont in time.
+aggregate_at_time = auditor.inspect_state_at(Time.now - 1.hour)
+```
+
+### Configuring
+
+#### Storage Backends
+
+Storage Backends at the method by which events and commands are stored in
+the system.
+
+```ruby
+Aggregates.configure do |config|
+  config.store_with MyAwesomeStorageBackend.new
+end
+```
+
+##### Dynamoid
+
+If `Aggregates` can `require 'dynamoid'` then it will provide the `Aggregates::Dynamoid::DynamoidStorageBackend` that
+stores using the [Dynmoid Gem](https://github.com/Dynamoid/dynamoid) for AWS DynamoDB.
+
+#### Adding Command Processors
+
+```ruby
+Aggregates.configure do |config|
+  # May call this method many times with different processors.
+  config.process_commands_with PostCommandProcessor.new
+end
+```
+
+#### Adding Event Processors
+
+```ruby
+Aggregates.configure do |config|
+  # May call this method many times with different processors.
+  config.process_events_with RssUpdateProcessor.new
+end
+```
+
+#### Adding Command Filters
+
+```ruby
+Aggregates.configure do |config|
+  config.filter_commands_with MyCommandFilter.new
+end
+```
+
+## Development
+
+To contribute, run:
+
+    git clone https://github.com/resilient-vitality/aggregates.git
+    cd aggregates
+    bin/setup
+
+You can also use the IRB console for direct access to all objects:
+
+    bin/console
+
+## Tests
+
+To test, run:
+
+    bundle exec rake
+
+## Versioning
+
+Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:
+
+- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
+- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
+- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
+
+## Code of Conduct
+
+Please note that this project is released with a [CODE OF CONDUCT](CODE_OF_CONDUCT.md). By
+participating in this project you agree to abide by its terms.
+
+## Contributions
+
+Read [CONTRIBUTING](CONTRIBUTING.md) for details.
+
+## License
+
+Copyright 2021 [Resilient Vitality](www.resilientvitality.com).
+Read [LICENSE](LICENSE.md) for details.
+
+## History
+
+Read [CHANGES](CHANGES.md) for details.
+Built with [Gemsmith](https://www.alchemists.io/projects/gemsmith).
+
+## Credits
+
+Developed by [Zach Probst](mailto:zprobst@resilientvitality.com) at [Resilient Vitality](www.resilientvitality.com).

data/lib/aggregates.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# A helpful library for building CQRS and Event Sourced Applications.
+module Aggregates
+  def self.configure
+    yield Configuration.instance
+  end
+
+  def self.new_aggregate_id
+    SecureRandom.uuid.to_s
+  end
+
+  def self.new_message_id
+    SecureRandom.uuid.to_s
+  end
+
+  def self.execute_command(command)
+    CommandDispatcher.instance.execute_command command
+  end
+
+  def self.execute_commands(*commands)
+    CommandDispatcher.instance.execute_commands(*commands)
+  end
+
+  def self.audit(type, aggregate_id)
+    Auditor.new type, aggregate_id
+  end
+end

data/lib/aggregates/aggregate_root.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # An AggregateRoot is a central grouping of domain object(s) that work to encapsulate
+  # parts of our Domain or Business Logic.
+  #
+  # The general design of aggregate roots should be as follows:
+  #   - Create functions that encapsulate different changes in your Aggregate Roots. These functions should enforce
+  #   constraints on the application. Then capture state changes by creating events.
+  #
+  #   - Create event handlers that actually performed the state changes captured by the events
+  #     made by processing commands using the above functions.
+  class AggregateRoot < EventProcessor
+    attr_reader :id
+
+    # Returns a new instance of an aggregate by loading and reprocessing all events for that aggregate.
+    def self.get_by_id(id)
+      instance = new id
+      instance.replay_history
+      instance
+    end
+
+    # Creates a new instance of an aggregate root. This should not be called directly. Instead, it should
+    # be called by calling AggregateRoot.get_by_id.
+    # :reek:BooleanParameter
+    def initialize(id, mutable: true)
+      super()
+
+      @id = id
+      @mutable = mutable
+      @sequence_number = 1
+      @event_stream = EventStream.new id
+    end
+
+    def process_event(event)
+      super
+      @sequence_number += 1
+    end
+
+    # Takes an event type and some parameters with which to create it. Then performs the following actions
+    #   1.) Builds the final event object.
+    #   2.) Processes the event locally on the aggregate.
+    #   3.) Produces the event on the event stream so that is saved by the storage backend and processed
+    #       by the configured processors of the given type.
+    def apply(event, params = {})
+      raise FrozenError unless @mutable
+
+      event = build_event(event, params)
+      process_event event
+      @event_stream.publish event
+    end
+
+    # Loads all events from the event stream of this instance and reprocesses them to
+    # get the current state of the aggregate.
+    def replay_history(up_to: nil)
+      events = @event_stream.load_events
+      events = events.select { |event| event.created_at <= up_to } if up_to.present?
+      events.each do |event|
+        process_event event
+      end
+    end
+
+    private
+
+    # Builds a new event from a given event type and parameter set. Includes parameters
+    # needed for all events that are derived from the aggregate's state.
+    def build_event(event, params)
+      default_args = { aggregate_id: @id, sequence_number: @sequence_number }
+      event.new(params.merge(default_args))
+    end
+  end
+end

data/lib/aggregates/auditor.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # The Auditor captures the state of a given aggregate at time of use. It provides listings of the
+  # commands and events that we executed on a given aggregate.
+  class Auditor
+    attr_reader :type, :aggregate_id
+
+    def initialize(type, aggregate_id)
+      @type = type
+      @aggregate_id = aggregate_id
+    end
+
+    # This method creates a new instance of the aggregate root and replays the events
+    # on the aggregate alone. Only events that happened prior to the time specified are
+    # processed.
+    def inspect_state_at(time)
+      aggregate = @type.new @aggregate_id, mutable: false
+      aggregate.replay_history up_to: time
+      aggregate
+    end
+
+    # Returns all stored events for a given aggregate.
+    def events
+      @events ||= Configuration.storage_backend.load_events_by_aggregate_id(@aggregate_id)
+    end
+
+    # Returns all commands for a given aggregate.
+    def commands
+      @commands ||= Configuration.storage_backend.load_commands_by_aggregate_id(@aggregate_id)
+    end
+
+    def events_processed_by(time)
+      events.select { |event| event.created_at < time }
+    end
+
+    def commands_processed_by(time)
+      commands.select { |event| event.created_at < time }
+    end
+
+    def commands_processed_after(time)
+      commands.select { |event| event.created_at > time }
+    end
+
+    def events_processed_after(time)
+      events.select { |event| event.created_at > time }
+    end
+  end
+end

data/lib/aggregates/command.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'dry/monads'
+require 'dry-validation'
+
+module Aggregates
+  # Commands are a type of message that define the shape and contract data that is accepted for an attempt
+  # at performing a state change on a given aggregate. Essentially, they provide the api for interacting with
+  # your domain. Commands should have descriptive names capturing the change they are intended to make to the domain.
+  # For instance, `ChangeUserEmail` or `AddComment`.
+  class Command < DomainMessage
+    # Provides a default contract for data validation on the command itself.
+    class Contract < Dry::Validation::Contract
+    end
+
+    def validate
+      Contract.new.call(attributes).errors.to_h
+    end
+
+    def validate!
+      errors = validate
+      raise CommandValidationError, errors unless errors.length.zero?
+    end
+  end
+end

data/lib/aggregates/command_dispatcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Aggregates
+  # The CommandDispatcher is effectively a router of incoming commands to CommandProcessors that are responsible
+  # for handling them appropriately. By convention, you likely will not need to interact with it directly, instead
+  # simply call Aggregates.process_command or Aggregates.process_commands.
+  class CommandDispatcher
+    include Singleton
+
+    def initialize
+      @config = Configuration.instance
+    end
+
+    # Takes a sequence of commands and executes them one at a time.
+    def process_commands(*commands)
+      commands.each do |command|
+        process_command command
+      end
+    end
+
+    # Takes a single command and processes it. The command will be validated through it's contract, sent to command
+    # processors and finally stored with the configured StorageBackend used for messages.
+    def process_command(command)
+      command.validate!
+      return unless should_process? command
+
+      send_to_processors command
+      store command
+    end
+
+    private
+
+    def should_process?(command)
+      # Each command processor is going to give a true/false value for itself.
+      # So if they all allow it, then we can return true. Else false.
+      @config.command_filters.all? do |command_filter|
+        command_filter.allow? command
+      end
+    end
+
+    def send_to_processors(command)
+      @config.command_processors.each do |command_processor|
+        command_processor.process_command command
+      end
+    end
+
+    def store(command)
+      @config.storage_backend.store_command command
+    end
+  end
+end

data/lib/aggregates/command_filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # Applies filters to commands to decouple filtering logic from the CommandProcessor.
+  class CommandFilter
+    include MessageProcessor
+    include WithAggregateHelpers
+
+    def allow?(command)
+      handle_message(command).all?
+    end
+  end
+end

data/lib/aggregates/command_processor.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # A command processor is a type that correlates commands to operations on an aggregate root.
+  class CommandProcessor
+    include MessageProcessor
+    include WithAggregateHelpers
+
+    def process_command(command)
+      handle_message command
+    end
+  end
+end

data/lib/aggregates/command_validation_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # Wraps a hash of errors when validating a command as an Exception.
+  class CommandValidationError < StandardError
+    attr_reader :errors
+
+    def initialize(errors, msg = nil)
+      super(msg)
+
+      @errors = errors
+    end
+  end
+end

data/lib/aggregates/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Aggregates
+  # Stores all of the items needed to dictate the exact behavior needed by
+  # the application consuming the Aggregates gem.
+  class Configuration
+    include Singleton
+
+    attr_reader :command_processors, :event_processors,
+                :storage_backend, :command_filters
+
+    def initialize
+      @command_processors = []
+      @event_processors = []
+      @command_filters = []
+      @storage_backend = InMemoryStorageBackend.new
+    end
+
+    def filter_commands_with(command_filter)
+      @command_filters << command_filter
+    end
+
+    def store_with(storage_backend)
+      @storage_backend = storage_backend
+    end
+
+    def process_events_with(event_processor)
+      @event_processors << event_processor
+    end
+
+    def process_commands_with(command_processor)
+      @command_processors << command_processor
+    end
+  end
+end

data/lib/aggregates/domain_message.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+
+module Aggregates
+  # The DomainMessage is not a class that should generally be interacted with unless
+  # extending Aggregates itself. It provides some core functionality that message types
+  # (Event and Command) both require.
+  class DomainMessage < Dry::Struct
+    attribute :aggregate_id, Types::String
+    attribute :message_id, Types::String.default(proc { Aggregates.new_message_id })
+    attribute :created_at, Types::Strict::DateTime.default(proc { Time.now })
+
+    def to_json(*args)
+      json_data = attributes.merge({ JSON.create_id => self.class.name })
+      json_data.to_json(args)
+    end
+
+    def self.json_create(arguments)
+      new arguments
+    end
+  end
+end

data/lib/aggregates/dynamoid/dynamoid_storage_backend.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/Documentation
+
+module Aggregates
+  # rubocop:enable Style/Documentation
+  begin
+    require 'dynamoid'
+
+    # Extensions to the Aggregates gem that provide message storage on DynamoDB.
+    module Dynamoid
+      # Stores events in DynamoDB using `Dynamoid`
+      class DynamoEventStore
+        include ::Dynamoid::Document
+
+        field :aggregate_id
+        field :sequence_number, :integer
+        field :data
+
+        table name: :events, hash_key: :aggregate_id, range_key: :sequence_number, timestamps: true
+
+        def self.store!(event, data)
+          args = { aggregate_id: event.aggregate_id, sequence_number: event.sequence_number, data: data }
+          event = new args
+          event.save!
+        end
+      end
+
+      # Stores commands in DynamoDB using `Dynamoid`
+      class DynamoCommandStore
+        include ::Dynamoid::Document
+
+        field :aggregate_id
+        field :data
+
+        table name: :commands, hash_key: :aggregate_id, range_key: :created_at, timestamps: true
+
+        def self.store!(command, data)
+          args = { aggregate_id: command.aggregate_id, data: data }
+          command = new args
+          command.save!
+        end
+      end
+
+      # Stores messages on DynamoDB using the dynamoid gem.
+      class DynamoidStorageBackend < StorageBackend
+        def store_event(event)
+          data = message_to_json_string(event)
+          DynamoEventStore.store! event, data
+        end
+
+        def store_command(command)
+          data = message_to_json_string(command)
+          DynamoCommandStore.store! command, data
+        end
+
+        def load_events_by_aggregate_id(aggregate_id)
+          DynamoEventStore.where(aggregate_id: aggregate_id).all.map do |stored_event|
+            json_string_to_message stored_event.data
+          end
+        end
+
+        def load_commands_by_aggregate_id(aggregate_id)
+          DynamoCommandStore.where(aggregate_id: aggregate_id).all.map do |stored_command|
+            json_string_to_message stored_command.data
+          end
+        end
+      end
+    end
+  rescue LoadError
+    # This is intentional to no do anything if it is not loadable.
+  end
+end

data/lib/aggregates/event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # The event class defines the entry point that all Events in your domain should
+  # subclass from. An Event describes something that happened. They are named in passed tense.
+  # For instance, if the user's email has changed, then you might create an event type called
+  # UserEmailChanged.
+  class Event < DomainMessage
+    attribute :sequence_number, Types::Integer
+  end
+end

data/lib/aggregates/event_processor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # EventProcessors respond to events that have occurred from Aggregates after.
+  # EventProcessors take on different roles depending on the application. The biggest
+  # role to to project aggregates as they are created and updated into a readable form
+  # for your application.
+  class EventProcessor
+    include MessageProcessor
+
+    def process_event(event)
+      handle_message event
+    end
+  end
+end

data/lib/aggregates/event_stream.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # An EventStream is a sequence, append only sequence of events that are read when reconstructing
+  # aggregates and written to when a command is processed by the aggregate.
+  #
+  # There is likely no need to interact with this class directly.
+  class EventStream
+    def initialize(aggregate_id)
+      @aggregate_id = aggregate_id
+      @config = Configuration.instance
+    end
+
+    def load_events
+      @config.storage_backend.load_events_by_aggregate_id(@aggregate_id)
+    end
+
+    def publish(event)
+      @config.event_processors.each do |event_processor|
+        event_processor.process_event event
+      end
+      @config.storage_backend.store_event event
+    end
+  end
+end

data/lib/aggregates/identity.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # Gem identity information.
+  module Identity
+    NAME = 'aggregates'
+    LABEL = 'Aggregates'
+    VERSION = '0.2.0'
+    VERSION_LABEL = "#{LABEL} #{VERSION}"
+  end
+end

data/lib/aggregates/in_memory_storage_backend.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # This is an extremely simple storage backend that retains all events and commands in process
+  # memory. This method does not persist beyond application restarts and should generally only be
+  # used in testing.
+  class InMemoryStorageBackend < StorageBackend
+    def initialize
+      super()
+
+      @events = {}
+      @commands = {}
+    end
+
+    def store_command(command)
+      commands_for_aggregate_id = load_commands_by_aggregate_id(command.aggregate_id)
+      commands_for_aggregate_id << command
+    end
+
+    def store_event(event)
+      event_for_aggregate_id = load_events_by_aggregate_id(event.aggregate_id)
+      event_for_aggregate_id << event
+    end
+
+    def load_events_by_aggregate_id(aggregate_id)
+      @events[aggregate_id] ||= []
+    end
+
+    def load_commands_by_aggregate_id(aggregate_id)
+      @commands[aggregate_id] ||= []
+    end
+  end
+end

data/lib/aggregates/message_processor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # MessageProcessor is a set of helper methods for routing messages
+  # to handlers defined at the class level for DomainMessages.
+  module MessageProcessor
+    # Provides a single mapping of Message Classes to a list of handler
+    # blocks that should be executed when that type of message is received.
+    module ClassMethods
+      def on(*message_classes, &block)
+        message_classes.each do |message_class|
+          handlers = message_mapping[message_class] ||= []
+          handlers.append block
+        end
+      end
+
+      def message_mapping
+        @message_mapping ||= {}
+      end
+
+      def handles_message?(message)
+        message_mapping.key?(message.class)
+      end
+    end
+
+    def self.included(host_class)
+      host_class.extend(ClassMethods)
+    end
+
+    def find_message_handlers(message, &block)
+      search_class = message.class
+      while search_class != DomainMessage
+        handlers = self.class.message_mapping[search_class]
+        handlers&.each(&block)
+        search_class = search_class.superclass
+      end
+    end
+
+    def handle_message(message)
+      find_message_handlers.map do |handler|
+        instance_exec(message, &handler)
+      end
+    end
+  end
+end

data/lib/aggregates/storage_backend.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Aggregates
+  # The StorageBackend class is responsible for providing an interface for storing Domain messages
+  # such as events and commands.
+  class StorageBackend
+    def store_event(_event)
+      raise NotImplementedError
+    end
+
+    def store_command(_command)
+      raise NotImplementedError
+    end
+
+    def load_events_by_aggregate_id(_aggregate_id)
+      raise NotImplementedError
+    end
+
+    def load_commands_by_aggregate_id(_aggregate_id)
+      raise NotImplementedError
+    end
+
+    protected
+
+    def message_to_json_string(message)
+      JSON.dump message.to_json
+    end
+
+    def json_string_to_message(json_string)
+      JSON.parse json_string, create_additions: true
+    end
+  end
+end

data/lib/aggregates/types.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+
+module Aggregates
+  module Types
+    include Dry.Types
+  end
+end

data/lib/aggregates/with_aggregate_helpers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Aggregates
+  # Helper functions for running blocks with a specified aggregate.
+  module WithAggregateHelpers
+    # Class Methods to extend onto the host class.
+    module ClassMethods
+      def with_aggregate(type, command, &block)
+        aggregate_id = command.aggregate_id
+        with_aggregate_by_id(type, aggregate_id, &block)
+      end
+
+      def with_aggregate_by_id(type, aggregate_id)
+        yield type.get_by_id aggregate_id
+      end
+    end
+
+    def self.included(host_class)
+      host_class.extend(ClassMethods)
+    end
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: aggregates
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Zach Probst
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dry-validation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description:
+email:
+- zprobst@resilientvitality.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.md
+files:
+- LICENSE.md
+- README.md
+- lib/aggregates.rb
+- lib/aggregates/aggregate_root.rb
+- lib/aggregates/auditor.rb
+- lib/aggregates/command.rb
+- lib/aggregates/command_dispatcher.rb
+- lib/aggregates/command_filter.rb
+- lib/aggregates/command_processor.rb
+- lib/aggregates/command_validation_error.rb
+- lib/aggregates/configuration.rb
+- lib/aggregates/domain_message.rb
+- lib/aggregates/dynamoid/dynamoid_storage_backend.rb
+- lib/aggregates/event.rb
+- lib/aggregates/event_processor.rb
+- lib/aggregates/event_stream.rb
+- lib/aggregates/identity.rb
+- lib/aggregates/in_memory_storage_backend.rb
+- lib/aggregates/message_processor.rb
+- lib/aggregates/storage_backend.rb
+- lib/aggregates/types.rb
+- lib/aggregates/with_aggregate_helpers.rb
+homepage: https://github.com/resilient-vitality/aggregates
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/resilient-vitality/aggregates/issues
+  changelog_uri: https://github.com/resilient-vitality/aggregates/blob/master/CHANGES.md
+  documentation_uri: https://github.com/resilient-vitality/aggregates
+  source_code_uri: https://github.com/resilient-vitality/aggregates
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A ruby gem for writing CQRS applications
+test_files: []