use_case 0.1.0

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+gemspec
+
+# Only used for tests
+gem "virtus", :git => "https://github.com/solnic/virtus.git"
+
+# Validations are optional, but required in order to test UseCase
+# itself
+gem "activemodel"

data/Gemfile.lock

@@ -0,0 +1,51 @@
+GIT
+  remote: https://github.com/solnic/virtus.git
+  revision: 97a161f19d20a961094112464075c284d68d35e4
+  specs:
+    virtus (1.0.0.beta1)
+      abstract_type (~> 0.0.5)
+      adamantium (~> 0.0.7)
+      backports (~> 3.0, >= 3.1.0)
+      coercible (~> 0.2)
+      descendants_tracker (~> 0.0.1)
+
+PATH
+  remote: .
+  specs:
+    use_case (0.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract_type (0.0.5)
+      backports (~> 3.0, >= 3.0.3)
+    activemodel (3.2.12)
+      activesupport (= 3.2.12)
+      builder (~> 3.0.0)
+    activesupport (3.2.12)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    adamantium (0.0.7)
+      backports (~> 3.0, >= 3.0.3)
+      ice_nine (~> 0.7.0)
+    backports (3.1.1)
+    builder (3.0.4)
+    coercible (0.2.0)
+      backports (~> 3.0, >= 3.1.0)
+      descendants_tracker (~> 0.0.1)
+    descendants_tracker (0.0.1)
+    i18n (0.6.4)
+    ice_nine (0.7.0)
+    minitest (4.7.0)
+    multi_json (1.6.1)
+    rake (10.0.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel
+  minitest (~> 4)
+  rake
+  use_case!
+  virtus!

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Gitorious AS
+
+Christian Johansen (christian@gitorious.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/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << "test"
+  test.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test

data/Readme.md

@@ -0,0 +1,298 @@
+# Use Case
+
+Compose non-trivial business logic into use cases, that combine:
+
+* Input parameter abstractions; type safety and coercion, and white-listing of
+  supported input for any given operation
+* Pre-conditions: System-level conditions that must be met, e.g. "a user must be
+  logged in" etc.
+* Input parameter validation: ActiveRecord-like validations as composable
+  objects. Combine specific sets of validation rules for the same input in
+  different contexts etc.
+* Commands: Avoid defensive coding by performing the core actions in commands
+  that receive type-converted input, and are only executed when pre-conditions
+  are met and input validated.
+
+## Example
+
+At its very simplest, a use case wraps a command. A command is any Ruby object
+with an `execute` method that receives one argument (input parameters). Because
+UseCase is intended as a mechanism for implementing non-trivial use cases, the
+following contrived example will seem particularly useless.
+
+```rb
+require "use_case"
+
+class HelloWorldCommand
+  def execute(params)
+    puts "Hello, #{params[:place]}!"
+  end
+end
+
+class PrintHelloWorld
+  include UseCase
+
+  def initialize
+    command(HelloWorldCommand.new)
+  end
+end
+
+# Usage
+PrintHelloWorld.new.execute(:place => "World")
+```
+
+Not that you are free to design your constructors any way you want.
+
+## Useful example
+
+A more useful example will use every aspect of a `UseCase`. Pre-conditions are
+conditions not directly related to input parameters, and whose failure signifies
+other forms of errors than simple validation errors. If you have a Rails
+application that uses controller filters, then those are very likely good
+candidates for pre-conditions.
+
+The following example is a simplified use case from
+[Gitorious](http://gitorious.org) where we want to create a new repository. To
+do this, we need a user that can admin the project under which we want the new
+repository to live.
+
+This example illustrates how to solve common design challenges in Rails
+applications, but that does not mean that `UseCase` is only useful to Rails
+applications.
+
+```rb
+require "use_case"
+require "virtus"
+
+# Input parameters can be sanitized and pre-processed anyway you like. One nice
+# way to go about it is to use Datamapper 2's Virtus gem to define a parameter
+# set.
+#
+# This class uses Project.find to look up a project by id if project_id is
+# provided and project is not. This is the only class that has
+class NewRepositoryInput
+  include Virtus
+  attribute :name, String
+  attribute :description, String
+  attribute :project, Project
+  attribute :project_id, Integer
+
+  def project
+    @project ||= Project.find(@project_id)
+  end
+end
+
+# Validate new repositories. Extremely simplified example.
+NewRepositoryValidator = UseCase::Validator.define do
+  validates_presence_of :name, :project
+end
+
+# This is often implemented as a controller filter in many Rails apps.
+# Unfortunately that means we have to duplicate the check when exposing the use
+# case in other contexts (e.g. a stand-alone API app, console API etc).
+class UserLoggedInPrecondition
+  # The constructor is only used by us and can look and do whever we want
+  def initialize(user)
+    @user = user
+  end
+
+  # A pre-condition must define this method
+  # Params is an instance of NewRepositoryInput
+  def satiesfied?(params)
+    !@user.nil?
+  end
+end
+
+# Another pre-condition that uses app-wide state
+class ProjectAdminPrecondition
+  def initialize(auth, user)
+    @auth = auth
+    @user = user
+  end
+
+  def satiesfied?(params)
+    @auth.can_admin?(@user, params.project)
+  end
+end
+
+# The business logic. Here we can safely assume that all pre-conditions are
+# satiesfied, and that input is valid and has the correct type.
+class CreateRepositoryCommand
+  def initialize(user)
+    @user = user
+  end
+
+  # Params is an instance of NewRepositoryInput
+  def execute(params)
+    params.project.repositories.create(:name => params.name, :user => @user)
+  end
+end
+
+# The UseCase - this is just wiring together the various classes
+class CreateRepository
+  include UseCase
+
+  # There's no contract to satiesfy with the constructor - design it to receive
+  # any dependencies you need.
+  def initialize(auth, user)
+    input_class(NewRepositoryInput)
+    pre_condition(UserLoggedInPrecondition.new(user))
+    pre_condition(ProjectAdminPrecondition.new(auth, user))
+    # Multiple validators can be added if needed
+    validator(NewRepositoryValidator)
+    command(CreateRepositoryCommand.new(user))
+  end
+end
+
+# Finally, the actual usage. This example is a Rails controller
+class RepositoryController < ApplicationController
+  include Gitorious::Authorization # Adds stuff like can_admin?(actor, thing)
+
+  # ...
+
+  def create
+    outcome = CreateRepository.new(self, current_user).execute(params)
+
+    outcome.pre_condition_failed do |condition|
+      redirect_to(login_path) and return if condition.is_a?(UserLoggedInPrecondition)
+      flash[:error] = "You're not allowed to do that"
+      redirect_to project_path
+    end
+
+    outcome.failure do |model|
+      # Render form with validation errors
+      render :new, :locals => { :repository => model }
+    end
+
+    outcome.success do |repository|
+      redirect_to(repository_path(repository))
+    end
+  end
+end
+```
+
+## Input sanitation
+
+In your `UseCase` instance (typically in the constructor), you can call the
+`input_class` method to specify which class is used to santize inputs. If you do
+not use this, inputs are forwarded to pre-conditions and commands untouched
+(i.e. as a `Hash`).
+
+Datamapper 2's [Virtus](https://github.com/solnic/virtus) is a very promising
+solution for input sanitation and some level of type-safety. If you provide a
+`Virtus` backed class as `input_class` you will get an instance of that class as
+`params` in pre-conditions and commands.
+
+## Validations
+
+The validator uses `ActiveModel::Validations`, so any Rails validation can go in
+here. The main difference is that the validator is created as a stand-alone
+object that can be used with any model instance. This design allows you to
+define multiple context-sensitive validations for a single object.
+
+You can of course provide your own validation if you want - any object that
+defines `call(object)` and returns something that responds to `valid?` is good.
+I am following the Datamapper project closely in this area.
+
+Because `UseCase::Validation` is not a required part of `UseCase`, and people
+may want to control their own dependencies, `activemodel` is _not_ a hard
+dependency. To use this feature, `gem install activemodel`.
+
+## Pre-conditions
+
+A pre-condition is any object that responds to `satiesfied?(params)` where
+params will either be a `Hash` or an instance of whatever you passed to
+`input_class`. The method should return `true/false`. If it raises, the outcome
+of the use case will call the `pre_condition_failed` block with the raised
+error. If it fails, the `pre_condition_failed` block will be called with the
+pre-condition instance that failed.
+
+## Commands
+
+A command is any Ruby object that defines an `execute(params)` method. Its
+return value will be passed to the outcome's `success` block. Any errors raised
+by this method is not rescued, so be sure to wrap `use_case.execute(params)` in
+a rescue block if you're worried that it raises.
+
+## Use cases
+
+A use case simply glues together all the components. Define a class, include
+`UseCase`, and configure the instance in the constructor. The constructor can
+take any arguments you like, making this solution suitable for DI (dependency
+injection) style designs.
+
+The use case can optionally call `input_class` once, `pre_condition` multiple
+times, and `validator` multiple times. It *must* call `command` once with the
+command object.
+
+## Outcomes
+
+`UseCase#execute` returns an `Outcome`. You can use the outcome in primarily two
+ways. The primary approach is one that takes blocks for the three situations:
+`success(&block)`, `failure(&block)`, and `pre_condition_failed(&block)`. Only
+one of these will ever be called. This allows you to declaratively describe
+further flow in your program.
+
+For use on the console and other situations, this style is not the most
+convenient. For that reason each of the three methods above can also be called
+without a block, and they always return something:
+
+* `success` returns the command result
+* `failure` returns the validation object (e.g. `failure.errors.inspect`)
+* `pre_condition_failed` returns the pre-condition that failed, *or* an
+  exception object, if a pre-condition raised an exception.
+
+In addition to these, the outcome object responds to `success?` and
+`pre_condition_failed?`.
+
+## Inspiration and design considerations
+
+This small library is very much inspired by
+[Mutations](http://github.com/cypriss/mutations). Nice as it is, I found it to
+be a little limiting in terms of what kinds of commands it could comfortably
+encapsulate. Treating everything as a hash of inputs makes it hard to do things
+like "redirect if there's no user, render form if there are validation errors
+and redirect to new object if successful".
+
+As I started working on my own solution I quickly recognized the power in
+separating input parameter type constraints/coercions from validation rules.
+This is another area where UseCase differs from Mutations. UseCase is probably
+slightly more "enterprise" than Mutations, but fits the kinds of problems I
+intend to solve with it better than Mutations did.
+
+## Testing
+
+Using UseCase will allow you to test almost all logic completely without loading
+Rails. In the example above, the input conversion is the only place that
+directly touches any classes from the Rails application. The rest of the classes
+work by the "data in, data out" principle, meaning you can easily test them with
+any kind of object (which spares you of loading heavy ActiveRecord-bound models,
+running opaque controller tets etc).
+
+## License
+
+UseCase is free software licensed under the MIT license.
+
+```
+The MIT License (MIT)
+
+Copyright (C) 2013 Gitorious AS
+
+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/lib/use_case.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "use_case/outcome"
+require "use_case/validator"
+require "ostruct"
+
+module UseCase
+  def input_class(input_class)
+    @input_class = input_class
+  end
+
+  def validator(validator)
+    validators << validator
+  end
+
+  def pre_condition(pc)
+    pre_conditions << pc
+  end
+
+  def command(command)
+    @command = command
+  end
+
+  def execute(params)
+    input = @input_class && @input_class.new(params) || params
+
+    if outcome = verify_pre_conditions(input)
+      return outcome
+    end
+
+    if outcome = validate_params(input)
+      return outcome
+    end
+
+    SuccessfulOutcome.new(self, @command.execute(input))
+  end
+
+  private
+  def verify_pre_conditions(input)
+    pre_conditions.each do |pc|
+      begin
+        return PreConditionFailed.new(self, pc) if !pc.satiesfied?(input)
+      rescue Exception => err
+        return PreConditionFailed.new(self, err)
+      end
+    end
+    nil
+  end
+
+  def validate_params(input)
+    validators.each do |validator|
+      result = validator.call(input)
+      return FailedOutcome.new(self, result) if !result.valid?
+    end
+    nil
+  end
+
+  def pre_conditions; @pre_conditions ||= []; end
+  def validators; @validators ||= []; end
+end

data/lib/use_case/outcome.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+
+module UseCase
+  class Outcome
+    attr_reader :use_case
+
+    def initialize(use_case = nil)
+      @use_case = use_case
+    end
+
+    def pre_condition_failed?; false; end
+    def success?; false; end
+    def success; end
+    def pre_condition_failed; end
+    def failure; end
+  end
+
+  class SuccessfulOutcome < Outcome
+    def initialize(use_case = nil, result = nil)
+      super(use_case)
+      @result = result
+    end
+
+    def success?; true; end
+
+    def success
+      yield @result if block_given?
+      @result
+    end
+
+    def to_s
+      "#<UseCase::SuccessfulOutcome: #{@result}>"
+    end
+  end
+
+  class PreConditionFailed < Outcome
+    def initialize(use_case = nil, pre_condition = nil)
+      super(use_case)
+      @pre_condition = pre_condition
+    end
+
+    def pre_condition_failed?; true; end
+
+    def pre_condition_failed
+      yield @pre_condition if block_given?
+      @pre_condition
+    end
+
+    def to_s
+      "#<UseCase::PreConditionFailed: #{@pre_condition}>"
+    end
+  end
+
+  class FailedOutcome < Outcome
+    def initialize(use_case = nil, errors = nil)
+      super(use_case)
+      @errors = errors
+    end
+
+    def failure
+      yield @errors if block_given?
+      @errors
+    end
+
+    def to_s
+      "#<UseCase::FailedOutcome: #{@errors}>"
+    end
+  end
+end

data/lib/use_case/validator.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "active_model"
+
+module UseCase
+  module Validator
+    def self.define(&block)
+      klass = Class.new do
+        include ActiveModel::Validations
+
+        def initialize(target)
+          @target = target
+        end
+
+        def method_missing(name, *args, &block)
+          @target.send(name, *args, &block)
+        end
+
+        def self.call(object)
+          validator = new(object)
+          validator.valid?
+          validator
+        end
+      end
+
+      klass.instance_eval(&block)
+      klass
+    end
+  end
+end

data/lib/use_case/version.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+
+module UseCase
+  VERSION = "0.1.0"
+end

data/test.rb

@@ -0,0 +1,96 @@
+require "virtus"
+require "use_case"
+
+class Project
+  attr_reader :title
+  def initialize(title); @title = title; end
+  def self.find(id); new("<Project> My name is #{id}"); end
+end
+
+class User
+  attr_reader :name
+  def initialize(name); @name = name; end
+  def self.find(id); new("<User> My name is #{id}"); end
+end
+
+class NewRepositoryInput
+  include Virtus
+
+  attribute :name, String
+  attribute :description, String
+  attribute :merge_requests_enabled, Boolean, :default => true
+  attribute :private_repository, Boolean, :default => true
+
+  attribute :user, User
+  attribute :user_id, Integer
+  attribute :project, Project
+  attribute :project_id, Integer
+
+  def project; @project ||= Project.find(@project_id); end
+  def user; @user ||= User.find(@user_id); end
+end
+
+class NewRepositoryValidator
+  include UseCase::Validator
+  validates_presence_of :name, :description, :merge_requests_enabled, :private_repository
+end
+
+class UserLoggedInPrecondition
+  def initialize(user)
+    @user = user
+  end
+
+  def satiesfied?(params)
+    @user[:id] == 42
+  end
+end
+
+class ProjectAdminPrecondition
+  def initialize(user)
+    @user = user
+  end
+
+  def satiesfied?(params)
+    @user[:name] == params.name
+  end
+end
+
+class CreateRepositoryCommand
+  def initialize(user)
+    @user = user
+  end
+
+  def execute(params)
+    @user.merge(params)
+  end
+end
+
+class CreateRepository
+  include UseCase
+
+  def initialize(user)
+    input_class(NewRepositoryInput)
+    pre_condition(UserLoggedInPrecondition.new(user))
+    pre_condition(ProjectAdminPrecondition.new(user))
+    validator(NewRepositoryValidator)
+    command(CreateRepositoryCommand.new(user))
+  end
+end
+
+### Example
+
+outcome = CreateRepository.new({ :id => 42, :name => "Boy" }).execute({ :name => "Boy" })
+
+outcome.precondition_failed do |pc|
+  puts "Pre-condition failed! #{pc}"
+end
+
+outcome.success do |result|
+  puts "Your request was successful! #{result}"
+end
+
+outcome.failure do |errors|
+  puts "There was a failure #{errors}"
+end
+
+puts outcome.to_s

data/test/sample_use_case.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "virtus"
+require "use_case"
+
+class Model
+  attr_reader :id, :name
+
+  def initialize(id, name)
+    @id = id
+    @name = name
+  end
+
+  def to_s; "#<#{self.class.name}[id: #{id}, name: #{name}]>"; end
+  def self.find(id); new(id, "From #{self.class.name}.find"); end
+end
+
+class Project < Model; end
+class Repository < Model; end
+
+class User < Model
+  def can_admin?; @can_admin; end
+  def can_admin=(ca); @can_admin = ca; end
+end
+
+class NewRepositoryInput
+  include Virtus
+  attribute :name, String
+end
+
+NewRepositoryValidator = UseCase::Validator.define do
+  validates_presence_of :name
+end
+
+class UserLoggedInPrecondition
+  def initialize(user); @user = user; end
+  def satiesfied?(params); @user && @user.id == 42; end
+end
+
+class ProjectAdminPrecondition
+  def initialize(user); @user = user; end
+  def satiesfied?(params); @user.can_admin?; end
+end
+
+class CreateRepositoryCommand
+  def initialize(user); @user = user; end
+  def execute(params); Repository.new(1349, params.name); end
+end
+
+class CreateRepository
+  include UseCase
+
+  def initialize(user)
+    input_class(NewRepositoryInput)
+    pre_condition(UserLoggedInPrecondition.new(user))
+    pre_condition(ProjectAdminPrecondition.new(user))
+    validator(NewRepositoryValidator)
+    command(CreateRepositoryCommand.new(user))
+  end
+end
+
+class ExplodingRepository
+  include UseCase
+
+  def initialize(user)
+    cmd = CreateRepositoryCommand.new(user)
+    def cmd.execute(params); raise "Crash!"; end
+    command(cmd)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "bundler/setup"
+require "minitest/autorun"
+
+Bundler.require(:default, :test)

data/test/use_case/outcome_test.rb

@@ -0,0 +1,144 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "test_helper"
+require "use_case/outcome"
+
+describe UseCase::Outcome do
+  it "exposes use case" do
+    use_case = 42
+    outcome = UseCase::Outcome.new(use_case)
+
+    assert_equal use_case, outcome.use_case
+  end
+
+  it "defaults to not failing and not being successful (noop)" do
+    outcome = UseCase::Outcome.new
+    outcome.success { fail "Shouldn't succeed" }
+    outcome.pre_condition_failed { fail "Shouldn't have failed pre-conditions" }
+    outcome.failure { fail "Shouldn't fail" }
+
+    refute outcome.pre_condition_failed?
+    refute outcome.success?
+  end
+
+  describe UseCase::SuccessfulOutcome do
+    it "exposes use case" do
+      use_case = { :id => 42 }
+      outcome = UseCase::SuccessfulOutcome.new(use_case)
+
+      assert_equal use_case, outcome.use_case
+    end
+
+    it "does not fail" do
+      outcome = UseCase::SuccessfulOutcome.new
+      outcome.pre_condition_failed { fail "Shouldn't have failed pre-conditions" }
+      outcome.failure { fail "Shouldn't fail" }
+
+      refute outcome.pre_condition_failed?
+      assert outcome.success?
+    end
+
+    it "yields and returns result" do
+      result = 42
+      yielded_result = nil
+      outcome = UseCase::SuccessfulOutcome.new(nil, result)
+      returned_result = outcome.success { |res| yielded_result = res }
+
+      assert_equal result, yielded_result
+      assert_equal result, returned_result
+    end
+
+    it "gets result without block" do
+      outcome = UseCase::SuccessfulOutcome.new(nil, 42)
+      assert_equal 42, outcome.success
+    end
+  end
+
+  describe UseCase::PreConditionFailed do
+    it "exposes use case" do
+      use_case = { :id => 42 }
+      outcome = UseCase::PreConditionFailed.new(use_case)
+
+      assert_equal use_case, outcome.use_case
+    end
+
+    it "does not succeed or fail" do
+      outcome = UseCase::PreConditionFailed.new
+      outcome.success { fail "Shouldn't succeed" }
+      outcome.failure { fail "Shouldn't fail" }
+
+      assert outcome.pre_condition_failed?
+      refute outcome.success?
+    end
+
+    it "yields and returns failed pre-condition" do
+      pre_condition = 42
+      yielded_pc = nil
+      outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+      returned_pc = outcome.pre_condition_failed { |pc| yielded_pc = pc }
+
+      assert_equal pre_condition, yielded_pc
+      assert_equal pre_condition, returned_pc
+    end
+
+    it "gets pre_condition without block" do
+      outcome = UseCase::PreConditionFailed.new(nil, 42)
+      assert_equal 42, outcome.pre_condition_failed
+    end
+  end
+
+  describe UseCase::FailedOutcome do
+    it "exposes use case" do
+      use_case = { :id => 42 }
+      outcome = UseCase::FailedOutcome.new(use_case)
+
+      assert_equal use_case, outcome.use_case
+    end
+
+    it "does not succeed or fail pre-conditions" do
+      outcome = UseCase::FailedOutcome.new
+      outcome.success { fail "Shouldn't succeed" }
+      outcome.pre_condition_failed { fail "Shouldn't fail pre-conditions" }
+
+      refute outcome.pre_condition_failed?
+      refute outcome.success?
+    end
+
+    it "yields and returns validation failure" do
+      failure = 42
+      yielded_result = nil
+      outcome = UseCase::FailedOutcome.new(nil, failure)
+      returned_result = outcome.failure { |result| yielded_result = result }
+
+      assert_equal failure, yielded_result
+      assert_equal failure, returned_result
+    end
+
+    it "gets failure without block" do
+      outcome = UseCase::FailedOutcome.new(nil, 42)
+      assert_equal 42, outcome.failure
+    end
+  end
+end

data/test/use_case/validator_test.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "test_helper"
+require "use_case/validator"
+
+NewPersonValidator = UseCase::Validator.define do
+  validates_presence_of :name
+end
+
+class Person
+  attr_accessor :name
+end
+
+describe UseCase::Validator do
+  it "passes valid object" do
+    person = Person.new
+    person.name = "Christian"
+    result = NewPersonValidator.call(person)
+
+    assert result.valid?
+  end
+
+  it "fails invalid object" do
+    result = NewPersonValidator.call(Person.new)
+
+    refute result.valid?
+    assert_equal 1, result.errors.count
+  end
+end

data/test/use_case_test.rb

@@ -0,0 +1,91 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2013 Gitorious AS
+#
+# 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.
+#++
+require "test_helper"
+require "use_case"
+require "sample_use_case"
+
+describe UseCase do
+  before do
+    @logged_in_user = User.new(42, "Christian")
+    @logged_in_user.can_admin = true
+  end
+
+  it "fails first pre-condition; no user logged in" do
+    outcome = CreateRepository.new(nil).execute({})
+
+    outcome.pre_condition_failed do |pc|
+      assert_equal UserLoggedInPrecondition, pc.class
+    end
+  end
+
+  it "fails second pre-condition; user cannot admin" do
+    @logged_in_user.can_admin = false
+    outcome = CreateRepository.new(@logged_in_user).execute({})
+
+    outcome.pre_condition_failed do |pc|
+      assert_equal ProjectAdminPrecondition, pc.class
+    end
+  end
+
+  it "fails with error if pre-condition raises" do
+    def @logged_in_user.id; raise "Oops!"; end
+    outcome = CreateRepository.new(@logged_in_user).execute({})
+
+    outcome.pre_condition_failed do |pc|
+      assert_equal RuntimeError, pc.class
+    end
+  end
+
+  it "fails on input validation" do
+    outcome = CreateRepository.new(@logged_in_user).execute({})
+
+    validation = outcome.failure do |v|
+      refute v.valid?
+      assert_equal 1, v.errors.count
+      assert v.errors[:name]
+    end
+
+    refute_nil validation
+  end
+
+  it "executes command" do
+    outcome = CreateRepository.new(@logged_in_user).execute({ :name => "My repository" })
+
+    result = outcome.success do |res|
+      assert_equal "My repository", res.name
+      assert res.is_a?(Repository)
+    end
+
+    refute_nil result
+  end
+
+  it "raises if command raises" do
+    use_case = ExplodingRepository.new(@logged_in_user)
+
+    assert_raises RuntimeError do
+      use_case.execute(nil)
+    end
+  end
+end

data/use_case.gemspec

@@ -0,0 +1,19 @@
+require "./lib/use_case/version"
+
+Gem::Specification.new do |s|
+  s.name = "use_case"
+  s.version = UseCase::VERSION
+  s.author = "Christian Johansen"
+  s.email = "christian@gitorious.com"
+  s.homepage = "http://gitorious.org/gitorious/use_case"
+  s.summary = s.description = ""
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files test`.split("\n")
+  s.require_path = "lib"
+
+  s.add_development_dependency "minitest", "~> 4"
+  s.add_development_dependency "rake"
+
+  s.required_ruby_version = ">= 1.9.2"
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: use_case
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Christian Johansen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email: christian@gitorious.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- Rakefile
+- Readme.md
+- lib/use_case.rb
+- lib/use_case/outcome.rb
+- lib/use_case/validator.rb
+- lib/use_case/version.rb
+- test.rb
+- test/sample_use_case.rb
+- test/test_helper.rb
+- test/use_case/outcome_test.rb
+- test/use_case/validator_test.rb
+- test/use_case_test.rb
+- use_case.gemspec
+homepage: http://gitorious.org/gitorious/use_case
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: ''
+test_files:
+- test/sample_use_case.rb
+- test/test_helper.rb
+- test/use_case/outcome_test.rb
+- test/use_case/validator_test.rb
+- test/use_case_test.rb