clean-architecture 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cff6e5d81156369ad42cbb55c06b1931b4949da5c1c3c1a80a2425d3307b459f
-  data.tar.gz: 6fa2e337acd93963c6fa915f70a4109b81ec2540721b086416a275b981593eac
+  metadata.gz: 79fccd9c446b769e45c8e7c4a6f378789cd33ae10a299e7966186c6b8f8161e1
+  data.tar.gz: 566434a7e22887b2228811569bb95c4dd6e252453bec836860f5437584c8850e
 SHA512:
-  metadata.gz: ec3751be4de839c3887ec1f4ca3a7ed3f7c6abe3068cdccfa12976f93cf8882416731e74be99507e555607889f1521145b17d46e435cfa9702370bca3492f0fc
-  data.tar.gz: 46d4eb2641a76e284265d54c870ecc695381befd52c3f786eee87703aa5081cb8fdb64fee34aedb38de0dcf9dd0e4c87920bd7b6b6c6bf36010c2903b1ed2e4d
+  metadata.gz: 121377ec84ca3bc904248256b38022d206edb19e149c025be35d66296df48ac9fd4f54ee1c1924d52140a07533bd5384f9d0a2825b897a5b603f9c51414bca6e
+  data.tar.gz: 4e5cb96519180360d657833b2c853e41023bf363d249e3eaf2468cf72f1fcccc541706602dfe251838cae46cf39a1addea9a99c6e21812c06e3d81255f3b0003

data/.github/workflows/rspec.yml

@@ -0,0 +1,21 @@
+name: RSpec Test Suite
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout branch
+      uses: actions/checkout@v1
+    - name: Set up Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.5.5
+    - name: Install system packages
+      run: |
+        command -v bundler || gem install bundler
+    - name: Install gems
+      run: bundle install --jobs $(nproc) --retry 3
+    - name: Run RSpec test suite
+      run: bundle exec rspec spec

data/.gitignore

@@ -1,2 +1,3 @@
 coverage
 tags
+/Gemfile.lock

data/.ruby-version

@@ -1 +1 @@
-2.4.2
+2.5.1

data/CHANGELOG.md

@@ -1,3 +1,45 @@
+3.0.0
+
+  * Add sorbet and support for Sorbet T::Struct
+
+2.6.1
+
+  * Update dependency on dry-validation
+
+2.6.0
+
+  * Bring `UseCases::AbstractUseCase` into line with dry-validation 1.0 & co.
+    * Use cases now have a 'contract', params act as per normal
+    * Predicates have been replaced with macros, they can still be shared
+    * Context variables passed into the use case parameters are accessible within the use case as `context(:my_context)`
+    * There is no need to redefine `initialize` in use cases, you can access context with `#context` and params via `#result_of_validating_params`
+
+2.5.0
+
+  * Remove restrictions on dry-rb gem
+
+2.4.0
+
+  * Introduce `UseCases::AbstractUseCase` to make it easier to create use cases with built in
+    validation.
+  * Add `UseCases::Form` to help map HTTP parameters to a use case's parameter object.
+
+2.3.1
+
+  * Fixed an issue with optional belongs_to relations in `AbstractActiveRecordEntityBuilder`
+
+2.3.0
+
+  * `AbstractActiveRecordEntityBuilder` now has a DSL for streamlining the use of builders for `has_many` and `belongs_to` relations.
+
+2.2.0
+
+  * Made `AbstractActiveRecordEntityBuilder` work with dry-struct >= 0.0.6.
+
+2.1.0
+
+  * Added `AbstractActiveRecordEntityBuilder` to help map ActiveRecord instances to `Dry::Struct` based entities.
+
 2.0.0
 
   * Support collections for use case targets and success payloads

data/Gemfile

@@ -15,6 +15,7 @@ group :development, :test do
   gem 'rspec'
   gem 'rubocop'
   gem 'rubocop-rspec'
+  gem 'sorbet'
   gem 'stackprof'
   gem 'timecop'
 end

data/README.md

@@ -3,6 +3,33 @@
 This gem provides helper interfaces and classes to assist in the construction of application with
 Clean Architecture, as described in [Robert Martin's seminal book](https://www.amazon.com/gp/product/0134494164).
 
+Table of Contents
+=================
+
+Generated by https://github.com/ekalinin/github-markdown-toc/blob/master/gh-md-toc
+
+* [Installation](#installation)
+* [Philosophy](#philosophy)
+   * [Screaming architecture - use cases as an organisational principle](#screaming-architecture---use-cases-as-an-organisational-principle)
+   * [Design principles](#design-principles)
+      * [SRP - The Single Responsibility principle](#srp---the-single-responsibility-principle)
+      * [OCP - The Open/Closed Principle, LSP - The Liskov Substitution Principle and DIP - The Dependency Inversion Principle](#ocp---the-openclosed-principle-lsp---the-liskov-substitution-principle-and-dip---the-dependency-inversion-principle)
+      * [ISP - The Interface Segregation Principle](#isp---the-interface-segregation-principle)
+   * [Component cohesion](#component-cohesion)
+      * [REP - The Reuse/Release Equivalence Principle, CCP - The Common Closure Principle & CRP - The Common Reuse Principle](#rep---the-reuserelease-equivalence-principle-ccp---the-common-closure-principle--crp---the-common-reuse-principle)
+   * [Component coupling](#component-coupling)
+      * [ADP - The Acyclic Dependencies Principle](#adp---the-acyclic-dependencies-principle)
+      * [SDP - The Stable Dependencies Principle](#sdp---the-stable-dependencies-principle)
+      * [SAP - The Stable Abstractions Principle](#sap---the-stable-abstractions-principle)
+* [Structure](#structure)
+   * [Practical suggestions for implementation](#practical-suggestions-for-implementation)
+* [Conventions](#conventions)
+   * [Result objects](#result-objects)
+   * [Idiomatic FP](#idiomatic-fp)
+      * [Multiple bind operations](#multiple-bind-operations)
+      * [Transactions](#transactions)
+* [Helper classes](#helper-classes)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -16,15 +43,13 @@ And then execute:
     $ bundle install
     $ bundle binstubs clean-architecture
 
-## Usage
+## Philosophy
 
 The intention of this gem is to help you build applications that are built from the use case down,
 and decisions about I/O can be deferred until the last possible moment. It relies heavily on the
 [duckface-interfaces](https://github.com/samuelgiles/duckface) gem to enforce interface
 implementation.
 
-## Clean architecture principles
-
 ### Screaming architecture - use cases as an organisational principle
 
 Uncle Bob suggests that your source code organisation should allow developers to easily find a listing of all use cases your application provides. Here's an example of how this might look in a
@@ -128,7 +153,9 @@ We satisfy the SAP by:
 
 - Thinking hard about the methods and parameters we specify in our interfaces. Are they solving for a general problem? Are we likely to have to change them when requirements change, and how we can avoid that?
 
-## Practical suggestions for implementation
+## Structure
+
+### Practical suggestions for implementation
 
 * The code that manages your inputs (e.g. a Rails controller) instantiates a persistence layer
   object
@@ -166,3 +193,395 @@ We satisfy the SAP by:
 ```
   use_case = MyBankingApplication::UseCases::RetailCustomerMakesADeposit.new(input_port)
 ```
+
+## Conventions
+
+### Result objects
+
+We make use of the [Dry-Rb](https://dry-rb.org/) collection of Gems to
+provide better control flow instead of relying on `raise` and `rescue`.
+Specifically, we use:
+
+- https://dry-rb.org/gems/dry-matcher/result-matcher/
+- https://dry-rb.org/gems/dry-monads/1.0/result/
+
+### Idiomatic FP
+
+#### Multiple `bind` operations
+
+When you want to bind or chain multiple method calls using the
+previous return value, consider using [Do
+Notation](https://dry-rb.org/gems/dry-monads/1.0/do-notation/)
+
+This is inspired by the Haskell do-notation which lets you go from
+writing this:
+
+```haskell
+action1
+  >>=
+    (\ x1 -> action2
+       >>=
+         (\ x2 -> mk_action3 x1 x2 ))
+```
+
+to this:
+
+```haskell
+do
+  x1 <- action1
+  x2 <- action2
+  mk_action3 x1 x2
+```
+
+#### Transactions
+
+If you don't want to manually handle the wiring between multiple
+Success/Failure objects, you can use the
+[dry-transaction](https://dry-rb.org/gems/dry-transaction/) gem which
+abstracts this away so that you just need to define steps, and deal with
+the input from the output of the previous result.
+
+```ruby
+require "dry/transaction"
+
+class CreateUser
+  include Dry::Transaction
+
+  step :validate
+  step :create
+
+  private
+
+  def validate(input)
+    # returns Success(valid_data) or Failure(validation)
+  end
+
+  def create(input)
+    # returns Success(user)
+  end
+end
+```
+
+# Helper classes
+
+The gem comes with some useful classes that can help you achieve a cleaner architecture with less work.
+
+## Active Record Entity Builder
+
+Maintain a separation between your business entities and your database requires the use of gateways that build your entities from records in the database.
+
+For Rails applications using ActiveRecord this can involve a bunch of boilerplate code where your simply creating a hash from the attributes of the database record & using those to create a new instance of your struct based entity.
+
+The `CleanArchitecture::Builders::AbstractActiveRecordEntityBuilder` can help remove this boilerplate by handling 99% of the mapping for you.
+
+### Usage:
+
+Create a builder class and have it inherit from `CleanArchitecture::Builders::AbstractActiveRecordEntityBuilder`, from here you need to point the builder at the entity you wish for it to create instances of with `.acts_as_builder_for_entity`, from there its just a case of instantiating the builder with an instance of your AR model and calling `#build`.
+
+Relations are handled easily, just define a builder for said entity and then declare the relation with `has_many :relation_name, use: MyBuilderClass` and `belongs_to :relation_name, use: MyBuilderClass`.
+
+If you wish to override the attributes used to construct the entity you can define a `#attributes_for_entity` method with said attributes in a hash, this can be useful for complex relations, files and other attributes that don't map perfectly from the database to your struct based entity.
+
+```ruby
+class Person < ApplicationRecord
+  has_many :interests, autosave: true, dependent: :destroy
+  belongs_to :father
+end
+
+class Entities::Person < Dry::Struct
+  attribute :forename, Types::Strict::String
+  attribute :surname, Types::Strict::String
+  attribute :father, Types.Instance(Person)
+  attribute :interests, Types.Array(Types.Instance(Interest))
+  attribute :birth_month, Types::Strict::String
+end
+
+class PersonBuilder < CleanArchitecture::Builders::AbstractActiveRecordEntityBuilder
+  acts_as_builder_for_entity Entities::Person
+
+  has_many :interests, use: InterestBuilder
+  belongs_to :father, use: PersonBuilder
+
+  def attributes_for_entity
+    { birth_month: @ar_model_instance.birth_date.month }
+  end
+end
+```
+
+## Use cases with contracts, errors & form objects
+
+Finding a way to map HTTP parameters to parameters within your use case, pass back & display validation errors and coerce types are difficult to replace when moving away from the typical `MyMode.update(params.permit(:some_param))` that a standard Rails app might use.
+
+The `CleanArchitecture::UseCases` component contains some useful classes for helping to make replacing these functions a little easier whilst still maintaining good boundaries.
+
+The 'contracts' use `dry-validation` and support all options included the sharing of contracts between use cases, more information can be found here: https://dry-rb.org/gems/dry-validation/. Don't be afraid of the seemingly magical `.contract` method that use cases have, all its doing is creating an anonymous `Class` and storing it in a class variable, the methods existence is justified by how it enables form objects & helps to standardise the process a little.
+
+`dry-validation` itself is actually built on top of `dry-schema`, as such most of the useful information on predicates can be found here: https://dry-rb.org/gems/dry-schema/basics/built-in-predicates/
+
+### Usage:
+
+Usage is fairly simple, use cases define a contract, parameters handed to a use case are validated, at which point if the parameters aren't valid you'll get an `Errors` object back within a `Failure`, if they are you'll get a success with a `Parameters`.
+
+Here is an example use case for a user updating their username that does a pre-flight check to ensure the username is available:
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class UserUpdatesNickname < CleanArchitecture::UseCases::AbstractUseCase
+      contract do
+        option :my_persistence_object
+
+        params do
+          required(:user_id).filled(:id)
+          required(:nickname).filled(:str)
+        end
+
+        rule(:nickname).validate(:not_already_taken)
+
+        register_macro(:not_already_taken) do
+          unless my_persistence_object.username_is_available?(values[key_name])
+            key.failure('is already taken')
+          end
+        end
+      end
+
+      extend Forwardable
+      include Dry::Monads::Do.for(:result)
+
+      def result
+        valid_params = yield result_of_validating_params
+        context(:my_persistence_object).result_of_updating_nickname(
+          valid_params[:id],
+          valid_params[:nickname]
+        )
+      end
+    end
+  end
+end
+```
+
+You could imagine a page with a simple form asking the user to enter their new username and you may want this form to display that message if the username isn't available. The `Form` class can be used to assist with the mapping of http parameters to the use case parameters. Best of all since the forms aren't tied to the use cases they can live within your web app far away from your business logic.
+
+```ruby
+module MyWebApp
+  class NicknameUpdateForm < CleanArchitecture::UseCases::Form
+    acts_as_form_for MyBusinessDomain::UseCases::UserUpdatesNickname
+  end
+end
+```
+
+The standard Rails form builder works with instances of `Form`.
+
+Putting these both together a controller action would look like the below example.
+
+- A new instance of the use case is passed a parameter object built from `params`.
+- If the use case is successful we'll show a flash message.
+- If unsuccessful we'll take the returned `Errors` (`Entities::FailureDetails` and plain strings are also handled by `#with_errors`) and add them to the form with `#with_errors` and re-render the `edit` action.
+
+```ruby
+module MyWebApp
+  class NicknamesController < ApplicationController
+    def update
+      Dry::Matcher::ResultMatcher.call(user_updates_nickname.result) do |matcher|
+        matcher.success do |_|
+          flash[:success] = 'Nickname successfully updated'
+          redirect_to action: :edit
+        end
+
+        matcher.failure do |errors|
+          @form = nickname_update_form.with_errors(errors)
+          render :edit
+        end
+      end
+    end
+
+    private
+
+    def user_updates_nickname
+      MyBusinessDomain::UseCases::UserUpdatesNickname.new(nickname_update_form.to_parameter_object)
+    end
+
+    def nickname_update_form
+      @nickname_update_form ||= NicknameUpdateForm.new(
+        params: params.permit(:user_id, :nickname),
+        context: { my_persistence_object: MyPersistence.new }
+      )
+    end
+  end
+end
+```
+
+There won't always be a complex form in front of a use case, sometimes its just one parameter, using the above example example you could easily execute the use case with a manually constructed parameter object if it was say an API only endpoint:
+
+```ruby
+module MyWebApp
+  class NicknamesController < ApplicationController
+    def update
+      Dry::Matcher::ResultMatcher.call(user_updates_nickname.result) do |matcher|
+        matcher.success do |_|
+          render json: { success: true }
+        end
+
+        matcher.failure do |errors|
+          render json: { errors: errors.full_messages }
+        end
+      end
+    end
+
+    private
+
+    def user_updates_nickname
+      MyBusinessDomain::UseCases::UserUpdatesNickname.new(user_updates_nickname_parameters)
+    end
+
+    def user_updates_nickname_parameters
+      MyBusinessDomain::UseCases::UserUpdatesNickname.parameters(
+        context: { my_persistence_object: MyPersistence.new },
+        user_id: params[:user_id],
+        nickname: params[:nickname]
+      )
+    end
+  end
+end
+```
+
+Elements of contracts can be shared amongst use cases, this can be very helpful for `options` (context) that you know every use case in a domain may require or validation rules that you know will be used in multiple use cases. Shared contracts can help tidy up your specs too by allowing you to test all your validation logic separately to what the use case itself does.
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class SharedContract < CleanArchitecture::UseCases::Contract
+      option :my_persistence_object
+
+      register_macro(:not_already_taken?) do
+        unless not_already_taken?(values[key_name])
+          key.failure('is already taken')
+        end
+      end
+
+      private
+
+      def not_already_taken?(username)
+        my_persistence_object.username_is_available?(values[key_name])
+      end
+    end
+  end
+end
+```
+
+Using a shared contract is simple; when you define the contract for a use case just specify the shared contract as an argument to `.contract`:
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class UserUpdatesNickname < CleanArchitecture::UseCases::AbstractUseCase
+      contract(SharedContract) do
+        option :my_persistence_object
+
+        params do
+          required(:user_id).filled(:id)
+          required(:nickname).filled(:str)
+        end
+
+        rule(:nickname).validate(:not_already_taken)
+```
+
+Use cases themselves are outside of their params just plain old ruby objects. There are only a few methods you'll use composing use cases:
+
+### `#result_of_validating_params`
+
+This methods gives you a Result monad with either `Success` containing a hash of the valid params or `Failure` with an `Errors` instance containing the validation errors. The `Do` syntax from `dry-monads` helps to tidy the usage of this method up:
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class UserUpdatesAge < CleanArchitecture::UseCases::AbstractUseCase
+      contract do
+        params do
+          required(:user_id).filled(:int)
+          required(:age).filled(:int)
+        end
+      end
+
+      include Dry::Monads::Do.for(:result)
+
+      def result
+        valid_params = yield result_of_validating_params
+
+        Dry::Monads::Success(valid_params[:age] * 365)
+      end
+    end
+  end
+end
+```
+
+### `#context`
+
+Any context variables defined as `option`'s in your use case contract have to be specified whenever creating an instance of the parameter objects for your use case. In practice this means you can't accidentally forget to pass in say a persistence object / repository / factory / etc.
+
+These context variables can be used within the use case using the `context` method:
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class UserUpdatesAge < CleanArchitecture::UseCases::AbstractUseCase
+      contract do
+        option :required_persistence_object
+
+        params do
+          required(:user_id).filled(:int)
+          required(:age).filled(:int)
+        end
+      end
+
+      include Dry::Monads::Do.for(:result)
+
+      def result
+        valid_params = yield result_of_validating_params
+
+        context(:required_persistence_object).update_user_age_result(
+          valid_params[:user_id],
+          valid_params[:age]
+        )
+      end
+    end
+  end
+end
+```
+
+You may wish to tidy access to context variables away into private methods to mask the implementation details.
+
+### `#fail_with_error_message`
+
+This method can be used for returning a simple message wrapped in an instance of `Errors`. Optionally you can specify the type of error should you wish for your controller to react different for say a record not being found vs an API connection error.
+
+```ruby
+module MyBusinessDomain
+  module UseCases
+    class UserUpdatesChristmasWishlist < CleanArchitecture::UseCases::AbstractUseCase
+      contract do
+        option :required_persistence_object
+
+        params do
+          required(:user_id).filled(:int)
+          required(:most_wanted_gift).filled(:str)
+        end
+      end
+
+      include Dry::Monads::Do.for(:result)
+
+      CHRISTMAS_DAY = Date.new('2019', '12', '25')
+
+      def result
+        valid_params = yield result_of_validating_params
+
+        if Date.today == CHRISTMAS_DAY
+          return fail_with_error_message('Uh oh, Santa has already left the North Pole!')
+        end
+
+        context(:required_persistence_object).change_most_wanted_gift(user_id, most_wanted_gift)
+      end
+    end
+  end
+end
+```