Insights at Workshop 14

Purify your programs with capability objects

Sun, 01 May 2016 16:39:05 +0000

Introducing capability objects to eliminate side effects and side causes

Pure funcations are predictable, and therefore easier to test and reason about than code with side effects. Some functional languages go to great lengths to control side effects, such as Haskell with its use of the IO Monad.

This post shows how we can get the same advantages in JavaScript. (The advantages are the same for many dynamic languages and I also use this technique in Ruby.) Capability objects provide a simple mechanism for controlling side effects and side causes. Their use can improve the rationality, readability and reusability of program components.

When is a function Pure?

A function is pure when isolated from side effects and side causes:

The only effect of it’s execution is the return value (side effect free).
The return value is always the same given the same arguments (side cause free).
A function with both has referential transparency(pure).

It is easiest to clarify these three with some examples.

// Side effect free
function flip(){
  return Math.random() >= 0.5 ? "heads" : "tails";
}

// Side cause free
function addAndLog(a, b){
  console.log("adding", a, b);
  return a + b;
}

// Pure
function add(a, b){
  return a + b;
}

There are many ways a function can become coupled to the outside world. Ways include accessing global variables such as the window object, logging and throwing errors. Finally any function that accepts a function as an argument (i.e. callback) will become polluted if that callback is impure.

A program cannot be useful without causing some side effect, it must at least display it’s result. The goal of a capability object is to separate the business logic and interaction with the outside world. This separation pushes impure code to the edges of our program leaving the logic pure. This purity makes validating code that performs important logic easier.

Capability Objects and effectively isolated functions.

A capability object is an object on which some of its methods may be impure or have side effects. An effectively isolated function is one that is pure when the capability object has only pure functionality.

The calling code then chooses to provide explicit access for a function to the outside world by controlling the capabilities that are passed in. If it helps this can be considered as dependency injection of all impure capabilities.

We make our examples effectively isolated by rewriting them to take appropriate capability objects.

function flip(randomiser){
  return randomiser.random() >= 0.5 ? "heads" : "tails";
}

function addAndLog(a, b, logger){
  logger.log("adding", a, b);
  return a + b;
}

// Already pure
function add(a, b){
  return a + b;
}

Ok, but why?

To show off the advantages of pure and side effect free functionality we need a more sophisticated example. Let’s start with a naieve implementation of a dispatcher. Dispatchers are a key part of the flux architecture

function Dispatcher(callbacks){
  this.dispatch = function(action){
    callbacks.forEach(function(callback){
      if (callback instanceof Function) {
        callback(action);
      } else {
        throw new TypeError("Callback is not a function");
      }
    });

    if (callbacks.length === 0) {
      console.warn(action);
    } else {
      console.info(action);
    }
  }
}

This dispatcher dispatches an action to each callback in a collection. Meaningful errors should be the result of any callback that is not a function. A log is required for each action that is dispatched. Finally if there are no callbacks our log should be a warning as we never want a dispatched action to have no effect.

The naieve implementation is tightly coupled to the world outside its scope. It creates side effects when throwing errors and writing log messages.

To isolate the dispatcher we make the following changes.

function Dispatcher(callbacks, logger){
  this.dispatch = function(action){
    callbacks.forEach(function(callback){
      if (callback instanceof Function) {
        callback(action);
      } else {
        var err = new TypeError("Callback is not a function");
        logger.error(err);
      }
    });

    if (callbacks.length === 0) {
      logger.warn(action);
    } else {
      logger.info(action);
    }
  };
}

In this version there is not a single side effect. A logger is passed as a dependency, so it is within scope when we call methods on it. Instead of throwing errors the dispatcher now reports errors via the logger.

Let us examine the advantages of these changes.

Detailed logs

In larger systems it is helpful to add labels to logs. One such label might be the section of code that logged the message. This can be achieved by starting the dispatcher with a logger that always adds a label to its log messages.

var logger = {
  info: function(message){
    console.info("The Dispatcher:", message);
  }
  // etc...
};

Clean logs

In production we might only be interested in messages that are a warning or an error. To set this up only our logger needs to know about a log level and we can just dispense with logs that are not important.

var logger = {
  info: function(message){
    if (LOG_LEVEL <= INFO_LOG_LEVEL) {
      console.info(message);
    }
  }
  // etc...
};

Tested logs

We have described a dispatcher that logs at different priorities an action that has no callbacks to one that has at least a single callback. This is the kind of behaviour it would be nice to test. Stubbing would have been the only option open to us to test the original code.

Stubbing methods on the global console object would require a cleanup step which can be problematic if the test fails. The effectively isolated dispatcher can use a fake logger when we are testing the log messages. This logger will record each call to a method we are interested in.

// This returns a function that records each time it is called
function createTranscriptFunction(){
  var transcript = [];
  var func = function(value){
    transcript.push(value);
  }
  func.transcript = transcript;
  return func;
}

var logger = {
  info: createTranscriptFunction(),
  warn: createTranscriptFunction(),
}

Reporting errors

The stack trace of an error is formed when the error is created and not when it is thrown. This means that if we pass the error to a logger which then throws it we still get the correct stacktrace.

In production it is not useful to throw errors. The customer is unlikely to be interested in a stacktrace. Additionally one bad callback is no reason to not call the other callbacks. The best case is that one bad callback is not important and its effect may not be visible to the user. If errors are occurring in production we want to be notified about them and let the user carry on.

Conversely in development errors should be thrown. As developers we want notification of broken code as soon as possible. The dispatcher does not need to be aware of a choice of error handling strategy. Instead it can simply be passed to an appropriate logger.

// Development
var logger = {
  error: function(err){
    throw err;
  }
};

// Production
var logger = {
  error: function(err){
    MyErrorServer.notifyException(err);
  }
};

Is it worth it.

So far only advantages have been highlighted, but what are the costs.

Passing around capability objects requires a bit more setup. Failing to pass in a logger can result in code failing even if all the business functionality is present. An option to handle when a logger is not present is to fallback to using the global console. I do not do this as I think that a missing logger is something that I want to be a failure and in production missing logs is a problem to which I want to be alerted.

Leaving debug comments in your codebase makes it a bit larger. Not really a problem as the amount of code is so small. If it turns out to be a problem the way to remove the debug calls is with a build step.

If a function causes many different side effects then it will require several capability objects. This is a pain but ultimately a good thing. Any function that needs access to more than two external resources is probably doing too much.

Resources

Why I won't leave Ruby for Elixir

Mon, 18 Apr 2016 19:24:05 +0000

This post is not about the Elixir community or job opportunities with Ruby. It is not really about Ruby vs Elixir at all. What I want to explain is why I am uncomfortable hitching my bandwaggon to the movement from Object Oriented Programming(OOP) to Functional Programming(FP).

Background

The first language I used professionally was Ruby. I have been working with it for several years. In that time I have looked at many ways to improve code quality. One set of guidelines for improving code is Domain Driven Design(DDD). This is a methodology for writing programs which reflect the domain of the problem they are trying to solve. DDD is applicable to all programming paradigms but is most often discussed in an OOP context.

More recently I have been employed to write Elixir. Elixir is a proudly functional language that is built atop the Erlang virtual machine(beam). It has some Ruby inspired syntax but few other similarities. Working with this new language was a thorough introduction to functional programming.

Elixir has some powerful concepts such as pattern matching, immutability and pipelines. These concepts are common across many functional programming languages but much rarer in most object oriented languages.

However as I became more familiar with these concepts I could find no good reason why they were limited to functional languages. In particular creating immutable objects certainly is possible and seemed to be valuable.

Which to choose

So I find myself in the situation do I want to program in a functional language or an object language.

When starting with Elixir one comment from Dave Thomas stuck in my mind. He said “I don’t think in objects, I think in processes”. I wondered which one I thought in or even if there is a best way to think.

Intriguingly I think DDD has a suggestion on whether it is better, as a programmer, to think in objects or processes. Ask the following question. Does the client(or any non technical stakeholder) think in processes or objects? The answer to that question will be the same answer to whether FP or OOP is a more suitable way to model their domain.

I certainly value immutability in a programming language and would agree that it can help make code predictable. My time developing with Elixir clear demonstrated this. However Ruby can have immutable objects. So in the end it comes down to the domain to see which paradigm is more suitable.

Thinking in processes can be helpful, but many of these processes will involve well-defined domain objects.

Browse the Catalogue
View that Item
Update your Basket
checkout == create an Order

In my opinion neither paradigm is superior. And my advice is to stop trying to pick a side and enjoy learning both.

What’s next for me

Erlang has some superpowers when it comes to writing parallel, fault tolerant code and Elixir inherits these powers. If a system is meant to manage many demands concurrently then I would use Elixir. A web socket server is an example of such a system. For a program with less strenuous requirements I would prefer to use Ruby.

So I have a preference for Ruby. This is because; Ruby’s support for functional concepts is better than working with objects in Elixir. In Ruby I can leverage most of the lessons I learned from my time in with functional programming.

Best of both

Some talks discussing immutability and objects.

Blending Functional and OO Programming in Ruby Great talk from Piotr Solnica about his exploration of this area.
Boundaries Immutable OO as FauxO, brilliance from Gary Bernhardt

Three JavaScript frameworks for 2016

Wed, 23 Mar 2016 14:00:00 +0000

Three modern JavaScript frameworks that are interesting and have something to teach you.

Keeping track of the latest JavaScript frameworks is exhausting. It is difficult to separate the genuinely interesting from the crowd. Recently I have had some time to explore the current offerings. This selection are my favourite and worth a second look.

Redux

Flux -> Reflux -> Redux

Flux was coined by Facebook to describe the recommended architecture to use with React.

The key concept is that of a unidirectional dataflow. Actions cause updates in a store(aka model). The model generates a view and this finally updates the DOM. User interactions are mapped to actions to close the loop.

Redux is a recent addition to the flux family tree. It develops on flux by confining all application state to a single store. This sounds a drastic limitation but creates some interesting payoffs. One of these benefits is that Redux offers a time-travelling debugger. This works by keeping a record of each version of the state and allowing a debugger to replay through this history. It is invaluable when debugging a process with many steps.

To get a thorough introduction to Redux there is a series of explanatory videos. These run through all the basic concepts very quickly.

Cycle

Haskell -> ReactiveX -> Cycle

Cycle takes inspiration from functional technologies such as Haskell and ReactiveX. Don’t be deterred by these advanced forebears. Only a limited number of concepts are used and they are explained when needed.

Cycles design starts with a proposition - what if the user was a function? The result is a unidirectional data flow, in common with FLux. However all key components are reactive instead of proactive. Much of Cycle is built on observables, which are leveraged from RX.js.

Modelling the system as an observable to a user is certainly unusual. To me the observable pattern is useful when the object being observed does not care about the behaviour (or even existence) of any observers. This is not the case for any real system. The user cares quite a lot about whether the program responds or not to its actions.

That said there are a few examples where this approach results in very elegant programs. The concept is well explained on the Cycle website, have a read through and decide if your system makes sense as an observable.

Vue

Backbone -> MV* -> MVVM

Vue uses the Model-View-ViewModel(MVVM) pattern. It is a focused toolset for dealing with the View and ViewModel layer. A few further core components of an app are included, such as a router. Apart from these the core business logic is completely in the hands of the developer.

Vue evolves the MVVM pattern forward in several respects. Complete widgets can be encapsulated in single .vue files These files contain HTML, CSS and JS. The databinding syntax that glues the View to ViewModel is concise and explicit. These changes create a powerful framework that will be familiar to developers who have used other MV* frameworks.

Vue rides the line between library and framework quite expertly. I particularly like the way it does not interfere with implementing the core application logic. It is quite possible to implement a flux architecture within a Vue project. Important for your project to remain buzzword compliant.

The documentation does a great job of describing the MVVM pattern. Particularly valuable when many explanations muddle all the various MV* patterns together.

Conclusion

All of these projects have ideas I have been able to use going forward. Perhaps the most significant for me was having one store for the state of an app. In my current project the single store has just been a wrapper around the history API. Encoding the entire app state in the URL has given the app the some nice properties. First is refreshing the page will not lose any information. Second the back button neatly steps through the history of the application.

So which of these three should you use? All of them, in the correct situation. They all have great documentation and learning them is valuable even if you do not use them.

If my next project had lots of collections, I would use Vue to create coherent components. But my design would be inspired by Redux and reduce the number of stateful components. For a more interactive product, I would employ Cycle. The observable model would be very nice for handling rich input from the user.

Well those are my three favourites at the moment;I am sure you have others that you can suggest.

Herinrik Jorteg created an example where the router was just a view into the state. link to old webcomponents frp post.

Dreamcoding my ideal language.

Thu, 26 Nov 2015 16:39:05 +0000

Dreamcoding is the process of writing down the code you wish to write, without considering implementaion. This post is what happened when I tried to apply that concept to a whole language.

I was first introduced to the concept of dreamcoding on the nobackend.org site. Conceptually it is very similar to ‘coding by wishful thinking’ that I have seen from Corey Haines.

What I want

In my career I have worked with JavaScript, Ruby and Python, most recently I have been working with Elixr. In my free-time I have experimented with yet more. These are all great languages yet there are certain features that might be useful that I have not found in any language. These ‘missing’ features are what I present here.

DISCLAIMER: These features might be harmful. I think all these features might be interesting but as I have not implemented them, so they could contain any problems.

All examples are highlighted as Ruby that’s just because they look more interesting than un-highlighted and Ruby has a very free syntax.

1. Named Curried Functions

My first feature is a function that is both curried and has named parameters. Currying is the partial application of functions. It allows for the very concise description of certain problems, for example mapping collections. Named arguments in functions are expressive at communicating the intent of a function. My hope is that named-curried functions could be both expressive and concise.

Such a combination might look like.

def divide(numerator, denominator)
  numerator / denominator
end

divide(numerator: 4, denominator: 2)
# => 2

half = divide(denominator: 2)
half(numerator: 6)
# => 3

invert = divide(numerator: 1)
invert(denominator: 4)
# => 0.25

# Perhaps if the function has arity 1 then the name of the final argument can be omitted
invert(4)
# => 0.25

Immutable objects

Objects are a useful abstraction in many cases to model a domain. In my experience, the most useful objects in domain modeling are small value objects. Immutable structures are cited to help improve the predictability of code, which I think is the case.

Most languages that are immutable are functional languages. The pass data around and do not have a way to attach domain information to custom objects. In the Ruby community there has been some discussion around immutability. However because it is not immutable by default it is slow as certain optimisations cannot be made.

Simple immutable objects can just be modeled as partially applied modules. Thought like this it would also be possible to have modules applied to different degrees, for example.

module User
  def first_name(first_name)
    first_name
  end

  def name(first_name, last_name)
    first_name ++ " " ++ last_name
  end
end

# Here we just ignore the unexpected argument passed in.
User.first_name(first_name: "Stuart", last_name: "Little")
# => "Stuart"

User.name(first_name: "Stuart", last_name: "Little")
# => "Stuart Little"

stuart = User(first_name: "Stuart", last_name: "Little")
stuart.name
# => "Stuart Little"

littles = User(last_name: "Little")
# => {User, {last_name: "Little"}}

littles.name(first_name: "Stuart")
# => "Stuart Little"

If logic is needed to instantiate objects this can be added as a function on the module. For example if we wanted to create a user from a CSV row.

module User
  def from_csv_archive(archive_string)
    id, first_name, last_name = archive_string.split(' ')
    User(first_name: first_name, last_name: last_name)
  end
end

Side Effects always Dependencies

A well structured way of handling side effects is important when writing modular code. I would like to see controlled access IO through an IO module that is not in the global namespace. This IO module would be passed as in a function argument list, this would mean that two things. First a fake implementation can always be passed in for the purpose of testing. Second the language would be able to track its use and make optimisations of the code that did not call upon external IO. Making IO always an explicit dependency might have advantages that the computer can assume functions without this declaration are pure.

IO.puts("Hello world!") # !! Error as no module IO found here

module ConsoleLogger
  def log(output, io=IO)
    io.puts(output)
  end
end

ConsoleLogger.log("Hello world!")
# Hello world!

// NullIO is a dummy object that has the same interface as the IO object.
ConsoleLogger.log(output: "Hello world!", io: NullIO)

Limited public interfaces

Controlling the public interface of a module is a good way to preserve modularity. In some languages it is very easy to write code that relies on implementation details. One way to control this would be to make all modules declare implementation of specific interfaces.

To go even further a function name can only be used once across all interfaces For example, if a value has a to_string method then it is certain that the value implements the printable interface. For this reason I want to experiment with structural typing where each function name is only able to refer to a single function signature within a certain context. By default every function is private and they are only exposed through interfaces.

# Define a to_string interface that takes no arguments and returns a string
interface Printable
  to_string :: Any -> String
end

# Trying to create another interface with the string function is an error
interface Other
  to_string :: Any -> String
end
# !! raise SignatureAlreadyDefined

module User
  # Simply defining this function marks this module as printable
  def to_string(user)
    "user"
  end

  # By default this will be private as it is not in any defined interface.
  def private_method
    :some_constant
  end
end

User.implements(Printable)
# => true

Conclusion

As a developer I am excited to build new things. I’m sure I would enjoy the challenge of implementing my own language. The reality is that this would be yak shaving of epic proportions. So, for the moment, I have decided on dreamcoding only.

These four features interest me, and I will continue my search for them. The next languages I want to investigate are Haskell, Scala and Typescript.

Do you see an obvious flaw in these features? Please do convince me. Is one of these features already in existence? That is excellent I would love to know where and see some examples

Organising client JavaScript with Rollup.js

Thu, 12 Nov 2015 08:33:05 +0000

Rollup.js is a great way to add structure to a large client-side code base.

You might not be wanting to tackle all of EcmaScript(ES6), yet still want to separate your JavaScript code into modules. Previously the best way to do this was Browserify with common.js modules. Rollup.js is the logical next step as it replaces the common.js modules with ES6 modules. It is also a component of Babel (a full ES6 transpiler) so there is an easy next step to get working with the rest of ES6.

I have recently introduced Rollup.js into my development workflow. The simple command line interface means it can be used without the overhead of taskrunners like(gulp). It is easy to integrate with existing tools for testing. I use the Karma test runner to execute my test framework of choice, which is currently Jasmine.

This post walks through my setup of Jasmine, Karma and rollup. Want to jump straight to the code? Visit this repository to see the code.

I will assume that you already have node and npm installed, need help see Installing Node.js and npm.

Setting up a node project

We first need to create a package.json file to identify our project as a node project. This can be done by hand or by executing npm init, which walks through setup. The only setup we need is to give the project a name, let’s call it calculator.

Next is to fetch the development dependencies we will use. Fetch all the dependencies by executing the following.

$ npm install --save-dev \
    rollup \
    jasmine \
    karma \
    karma-jasmine \
    karma-firefox-launcher

At this point make sure that you have added node_modules to your .gitignore file. It is not a good idea to commit all these node files to version control-something that I have done on too many occasions.

Setting up Karma.js

The Karma test runner also comes with a handy project initializer which will create a karma.conf.js file. Run the karma initializer with the following options.

$  ./node_modules/.bin/karma init

Which testing framework do you want to use ?
Press tab to list possible options. Enter to move to the next question.
> jasmine

Do you want to use Require.js ?
This will add Require.js plugin.
Press tab to list possible options. Enter to move to the next question.
> no

Do you want to capture any browsers automatically ?
Press tab to list possible options. Enter empty string to move to the next question.
> Firefox
>

What is the location of your source and test files ?
You can use glob patterns, eg. "js/*.js" or "test/**/*Spec.js".
Enter empty string to move to the next question.
> test/bundle.js
11 11 2015 17:04:52.298:WARN [init]: There is no file matching this pattern.

>

Should any of the files included by the previous patterns be excluded ?
You can use glob patterns, eg. "**/*.swp".
Enter empty string to move to the next question.
>

Do you want Karma to watch all the files and run the tests on change ?
Press tab to list possible options.
> no


Config file generated at "/home/peter/Projects/Calculator/karma.conf.js".

Note

We do not need Require.js as we will be replacing this with Rollup.js
You can select any browser from the list, just make sure that you have installed the correct browser runner.
Don’t worry about the missing test file, we will add it shortly.

Creating our first test

Let’s create a single test to check out Karma setup. We will create a main test file and add an example test.

// test/main.js

describe("A suite", function() {
  it("contains spec with an expectation", function() {
    expect(true).toBe(true);
  });
});

To bundle this file use Rollup with its default settings and store the output. At this point the output will be unchanged, this is because we are yet to import any modules

$ ./node_modules/.bin/rollup test/main.js > test/bundle.js

Now our bundle is available we can run the test.

$ ./node_modules/.bin/karma start --singleRun

This will show one passing test. As test/bundle.js is just a derived file it does not belong in version control. Add a line for it in the .gitignore.

Simple test execution

Typing all those commands to execute the tests would be painful. We can make life much easier by declaring them as npm scripts. First one change is needed in karma.conf.js, we will set singleRun configuration to be true.

// karma.conf.js

module.exports = function(config) {
  config.set({
    // Continuous Integration mode
    // if true, Karma captures browsers, runs the tests and exits
    singleRun: true,
  });
};

A lot of functionality can end up in npm scripts and it is easy to write magical single line scripts that no-one understands. My advice is to write small contained scripts for bundling and running the tests. Then have a third script that coordinates the small component scripts. Add these scripts into package.json.

// package.json
{
  "scripts": {
    "test": "npm run -s test:build && npm run -s test:run",
    "test:build": "rollup ./test/main.js > test/bundle.js",
    "test:run": "karma start"
  },
}

To run the project tests we can just execute the npm test script.

$ npm -s test

This single simple test command follows npm conventions and is easy to remember. Having a trivial test command is important if test driving the development of a project.

Testing some real code

At the moment we have Rollup.js setup but it is redundant as we have no modules. It is time to test some real code for a calculator. The first feature a calculator should have is the ability to add two numbers. Let’s adjust the test file so that it imports the calculator and add a meaningful test.

// test/main.js

// Import all exported functions from the calculator source file
// They will be available as part of the calculator namespace
import * as calculator from "../src/calculator";

describe("A Calculator", function() {
  it("should be able to add two numbers", function() {
    expect(calculator.add(1, 2)).toEqual(3);
  });
});

The tests should now be failing, there is no code after all. There are several features a good calculator might need. To keep features separate the calculator module will import modules to gain its utility.

// src/calculator.js

// Import add from the `calculator/add.js` file
import add from "./calculator/add";

// Export add as one of the exports for the calculator module
export { add };

// src/calculator/add.js

// export the function add as the default for this module
export default function add(a, b) { return a + b; }

With the tests passing again our impressive calculator is taking shape.

Building a distribution

The final thing, now we have working calculator components, is to bundle the source into a single file. This is so it can be consumed in all the browsers that are not yet supporting ES6 modules.

Using Rollup.js again we bundle the distribution and save it in index.js.

$ ./node_modules/.bin/rollup \
    --format iife \
    --name calculator \
    src/calculator.js >  index.js

We pass the format and name options so that our final bundle is available in the global namespace and can be used by other js code.

Again to keep our version control neat we add index.js to .gitignore.

Conclusion

This has so far been a convenient way for me to add some structure to my projects. It has been much simpler to setup than Browserify with Gulp or Grunt. Check out the code for the calculator project the result of this walk through. Tell me what you think about this approach, if you would use it or if anything is missing.

Handling Errors in Elixir, No one say Monad.

Sun, 18 Oct 2015 17:00:05 +0000

Being Contrary

This post is to extend a throwaway comment I made on Twitter about returning tagged tuples as the result of any expression in Elixir.

Tempted to say all elixir funcs should return a result tuple. {:ok, 4} = 2 + 2

Obviously several people disagreed and a tweet was never going to be enough to explain my reasoning. So here goes…

Update

I recently implemented the ideas that are discussed here. Check out OK to jump straight to the results.

Some background

Tuple: A data structure consisting of multiple parts.
Tagged Tuple: A tuple where the first part is an atom that acts as a label describing the remaining contents in the tuple.

Elixir has inherited the tagged tuple error handling convention from Erlang. Let’s take a function that has a chance of failing to compute. If all goes well, the function will return a tuple tagged with the :ok atom and a value. If the function could not return a value then it returns a tuple tagged :error and the reason. Subsequent code can then pattern match on the tag to call the correct behaviour.

case MyModule.flaky_method do
  {:ok, value} -> IO.puts "All good value was: #{value}."
  {:error, reason} -> IO.puts "Uh oh! Failed due to #{reason}."
end

Returning a tagged tuple is only a convention. In the real world many functions do not adhere to this contract:

Some functions simply return nil or :error instead of a tuple and a reason.
Some functions can’t fail so just return a value. As in my original tweet, adding 2 numbers always works and so 2 + 2 will only return 4.
Some functions borrow a Ruby convention and have functions that can throw errors and end with an exclamation mark.

A problem to solve

So before presenting you with a solution it’s good to have a problem:

Imagine I have a JSON file of information about people in my company. I want to fetch all the data relating to me in this file.

To do this I first read the file, then parse the JSON, and finally search for the details relating to me. Ideally our code will resemble an intuitive description of the problem; we described this problem as a sequence of steps and so our code should read as a sequence of steps. Given that it is possible for each of our steps to fail, we need to prepare to handle those errors. The error handling can pollute our nice list of instructions and result in code littered with conditionals.

result = case File.read("my_company/employees.json") do
  {:ok, contents} ->
    case Poison.decode(contents) do
      {:ok, json} ->
        case Dict.fetch(json, "Peter") do
          {:ok, data} -> {:ok, data}
          :error -> {:error, :key_not_found}
          # Notice the Dict API doesn't return error with reason.
          # So we add a reason to make it conform.
        end
      {:error, reason} -> {:error, reason}
    end
  {:error, reason} -> {:error, reason}
end

Well that’s ugly. Can we do this better?

Thinking about it a bit harder we can see a common pattern in the code: If the result of a step is successful, we want to take the value of the result and use it in the next step. But if the result was an error then we want to stop processing.

How about a Result module?

Let’s create a module that has the responsibilty of handling this conventional error pattern. The Result module handles passing values from :ok tagged tuples to the next function. But if the result is an :error tagged tuple then following functions will simply be ignored.

The function of interest is bind. It has the following behaviour:

If the result given is a success, call the next function with the returned value.
If the result is a failure, don’t invoke the next function.

defmodule Result do
  def bind({:ok, value}, func) when is_function(func, 1), do: func.(value)
  def bind(failure = {:error, _}, _func), do: failure
end

With the bind method we can then return to a linear set of steps.

import Result

{:ok, "my_company/employees.json"}
|> bind(&File.read/1)
|> bind(&Poison.decode/1)
|> bind(fn
  (%{"Peter": data}) -> {:ok, data}
  (_) -> {:error, :key_not_found}
  # This noise here is only necessary as the Dict returns :error without a reason
end)

Not bad! We have a single list of steps, but having the bind function and function capturing everywhere still makes this a bit messy.

Can we go better again?

There is a monad in the house.

This combination of tagged tuples can be viewed as a result monad. The result monad is a monad because it has features in common with other monads.

Monads are a very abstract concept and as we are not trying to generalise any further we do not need to investigate them any further. Using the result tuple as a monad allows us to use the experience of people who have thought more about monads.

For this reason I am working on an extension to the result module that will handle tagged tuples as monads. I want it to be able to handle {:ok, value} | {:error, reason} only so that it provides guidance on the API for other functions. The extension will be the ok-pipeline macro - |ok>. This macro will be a combination of an elixir pipeline and the bind function.

With this ok-pipeline our example problem could be refactored even further.

I have assumed the API for dict is updated

use Result

def get_employee_data(file, name) do
  {:ok, file}
  |ok> File.read
  |ok> Poison.decode
  |ok> Dict.fetch(name)
end

def handle_user_data({:ok, data}), do: IO.puts("Contact at #{data["email"]}")
def handle_user_data({:error, :enoent}), do: IO.puts("File not found")
def handle_user_data({:error, {:invalid, _}}), do: IO.puts("Invalid JSON")
def handle_user_data({:error, :key_not_found}), do: IO.puts("Could not find employee")

get_employee_data("my_company/employees.json")
|> handle_user_data

Conclusion

At the end of the last example we used a regular pipe to pass the tuple to the function instead of to the extracted value. In practice this often happens as the last step because we can’t put off handling errors forever. And nor should we, code is confident when we can handle errors all in one place. This last function that knows about errors expects a tuple and not just the value - to label this difference I normally name them handle_something.

So does considering monads in a pipeline help or hinder your thinking? I think it helps and have managed to use a result pipeline in a couple of places so far. If you are able to try it out do let me know how it goes.

Resources

Finally a few excellent resources on monads if you want to read further but I stress that a full understanding is not necessary to enjoy the benefits.

OK Elegant error handling in elixir pipelines.
Refactoring Ruby with Monads
Whistle-stop tour of monads with Tom Stuart. His Optional is the analogue of the Result monad.
Monads in Pictures
Best resource for explaining monads, done with pictures. Thanks to Aditya Bhargava for this one.

Domain Driven Design, Where the real value lies.

Thu, 20 Aug 2015 16:56:05 +0000

Conclusion of Domain Drive Design series following on from Interactors.

Confession

This is the final post in this series, and I have a confession. What has been discussed so far has not been the whole story of Domain Driven Design.

So far several useful patterns have been covered. These make up the tactics of Domain Driven Design. However tactics should not be employed without a strategy. Without an understanding of the strategy you will end up with a cargo cult. I did not realise the importance of the strategy when I started writing these articles. And in my defence, even Eric Evans has said he wishes that he put more emphasis on the strategy in his book that started Domain Driven Design.

Explaining the strategy.

Domain Driven Design has much to say on the best environment for development. Key is that all interested parties in a project are able to understand each other. These parties could be developers, managers, client, designers, customers and more. To ensure understanding, time should be spent to develop a domain specific language. In addition barriers between those developing the software and the users of the software should be eliminated as much as possible.

Once this has been achieved the developers should not need to make assumptions and instead consult stakeholders when making decisions. Implementing software is difficult enough and without distilled domain knowledge it has very little chance of solving the problem at hand.

Much of the strategy can be described as common sense but that doesn’t mean it does not bear repeating or explicitly naming. I think it is unhelpful that both the tactics and strategy of Domain Driven Design are interlaced. To encapsulate the core concepts of the strategy in Domain Driven Design I would like to try the following definition.

Knowledge Limited Programming: The decision to not develop a piece of code until the situation requiring its development is known.

Revisiting the tactics

With an understanding of the strategy we can reexamine the patterns in a more informed context. There are two distinct groups for the design objects. First, those that represent concepts from the domain. They are:

Entities - A domain object with an identity that can change over time, such as customer.
Values - A domain object without an identity separate to its attributes e.g. price, discount code or address.
Interactors - A domain object that represents an action or activity e.g. login, checkout, signup etc.

The rest with the purpose of protecting the core domain from technical concerns.

Form objects - Prevents the HTML form considerations effecting our domain
Repository - Prevents the database structure from penetrating the domain model

Without the strategy it is tempting to ask developers what entities should look like. With the strategy the answer is whatever makes most sense in the domain. Of course there are many similarities between projects that allow common behaviour to be reused but the domain model should not be tied to a library’s language or layout. My mantra for employing the tactics of Domain Driven Design would be:

Use domain concepts not language constructs.

I have written gems to help with value objects and form objects, both are small so they encroach as little as possible on the domain.

Typetanic A library of value objects to help start a project, at the moment just email. As your domain grows richer you should throw out the Typetanic version and replace with custom implementations.
Vulcanize A library for building form objects. Domain representation is handled by value objects that the consumer needs to provide.

Rails: friend or foe?

When I started investigating Domain Driven Design, I tried to push as far away from Rails conventions as possible. This was not due to dislike of Rails but to get the perspective that comes with distance.

Within Rails there is a strategy and tactics, the “Rails way” and the “Rails stack” consisting of all the “Active* Gems”. The strategy is to define what is common across applications. Then to provide that core as a default without any thought needed on the developers part. This is exactly the opposite of defining a domain language specifically for your problem. I am of the opinion that the “Rails Way” is incompatible with the strategy of Domain Driven Design.

Rails strategy is implemented with a well defined MVC architecture. MVC provides a clear way to break up an application into the three layers. However, there is no help in deciding how to break down an application further. The patterns from Domain Driven Design do however help with breaking down the domain model. It is certainly possible to use Domain Driven Design to break down a model with an MVC application. I am of the opinion that the “Rails Stack” is compatible within a domain driven application.

Other views

What about Domain Driven Design compared to hexagonal rails and clean architecture? The patterns of DDD are represented in both of these architectures. For example, clean architecture makes use of interactors to separate a delivery mechanism from a core of entities. Hexagonal Rails talks of ports in the domain for infrastructure adapters. The UI adapter is the delivery mechanism and a database adapter could be encapsulated by a repository.

The strategic side of Domain Driven Design is emphasised less in the other two. Patterns are suggested for technical benefits. Code is more extensible, more maintainable; easier to test. These improvements will of course lead to faster development cycles and happier clients/customers but the emphasis seems to be on the technical wins. I think this emphasis is important because DDD has a helpful dialogue on when not to implement any of the advanced patterns. Take for example the following hypothetical conversation.

After thrashing out the details we discovered that what the client wanted was a Rails app, so we build a Rails app.

This discussion focuses on the core of the Domain Driven Design strategy.

What’s next

I have been developing an example ddd project - it is a to-do list. It may be small but the strategy of DDD should be applicable to a project of any size. It is a work in progress and would be a great place to discuss DDD. Just open an issue if you think I can do it better.

A few parting thoughts on lessons I have learned:

If there is such a thing as strings in your domain their length method should return a number in centimeters
Prefer vertical grouping, section not layers
Do not redesign code for tests but if it’s hard to test, that is a warning
Design patterns are most useful for communication between humans

Resources

The Two Sides of Domain-Driven Design (DDD)
This post from Lev Gorodinski explores Domain-Driven Design from the tactical and strategic perspectives
Clean Architecture
A really comprehensive article on employing clean architecture with the Rails stack by Luis Zamith
Eric Evans on Domain-Driven Design at 10 Years
Really interesting chat with Eric Evans on the 10 years of Domain Driven Design since his book was released.
Just Job
A to-do list built from the ground up using the principles of Domain Driven Design(DDD)
Dicovering the joy of over design
The beginning of these articles, getting started with Domain Driven Design.

Introducing Interactors to represent getting stuff done.

Sun, 16 Aug 2015 16:56:05 +0000

Part 5 in Domain Drive Design series following on from Repositories.

What’s in a name?

Interactors suffer from a bit of an identity crisis. I have seen them called ‘interactors’, ‘use cases’ and ‘service objects’. Here is my take on each of those terms:

Service object is used to describe the encapsulation of an external service that your system uses. E.g. you might have an ‘email’ service object.

Use case makes the most sense on a non-technical level, so the ‘Login usecase’ is something that a customer does.

Interactor is the technical term for the Ruby object that is used to perform a given use case.

I believe ‘interactor’ is the most useful term when talking about an implementation and will therefore stick to that.

What are interactors?

An interactor orchestrates components in a system to complete a specific business use case. It is important that an interactor knows how to delegate — the desired result should be achieved without the interactor carrying out any of the work itself. It should also know nothing about how the result of its action will be presented to the user.

As something that is defined by what they do not do, it is tricky to see the value out of context. However the separation they enforce between the code that deals with rendering, HTTP, and sessions from the code with the important business logic rapidly increases in value as the system grows. It also removes dependence on any particular framework; when all the framework code is outside the interactors then it can be replaced whilst leaving the business logic untouched.

Basic Structure

An interaction can occur only once. A user many try the same interaction multiple times but as a different outcome is possible on each occasion it is classified as a separation interaction. What happens as the result of an interaction cannot be changed after it has occurred.

An instance of an interactor is used to represent a single interaction. To reflect the desired behaviour it is initialized with all of the required parameters and context; these cannot be modified after initialization. On the object the only methods that are available are query methods to report on what occurred. People often add success?/failure? methods but I try to use terms that are specific to the interaction such as created?/deleted?/approved?.

That interactors cannot be modified means they are immutable. Ruby makes immutability hard so I do not write any code to enforce this and simply follow the convention of only querying they response object.

An example interactor representing the user use case of creating a post for a blog might look something like the following.

# Inside a controller action
def create
  # Coerce insecure user input into the domain context
  form = CreatePostForm.new params[:post]

  # Run the use case passing in everything that is needed as arguments
  create_post = CreatePost.new self, form

  # Query the interactor instance on the outcome of the interaction
  if create_post.created?
    redirect_to post_url(create_post.post)
  else
    @form = create_post.form
    render :new
  end
end

# in a create_post.rb file
class CreatePost
  # initialize with the params in the form and the user in the context
  def initialize(context, form)
    @form = form
    @user = context.current_user
    run
  end

  attr_reader :form, :user, :post

  private

  def run
    if form.valid?
      @post = Post.create form
      @created = true
    end
  end

end

The controller action knows how to call an interactor as well as the methods it can query to find the outcome. The controller may not interact with the domain in any other way, all entities, values and services and invisible to it. The interactor does not know anything about the framework, the results it exposes have no knowledge of how they will be presented, i.e. there are no to_html methods. The controller or a dedicated presenter will convert the plain data objects into a rendered view.

The interactors demote a strong boundary between your domain code which should be pure ruby and your framework code which can be full of framework specific terms, from rails/sinatra/etc. This boundary allows you to test the two pieces in isolation.

Testing the domain

Testing the domain with interactors is easy because they explicitly passed all parameters during there initialization. The steps to test the domain are setup the arguments to be passed to the Interactor, initialize the interactor and finally query on the result. It is immutable so test can be run in any order. The benefits of this include.

There is no need to have a step where you log in the user. Just pass any user into the context
Any other awkward things like mailers or bug reporting can have null implementations, also part of the context.
All return values are Ruby objects and these are much easier to test on.

With interactors it also becomes much easier to write an integration test than to write a test that needs to make a HTTP request and understand HTML responses. This is an example of testing an interactor.

class CreatePostTest < Minitest::Test
  def valid_form
    CreatePostForm.new :title => 'A nice title'
  end

  def invalid_form
    CreatePostForm.new :title => '<script>bad code</script>'
  end

  def context
    OpenStruct.new :current_user => nullUser
  end

  def test_will_not_create_post_with_invalid_title
    create_post = CreatePost.new context, invalid_form
    refute create_post.created?
  end

  def test_will_create_post_with_valid_title
    create_post = CreatePost.new context, valid_form
    assert create_post.created?
  end
end

Compare this with the last test you wrote where you had to check an action from a logged in user which required RackTest or Capybara.

Testing the controllers and views

Working with interactors does not improve dealing with HTML parsing or setting up session data. In those test you will still want to make use of RackTest or Capybara. What it does do is make those tests a whole lot simpler. You can write a single test for each possible outcome for a given interactor where the outcome is stubbed. With one logical test for each usecase outcome you can escape from trying to test the domain through the unwieldy web based interface.

My interactor implementation AllSystems

It would certainly be possible to implement interactors without a gem. I am also a fan of less dependencies where possible. However using a very small gem allows me not have to keep checking the plumbing of my interactor objects. I have written a gem called AllSystems that allows blocks to be passed for each possible outcome. This follows the principle of tell don’t ask which is best laid out in the talk eastward oriented code.

So what do you think? Will you be tempted to try interactors or do you have a way to keep the framework you use encapsulated? Leave me a comment I will be very interested.

Resources

Anatomy of a Rails Service Object
Overview on designing a service object in rails from David Copeland. These are interactors as describe here and they should work outside of rails.
What service objects are not
Again called service objects this is a good post from Kamil Lelonek. Good advice on what does not belong in an interactor, hint it’s nearly everything.
Eastward Ho! A Clear Path Through Ruby With OO
One of the best talks online. Jim Gay gives advice for writing code that follows tell don’t ask.
AllSystems gem
Simple interactor objects in Ruby written by myself.

Untangle your Domain Model from the Database

Sun, 09 Aug 2015 20:20:06 +0000

Part 5 in Domain Drive Design series following on from Entities and Records.

The Domain Model is not just model objects

I have asserted that for any non-trivial program the modeling of the problem space should not be handled by individual model objects. Instead it should be handled through the coordinated action of many domain objects. In the last post we introduced entities and records to handle some of the concerns of modeling a system. In this post we discuss the repository pattern as a solution to our need to store and recover those entities and records.

I would recommend reading the post on Entities and Records first. Don’t want to? Well, in summary, records are dumb data stores where the state of the system resides. Entities are stateless wrappers for records that hold behaviour that requires some of the records contents. We do not need to know of the existence of the records and should interact with them only through the entities that wrap them.

The Problem of Persistence

The database is a small concern in a system. It is easy to forget this when developing in frameworks where you have to choose the database up front and where the methods on a model are exact reflections of your database schema. The littering of database concerns across the codebase is a distraction from writing the code most suited to your domain. For this reason we treat the database as a detail and want it isolated from the core entities.

We want to get to a stage where we have record objects that we do not interact with directly and entities that have no knowledge of the database. This is excellent — we have achieved separating knowledge of the database and the main behaviour of the application.

Now we need a way to persist the records. This task falls to a repository. The repository will be the only thing that knows the storage mechanism supporting the application.

Using a Repository

Here is a quick one sentence summary of the repository pattern by Martin Fowler:

A Repository mediates between the domain and data mapping layers, acting like an in-memory domain object collection.

Before proceeding we need to introduce the concept of an aggregate. In the last post we introduced two entities: a User and Credentials both of which wrapped a record object the User::Record. This collection of objects acted together to model a single user. Collections like this are described in Domain Driven Design as an aggregate. Martin Fowler provides an excellent summary on aggregates. This description comes with advice on handling these aggregates. Key is that one of the components should be recognisable as the aggregate root and any reference from outside the aggregate should go to the root only.

In our system the User is the root of the aggregate. This implies we should only be able to get load or save our user entity and the credentials it comes with and not directly load/save the credentials object. For this reason we need a repository of users and not one of credentials, this also explains why the record was named the User::Record as it is an implementation detail that will be used as a foundation to our User::Repository.

The key feature of our repository is that it should act as a collection of user entities. It does not need to look like a database and semantics of SQL or any other query language should not be evident in the API it exposes. The only difference between a repository and typical in-memory collection is that it will probably have a more sophisticated set of query methods than a normal collection.

Let’s design how we would like a repository to be used. We will want simple queries such as first and last. Retrieving by an id value is like a key lookup and so a [] method is useful; or even better, a fetch method. Then there will be queries that are specific to the collection; for example, finding all users by a family name.

I recommend designing your API with pagination in mind unless you are sure it is unnecessary. This is because adding it later can be trouble.

# Simple query
adam = User::Repository.first
# => #<User fullname="Adam Smith">

# Complex query, perhaps involving paginated results
johnes = User::Repository.family "johnes", page: 2
# => [#<User fullname="Emma Johnes">, #<User fullname="Kate Johnes">]

# Handling missing entries with useful null objects
user = User::Repository.fetch('ID_001') { GuestUser.new }
# => #<GuestUser>

# Building empty entities with correct record structures
new_user = User::Repository.build
# => #<User fullname="">

# Editing user
new_user.full_name = "Peter Saxton"
# => #<User fullname="Peter Saxton">

# Adding user to collection of users.
User::Repository.save new_user
# => #<User::Repository>

Building the Repository

Once we know how we would like to use our repository, we can set about implementing it. There are several ways to go about this but I always try to go for the simplest.

There are some very capable Object Relational Mappers available, the best being Sequel. I don’t want to reinvent handling SQL so I build on top of the Sequel library. The following implementation will realise the behaviour above:

class User::Repository
  class << self
    def build
      User.new User::Record.new
    end

    def save(entity)
      entity.record.save
      self
    end

    def remove(entity)
      entity.record.destroy
      self
    rescue Sequel::NoExistingObject
      raise RecordAbsent
    end

    def first
      record = User::Record.first
      User.new record
    end

    def last_login
      record = User::Record
        .sort(:last_login_at)
        .first
      User.new record
    end

    def family(last_name, page: 1, page_size: 15)
      records = User::Record
        .where(:last_name => last_name)
        .sort(:first_name)
        .paginate(page, page_size)
      records.map User.new
    end
  end
end

Design Overkill

This example repository does everything that is required of it. Despite that it fails on being elegant code. For example, the line entity.record.save goes against the good advice of The Law of Demeter.It is also implicitly dependent on the User::Record and User classes.

There are ways to fix some of these design complaints. If you would like to see some of these solutions have a look at Lotus Model or Ruby Object Mapper (ROM). However, in all the projects where I have employed a repository I have not gone much further than the code shown in the example above. As this series is all about well designed code and the benefits that can be got from doing the right thing, the question is: why do I stop here?

To make a generic repository that can be backed by a sequel backend or an in-memory backend is complex. It requires adapters and an in-memory implementation of storage. If queries are sophisticated then the in memory-adapter needs to support a similar set of queries.

Creating a generic query interface when I might never use it is overkill and so I choose to stick with the bad code. The saving grace with this dirty code is that it is contained within the repository.

Another reason to create a generic adapter to the database is to allow testing without the database in place. As shown in the previous post I can test entities without a database by replacing the record objects with simple OpenStructs. The remaining tests that can’t make this replacement are slower yet the number of tests are small because the repository is focused on handling only queries on the collection.

In reality I have found this level of sophistication in the repository a good compromise between isolated code and building adapters that might never be used. As ROM or the Lotus model mature I might find myself using these and getting the isolation I have currently traded away.

Have you tried using the repository pattern or perhaps employ the datamapper pattern? Let me know in the comments below.

The next post will be the last in the series and will introduce interactors. Then we can finally mate our domain model with the framework of choice and make our program available to the world.

Tackling God objects in Ruby applications

Sun, 02 Aug 2015 21:20:00 +0000

Part 4 in Domain Drive Design series following on from form objects.

The worst advice I have followed

Fat Model, Skinny controller

This advice is only good advice in that a fat model is slightly preferable to a fat controller. When creating projects with Rails I would have a single model for a single database table. So as a database table grows then data in the model representation grows. Object Oriented Programming (OOP) is about packaging behavior with data, as the data in the model increases the behavior on the model tends to follow this increase. Quite soon you end up with a fat model and shorty afterwards a God object. God objects are objects that seem to know and act upon all parts of the system. They are an antipattern that are in violation of the single responsibility principle.

Recently I have seen people blaming Rails and particularly ActiveRecord (the library) for encouraging God objects. ActiveRecord is a beast but also a fantastic piece of software. Most importantly it is a tool and doesn’t encourage or discourage God objects. ActiveRecord does, however, facilitate making over sized objects if you are not disciplined. What does encourage creating God objects is simplistic advice such as ‘fat model skinny controller’.

So what is good practise? Well I think that it is small, well defined, single responsibility objects everywhere.

The persistence problem

Handling the data in a single database table, sounds like a single responsibility so why not a single object. That is a valid starting point but for anything beyond a trivial application it is too simplistic. To break apart our model let’s look at some of the key functionality we need when handling a database table.

Data serialization. The database will not understand our domain objects, so we need to transform them to and from a format that the database does understand. We should do this as near the database as possible so that the database has the smallest possible influence on the rest of our code.
Querying. We will want to be able to fetch the correct items from our database. This may be simple or it may involve filtering on many fields, such as find all the declined orders for this month for customers who signed up more than a year ago.
Business Logic. What you want to accomplish with your data, this is specific to your problem and as such there is no limit to how complex this part might be.

Building a solution

First we want to separate querying, this functionality acts on the whole database table while the other two parts need to act of individual entries. To handle querying we will introduce repositories in the next post.

To split serialization and behavior I employ the decorator pattern. I have a core Record object that formats the data saved to it. Record objects are just dumb data buckets. Business logic is built into entities - each entity wraps a single record and has no state other that the record object it is decorating.

Records

These are the only objects anywhere in my system that know how data is stored in the database. We often don’t think about databases as out of our control but we did not build them and so the API is not of our design. Therefore it most likely will not be the best representation of data in our domain. For this reason Record objects act as gatekeepers to information from the database in a way analagous to form objects normalising input from user input.

The only logic a Record object should have should be packing domain objects into the database and initializing domain objects from entries in the database.

Talking to a database is a solved problem and I use an ORM, either ActiveRecord or Sequel. The benefits of using an ORM library is that I can write Record very quickly. However both ORMs have many features that allow them to act as far more than a data bucket. It is only by being disciplined that the functionality of a record remains serialization only.

class UserRecord < Sequel::Model(:users)
end

Entities

These objects encapsulate business logic and so have very little in common with each other, or across projects. The only consistent feature is that the are initialized with a record and that they cannot have any state on themselves. They must always update the record if something changes.

Multiple entity classes can be created for a single record class. These entities are separated by business concerns and there is no limit to how many can be made for a single record. Now the behavior can be built up of small manageable parts no matter how large our database table grows.

Other parts of the program should never need to interact with a record directly but only with an entity that is decorating it. Good DDD code should communicate in a language understood by the client. They will understand user but not ‘user entity’ or ‘user record’ for this reason the user is represented by the user entity and the user record is just an implementation detail

Examples

A very typical example would be similar to the following. A user represents the information kept in the users database table. There is a good amount of meta information associated with the account such as authentication credentials.

Following good design principles we have dedicated value objects for email, password and name. This means we have moved validation away from our entities. Our record layer will happily dump and load these value objects to the database. However features continue to be added and our user needs a combined full name and also the ability to authenticate. These methods are not part of the same set of responsibility and so we look for a way to separate them.

Authentication is often a good candidate to be separated to a single purpose entity. In this example we have done just that and named the extracted class ‘Credentials’.

class UserRecord < Sequel::Model(:users)
  # Turns database friendly representations of values in to rich objects specific to our domain
  plugin :serialization

  serialize_attributes [Email.method(:dump), Email.method(:load)], :email
  serialize_attributes [Password.method(:dump), Password.method(:load)], :password
  serialize_attributes [Name.method(:dump), Name.method(:load)], :first_name, :last_name
end

class User
  # Enities make no sense if they don't also have a record to preserve state
  def initialize(record)
    @record = record
  end

  attr_reader :record
  private :record

  # Behaviour that the user can handle itself.
  def full_name
    "#{record.first_name} #{record.last_name}"
  end

  def full_name=(full_name)
    first_name, last_name = full_name.split ' '
    record.first_name = first_name
    record.last_name = last_name
  end

  # Behaviour that the user delegates to a dedicated credentials object
  def authenticate(submitted_password)
    credentials.authenticate submitted_password
  end

  # The credentials object also uses the same record
  def credentials
    @credentials ||= Credentials.new record
  end
end

class Credentials
  def initialize(record)
    @record = record
  end

  attr_reader :record
  private :record

  # Logic for authentication can grow and is cleanly separated from the main user object
  def authenticate(submitted_password)
    return nil unless correct_password? submitted_password
    record_login
    self
  end

  private

  def correct_password?(submitted_password)
    record.password == submitted_password
  end

  def record_login(date_time = DateTime.now)
    self.last_login_at = date_time
  end
end

Testing

Testing records is done in much the same way as you would have tested methods on any ActiveRecord model. The main difference is that there should be much fewer tests and these tests should be simply setting a value and testing the same value is retrieved.

Tests that hit the database are slower because of their interaction with the database. I don’t stub the database out at this level as a record is only about talking to the database. These tests are few enough that slower tests are not a problem.

class UserRecordTests < MiniTest::Test
  # My helper to refresh the database after each test
  include DatabaseTesting

  def test_can_save_first_name
    # create domain object
    first_name = Name.new 'Peter'

    # set record entry
    record = UserRecord.new first_name: first_name

    # assert against domain object
    assert_equal first_name, record.first_name
  end
end

Testing for entities can easily be separated from the database by providing them with a stand in record. My tests all initialize the entity with an openstruct to stand in for the record. There are then two kinds of tests. First setting values on the openstruct and testing the entities behave correctly. Otherwise, manipulating the entity and asserting the correct values are in the openstruct

class UserTest < Minitest::Test
  def record
    @record ||= OpenStruct.new
  end

  def user
    @user = User.new record
  end

  def teardown
    @user = nil
    @record = nil
  end

  def test_user_has_correct_full_name
    # Setup record
    record.first_name = 'Peter'
    record.last_name = 'Saxton'

    # Check behavior
    assert_equal 'Peter Saxton', user.full_name
  end

  def test_user_sets_first_name_on_record
    # Manipulate user
    user.full_name = 'Peter Saxton'

    # Check record
    assert_equal 'Peter', record.first_name
  end

  def test_user_sets_last_name_on_record
    user.full_name = 'Peter Saxton'
    assert_equal 'Saxton', record.last_name
  end
end

Conclusion

This is my take on entities and records. I encourage you to give them a try as multiple entities can be an effective cure for god objects. This is not quite the whole persistence problem solved as we still need to pull the correct records out of our database. That is my next post and it’s on repositories.

Resources

Fat model skinney controller is a load of rubbish Don’t make my mistakes wish I had found this post earlier, thanks Jon Cairns
Skinny Controllers, Skinny Models Worth saying one more time, this time from thoughtbot and Joe Ferris
How I use ActiveRecord serialize with custom data types
Explaining the serialize method in active record by Zachary Porter
Building rich domain objects Separating models on similar lines using models, data objects and repositories from Victor Savkin