use_case 0.6.0 → 0.7.0

data/Readme.md

@@ -155,11 +155,12 @@ class CreateRepository
   # any dependencies you need.
   def initialize(auth, user)
     input_class(NewRepositoryInput)
-    pre_condition(UserLoggedInPrecondition.new(user))
-    pre_condition(ProjectAdminPrecondition.new(auth, user))
-    # A command has 0, 1 or many validators (e.g. :validators => [...])
-    # The use case can span multiple commands (see below)
-    command(CreateRepositoryCommand.new(user), :validator => NewRepositoryValidator)
+    add_pre_condition(UserLoggedInPrecondition.new(user))
+    add_pre_condition(ProjectAdminPrecondition.new(auth, user))
+    # A step is comprised of a command with 0, 1 or many validators
+    # (e.g. :validators => [...])
+    # The use case can span multiple steps (see below)
+    step(CreateRepositoryCommand.new(user), :validator => NewRepositoryValidator)
   end
 end
 ```
@@ -170,17 +171,25 @@ This is the high-level overview of how `UseCase` strings up a pipeline
 for you to plug in various kinds of business logic:
 
 ```
-User input (-> input sanitation) (-> pre-conditions) [(-> builder) (-> validations) -> command]*
+User input (-> input sanitation) (-> pre-conditions) -> steps
 ```
 
 1. Start with a hash of user input
 2. Optionally wrap this in an object that performs type-coercion,
    enforces types etc.
 3. Optionally run pre-conditions on the santized input
-4. Optionally refine input by running it through a pre-execution "builder"
-5. Optionally run (refined) input through one or more validators
-6. Execute command(s) with (refined) input
-7. Repeat steps 4-7 as necessary
+4. Execute steps. The initial step is fed the sanitized input, each
+   following command is fed the result from the previous step.
+
+Each step is a pipeline in its own right:
+
+```
+Step: (-> builder) (-> validations) -> command
+```
+
+1. Optionally refine input by running it through a pre-execution "builder"
+2. Optionally run (refined) input through one or more validators
+3. Execute command with (refined) input
 
 ## Input sanitation
 
@@ -222,27 +231,26 @@ dependency. To use this feature, `gem install activemodel`.
 
 ## Builders
 
-When user input has passed input sanitation and pre-conditions have
-been satisfied, you can optionally pipe input through a "builder"
-before handing it over to validations and a command.
+When user input has passed input sanitation and pre-conditions have been
+satisfied, you can optionally pipe input through a "builder" before handing it
+over to validations and a command.
 
 The builder should be an object with a `build` or a `call` method (if it has
 both, `build` will be preferred). The method will be called with santized input.
 The return value will be passed on to validators and the commands.
 
-Builders can be useful if you want to run validations on a domain
-object rather than directly on "dumb" input.
+Builders can be useful if you want to run validations on a domain object rather
+than directly on "dumb" input.
 
 ### Example
 
-In a Rails application, the builder is useful to wrap user input in an
-unsaved `ActiveRecord` instance. The unsaved object will be run
-through the validators, and (if found valid), the command can save it
-and perform additional tasks that you possibly do with `ActiveRecord`
-observers now.
+In a Rails application, the builder is useful to wrap user input in an unsaved
+`ActiveRecord` instance. The unsaved object will be run through the validators,
+and (if found valid), the command can save it and perform additional tasks that
+you possibly do with `ActiveRecord` observers now.
 
-This example also shows how to express uniqueness validators when you
-move validations out of your `ActiveRecord` models.
+This example also shows how to express uniqueness validators when you move
+validations out of your `ActiveRecord` models.
 
 ```rb
 require "activemodel"
@@ -289,7 +297,7 @@ class CreateUser
     input_class(NewUserInput)
     cmd = NewUserCommand.new
     # Use the command as a builder too
-    command(cmd, :builder => cmd, :validator => UserValidator)
+    step(cmd, :builder => cmd, :validator => UserValidator)
   end
 end
 
@@ -299,19 +307,59 @@ outcome.success? #=> true
 outcome.result #=> #<User name: "Chris">
 ```
 
+If the command fails to execute due to validation errors, using the builder
+allows us to access the partial object for re-rendering forms etc. Because this
+is such a common scenario, the command will automatically be used as the builder
+as well if there is no explicit `:builder` option, and the command responds to
+`build`. This means that the command in the previous example could be written as
+so:
+
+```rb
+class CreateUser
+  include UseCase
+
+  def initialize
+    input_class(NewUserInput)
+    step(NewUserCommand.new, :validator => UserValidator)
+  end
+end
+```
+
+When calling `execute` on this use case, we can observe the following flow:
+
+```rb
+# This
+params = { :name => "Dude" }
+CreateUser.new.execute(params)
+
+# ...roughly expands to:
+# (command is the command instance wired in the use case constructor)
+input = NewUserInput.new(params)
+prepared = command.build(input)
+
+if UserValidator.call(prepared).valid?
+  command.execute(prepared)
+end
+```
+
 ### Note
 
-I'm not thrilled by `builder` as a name/concept. Suggestions for a
-better name is welcome.
+I'm not thrilled by `builder` as a name/concept. Suggestions for a better name
+is welcome.
 
 ## Commands
 
-A command is any Ruby object that defines an `execute(params)` method. Its
+A command is any Ruby object that defines an `execute(params)` method.
+Alternately, it can be an object that responds to `call` (e.g. a lambda). 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. Better yet, detect known causes
 of exceptions in a pre-condition so you know that the command does not raise.
 
+If the command responds to the `build` message and there is no explicitly
+configured `:builder` for the current step, the command is also used as a
+builder (see example above, under "Builders").
+
 ## Use cases
 
 A use case simply glues together all the components. Define a class, include
@@ -319,16 +367,16 @@ A use case simply glues together all the components. Define a class, include
 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 `command` multiple times.
+The use case can optionally call `input_class` once, `add_pre_condition`
+multiple times, and `step` multiple times.
 
-When using multiple commands, input sanitation with the `input_class` is
+When using multiple steps, input sanitation with the `input_class` is
 performed once only. Pre-conditions are also only checked once - before any
-commands are executed. The use case will then execute the commands:
+steps are executed. The use case will then execute the steps:
 
 ```
-command_1: sanitizied_input -> (builder ->) (validators ->) command
-command_n: command_n-1 result -> (builder ->) (validators ->) command
+step_1: sanitizied_input -> (builder ->) (validators ->) command
+step_n: command_n-1 result -> (builder ->) (validators ->) command
 ```
 
 In other words, all commands except the first one will be executed with the

data/lib/use_case/version.rb

@@ -24,5 +24,5 @@
 #++
 
 module UseCase
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/use_case.rb

@@ -31,13 +31,13 @@ module UseCase
     @input_class = input_class
   end
 
-  def pre_condition(pc)
+  def add_pre_condition(pc)
     pre_conditions << pc
   end
 
-  def command(command, options = {})
-    @commands ||= []
-    @commands << {
+  def step(command, options = {})
+    @steps ||= []
+    @steps << {
       :command => command,
       :builder => options[:builder],
       :validators => Array(options[:validators] || options[:validator])
@@ -51,23 +51,27 @@ module UseCase
       return outcome
     end
 
-    execute_commands(@commands, input)
+    execute_steps(@steps, input)
   end
 
   private
-  def execute_commands(commands, params)
-    result = commands.inject(params) do |input, command|
+  def execute_steps(steps, params)
+    result = steps.inject(params) do |input, step|
       begin
-        input = prepare_input(input, command[:builder])
+        input = prepare_input(input, step)
       rescue Exception => err
         return PreConditionFailed.new(self, err)
       end
 
-      if outcome = validate_params(input, command[:validators])
+      if outcome = validate_params(input, step[:validators])
         return outcome
       end
 
-      command[:command].execute(input)
+      if step[:command].respond_to?(:execute)
+        step[:command].execute(input)
+      else
+        step[:command].call(input)
+      end
     end
 
     SuccessfulOutcome.new(self, result)
@@ -84,10 +88,11 @@ module UseCase
     nil
   end
 
-  def prepare_input(input, builder)
-    return input if !builder
+  def prepare_input(input, step)
+    builder = step[:builder] || step[:command]
     return builder.build(input) if builder.respond_to?(:build)
-    builder.call(input)
+    return step[:builder].call(input) if step[:builder]
+    input
   end
 
   def validate_params(input, validators)

data/test/sample_use_case.rb

@@ -74,9 +74,9 @@ class CreateRepository
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    pre_condition(UserLoggedInPrecondition.new(user))
-    pre_condition(ProjectAdminPrecondition.new(user))
-    command(CreateRepositoryCommand.new(user), :validators => NewRepositoryValidator)
+    add_pre_condition(UserLoggedInPrecondition.new(user))
+    add_pre_condition(ProjectAdminPrecondition.new(user))
+    step(CreateRepositoryCommand.new(user), :validators => NewRepositoryValidator)
   end
 end
 
@@ -86,7 +86,7 @@ class ExplodingRepository
   def initialize(user)
     cmd = CreateRepositoryCommand.new(user)
     def cmd.execute(params); raise "Crash!"; end
-    command(cmd)
+    step(cmd)
   end
 end
 
@@ -104,7 +104,7 @@ class CreateRepositoryWithBuilder
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    command(CreateRepositoryCommand.new(user), {
+    step(CreateRepositoryCommand.new(user), {
         :validators => NewRepositoryValidator,
         :builder => RepositoryBuilder
       })
@@ -116,13 +116,20 @@ class CreateRepositoryWithExplodingBuilder
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    command(CreateRepositoryCommand.new(user), :builder => self)
+    step(CreateRepositoryCommand.new(user), :builder => self)
   end
 
   def build; raise "Oops"; end
 end
 
 class PimpRepositoryCommand
+  def execute(repository)
+    repository.name += " (Pimped)"
+    repository
+  end
+end
+
+class PimpRepositoryCommandWithBuilder
   def build(repository)
     repository.id = 42
     repository
@@ -139,8 +146,8 @@ class CreatePimpedRepository
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    command(CreateRepositoryCommand.new(user))
-    command(PimpRepositoryCommand.new)
+    step(CreateRepositoryCommand.new(user))
+    step(PimpRepositoryCommand.new)
   end
 end
 
@@ -149,9 +156,9 @@ class CreatePimpedRepository2
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    command(CreateRepositoryCommand.new(user), :builder => RepositoryBuilder)
-    cmd = PimpRepositoryCommand.new
-    command(cmd, :builder => cmd)
+    step(CreateRepositoryCommand.new(user), :builder => RepositoryBuilder)
+    cmd = PimpRepositoryCommandWithBuilder.new
+    step(cmd, :builder => cmd)
   end
 end
 
@@ -165,8 +172,26 @@ class CreatePimpedRepository3
 
   def initialize(user)
     input_class(NewRepositoryInput)
-    command(CreateRepositoryCommand.new(user), :builder => RepositoryBuilder, :validator => NewRepositoryValidator)
-    cmd = PimpRepositoryCommand.new
-    command(cmd, :builder => cmd, :validators => [NewRepositoryValidator, PimpedRepositoryValidator])
+    cmd = PimpRepositoryCommandWithBuilder.new
+    step(CreateRepositoryCommand.new(user), :builder => RepositoryBuilder, :validator => NewRepositoryValidator)
+    step(cmd, :builder => cmd, :validators => [NewRepositoryValidator, PimpedRepositoryValidator])
+  end
+end
+
+class InlineCommand
+  include UseCase
+
+  def initialize
+    step(lambda { |params| params[:name] })
+  end
+end
+
+class ImplicitBuilder
+  include UseCase
+
+  def initialize(user)
+    input_class(NewRepositoryInput)
+    step(CreateRepositoryCommand.new(user), :builder => RepositoryBuilder)
+    step(PimpRepositoryCommandWithBuilder.new)
   end
 end

data/test/use_case_test.rb

@@ -134,4 +134,18 @@ describe UseCase do
     refute outcome.success?
     assert_equal "You cannot win", outcome.failure.errors[:name].join
   end
+
+  it "calls command lambda" do
+    outcome = InlineCommand.new.execute({ :name => "Dissection" })
+
+    assert outcome.success?
+    assert_equal "Dissection", outcome.result
+  end
+
+  it "implicitly uses command as builder" do
+    outcome = ImplicitBuilder.new(@logged_in_user).execute({ :name => "Mr" })
+
+    assert_equal 42, outcome.result.id
+    assert_equal "Mr! (Pimped)", outcome.result.name
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: use_case
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-04 00:00:00.000000000 Z
+date: 2013-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest