cuprum 0.10.0 → 1.0.0.rc.1

data/README.md

@@ -4,45 +4,41 @@ An opinionated implementation of the Command pattern for Ruby applications. Cupr
 
 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) - 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.
+- [Commands](#Commands) - A function-like object that responds to `#call` and returns a `Result`.
+- [Operations](#Operations) - A stateful `Command` that wraps and delegates to its most recent `Result`.
+- [Results](#Results) - An immutable data object with a status (either `:success` or `:failure`), and optional `#value` and/or `#error` objects.
+- [Errors](#Errors) - Encapsulates a failure state of a command.
+- [Matchers](#Matchers) - Define handling for results based on status, error, and value.
 
 ## About
 
-[comment]: # "Status Badges will go here."
-
 Traditional frameworks such as Rails focus on the objects of your application - the "nouns" such as User, Post, or Item. Using Cuprum or a similar library allows you the developer to make your business logic - the "verbs" such as Create User, Update Post or Ship Item - a first-class citizen of your project. This provides several advantages:
 
 - **Consistency:** Use the same Commands to underlie controller actions, worker processes and test factories.
 - **Encapsulation:** Each Command is defined and run in isolation, and dependencies must be explicitly provided to the command when it is initialized or run. This makes it easier to reason about the command's behavior and keep it insulated from changes elsewhere in the code.
 - **Testability:** Because the logic is extracted from unnecessary context, testing its behavior is much cleaner and easier.
-- **Composability:** Complex logic such as "find the object with this ID, update it with these attributes, and log the transaction to the reporting service" can be extracted into a series of simple Commands and composed together. The [Chaining](#label-Chaining+Commands) feature allows for complex control flows.
+- **Composability:** Complex logic such as "find the object with this ID, update it with these attributes, and log the transaction to the reporting service" can be extracted into a series of simple Commands and composed together. The [step](#label-Command+Steps) feature allows for complex control flows.
 - **Reusability:** Logic common to multiple data models or instances in your code, such as "persist an object to the database" or "find all records with a given user and created in a date range" can be refactored into parameterized commands.
 
-### Alternatives
+### Why Cuprum?
+
+Cuprum allows you to define or extract business logic from models, controllers, jobs or freeform services, and to control the flow of that logic by composing together atomic commands. At its heart, Cuprum relies on three features: commands, results, and control flow using steps.
 
-If you want to extract your logic but Cuprum is not the right solution for you, there are a number of alternatives, including
-[ActiveInteraction](https://github.com/AaronLasseigne/active_interaction),
-[Dry::Monads](https://dry-rb.org/gems/dry-monads/),
-[Interactor](https://github.com/collectiveidea/interactor),
-[Trailblazer](http://trailblazer.to/) Operations,
-and [Waterfall](https://github.com/apneadiving/waterfall).
+There are a number of other Ruby libraries and frameworks that provide similar solutions, such as [ActiveInteraction](https://github.com/AaronLasseigne/active_interaction), [Interactor](https://github.com/collectiveidea/interactor), and [Waterfall](https://github.com/apneadiving/waterfall). These libraries may focus on only one aspect (e.g. defining commands or control flow), or include features deliberately omitted from Cuprum such as hooks or callbacks.
+
+On the opposite end of the scale, frameworks such as [Dry::Monads](https://dry-rb.org/gems/dry-monads/) or [Trailblazer](http://trailblazer.to/) can also provide similar functionality to Cuprum. These frameworks require a larger commitment to use, particularly for a smaller team or on a smaller project, and often use idiosyncratic syntax that requires a steep learning curve. Cuprum is designed to offer a lightweight alternative that should be much more accessible to new developers.
 
 ### Compatibility
 
-Cuprum is tested against Ruby (MRI) 2.3 through 2.5.
+Cuprum is tested against Ruby (MRI) 2.6 through 3.0.
 
 ### Documentation
 
-Method and class documentation is available courtesy of [RubyDoc](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master).
-
 Documentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.
 
 ### License
 
-Copyright (c) 2019 Rob Smith
+Copyright (c) 2019-2021 Rob Smith
 
 Cuprum is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -54,11 +50,315 @@ To report a bug or submit a feature request, please use the [Issue Tracker](http
 
 To contribute code, please fork the repository, make the desired updates, and then provide a [Pull Request](https://github.com/sleepingkingstudios/cuprum/pulls). Pull requests must include appropriate tests for consideration, and all code must be properly formatted.
 
-### Credits
+### Code of Conduct
+
+Please note that the `Cuprum` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/cuprum/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
+
+## Getting Started
+
+Let's take a look at using Cuprum to define some business logic. Consider the following case study: we are defining an API for a lending library. We'll start by looking at our core models:
+
+- A `Patron` is a user who can borrow books from the library.
+- A `Title` represents a book, of which the library may have one or many copies.
+- A `PhysicalBook` represents one specific copy of a book. Each `PhysicalBook` belongs to a `Title`, and each `Title` can have zero, one, or many `PhysicalBook`s. A given `PhysicalBook` may or may not be available to lend out (borrowed by a patron, missing, or damaged).
+- A `BookLoan` indicates that a specific `PhysicalBook` is either being held for or checked out by a `Patron`.
+
+Some books are more popular than others, so library patrons have asked for a way to reserve a book so they can borrow it when a copy becomes available. We could build this feature in the traditional Rails fashion, but the logic is a bit more complicated and our controller will get kind of messy. Let's try building the logic using commands instead. We've already built our new model:
+
+- A `BookReservation` indicates that a `Patron` is waiting for the next available copy of a `Title`. Whenever the next `PhysicalBook` is available, then the oldest `BookReservation` will convert into a `BookLoan`.
+
+Here is the logic required to fulfill a reserve book request:
+
+- Validate the `Patron` making the request, based on the `patron_id` API parameter.
+    - Does the patron exist?
+    - Is the patron active?
+    - Does the patron have unpaid fines?
+- Validate the `Title` requested, based on the `title_id` API parameter.
+    - Does the book exist in the system?
+    - Are there any physical copies of the book in the system?
+- Are all of the physical books checked out?
+    - If so, we create a `BookReservation` for the `Title` and the `Patron`.
+    - If not, we create a `BookLoan` for a `PhysicalBook` and the `Patron`.
+
+Let's get started by handling the `Patron` validation.
+
+```ruby
+class FindValidPatron < Cuprum::Command
+  private
+
+  def check_active(patron)
+    return if patron.active?
+
+    failure(Cuprum::Error.new(message: "Patron #{patron.id} is not active"))
+  end
+
+  def check_unpaid_fines(patron)
+    return unless patron.unpaid_fines.empty?
+
+    failure(Cuprum::Error.new(message: "Patron #{patron_id} has unpaid fines"))
+  end
+
+  def find_patron(patron_id)
+    Patron.find(patron_id)
+  rescue ActiveRecord::RecordNotFound
+    failure(Cuprum::Error.new(message: "Unable to find patron #{patron_id}"))
+  end
+
+  def process(patron_id)
+    patron = step { find_patron(patron_id) }
+
+    step { check_active(patron) }
+
+    step { check_unpaid_fines(patron) }
+
+    success(patron)
+  end
+end
+```
+
+There's a lot going on there, so let's dig in. We start by defining a subclass of `Cuprum::Command`. Each command must define a `#process` method, which implements the business logic of the command. In our case, `#process` is a method that takes one argument (the `patron_id`) and defines a series of steps.
+
+Steps are a key feature of Cuprum that allows managing control flow through a command. Each `step` has a code block, which can return either a `Cuprum::Result` (either passing or failing) or any Ruby object. If the block returns an object or a passing result, the step passes and returns the object or the result value. However, if the block returns a failing result, then the step fails and halts execution of the command, which immediately returns the failing result.
+
+In our `FindValidPatron` command, we are defining three steps to run in sequence. This allows us to eschew conditional logic - we don't need to assert that a Patron exists before checking whether they are active, because the `step` flow handles that automatically. Looking at the first line in `#process`, we also see that a passing `step` returns the *value* of the result, rather than the result itself - there's no need for an explicit call to `result.value`.
+
+Finally, `Cuprum::Command` defines some helper methods. Each of our three methods includes a `failure()` call. This is a helper method that wraps the given error in a `Cuprum::Result` with status: `:failure`. Likewise, the final line in `#process` has a `success()` call, which wraps the value in a result with status: `:success`.
+
+Let's move on to finding and validating the `Title`.
+
+```ruby
+class FindValidTitle < Cuprum::Command
+  private
+
+  def find_title(title_id)
+    Title.find(title_id)
+  rescue ActiveRecord::RecordNotFound
+    failure(Cuprum::Error.new(message: "Unable to find title #{title_id}"))
+  end
+
+  def has_physical_copies?(title)
+    return unless title.physical_books.empty?
+
+    failure(Cuprum::Error.new(message: "No copies of title #{title_id}"))
+  end
+
+  def process(title_id)
+    title = step { find_title(title_id) }
+
+    step { has_physical_copies?(title) }
+
+    success(title)
+  end
+end
+```
+
+This command is pretty similar to the `FindValidPatron` command. We define a `#process` method that has a few steps, each of which delegates to a helper method. Note that we have a couple of different interaction types here. The `#find_title` method captures exception handling and translates it into a Cuprum result, while the `#has_physical_copies?` method handles conditional logic. We can also see using the first `step` in the `#process` method to easily transition from Cuprum into plain Ruby.
+
+We've captured some of our logic in sub-commands - let's see what it looks like putting it all together.
+
+```ruby
+class LoanOrReserveTitle < Cuprum::Command
+  private
+
+  def available_copies?(title)
+    title.physical_books.any?(&:available?)
+  end
+
+  def loan_book(patron:, title:)
+    physical_book = title.physical_books.select(&:available?).first
+    loan          = BookLoan.new(loanable: physical_book, patron: patron)
+
+    if loan.valid?
+      loan.save
+
+      success(loan)
+    else
+      message = "Unable to loan title #{title.id}:" \
+                " #{reservation.errors.full_messages.join(' ')}"
+      error   = Cuprum::Error.new(message: message)
+
+      failure(error)
+    end
+  end
+
+  def process(title_id:, patron_id:)
+    patron = step { FindValidPatron.new.call(patron_id) }
+    title  = step { FindValidTitle.new.call(title_id) }
+
+    if available_copies?(title)
+      loan_book(patron: patron, title: title)
+    else
+      reserve_title(patron: patron, title: title)
+    end
+  end
+
+  def reserve_title(patron:, title:)
+    reservation = BookReservation.new(patron: patron, title: title)
+
+    if reservation.valid?
+      reservation.save
+
+      success(reservation)
+    else
+      message = "Unable to reserve title #{title.id}:" \
+                " #{reservation.errors.full_messages.join(' ')}"
+      error   = Cuprum::Error.new(message: message)
+
+      failure(error)
+    end
+  end
+end
+```
+
+This command pulls everything together. Instead of using helper methods to power our steps, we are instead using our previously defined commands.
+
+Through the magic of composition, each of the checks we defined in our prior commands is used to gate the control flow - the patron must exist, be active and have no unpaid fines, and the book must exist and have physical copies. If any of those steps fail, the command will halt execution and return the relevant error. Conversely, we're able to encapsulate that logic - reading through `ReserveBook`, we don't need to know the details of what makes a valid patron or book (but if we do need to look into things, we know right where that logic lives and how it was structured).
+
+Finally, we're using plain old Ruby conditionals to determine whether to reserve the book or add the patron to a wait list. Cuprum is a powerful tool, but you don't have to use it for everything - it's specifically designed to be easy to move back and forth between Cuprum and plain Ruby. We could absolutely define a `HasAvailableCopies` command, but we don't have to.
+
+### Using The Command
+
+We've defined our `LoanOrReserveTitle` command. How can we put it to work?
+
+```ruby
+command = LoanOrReserveTitle.new
+
+# With invalid parameters.
+result = command.call(patron_id: 1_000, title_id: 0)
+result.status   #=> :failure
+result.success? #=> false
+result.error    #=> A Cuprum::Error with message "Unable to find patron 1000"
+
+# With valid parameters.
+result = command.call(patron_id: 0, title_id: 0)
+result.status   #=> :success
+result.success? #=> true
+result.value    #=> An instance of BookReservation or WaitingListReservation.
+```
+
+Using a `Cuprum` command is simple:
+
+First, instantiate the command. In our case, we haven't defined any constructor parameters, but other commands might. For example, a `SearchRecords` command might take a `record_class` parameter to specify which model class to search.
+
+Second, call the command using the `#call` method. Here, we are passing in `book_id` and `patron_id` keywords. Internally, the command is delegating to the `#process` method we defined (with some additional logic around handling `step`s and ensuring that a result object is returned).
+
+The return value of `#call` will always be a `Cuprum::Result`. Each result has the following properties:
+
+- A `#status`, either `:success` or `:failure`. Also defines corresponding helper methods `#success?` and `#failure?`.
+- A `#value`. By convention, most successful results will have a non-`nil` value, such as the records returned by a query.
+- An `#error`. Each failing result should have a non-`nil` error. Using an instance of `Cuprum::Error` or a subclass is strongly recommended, but a result error could be a simple message or other errors object.
 
-Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use these tools every day, but they're not just written for me. If you find this project helpful in your own work, or if you have any questions, suggestions or critiques, please feel free to get in touch! I can be reached [on GitHub](https://github.com/sleepingkingstudios/cuprum) or [via email](mailto:merlin@sleepingkingstudios.com). I look forward to hearing from you!
+In rare cases, a result may have both a value and an error, such as the result for a partial query.
 
-## Concepts
+Now that we know how to use a command, how can we integrate it into our application? Our original use case is defining an API, so let's build a controller action.
+
+```ruby
+class ReservationsController
+  def create
+    command = LoanOrReserveTitle.new
+    result  = command.call(patron_id: patron_id, title_id: title_id)
+
+    if result.failure?
+      render json: { ok: false, message: result.error.message }
+    elsif result.value.is_a?(BookReservation)
+      render json: {
+        ok:      true,
+        message: "You've been added to the wait list."
+      }
+    else
+      render json: {
+        ok:      true,
+        message: 'Your book is waiting at your local library!'
+      }
+    end
+  end
+
+  private
+
+  def patron_id
+    params.require(:patron_id)
+  end
+
+  def title_id
+    params.require(:title_id)
+  end
+end
+```
+
+All of the complexity of the business logic is encapsulated in the command definition - all the controller needs to do is call the command and check the result.
+
+### Next Steps
+
+We've defined a command to encapsulate our business logic, and we've incorporated that command into our application. Where can we go from here?
+
+One path forward is extracting out more of the logic into commands. Looking back over our code, we're relying heavily on some of the pre-existing methods on our models. Extracting this logic lets us simplify our models.
+
+We can also use Cuprum to reduce redundancy. Take another look at `LoanOrReserveTitle` - the `#loan_book` and `#reserve_title` helper methods look pretty similar. Both methods take a set of attributes, build a record, validate the record, and then save the record to the database. We can build a command that implements this behavior for any record class.
+
+```ruby
+class InvalidRecordError < Cuprum::Error
+  def initialize(errors:, message: nil)
+    @errors = errors
+
+    super(message: generate_message(message))
+  end
+
+  attr_reader :errors
+
+  private
+
+  def generate_message(message)
+    "#{message}: #{errors.full_messages.join(' ')}"
+  end
+end
+
+class CreateRecord
+  def initialize(record_class:, short_message: nil)
+    @record_class  = record_class
+    @short_message = short_message
+  end
+
+  attr_reader :record_class
+
+  def short_message
+    @short_message ||= "create #{record_class_name}"
+  end
+
+  private
+
+  def process(attributes:)
+    record = record_class.new(attributes)
+
+    step { validate_record(record) }
+
+    record.save
+
+    success(record)
+  end
+
+  def record_class_name
+    record_class.name.split('::').last.underscore.tr('_', ' ')
+  end
+
+  def validate_record(record)
+    return if record.valid?
+
+    error = InvalidRecordError.new(
+      errors:  record.errors,
+      message: "Unable to #{short_message}"
+    )
+    failure(error)
+  end
+end
+```
+
+This command is a little more advanced than the ones we've built previously. We start by defining a constructor for the command. This allows us to customize the behavior of the command for each use case, in this case specifying what type of record we are building. We continue using steps to manage control flow and handle errors, and helper methods to keep the `#process` method clean and readable. In a production-ready version of this command, we would probably add additional steps to encompass building the record (which can fail given invalid attribute names) and persisting the record to the database (which can fail even for valid records due to database constraints or unavailable connections).
+
+We're also defining a custom error class, which gives us three benefits. First, it allows us to move some of our presentation logic (the error message) out of the command itself. Second, it lets us pass additional context with the error, in this case the `errors` object for the invalid record object. Third, an error class gives us a method to identify what kind of error occurred.
+
+The latter two are particularly important when handling errors returned by a failing command. For example, an API response for a failed validation might include a JSON object serializing the validation errors. Likewise, the application should have different responses to an `InvalidSession` error (redirect to a login page) compared to a `BookNotFound` error (display a message and return to book selection) or a `PatronUnpaidFines` error (show a link to pay outstanding fines). Using custom error classes allows the application to adapt its behavior based on the type of failure, either with a conventional Ruby conditional or `case` statement, or by using a `Cuprum::Matcher`.
+
+## Reference
 
 ### Commands
 
@@ -68,8 +368,6 @@ Commands are the core feature of Cuprum. In a nutshell, each `Cuprum::Command` i
 
 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)
-
 #### Defining Commands
 
 The recommended way to define commands is to create a subclass of `Cuprum::Command` and override the `#process` method.
@@ -267,7 +565,7 @@ multiply_command.call(operands: [3, 3])
 #=> returns a result with value 9
 ```
 
-### Composing Commands
+#### Composing Commands
 
 Because Cuprum::Command instances are proper objects, they can be composed like any other object. For example, we could define some basic mathematical operations by composing commands:
 
@@ -328,7 +626,7 @@ add_two_command.call(8).value #=> 10
 
 You can achieve even more powerful composition by passing in a command as an argument to a method, or by creating a method that returns a command.
 
-#### Commands As Arguments
+##### Commands As Arguments
 
 Since commands are objects, they can be passed in as arguments to a method or to another command. For example, consider a command that calls another command a given number of times:
 
@@ -380,7 +678,7 @@ end
 
 This pattern is also useful for testing. When writing specs for the FulfillOrder command, simply pass in a mock double as the delivery command. This removes any need to stub out the implementation of whatever shipping method is used (or worse, calls to external services).
 
-#### Commands As Returned Values
+##### Commands As Returned Values
 
 We can also return commands as an object from a method call or from another command. One use case for this is the Abstract Factory pattern.
 
@@ -410,7 +708,7 @@ Notice that our factory includes error handling - if the user does not have a va
 
 The [Command Factory](#label-Command+Factories) defined by Cuprum is another example of using the Abstract Factory pattern to return command instances. One use case for a command factory would be defining CRUD operations for data records. Depending on the class or the type of record passed in, the factory could return a generic command or a specific command tied to that specific record type.
 
-### Command Steps
+#### Command Steps
 
 Separating out business logic into commands is a powerful tool, but it does come with some overhead, particularly when checking whether a result is passing, or when converting between results and values. When a process has many steps, each of which can fail or return a value, this can result in a lot of boilerplate.
 
@@ -526,43 +824,7 @@ result.success? #=> true
 result.value    #=> an instance of BookReservation
 ```
 
-#### Using Methods As Steps
-
-Steps can also be defined as method calls. Instead of providing a block to `#step`, provide the name of the method as the first argument, either as a symbol or as a string. Any subsequent arguments, keywords, or a block is passed to the method when it is called.
-
-A step defined with a method behaves the same as a step defined with a block. If the method returns a successful result, then `#step` will return the value of the result. If the method returns a failing result, then `#step` will throw `:cuprum_failed_result` and the result, to be caught by the `#process` method or the containing `#steps` block.
-
-We can use this to rewrite our `ReserveBookByTitle` command to use methods:
-
-```ruby
-class ReserveBookByTitle < Cuprum::Result
-  private
-
-  def check_user_status(user)
-    CheckUserStatus.new(user)
-  end
-
-  def create_book_reservation(book:, user:)
-    CreateBookReservation.new(book: book, user: user)
-  end
-
-  def find_book_by_title(title)
-    FindBookByTitle.new.call(title)
-  end
-
-  def process(title:, user:)
-    step :check_user_status, user
-
-    book = step :find_book_by_title, title
-
-    create_book_reservation, book: book, user: user
-  end
-end
-```
-
-In this case, our methods simply delegate to our previously defined commands. However, a more complex example could include other logic in each method, or even a sequence of steps defining subtasks for the method. The only requirement is that the method returns a result. You can use the `#success` helpers to wrap a non-result value, or the `#failure` helper to generate a failing result.
-
-#### Using Steps Outside Of Commands
+##### Using Steps Outside Of Commands
 
 Steps can also be used outside of a command. For example, a controller action might define a sequence of steps to run when the corresponding endpoint is called.
 
@@ -625,12 +887,43 @@ A few things to note about this example. First, we have a couple of examples of
 
 You can define even more complex logic by defining multiple `#steps` blocks. Each block represents a series of tasks that will terminate on the first failure. Steps blocks can even be nested in one another, or inside a `#process` method.
 
+#### Handling Exceptions
+
+    require 'cuprum/exception_handling'
+
+Cuprum defines a utility module to rescue uncaught exceptions when calling a command.
+
+```ruby
+class UnsafeCommand < Cuprum::Command
+  private
+
+  def process
+    raise 'Something went wrong.'
+  end
+end
+
+class SafeCommand < UnsafeCommand
+  include Cuprum::ExceptionHandling
+end
+
+UnsafeCommand.new.call
+#=> raises a StandardError
+
+result = SafeCommand.new.call
+#=> a Cuprum::Result
+result.error
+#=> a Cuprum::Errors::UncaughtException error.
+result.error.message
+#=> 'uncaught exception in SafeCommand -' \
+    ' StandardError: Something went wrong.'
+```
+
+Exception handling is *not* included by default - add `include Cuprum::ExceptionHandling` to your command classes to use this feature.
+
 ### Results
 
     require 'cuprum'
 
-[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 `#error` object (defaults to `nil`), and a `#status` (either `:success` or `:failure`, and accessible via the `#success?` and `#failure?` predicates).
 
 ```ruby
@@ -700,38 +993,52 @@ result.failure? #=> false
 
     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.
+A `Cuprum::Error` encapsulates a specific failure state of a Command. Each Error has a `#message` property which defaults to nil. Each Error also has a `#type` property which is determined by the Error class or subclass, although it can be overridden by passing a `:type` parameter to the constructor.
 
 ```ruby
 error = Cuprum::Error.new
 error.message => # nil
+error.type    => 'cuprum.error'
 
 error = Cuprum::Error.new(message: 'Something went wrong.')
 error.message => # 'Something went wrong.'
+
+error = Cuprum::Error.new(type: 'example.custom_type')
+error.type => 'example.custom_type'
 ```
 
 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
+  TYPE = 'example.errors.not_found'
+
   def initialize(resource:, resource_id:)
     @resource    = resource
     @resource_id = resource_id
 
-    super(message: "#{resource} not found with id #{resource_id}")
+    super(
+      message:     "#{resource} not found with id #{resource_id}",
+      resource:    resource,
+      resource_id: resource_id
+    )
   end
 
   attr_reader :resource, :resource_id
 end
 
 class ValidationError < Cuprum::Error
+  TYPE = 'example.errors.validation'
+
   def initialize(resource:, errors:)
     @resource = resource
     @errors   = errors
 
-    super(message: "#{resource} was invalid")
+    super(
+      errors:   errors,
+      message:  "#{resource} was invalid",
+      resource: resource
+    )
   end
 
   attr_reader :resource, :errors
@@ -740,12 +1047,182 @@ end
 
 It is optional but recommended to use a `Cuprum::Error` when returning a failed result from a command.
 
+#### Comparing Errors
+
+There are circumstances when it is useful to compare Error objects, such as when writing tests to specify the failure states of a command. To accommodate this, you can pass additional properties to `Cuprum::Error.new` (or to `super` when defining a subclass). These "comparable properties", plus the type and message (if any), are used to compare the errors.
+
+An instance of `Cuprum::Error` is equal to another (using the `#==` equality comparison) if and only if the two errors have the same `class` and the two errors have the same comparable properties.
+
+```ruby
+red     = Cuprum::Error.new(message: 'wrong color', color: 'red')
+blue    = Cuprum::Error.new(message: 'wrong color', color: 'blue')
+crimson = Cuprum::Error.new(message: 'wrong color', color: 'red')
+
+red == blue
+#=> false
+
+red == crimson
+#=> true
+```
+
+This can be particularly important when defining Error subclasses. By passing the constructor parameters to `super`, below, we will be able to compare different instances of the `NotFoundError`. The errors will only be equal if they have the same message, resource, and resource_id properties.
+
+```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}",
+      resource:    resource,
+      resource_id: resource_id,
+    )
+  end
+
+  attr_reader :resource, :resource_id
+end
+```
+
+Finally, by overriding the `#comparable_properties` method, you can customize how Error instances are compared.
+
+```ruby
+class WrongColorError < Cuprum::Error
+  def initialize(color:, shape:)
+    super(message: "the #{shape} is the wrong color")
+
+    @color = color
+    @shape = shape
+  end
+
+  attr_reader :color
+
+  protected
+
+  def comparable_properties
+    { color: color }
+  end
+end
+```
+
+#### Serializing Errors
+
+Some use cases require serializing error objects - for example, rendering an error response as JSON. To handle this, `Cuprum::Error` defines an `#as_json` method, which generates a representation of the error as a `Hash` with `String` keys. By default, this includes the `#type` and `#message` (if any) as well as an empty `:data` Hash.
+
+Subclasses can override this behavior to include additional information in the `:data` Hash, which should always use `String` keys and have values composed of basic types and data structures. For example, if an error is passed a `Class`, consider serializing the name of the class to `:data`.
+
+```ruby
+error = Cuprum::Error.new
+error.as_json #=> { data: {}, message: nil, type: 'cuprum.error' }
+
+error = Cuprum::Error.new(message: 'Something went wrong.')
+error.as_json #=> { data: {}, message: 'Something went wrong.', type: 'cuprum.error' }
+
+error = Cuprum::Error.new(type: 'example.custom_error')
+error.as_json #=> { data: {}, message: nil, type: 'example.custom_error' }
+
+class ModuleError < Cuprum::Error
+  TYPE = 'example.module_error'
+
+  def initialize(actual:)
+    @actual = actual
+    message = "Expected a Module, but #{actual.name} is a Class"
+
+    super(actual: actual, message: message)
+  end
+
+  attr_reader :actual
+
+  private
+
+  def as_json_data
+    { actual: actual.name }
+  end
+end
+
+error = ModuleError.new(actual: String)
+error.as_json #=>
+# {
+#   data:    { actual: 'String' },
+#   message: 'Expected a Module, but String is a Class',
+#   type:    'example.module_error'
+# }
+```
+
+**Important Note:** Be careful when serializing error data - this may expose sensitive information or internal details about your system that you don't want to display to users. Recommended practice is to have a whitelist of serializable errors; all other errors will display a generic error message instead.
+
+### Middleware
+
+```ruby
+require 'cuprum/middleware'
+```
+
+A middleware command wraps the execution of another command, allowing the developer to compose functionality without an explicit wrapper command. Because the middleware is responsible for calling the wrapped command, it has control over when that command is called, with what parameters, and how the command result is handled.
+
+To use middleware, start by defining a middleware command. This can either be a class that includes Cuprum::Middleware, or a command instance that extends Cuprum::Middleware. Each middleware command's #process method takes as its first argument the wrapped command. By convention, any additional arguments and any keywords or a block are passed to the wrapped command, but some middleware will override ths behavior.
+
+```ruby
+class ExampleCommand < Cuprum::Command
+  private def process(**options)
+    return failure(options[:error]) if options[:error]
+
+    "Options: #{options.inspect}"
+  end
+end
+
+class LoggingMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  # The middleware injects a logging step before the wrapped command is
+  # called. Notice that this middleware is generic, and can be used with
+  # virtually any other command.
+  private def process(next_command, *args, **kwargs)
+    Logger.info("Calling command #{next_command.class}")
+
+    super
+  end
+end
+
+command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+middleware = LoggingMiddleware.new
+result     = middleware.call(command, { id: 0 })
+#=> logs "Calling command ExampleCommand"
+result.value
+#=> "Options: { id: 0 }"
+```
+
+When defining #process, make sure to either call super or call the wrapped command directly, unless the middleware is specifically intended not to call the wrapped command under those circumstances.
+
+Middleware is powerful because it allows the developer to manipulate the parameters passed to a command, add handling to a result, or even intercept or override the command execution. These are some of the possible use cases for middleware:
+
+- Injecting code before or after a command.
+- Changing the parameters passed to a command.
+- Adding behavior based on the command result.
+- Overriding the command behavior based on the parameters.
+
+```ruby
+class AuthenticationMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  # The middleware finds the current user based on the given keywords. If
+  # a valid user is found, the user is then passed on to the command.
+  # If a user is not found, then the middleware will immediately halt (due
+  # to #step) and return the failing result from the authentication
+  # command.
+  private def process(next_command, *args, **kwargs)
+    current_user = step { AuthenticateUser.new.call(**kwargs) }
+
+    super(next_command, *args, current_user: current_user, **kwargs)
+  end
+end
+```
+
+Middleware is loosely coupled, meaning that one middleware command can wrap any number of other commands. One example would be logging middleware, which could record when a command is called and with what parameters. For a more involved example, consider authorization in a web application. If individual actions are defined as commands, then a single authorization middleware class could wrap each individual action, reducing both the testing burden and the amount of code that must be maintained.
+
 ### Operations
 
     require 'cuprum'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
-
 An Operation is like a Command, but with two key differences. First, an Operation retains a reference to the result object from the most recent time the operation was called, and delegates the methods defined by `Cuprum::Result` to the most recent result. This allows a called Operation to replace a `Cuprum::Result` in any code that expects or returns a result. Second, the `#call` method returns the operation instance, rather than the result itself.
 
 These two features allow developers to simplify logic around calling and using the results of operations, and reduce the need for boilerplate code (particularly when using an operation as part of an existing framework, such as inside of an asynchronous worker or a Rails controller action).
@@ -777,13 +1254,235 @@ An operation inherits the `#call` method from Cuprum::Command (see above), and d
 
 #### The Operation Mixin
 
-[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
-
 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.
 
-### Command Factories
+### Matchers
+
+    require 'cuprum/matcher'
+
+A Matcher provides a simple DSL for defining behavior based on a Cuprum result object.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:failure) { 'Something went wrong' }
+
+  match(:success) { 'Ok' }
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> 'Something went wrong'
+
+matcher.call(Cuprum::Result.new(status: :success))
+#=> 'Ok'
+```
+
+First, the matcher defines possible matches using the `.match` method. This can either be called on a subclass of `Cuprum::Matcher` or by passing a block to the constructor, as above. Each match clause must have the matching status, and a block that is executed when a result matches that clause. The clause can also filter by the result value or error (see Matching Values And Errors, below).
+
+Once the matcher has found a matching clause, it then calls the block in the clause definition. If the block accepts an argument, the result is passed to the block; otherwise, the block is called with no arguments. This allows the match clause to use the error or value of the result.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:failure) { |result| result.error.message }
+end
+
+error = Cuprum::Error.new(message: 'An error has occurred.')
+matcher.call(Cuprum::Result.new(error: error))
+#=> 'An error has occurred.'
+```
+
+If the result does not match any of the clauses, a `Cuprum::Matching::NoMatchError` is raised.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success) { :ok }
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> raises Cuprum::Matching::NoMatchError
+```
+
+#### Matching Values And Errors
+
+In addition to a status, match clauses can specify the type of the value or error of a matching result. The error or value must be a Class or Module, and the clause will then match only results whose error or value is an instance of the specified Class or Module (or a subclass of the Class).
+
+```ruby
+class MagicSmokeError < Cuprum::Error; end
+
+matcher = Cuprum::Matcher.new do
+  match(:failure) { 'Something went wrong.' }
+
+  match(:failure, error: Cuprum::Error) do |result|
+    "ERROR: #{result.error.message}"
+  end
+
+  match(:failure, error: MagicSmokeError) do
+    "PANIC: #{result.error.message}"
+  end
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> 'Something went wrong.'
+
+error = Cuprum::Error.new(message: 'An error has occurred.')
+matcher.call(Cuprum::Result.new(error: error)
+#=> 'ERROR: An error has occurred.'
+
+error = MagicSmokeError.new(message: 'The magic smoke is escaping.')
+matcher.call(Cuprum::Result.new(error: error))
+#=> 'PANIC: The magic smoke is escaping.'
+```
+
+The matcher will always apply the most specific match clause. In the example above, the result with a `MagicSmokeError` matches all three clauses, but only the final clause is executed.
+
+You can also specify the value of a matching result:
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success, value: String) { 'a String' }
+
+  match(:success, value: Symbol) { 'a Symbol' }
+end
+
+matcher.call(Cuprum::Result.new(value: 'Greetings, programs!'))
+#=> 'a String'
+
+matcher.call(Cuprum::Result.new(value: :greetings_starfighter))
+#=> 'a Symbol'
+```
+
+#### Using Matcher Classes
+
+Matcher classes allow you to define custom behavior that can be called as part of the defined match clauses.
+
+```ruby
+class LogMatcher < Cuprum::Matcher
+  match(:failure) { |result| log(:error, result.error.message) }
+
+  match(:success) { log(:info, 'Ok') }
+
+  def log(level, message)
+    puts "#{level.upcase}: #{message}"
+  end
+end
+
+matcher = LogMatcher.new
+matcher.call(Cuprum::Result.new(status: :success))
+#=> prints "INFO: Ok" to STDOUT
+```
+
+Match clauses are also inherited by matcher subclasses. Inherited clauses are sorted the same as clauses defined on the matcher directly - the most specific clause is matched first, followed by less specific clauses and finally the generic clause (if any) for that result status.
+
+```ruby
+class CustomLogMatcher < Cuprum::Matcher
+  match(:failure, error: ReallyBadError) do |result|
+    log(:fatal, result.error.message)
+  end
+end
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommandFactory)
+matcher = CustomLogMatcher.new
+result  = Cuprum::Result.new(error: Cuprum::Error.new('Something went wrong.'))
+matcher.call(result)
+#=> prints "ERROR: Something went wrong." to STDOUT
+
+result  = Cuprum::Result.new(error: ReallyBadError.new('Computer on fire.'))
+matcher.call(result)
+#=> prints "FATAL: Computer on fire." to STDOUT
+```
+
+#### Match Contexts
+
+Match contexts provide an alternative to defining custom matcher classes - instead of defining custom behavior in the matcher itself, the match clauses can be executed in the context of another object.
+
+```ruby
+class Inflector
+  def capitalize(message)
+    message.split(' ').map(&:capitalize).join(' ')
+  end
+end
+
+matcher = Cuprum::Matcher.new(inflector) do
+  match(:success) { |result| capitalize(result.value) }
+end
+matcher.call(Cuprum::Result.new(value: 'greetings starfighter'))
+#=> 'Greetings Starfighter'
+```
+
+For example, a controller in a web framework might need to define behavior for handling different success and error cases for business logic that is defined as Commands. The controller itself defines methods such as `#render` and `#redirect` - by creating a matcher using the controller as the match context, the matcher can call upon those methods to generate a response.
+
+You can also call an existing matcher with a new context. The `#with_context` method returns a copy of the matcher with the given object set as the match context.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success) { |result| capitalize(result.value) }
+end
+matcher
+  .with_context(inflector)
+  .call(Cuprum::Result.new(value: 'greetings starfighter'))
+#=> 'Greetings Starfighter'
+```
+
+#### Matcher Lists
+
+Matcher lists handle matching a result against an ordered group of matchers.
+
+When given a result, a matcher list will check for the most specific matching clause in each of the matchers. A clause matching both the value and error will match first, followed by a clause matching only the result value or error, and finally a clause matching only the result status will match.
+
+If none of the matchers have a clause that matches the result, a `Cuprum::Matching::NoMatchError` will be raised.
+
+```ruby
+generic_matcher = Cuprum::Matcher.new do
+  match(:failure) { 'generic failure' }
+  #
+  match(:failure, error: CustomError) { 'custom failure' }
+end
+specific_matcher = Cuprum::Matcher.new do
+  match(:failure, error: Cuprum::Error) { 'specific failure' }
+end
+matcher_list = Cuprum::MatcherList.new(
+  [
+    specific_matcher,
+    generic_matcher
+  ]
+)
+
+generic_matcher = Cuprum::Matcher.new do
+  match(:failure) { 'generic failure' }
+
+  match(:failure, error: CustomError) { 'custom failure' }
+end
+specific_matcher = Cuprum::Matcher.new do
+  match(:failure, error: Cuprum::Error) { 'specific failure' }
+end
+matcher_list = Cuprum::MatcherList.new(
+  [
+    specific_matcher,
+    generic_matcher
+  ]
+)
+
+# A failure without an error does not match the first matcher, so the
+# matcher list continues on to the next matcher in the list.
+result = Cuprum::Result.new(status: :failure)
+matcher_list.call(result)
+#=> 'generic failure'
+
+# A failure with an error matches the first matcher.
+error  = Cuprum::Error.new(message: 'Something went wrong.')
+result = Cuprum::Result.new(error: error)
+matcher_list.call(result)
+#=> 'specific failure'
+
+# A failure with an error subclass still matches the first matcher, even
+# though the second matcher has a more exact match.
+error  = CustomError.new(message: 'The magic smoke is escaping.')
+result = Cuprum::Result.new(error: error)
+matcher_list.call(result)
+#=> 'specific failure'
+```
+
+One use case for matcher lists would be in defining hierarchies of classes or objects that have matching functionality. For example, a generic controller class might define default success and failure behavior, an included mixin might provide handling for a particular scope of errors, and a specific controller might override the default behavior for a given action. Using a matcher list allows each class or module to define its own behavior as independent matchers, which the matcher list then composes together.
+
+### Command Factories
 
 Commands are powerful and flexible objects, but they do have a few disadvantages compared to traditional service objects which allow the developer to group together related functionality and shared implementation details. To bridge this gap, Cuprum implements the CommandFactory class. Command factories provide a DSL to quickly group together related commands and create context-specific command classes or instances.
 
@@ -1089,8 +1788,6 @@ Cuprum includes a small number of predefined commands and their equivalent opera
 
     require 'cuprum/built_in/identity_command'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
-
 A pregenerated command that returns the value or result with which it was called.
 
 ```ruby
@@ -1104,8 +1801,6 @@ result.success? #=> true
 
     require 'cuprum/built_in/identity_operation'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
-
 A pregenerated operation that sets its result to the value or result with which it was called.
 
 ```ruby
@@ -1118,8 +1813,6 @@ operation.success? #=> true
 
     require 'cuprum/built_in/null_command'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
-
 A pregenerated command that does nothing when called. Accepts any arguments.
 
 ```ruby
@@ -1133,8 +1826,6 @@ result.success? #=> true
 
     require 'cuprum/built_in/null_operation'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
-
 A pregenerated operation that does nothing when called. Accepts any arguments.
 
 ```ruby
@@ -1142,7 +1833,3 @@ operation = Cuprum::BuiltIn::NullOperation.new.call
 operation.value    #=> nil
 operation.success? #=> true
 ```
-
-## Reference
-
-Method and class documentation is available courtesy of [RubyDoc](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master).