cuprum 0.8.0 → 0.9.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cafecaeff8b2c0209616cd9303613d88723c2477
-  data.tar.gz: b4d1c2cdde687815ac835631c460a45d15a3306d
+SHA256:
+  metadata.gz: 92d562710780dafcd20a5114fea623303dde6c22f7fbb2588eae26fd10adb419
+  data.tar.gz: 5a0c7d60b320673d3816b63b7480d84f4fa062bd52efb3b6ccca6de5237778a1
 SHA512:
-  metadata.gz: f465ecb20dd65d5e835f6f506bbaca272e39637a5b127fac31929fef88a880069ed8b7f86802b207b01b767de952d641a688344dfabd8b1d4347d904daf926d7
-  data.tar.gz: be12f0a8d8be45ba1aabc854b48be53be13e2716d39e1c48fecae038b99019880c19686fd96bb1d1ff04272400650723df47b789ebe48b60da1e6ba844175f3a
+  metadata.gz: 147d1581adb612e620a629429a7207f84a7e15a6224da5045ef30a9f270aa72ae2b9a3332221054ee902a205c1d60224d31eec998450d45bb68b335b10d5c255
+  data.tar.gz: 2db46aea35210874659ae9e69df64574d1f0e89e600937f6b20d45c56222c656477e663b722069b89fbe3d97d663189e7edb79776d72a67dcca3e8bdb6bd7607

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.9.0
+
+The "'Tis Not Too Late To Seek A Newer World" Update
+
+Major refactoring of Command processing and the Result object. This update is **not** backwards compatible.
+
+### Commands
+
+Removed the `#success` and `#failure` chaining helpers.
+
+Permanently removed the deprecated ResultHelpers mixin.
+
+### Errors
+
+Added `Cuprum::Error`, which encapsulates the failure state of a result. It is *recommended*, but not required, that when creating a failing Result, the `:error` property be set to an instance of `Cuprum::Error`.
+
+### Results
+
+Results are now nominally immutable objects. All mutator methods have been removed, including `#failure!`, `#success!`, and `#update`. The `#empty?` predicate has also been removed.
+
+Updated the constructor to take the following keyword arguments: `:value`, `:error`, and `:status`.
+
+- The status can now be overridden on a new Result by passing in the `:status`.
+- Resolves an issue when attempting to instantiate a result with a Hash value.
+- *Note:* The value must now be passed in as a keyword.
+- *Note:* The `:errors` keyword has been renamed to `:error`.
+
+Removed the `:halted` status.
+
+### Other Changes
+
+Removed the `Cuprum#warn` functionality.
+
+### Upgrade Notes
+
+Anywhere a new `Cuprum::Result` is created directly, update the arguments to match the new `value:` and `error:` keywords.
+
+Anywhere the `#result` is referenced inside a command, instead return the desired value directly, or return a result with the desired error.
+
+Anywhere a command is chained with the `#success` or `#failure` shorthand, use the full `chain(on: :success)` or `chain(on: :failure)` format.
+
 ## 0.8.0
 
 The "We Have The Technology" Update.

data/DEVELOPMENT.md

@@ -2,22 +2,26 @@
 
 ## Version 0.9.0
 
-The "Second Star To The Right" Update
-
-### Actions
-
-#### LifecycleHooks
-
-- :before, :after hooks
-  - NOT included in Command by default
+The "'Tis Not Too Late To Seek A Newer World" Update
 
 ## Version 0.10.0
 
-'The "Out Of Context Problem" Update'
+The "One Small Step" Update
 
 ### Commands
 
-- #context object
+- Implement #<<, #>> composition methods.
+  - Calls commands in order passing values.
+  - Return Result early on Failure (or not Success), otherwise final Result.
+- Implement #step method (used in #process).
+  - Called with command (block? method?) that returns a Result.
+  - Raise (and catch) exception on non-success Result (test custom status?)
+  - Otherwise return Result#value.
+
+### Matcher
+
+- Handle success(), failure(), failure(SomeError) cases.
+  - Custom matcher to handle additional cases - halted, pending, etc?
 
 ## Version 1.0.0
 

data/README.md

@@ -6,7 +6,8 @@ It defines the following concepts:
 
 - [Commands](#label-Commands) - A function-like object that responds to `#call` and returns a `Result`.
 - [Operations](#label-Operations) - A stateful `Command` that wraps and delegates to its most recent `Result`.
-- [Results](#label-Results) - A data object with a `#value`, an `#errors` object, and `#success?` and `#failure?` status methods.
+- [Results](#label-Results) - An immutable data object with a status (either `:success` or `:failure`), and either a `#value` or an `#error` object.
+- [Errors](#label-Errors) - Encapsulates a failure state of a command.
 
 ## About
 
@@ -41,7 +42,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2017 Rob Smith
+Copyright (c) 2019 Rob Smith
 
 Cuprum is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -63,9 +64,9 @@ Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use thes
 
     require 'cuprum'
 
-Commands are the core feature of Cuprum. In a nutshell, each Cuprum::Command is a functional object that encapsulates a business logic operation. A Command provides a consistent interface and tracking of result value and status. This minimizes boilerplate and allows for interchangeability between different implementations or strategies for managing your data and processes.
+Commands are the core feature of Cuprum. In a nutshell, each `Cuprum::Command` is a functional object that encapsulates a business logic operation. A Command provides a consistent interface and tracking of result value and status. This minimizes boilerplate and allows for interchangeability between different implementations or strategies for managing your data and processes.
 
-Each Command implements a `#call` method that wraps your defined business logic and returns an instance of Cuprum::Result. The result wraps the returned data (with the `#value` method), any `#errors` generated when running the Command, and the overall status with the `#success?` and `#failure` methods. For more details about Cuprum::Result, [see below](#label-Results).
+Each Command implements a `#call` method that wraps your defined business logic and returns an instance of `Cuprum::Result`. The result has a status (either `:success` or `:failure`), and may have a `#value` and/or an `#error` object. For more details about Cuprum::Result, [see below](#label-Results).
 
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
 
@@ -77,12 +78,13 @@ The recommended way to define commands is to create a subclass of `Cuprum::Comma
 class BuildBookCommand < Cuprum::Command
   def process attributes
     Book.new(attributes)
-  end # method process
-end # class
+  end
+end
 
 command = BuildPostCommand.new
-result  = command.call(:title => 'The Hobbit')
-result.class #=> Cuprum::Result
+result  = command.call(title: 'The Hobbit')
+result.class    #=> Cuprum::Result
+result.success? #=> true
 
 book = result.value
 book.class #=> Book
@@ -97,23 +99,30 @@ Because a command is just a Ruby object, we can also pass values to the construc
 class SaveBookCommand < Cuprum::Command
   def initialize repository
     @repository = repository
-  end # constructor
+  end
 
   def process book
-    @repository.persist(book)
-  end # method process
-end # class
+    if @repository.persist(book)
+      success(book)
+    else
+      failure('unable to save book')
+    end
+  end
+end
 
 books = [
-  Book.new(:title => 'The Fellowship of the Ring'),
-  Book.new(:title => 'The Two Towers'),
-  Book.new(:title => 'The Return of the King')
+  Book.new(title: 'The Fellowship of the Ring'),
+  Book.new(title: 'The Two Towers'),
+  Book.new(title: 'The Return of the King')
 ]
 command = SaveBookCommand.new(books_repository)
 books.each { |book| command.call(book) }
 ```
 
-Here, we are reusing the same command three times, rather than creating a new save command for each book. Each book is persisted to the `books_repository`. This is also an example of how using commands can simplify code - notice that nothing about the `SaveBookCommand` is specific to the `Book` model. Thus, we could refactor this into a generic `SaveModelCommand`.
+Here, we are defining a command that might fail - maybe the database is unavailable, or there's a constraint that is violated by the inserted attributes. If the call to `#persist` succeeds, we're returning a Result with a status of `:success` and the value set to the persisted book.
+Conversely, if the call to `#persist` fails, we're returning a Result with a status of `:failure` and a custom error message. Since the `#process` method returns a Result, it is returned directly by `#call`.
+
+Note also that we are reusing the same command three times, rather than creating a new save command for each book. Each book is persisted to the `books_repository`. This is also an example of how using commands can simplify code - notice that nothing about the `SaveBookCommand` is specific to the `Book` model. Thus, we could refactor this into a generic `SaveModelCommand`.
 
 A command can also be defined by passing block to `Cuprum::Command.new`.
 
@@ -136,9 +145,9 @@ Commands defined using `Cuprum::Command.new` are quick to use, but more difficul
 
 Calling the `#call` method on a `Cuprum::Command` instance will always return an instance of `Cuprum::Result`. The result's `#value` property is determined by the object returned by the `#process` method (if the command is defined as a class) or the block (if the command is defined by passing a block to `Cuprum::Command.new`).
 
-The `#value` depends on whether or not the returned object is a result or is compatible with the result interface. Specifically, any object that responds to the methods `#to_result`, `#value`, and `#success?` is considered to be a result.
+The `#value` depends on whether or not the returned object is a result or is compatible with the result interface. Specifically, any object that responds to the method `#to_cuprum_result` is considered to be a result.
 
-If the object returned is **not** a result, then the `#value` of the returned result is set to the object.
+If the object returned by `#process` is **not** a result, then the `#value` of the returned result is set to the object.
 
 ```ruby
 command = Cuprum::Command.new { 'Greetings, programs!' }
@@ -147,46 +156,18 @@ result.class #=> Cuprum::Result
 result.value #=> 'Greetings, programs!'
 ```
 
-If the object returned is the command's own result object, then the `#value` of the returned result is unchanged. For convenience, methods to set the result status or mark the result as halted will return the result.
+If the object returned by `#process` is a result object, then result is returned directly.
 
 ```ruby
-command = Cuprum::Command.new { result.failure! }
+command = Cuprum::Command.new { Cuprum::Result.new(value: 'Greetings, programs!') }
 result  = command.call
-result.class    #=> Cuprum::Result
-result.value    #=> nil
-result.success? #=> false
-```
-
-If the object returned is another result or compatible object, then `#call` will call the `#to_result` method on the result and return the resulting object.
-
-```ruby
-command = Cuprum::Command.new { |value| Cuprum::Result.new(value) }
-result  = command.call('Greetings, starfighter!')
 result.class #=> Cuprum::Result
-result.value #=> 'Greetings, starfighter!'
-```
-
-In some cases, returning a result directly will discard information on the command's own result object. When this occurs, Cuprum will display a warning.
-
-```ruby
-command =
-  Cuprum::Command.new do
-    result.errors << 'Oops! We are throwing away this result.'
-
-    Cuprum::Result.new
-  end
-
-#=> This calls Kernel#warn with a warning message.
-result = command.call
-result.class    #=> Cuprum::Result
-result.value    #=> nil
-result.success? #=> true
-result.errors   #=> []
+result.value #=> 'Greetings, programs!'
 ```
 
 #### Success, Failure, and Errors
 
-Whether defined with a block or in the `#process` method, the Command implementation can access an `#errors` object while in the `#call` method. Any errors added to the errors object will be exposed by the `#errors` method on the result object.
+Each Result has a status, either `:success` or `:failure`. A Result will have a status of `:failure` when it was created with an error object. Otherwise, a Result will have a status of `:success`. Returning a failing Result from a Command indicates that something went wrong while executing the Command.
 
 ```ruby
 class PublishBookCommand < Cuprum::Command
@@ -194,40 +175,38 @@ class PublishBookCommand < Cuprum::Command
 
   def process book
     if book.cover.nil?
-      errors << 'This book does not have a cover.'
-
-      return
-    end # if
+      return Cuprum::Result.new(error: 'This book does not have a cover.')
+    end
 
     book.published = true
 
     book
-  end # method process
-end # class
+  end
+end
 ```
 
-In addition, the result object defines `#success?` and `#failure?` predicates. If the result has no errors, then `#success?` will return true and `#failure?` will return false.
+In addition, the result object defines `#success?` and `#failure?` predicates.
 
 ```ruby
-book = Book.new(:title => 'The Silmarillion', :cover => Cover.new)
+book = Book.new(title: 'The Silmarillion', cover: Cover.new)
 book.published? #=> false
 
 result = PublishBookCommand.new.call(book)
-result.errors   #=> []
+result.error    #=> nil
 result.success? #=> true
 result.failure? #=> false
 result.value    #=> book
 book.published? #=> true
 ```
 
-If the result does have errors, `#success?` will return false and `#failure?` will return true.
+If the result does have an error, `#success?` will return false and `#failure?` will return true.
 
 ```ruby
-book = Book.new(:title => 'The Silmarillion', :cover => nil)
+book = Book.new(title: 'The Silmarillion', cover: nil)
 book.published? #=> false
 
 result = PublishBookCommand.new.call(book)
-result.errors   #=> ['This book does not have a cover.']
+result.error    #=> 'This book does not have a cover.'
 result.success? #=> false
 result.failure? #=> true
 result.value    #=> book
@@ -248,7 +227,7 @@ add_command = Cuprum::Command.new do |addend, i|
   addend.times { i = increment_command(i).value }
 
   i
-end # command
+end
 
 add_command.call(1, 1).value #=> 2
 add_command.call(1, 2).value #=> 3
@@ -274,8 +253,12 @@ class AddCommand < Cuprum::Command
 
   private
 
+  def increment_command
+    @increment_command ||= IncrementCommand.new
+  end
+
   def process i
-    addend.times { i = IncrementCommand.new.call(i).value }
+    addend.times { i = increment_command.call(i).value }
 
     i
   end
@@ -335,9 +318,7 @@ second_command.call #=> Outputs 'First command!' then 'Second command!'.
 first_command.call #=> Outputs 'First command!' to STDOUT.
 ```
 
-When a chained command is called, the original command is called with whatever parameters are passed in to the `#call` method, and the command executes the `#process` method as normal, generating a `Cuprum::Result` and assigning it a value and optionally errors or a status. Rather than returning this result, however, it is passed on to the next command in the chain. In the context of a chained command, this means two things.
-
-First, the next command is called. If the next command does not take any arguments, it is not passed any arguments. If the next command takes one or more arguments, it is passed the `#value` of that previous result.
+When a chained command is called, the original command is called with whatever parameters are passed in to the `#call` method, and the command executes the `#process` method as normal. Rather than returning the result, however, the next command in the chain is called. If the next command does not take any arguments, it is not passed any arguments. If the next command takes one or more arguments, it is passed the `#value` of that previous result. When the final command in the chain is called, that result is returned.
 
 ```ruby
 double_command    = Cuprum::Command.new { |i| 2 * i }
@@ -360,87 +341,38 @@ result.class #=> Cuprum::Result
 result.value #=> 25
 ```
 
-Second, the previous result is set as the result of the next command (before it is evaluated). This makes it available to the next command during execution as the `#result` method, and makes available the value, errors, and status of the previous command (and avoids unnecessary object allocation). The value of the result will be updated to reflect the return value of the next command execution.
-
-```ruby
-validate_command =
-  Cuprum::Command.new do |object|
-    result.errors << 'Object is invalid!' unless object.valid?
-
-    object
-  end
-persist_command =
-  Cuprum::Command.new do |object|
-    object.save if result.success?
-
-    object
-  end
-chained_command = validate_command.chain(persist_command)
-
-# First, validate_command is called with a valid object. This creates a result
-# with no errors and whose value is the valid object.
-#
-# Then, persist_command is called with the object, and its result is assigned to
-# the previous result. Since there are no errors on the result, the object is
-# saved. Finally, the value of the result is set to the object, and the result
-# is returned.
-result = chained_command.call(a_valid_object) #=> Saves the object.
-result.value              #=> a_valid_object
-result.errors             #=> []
-a_valid_object.persisted? #=> true
-
-# First, validate_command is called with an invalid object. This creates a
-# result whose value is the invalid object, and with errors 'Object is
-# invalid!'.
-#
-# Then, persist_command is called with the object, and its result is assigned to
-# the previous result. Since the result has an error, the object is not saved.
-# Finally, the value of the result is set to the object, and the result
-# is returned.
-result = chained_command.call(an_invalid_object) #=> Does not save the object.
-result.value                 #=> an_invalid_object
-result.errors                #=> ['Object is invalid!']
-an_invalid_object.persisted? #=> false
-```
-
 #### Conditional Chaining
 
-The `#chain` method can be passed an optional `:on => value` keyword. This keyword determines whether or not the chained command will execute, based on the previous result status. Possible values are `:success`, `:failure`, `:always`, or `nil`. The default value is `nil`.
-
-If the `:on` keyword is omitted, the chained command will always be executed after the previous command unless the result is halted (see [Halting A Command Chain](#label-Commands))
+The `#chain` method can be passed an optional `on: value` keyword. This keyword determines whether or not the chained command will execute, based on the previous result status. Possible values are `:success`, `:failure`, `:always`, or `nil`. The default value is `nil`.
 
-If the command is chained with `:on => :success`, then the chained command will only execute if the previous result is passing, e.g. the `#success?` method returns true and the command is not halted. A result is passing if there are no errors, or if the status is set to `:success`.
+If the command is chained with `on: :always`, or if the `:on` keyword is omitted, the chained command will always be executed after the previous command.
 
-If the command is chained with `:on => :failure`, then the chained command will only execute if the previous result is failing, e.g. the `#success?` method returns false and the command is not halted. A result is failing if the errors object is not empty, or if the status is set to `:failure`.
+If the command is chained with `on: :success`, then the chained command will only execute if the previous result is passing, e.g. the `#success?` method returns true. A result is passing if there is no `#error`, or if the status is set to `:success`.
 
-If the command is chained with `:on => always`, then the chained command will always be executed, even if the previous result is halted.
+If the command is chained with `on: :failure`, then the chained command will only execute if the previous result is failing, e.g. the `#success?` method returns false. A result is failing if there is an `#error`, or if the status is set to `:failure`.
 
 ```ruby
 find_command =
   Cuprum::Command.new do |attributes|
-    book = Book.where(:id => attributes[:id]).first
+    book = Book.where(id: attributes[:id]).first
 
-    result.errors << 'Book not found' unless book
+    return book if book
 
-    book
+    Cuprum::Result.new(error: 'Book not found')
   end
 create_command =
   Cuprum::Command.new do |attributes|
     book = Book.new(attributes)
 
-    if book.save
-      result.success!
-    else
-      book.errors.full_messages.each { |message| result.errors << message }
-    end
+    return book if book.save
 
-    book
+    Cuprum::Result.new(error: book.errors.full_messages)
   end
 
-find_or_create_command = find_command.chain(create_command, :on => :failure)
+find_or_create_command = find_command.chain(create_command, on: :failure)
 
 # With a book that exists in the database, the find_command is called and
-# returns a result with no errors and a value of the found book. The
+# returns a result with no error and a value of the found book. The
 # create_command is not called.
 hsh    = { id: 0, title: 'Journey to the West' }
 result = find_or_create_command.call(hsh)
@@ -448,19 +380,18 @@ book   = result.value
 book.id         #=> 0
 book.title      #=> 'Journey to the West'
 result.success? #=> true
-result.errors   #=> []
+result.error    #=> nil
 
 # With a book that does not exist but with valid attributes, the find command
 # returns a failing result with a value of nil. The create_command is called and
-# creates a new book with the attributes, returning a passing result but
-# preserving the errors.
+# creates a new book with the attributes, returning a passing result.
 hsh    = { id: 1, title: 'The Ramayana' }
 result = find_or_create_command.call(hsh)
 book   = result.value
 book.id         #=> 1
 book.title      #=> 'The Ramayana'
 result.success? #=> true
-result.errors   #=> ['Book not found']
+result.error    #=> nil
 
 # With a book that does not exist and with invalid attributes, the find command
 # returns a failing result with a value of nil. The create_command is called and
@@ -472,36 +403,7 @@ book   = result.value
 book.id         #=> 2
 book.title      #=> nil
 result.success? #=> false
-result.errors   #=> ['Book not found', "Title can't be blank"]
-```
-
-The `#success` method can be used as shorthand for `chain(command, :on => :success)`. Likewise, the `#failure` method can be used in place of `chain(command, :on => :failure)`.
-
-#### Halting A Command Chain
-
-If the `#halt` method is called as part of a Command block or `#process` method, the command chain is halted. Any subsequent chained commands will not be called unless they were chained with the `:on => :always` option. This allows you to terminate a Command chain early without having to raise and rescue an exception.
-
-```ruby
-double_command  = Cuprum::Command.new { |i| 2 * i }
-halt_command    = Cuprum::Command.new { |value| value.tap { result.halt! } }
-add_one_command = Cuprum::Command.new { |i| i + 1 }
-
-chained_command =
-  double_command
-    .chain(halt_command)
-    .chain(add_one_command)
-    .chain(:on => :always) { |count| "There are #{count} lights!" }
-
-# First, double_command is called with 2, returning a result with no errors and
-# a value of 4. Then, halt_command is called, which marks the result as halted.
-# Because the result is now halted, the add_one_command is not called. Finally,
-# the last command is called (even though the result is halted, the command is
-# chained :on => :always), which returns a result with the string value. The
-# result is passing, but is still halted.
-result = chained_command.call(2)
-result.value    #=> 'There are 4 lights!'
-result.success? #=> true
-result.halted?  #=> true
+result.error    #=> ["Title can't be blank"]
 ```
 
 ### Advanced Chaining
@@ -515,9 +417,7 @@ The `#tap_result` method allows you to insert arbitrary code into a command chai
 ```ruby
 command =
   Cuprum::Command.new do
-    result.errors << 'Example error'
-
-    'Example value'
+    Cuprum::Result.new(value: 'Example value', error: 'Example error')
   end
 chained_command =
   command
@@ -530,32 +430,32 @@ result = chained_command.call
 result.class    #=> Cuprum::Result
 result.value    #=> 'Example value'
 result.success? #=> false
-result.errors   #=> ['Example error']
+result.error    #=> 'Example error'
 ```
 
-Like `#chain`, `#tap_result` can be given an `:on => value` keyword.
+Like `#chain`, `#tap_result` can be given an `on: value` keyword.
 
 ```ruby
 find_book_command =
   Cuprum::Command.new do |book_id|
-    book = Book.where(:id => book_id).first
+    book = Book.where(id: book_id).first
 
-    result.errors << "Unable to find book with id #{book_id}" unless book
+    return book if book
 
-    book
+    Cuprum::Result.new(error: "Unable to find book with id #{book_id}")
   end
 
 chained_command =
   find_book_command
-    .tap_result(:on => :success) do |result|
-      render :show, :locals => { :book => result.value }
+    .tap_result(on: :success) do |result|
+      render :show, locals: { book: result.value }
     end
-    .tap_result(:on => :failure) do
+    .tap_result(on: :failure) do
       redirect_to books_path
     end
 
 # Calls find_book_command with the id, which queries for the book and returns a
-# result with a value of the book and no errors. Then, the first tap_result
+# result with a value of the book and no error. Then, the first tap_result
 # block is evaluated, calling the render method and passing it the book via the
 # result.value method. Because the result is passing, the next block is skipped.
 # Finally, the result of find_book_command is returned unchanged.
@@ -563,7 +463,7 @@ result = chained_command.call(valid_id)
 result.class    #=> Cuprum::Result
 result.value    #=> an instance of Book
 result.success? #=> true
-result.errors   #=> []
+result.error    #=> nil
 
 # Calls find_book_command with the id, which queries for the book and returns a
 # result with a value of nil and the error message. Because the result is
@@ -574,14 +474,14 @@ result = chained_command.call(invalid_id)
 result.class    #=> Cuprum::Result
 result.value    #=> nil
 result.success? #=> false
-result.errors   #=> ['Unable to find book with id invalid_id']
+result.error    #=> ['Unable to find book with id invalid_id']
 ```
 
 #### Yield Result
 
 The `#yield_result` method offers advanced control over a chained command step. The method takes a block and yields the previous result. If the object returned by the block is not a result, a new result is created with a value equal to the returned object. In either case, the result is returned and passed to the next command, or returned by `#call` if `#tap_result` is the last item in the chain.
 
-Unlike `#chain`, the block in `#yield_result` yields the previous result, not the previous value. In addition, `#yield_result` does not automatically carry over any errors from the previous result, the result status, or whether the result was marked as halted.
+Unlike `#chain`, the block in `#yield_result` yields the previous result, not the previous value.
 
 ```ruby
 chained_command =
@@ -589,9 +489,7 @@ chained_command =
     'Example value'
   end
   .yield_result do |result|
-    result.errors << 'Example error'
-
-    result
+    Cuprum::Result.new(error: 'Example error')
   end
   .yield_result do |result|
     "The last result was a #{result.success? ? 'success' : 'failure'}."
@@ -599,54 +497,22 @@ chained_command =
 
 # The first command creates a passing result with a value of 'Example value'.
 #
-# This is passed to the first yield_result block, which adds the 'Example error'
-# string to the result errors, and then returns the result. Because the
-# yield_result block returns the previous result, it is then passed to the next
-# item in the chain.
+# This is passed to the first yield_result block, which creates a new result
+# with the same value and the string 'Example error' as the error object. It is
+# then passed to the next command in the chain.
 #
 # Finally, the second yield_result block is called, which checks the status of
-# the passed result. Since the second block does not return the previous result,
+# the passed result. Since the final block does not return the previous result,
 # the previous result is discarded and a new result is created with the string
 # value starting with 'The last result was ...'.
 result = chained_command.call
 result.class    #=> Cuprum::Result
 result.value    #=> 'The last result was a failure.'
 result.success? #=> true
-result.errors   #=> []
+result.error    #=> nil
 ```
 
-Like `#chain`, `#yield_result` can be given an `:on => value` keyword.
-
-```ruby
-# The Collatz conjecture in mathematics concerns a sequence of numbers defined
-# as follows. Start with any positive integer. If the number is even, then
-# divide the number by two. If the number is odd, multiply by three and add one.
-# These steps are repeated until the value is one or the numbers loop.
-step_command =
-  Cuprum::Command.new do |i|
-    result.failure! unless i.even?
-
-    i
-  end
-    .yield_result(:on => :success) { |result| result.value / 2 }
-    .yield_result(:on => :failure) { |result| 1 + 3 * result.value }
-
-# Because the value is even, the first command returns a passing result with a
-# value of 8. The first yield_result block is then called with that result,
-# returning a new result with a value of 4. The result is passing, so the second
-# yield_result block is skipped and the result is returned.
-result = collatz_command.call(8)
-result.value    #=> 4
-result.success? #=> true
-
-# Because the value is odd, the first command returns a failing result with a
-# value of 5. Because the result is failing, the first yield_result block is
-# skipped. The second yield_result block is then called with the result,
-# returning a new (passing) result with a value of 16.
-result = collatz_command.call(5)
-result.value    #=> 16
-result.success? #=> true
-```
+Like `#chain`, `#yield_result` can be given an `on: value` keyword.
 
 Under the hood, both `#chain` and `#tap_result` are implemented on top of `#yield_result`.
 
@@ -677,14 +543,14 @@ result = CreateCommentCommand.new.call({ user_id: '12345', body: body })
 
 result.value    #=> an instance of Comment with the given user_id and body.
 result.success? #=> true
-Comment.count   #=> 1; the comment was added to the database
+Comment.count   #=> 1 - the comment was added to the database
 
 result = CreateCommentCommand.new.call({ user_id: nil, body: body })
 
 result.value    #=> an instance of Comment with the given user_id and body.
 result.success? #=> false
-result.errors   #=> ["User id can't be blank"]
-Comment.count   #=> 1; the comment was not added to the database
+result.error    #=> ["User id can't be blank"]
+Comment.count   #=> 1 - the comment was not added to the database
 ```
 
 ### Results
@@ -693,36 +559,115 @@ Comment.count   #=> 1; the comment was not added to the database
 
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
 
-A Cuprum::Result is a data object that encapsulates the result of calling a Cuprum command. Each result has a `#value`, an `#errors` object (defaults to an Array), and status methods `#success?`, `#failure?`, and `#halted?`.
+A `Cuprum::Result` is a data object that encapsulates the result of calling a Cuprum command. Each result has a `#value`, an `#error` object (defaults to `nil`), and a `#status` (either `:success` or `:failure`, and accessible via the `#success?` and `#failure?` predicates).
+
+```ruby
+result = Cuprum::Result.new
+
+result.value    #=> nil
+result.error    #=> nil
+result.status   #=> :success
+result.success? #=> true
+result.failure? #=> true
+```
+
+Creating a result with a value stores the value.
 
 ```ruby
 value  = 'A result value'.freeze
-result = Cuprum::Result.new(value)
+result = Cuprum::Result.new(value: value)
 
 result.value    #=> 'A result value'
-result.errors   #=> []
+result.error    #=> nil
+result.status   #=> :success
 result.success? #=> true
 result.failure? #=> false
-result.halted?  #=> false
 ```
 
-Adding errors to the `#errors` object will change the status of the result.
+Creating a Result with an error stores the error and sets the status to `:failure`.
+
+```ruby
+error  = Cuprum::Error.new(message: "I'm sorry, something went wrong.")
+result = Cuprum::Result.new(error: error)
+result.value    #=> nil
+result.error    #=> Error with message "I'm sorry, something went wrong."
+result.status   #=> :failure
+result.success? #=> false
+result.failure? #=> true
+```
+
+Although using a `Cuprum::Error` instance as the `:error` is recommended, it is not required. You can use a custom error object, or just a string message.
 
 ```ruby
-result.errors << "I'm sorry, something went wrong."
+result = Cuprum::Result.new(error: "I'm sorry, something went wrong.")
+result.value    #=> nil
+result.error    #=> "I'm sorry, something went wrong."
+result.status   #=> :failure
 result.success? #=> false
 result.failure? #=> true
 ```
 
-The status can also be overriden with the `#success!` and `#failure!` methods, which will set the status regardless of the presence or absence of errors.
+Finally, the status can be overridden via the `:status` keyword.
 
 ```ruby
-result.success!
-result.errors   #=> ["I'm sorry, something went wrong."]
+result = Cuprum::Result.new(status: :failure)
+result.error    #=> nil
+result.status   #=> :failure
+result.success? #=> false
+result.failure? #=> true
+
+error  = Cuprum::Error.new(message: "I'm sorry, something went wrong.")
+result = Cuprum::Result.new(error: error, status: :success)
+result.error    #=> Error with message "I'm sorry, something went wrong."
+result.status   #=> :success
 result.success? #=> true
 result.failure? #=> false
 ```
 
+### Errors
+
+    require 'cuprum/error'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FError)
+
+A `Cuprum::Error` encapsulates a specific failure state of a Command. Each Error has a `#message` property, which defaults to nil.
+
+```ruby
+error = Cuprum::Error.new
+error.message => # nil
+
+error = Cuprum::Error.new(message: 'Something went wrong.')
+error.message => # 'Something went wrong.'
+```
+
+Each application should define its own failure states as errors. For example, a typical web application might define the following errors:
+
+```ruby
+class NotFoundError < Cuprum::Error
+  def initialize(resource:, resource_id:)
+    @resource    = resource
+    @resource_id = resource_id
+
+    super(message: "#{resource} not found with id #{resource_id}")
+  end
+
+  attr_reader :resource, :resource_id
+end
+
+class ValidationError < Cuprum::Error
+  def initialize(resource:, errors:)
+    @resource = resource
+    @errors   = errors
+
+    super(message: "#{resource} was invalid")
+  end
+
+  attr_reader :resource, :errors
+end
+```
+
+It is optional but recommended to use a `Cuprum::Error` when returning a failed result from a command.
+
 ### Operations
 
     require 'cuprum'
@@ -737,8 +682,8 @@ These two features allow developers to simplify logic around calling and using t
 class CreateBookOperation < Cuprum::Operation
   def process
     # Implementation here.
-  end # method process
-end # class
+  end
+end
 
 # Defining a controller action using an operation.
 def create
@@ -750,13 +695,13 @@ def create
     @book = operation.value
 
     render :new
-  end # if-else
-end # create
+  end
+end
 ```
 
 Like a Command, an Operation can be defined directly by passing an implementation block to the constructor or by creating a subclass that overwrites the #process method.
 
-An operation inherits the `#call` method from Cuprum::Command (see above), and delegates the `#value`, `#errors`, `#success?`, and `#failure` methods to the most recent result. If the operation has not been called, these methods will return default values.
+An operation inherits the `#call` method from Cuprum::Command (see above), and delegates the `#value`, `#error`, `#success?`, and `#failure` methods to the most recent result. If the operation has not been called, these methods will return default values.
 
 #### The Operation Mixin
 
@@ -764,13 +709,6 @@ An operation inherits the `#call` method from Cuprum::Command (see above), and d
 
 The implementation of `Cuprum::Operation` is defined by the `Cuprum::Operation::Mixin` module, which provides the methods defined above. Any command class or instance can be converted to an operation by including (for a class) or extending (for an instance) the operation mixin.
 
-Finally, the result can be halted using the `#halt` method, which indicates that further chained commands should not be executed.
-
-```ruby
-result.halt!
-result.halted? #=> true
-```
-
 ### Command Factories
 
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommandFactory)
@@ -898,15 +836,15 @@ class PublishedBooksCommand < Cuprum::Command
 end
 
 class BookFactory < Cuprum::CommandFactory
-  command :published do
-    PublishedBooksCommand.new(books_collection)
-  end
-
   def initialize(books)
     @books_collection = books
   end
 
   attr_reader :books_collection
+
+  command :published do
+    PublishedBooksCommand.new(books_collection)
+  end
 end
 ```
 
@@ -1207,16 +1145,6 @@ Returns a new instance of Cuprum::Command. If a block is given, the `#call` meth
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#initialize-instance_method)
 
-#### `#build_errors`
-
-*(Private Method)*
-
-    build_errors() #=> Array
-
-Generates an empty errors object. When the command is called, the result will have its `#errors` property initialized to the value returned by `#build_errors`. By default, this is an array. If you want to use a custom errors object type, override this method in a subclass.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#build_errors-instance_method)
-
 #### `#call`
 
     call(*arguments, **keywords) { ... } #=> Cuprum::Result
@@ -1235,9 +1163,9 @@ Registers a command or block to run after the current command, or after the last
 
 The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
 
-The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command or on any errors generated, use the block form of #chain.
+The block will be passed the #result of the previous command as its parameter.
 
-If the block returns a Cuprum::Result (or an object responding to #value and #success?), the block result will be returned (or passed to the next chained command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
+If the block returns a Cuprum::Result (or an object responding to `#to_cuprum_result`), the block result will be returned (or passed to the next chained command, if any). If the block returns any other value (including `nil`), the `#result` of the previous command will be returned or passed to the next command.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain-instance_method)
 
@@ -1253,29 +1181,13 @@ As `#chain`, but modifies the current command instead of creating a clone.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain!-instance_method)
 
-#### `#else`
-
-    else(command) #=> Cuprum::Command
-
-Shorthand for `command.chain(:on => :failure)`. Registers a command or block to run after the current command. The chained command will only run if the previous command was unsuccessfully run.
-
-The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
-
-    else() { |result| ... } #=> Cuprum::Command
-
-The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command or on any errors generated, use the block form of #chain.
-
-If the block returns a Cuprum::Result (or an object responding to #value and #success?), the block result will be returned (or passed to the next chained command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#else-instance_method)
-
 #### `#tap_result`
 
     tap_result(on: nil) { |previous_result| } #=> Cuprum::Result
 
 Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the previous result returned or yielded to the next block. The return value of the block is discarded.
 
-If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
+If the `on` parameter is set to `:success`, the block will be called if the last result is successful. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing. Finally, if the `on` parameter is set to `:always` or to `nil`, the block will always be called.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result-instance_method)
 
@@ -1289,29 +1201,13 @@ As `#tap_result`, but modifies the current command instead of creating a clone.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result!-instance_method)
 
-#### `#then`
-
-    then(command) #=> Cuprum::Command
-
-Shorthand for `command.chain(:on => :success)`. Registers a command or block to run after the current command. The chained command will only run if the previous command was successfully run.
-
-The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
-
-    then() { |result| ... } #=> Cuprum::Command
-
-The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command or on any errors generated, use the block form of #chain.
-
-If the block returns a Cuprum::Result (or an object responding to #value and #success?), the block result will be returned (or passed to the next chained command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#then-instance_method)
-
 #### `#yield_result`
 
     yield_result(on: nil) { |previous_result| } #=> Cuprum::Result
 
 Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the return value wrapped in a result and returned or yielded to the next block.
 
-If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
+If the `on` parameter is set to `:success`, the block will be called if the last result is successful. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing. Finally, if the `on` parameter is set to `:always` or to `nil`, the block will always be called.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result-instance_method)
 
@@ -1367,65 +1263,29 @@ A Cuprum::Result defines the following methods:
 
     ==(other) #=> true, false
 
-Performs a fuzzy comparison with the other object. At a minimum, the other object must respond to `#value` and `#success?`, and the values of `other.value` and `other.success?` must be equal to the corresponding value on the result. In addition, if the `#failure?`, `#errors`, or `#halted?` methods are defined on the other object, then the value of each defined method is compared to the value on the result. Returns true if all values match, otherwise returns false.
-
-#### `#empty?`
-
-    empty?() #=> true, false
-
-Helper method that returns true for a new result. The method returns false if `result.value` is not nil, if `result.errors` is not empty, if the status has been manually set with `#success!` or `#failure!`, or if the result has been halted.
+Performs a fuzzy comparison with the other object. At a minimum, the other object must respond to `#value`, `#success?`, `#error` and the values of `other.value`, `other.success?`, and `other.error` must be equal to the corresponding value on the result. Returns true if all values match, otherwise returns false.
 
-#### `#errors`
+#### `#error`
 
-    errors() #=> Array
+    error() #=> nil
 
-The errors generated by the command, or an empty array if no errors were generated.
+The error generated by the command, or `nil` if no error was generated.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#errors-instance_method)
-
-#### `#failure!`
-
-    failure!() #=> Cuprum::Result
-
-Marks the result as failing and returns the result. Calling `#failure?` will return true, even if the result has no errors.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure!-instance_method)
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#error-instance_method)
 
 #### `#failure?`
 
     failure?() #=> true, false
 
-True if the command generated one or more errors or was marked as failing. Otherwise false.
+True if the command generated an error or was marked as failing. Otherwise false.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
 
-#### `#halt!`
-
-    halt!() #=> Cuprum::Result
-
-Marks the result as halted and returns the result. Calling `#halted?` will return true.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#halt!-instance_method)
-
-#### `#halted?`
-
-    halted?() #=> true, false
-
-True if the result is halted, which prevents chained commands from executing.
-
-#### `#success!`
-
-    success!() #=> Cuprum::Result
-
-Marks the result as passing and returns the result. Calling `#success?` will return true, even if the result has errors.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success!-instance_method)
-
 #### `#success?`
 
     success?() #=> true, false
 
-True if the command did not generate any errors, or the result has errors but was marked as passing. Otherwise false.
+True if the command did not generate an error, or the result has an error but was marked as passing. Otherwise false.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success%3F-instance_method)
 
@@ -1465,9 +1325,9 @@ Finds or creates a spy object for the given module or class. Each time that the
     # Observing calls to instances of a command.
     spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
 
-    expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+    expect(spy).to receive(:call).with(1, 2, 3, four: '4')
 
-    CustomCommand.new.call(1, 2, 3, :four => '4')
+    CustomCommand.new.call(1, 2, 3, four: '4')
 
     # Observing calls to a chained command.
     spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
@@ -1483,6 +1343,6 @@ Finds or creates a spy object for the given module or class. Each time that the
       expect(spy).to receive(:call)
 
       CustomCommand.new.call
-    end # spy_on
+    end
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)