Build Status Coverage Status

A classic DCI implementation for ruby with some extra sugar. I've been using DCI in my Rails projects and I extracted some common patterns into this gem.

Add this line to your application's Gemfile:

gem 'ruby_dci', require: 'dci'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby_dci

First of all, make yourself familiar with DCI :

DCI (Data Context Interaction) is a new way to look at object-oriented programming. Instead of focusing on individual objects, the DCI paradigm focuses on communication between objects and makes it explicit. It improves the readability of the code, which helps programmers to reason about their programs.

With the theory out of the way, let's see what this gem will give you. You will get:

• DCI::Context module to include in your contexts or use cases.
• DCI::Role module to include in your roles.
• Transaction support for the code executed in the context.
• Event routing and processing which should run after the transaction is commited.

This is a common pattern with DCI. You run your use case, code is executed in a transaction, and then later you want to publish the result to the message broker for example.

I configure the gem in config/initializers/dci_configuration.rb.

DCI.configure do |config|
 config.routes = Hash.new([])
 config.router = EventRouter.new
 config.transaction_class = ApplicationRecord
 config.raise_in_event_router = !Rails.env.production?
 config.on_exception_in_router = -> (exception) {}
end

Usually you want your code to run in a transaction. Either everything runs fine, or nothing is saved. This is done by wrapping the executed code in a transaction block. I use ActiveRecord, but you can use whatever you want. Your class just needs to implement a transaction method that takes a block. If you don't want any transactions, you can either skip config.transaction_class completely, or set it to DCI::NullTransaction.

This is your mapping of events that may happen in the context. Key is a class name, and the value is an array of method names. Example:

{
 DomainEvents::ProductAddedToCart => [ :send_product_added_notification ]
}

The system will know that it needs to execute send_product_added_notification from config.route_methods for every event of class DomainEvents::ProductAddedToCart. If you don't have any actions that you need to perform after a transaction, then just skip config.event_routes completely or set it to Hash.new([]).

I implement events as plain ruby Structs. Example:

module DomainEvents
 ProductAddedToCart = Struct.new(:product)
end

Why do I do it like this? It makes it easier to add other callbacks later. I can do it in one place instead of searching through hundreds of files. Also makes testing easier.

This is a class that implements the methods for the config.routes mapping. Example:

class EventRouter
 def send_product_added_notification(event)
 AddedToCartNotificationJob.perform_later(id: event.product.id)
 end
end

When your transaction is commited, you don't want to raise an exception during event processing. You can turn it off in production environment, but still raise when you are developing.

config.raise_in_event_router = !Rails.env.production?

In case there is an exception in the event router, you can provide a handler for the exception. It should be a lambda that receives an exception as a parameter. You can use it to log the exception. If you don't need any logging, just skip config.on_exception_in_router completely, or assign an empty lambda.

config.on_exception_in_router = -> (exception) { Rails.logger.error(exception) }

In a Rails app I put my contexts in app/contexts. You define a context by including DCI::Context.

class AddProductToCart
 include DCI::Context
 attr_accessor :customer, :product
 def initialize(user:, product:)
 @customer = user.extend(Customer)
 @product = product
 end
 def call
 customer.add_to_cart!(product: product)
 end
end

Somewhere else in code, for example in a controller, you call it like this:

AddProductToCart.call(user: current_user, product: @product)

Couple of thigs to keep in mind:

• The context will either succeed or raise an exception. I prefer to rescue exceptions instead of checking for result. This has a benefit of keeping my code linear, instead of if .. else nesting.
• There is usually no result from the .call. For example, if you want to create a User record, don't pass request params to your context, then create the object somewhere in a role and somehow try to return this object back. Instead build the User object already in the controller and pass the instance to your .call. Will save you a lot of headache.

In a Rails app I put my roles in app/roles. Roles are plain ruby modules. You define a role by including DCI::Role. A role has access to the context and to the context_events methods. You can push events to context_events to process them after the transaction.

module Customer
 include DCI::Role
 def add_to_cart!(product:)
 # do your thing
 # add event to the context
 context_events << DomainEvents::ProductAddedToCart.new(product)
 end
end

The gem includes a RSpec matcher include_context_event. Use it like this:

In rails_helper.rb:

require 'dci/rspec/matchers'

In your spec:

expect(customer).to include_context_event DomainEvent::ProductAddedToCart

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.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruby_dci.

The gem is available as open source under the terms of the MIT License.