interactor-contracts 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 155341334dd614cae42bd73f08e6791280ba8481ce82fb99c1803ec6efff45b4
-  data.tar.gz: e57c5cd09039e621a0df9bec33b6fcfc98b543b5d99eaf0caebc2aeb1069abdf
+  metadata.gz: 6209758247e17ba8e6ef497cf6266e864cdd0a3cc33d9755f1cce473c6ed2c29
+  data.tar.gz: dac680662651cdfdb9aa193158165978a03766ca88f05ac95e5768c85c7d18d4
 SHA512:
-  metadata.gz: 67e22c927d40745bb42ffa6746e3f4685282c632e05f6fb18f266a686f5c10f2c339ddba5e98604d4718ce5bc47254654054775acc0d5af78ed55ef86e2e566b
-  data.tar.gz: 199b4e95400eadea32fcba1cec5517d859a06fc57ebd394ebbd5a2497d2f90d56cde7fa6878ce261d7d792bea9b7262c89ede01e21fdba501a02109ae6b2f0e1
+  metadata.gz: 45047bfb79bb8233b12d8f91dfe730633a7cdea37e1c3e643bdd6300a5befefc2bea2f2808f4ff7321d5e37e0b16989a8e0bd5aa92a5e12be3fdc95f3b239ac8
+  data.tar.gz: 77e09b1dbcb20c9294c6af0c2dfac4fd84e982063c875907f46038b17e55aa0ea25f5ba134f49fc1c043fdcdc835333c87c9d8c89f5dc1e58e407a49fd4d66d7

data/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file. This projec
 
 [semver]: http://semver.org/spec/v2.0.0.html
 
+## [0.3.0] - 2019-10-09
+
+### Added
+
+* [#27](https://github.com/michaelherold/interactor-contracts/pull/27): Upgrade dry-validation to 1.0 - [@vaihtovirta](https://github.com/vaihtovirta).
+* [#30](https://github.com/michaelherold/interactor-contracts/pull/30): Allow setting a custom I18n backend for contract messages - [@michaelherold](https://github.com/michaelherold).
+
+### Changed
+
+* [#29](https://github.com/michaelherold/interactor-contracts/pull/29): Renamed the `assures` method to `promises` and all of the internals to reflect the new naming. This is a backward-compatible change due to an alias of `assures` to `promises` - [@michaelherold](https://github.com/michaelherold), suggested by [@KelseyDH](https://github.com/KelseyDH).
+
+### Fixed
+
+* [#26](https://github.com/michaelherold/interactor-contracts/pull/26): Fix bug with inheritance - [@raykov](https://github.com/raykov).
+
+### Miscellaneous
+
+* [#24](https://github.com/michaelherold/interactor-contracts/pull/24): Fixed a typo in the gem specification - [@bittersweet](https://github.com/bittersweet).
+* [#28](https://github.com/michaelherold/interactor-contracts/pull/28): Fixed
+the Travis configuration to stop failing on JRuby builds - [@michaelherold](https://github.com/michaelherold).
+
 ## [0.2.0] - 2019-05-27
 
 ### Added
@@ -35,5 +56,7 @@ All notable changes to this project will be documented in this file. This projec
 * [#4](https://github.com/michaelherold/interactor-contracts/pull/4): Added Danger as a collaboration tool - [@michaelherold](https://github.com/michaelherold).
 * [#6](https://github.com/michaelherold/interactor-contracts/pull/6): Updated the README - [@michaelherold](https://github.com/michaelherold).
 
+[unreleased]: https://github.com/michaelherold/interactor-contracts/compare/v0.2.0...master
+[0.3.0]: https://github.com/michaelherold/interactor-contracts/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/michaelherold/interactor-contracts/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/michaelherold/interactor-contracts/tree/v0.1.0

data/README.md

@@ -9,7 +9,7 @@
 [travis]: https://travis-ci.org/michaelherold/interactor-contracts
 
 Interactor::Contracts is an extension to the [interactor] gem that gives you
-the ability to specify the expectations (expected inputs) and assurances
+the ability to specify the expectations (expected inputs) and promises
 (expected outputs) of your interactors.
 
 [interactor]: https://github.com/collectiveidea/interactor
@@ -33,7 +33,7 @@ Or install it yourself as:
 ## Usage
 
 Let's extend the sample `AuthenticateUser` from the Interactor examples with a
-contract that specifies its expectations and assurances.
+contract that specifies its expectations and promises.
 
 ```ruby
 class AuthenticateUser
@@ -45,7 +45,7 @@ class AuthenticateUser
     required(:password).filled
   end
 
-  assures do
+  promises do
     required(:user).filled
     required(:token).filled
   end
@@ -65,23 +65,38 @@ class AuthenticateUser
 end
 ```
 
+### Inputs: expectations
+
 The `expects` block defines the expectations: the expected attributes of the
 context prior to the interactor running, along with any predicates that further
 constrain the input.
 
-The `assures` block defines the assurances: the expected attributes of the
+### Outputs: promises
+
+The `promises` block defines the promises: the expected attributes of the
 context after the interactor runs and successfully completes, along with any
-predicates the further constrain the output.
+predicates the further constrain the output. Note, for backward-compatibility,
+this is also available via the `assures` method.
 
 Because interactors can have transitive dependencies through the use of
 organizers, any other inputs or outputs are ignored from the perspective of
 the contract and are passed along to the outgoing (successful) context.
 
-Both `expects` and `assures` wrap [dry-validation], so you can use any
+Both `expects` and `promises` wrap [dry-validation], so you can use any
 predicates defined in it to describe the expected inputs and outputs of your
 interactor.
 
-To hook into a failed expectation or assurance, you can use the `on_breach`
+### Contract failures: breaches
+
+By default, contract failures, or breaches, behave like the example above:
+breached keys are set on the failed context with their contract failures as
+values. Note that you do not have to define an `on_breach` for the behavior, but
+if you do this behavior will not occur.
+
+If there are more complicated things you wish to do with contract failures, you
+can define one or more breach handlers.
+
+To hook into a failed expectation or promise, you can use the `on_breach`
 method to defined a breach handler. It should take a 1-arity block that expects
 an array of `Breach` objects. These objects have a `property` attribute that
 will give you the key that's in breach of its contract. Breaches also have a
@@ -100,8 +115,47 @@ result = AuthenticateUser.call({})
 result.failure?  #=> true
 ```
 
+If you would rather have your contract breaches be aggregated into, for example,
+an `errors` property, you could use a breach handler like the following:
+
+```ruby
+on_breach do |breaches|
+  context.fail!(errors: breaches)
+end
+```
+
 [dry-validation]: https://github.com/dryrb/dry-validation
 
+### I18n support
+
+You can [configure the underlying `dry-validation` contract][config] by passing
+a block to the `config` method in your contract. This block will be evaluated on
+the underlying configuration for the contract. For example, if you want to set
+up the contract to use I18n in your Rails app, you might do something like this:
+
+```ruby
+class MyInteractor
+  include Interactor
+  include Interactor::Contracts
+
+  config do
+    messages.backend = :i18n
+    messages.load_paths << Rails.root / 'config' / 'locales' / 'errors.yml'
+    messages.top_namespace = :interactor_contracts
+  end
+end
+```
+
+This sets up the I18n system (assuming the delicate load-order has been done in
+the right way - you have to require `i18n` prior to requiring
+`interactor-contracts` since we load `dry-validation` immediately) to use your
+custom file. All lookups for error messages happen starting at the
+`interactor_contracts` key in this example.
+
+See [the documentation for `dry-validation`][config] for more information.
+
+[config]: https://dry-rb.org/gems/dry-validation/1.0/configuration/
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
@@ -140,7 +194,7 @@ versions:
 * Ruby 2.4
 * Ruby 2.5
 * Ruby 2.6
-* JRuby 9.1
+* JRuby 9.2
 
 If something doesn't work on one of these versions, it's a bug.
 

data/interactor-contracts.gemspec

@@ -1,15 +1,30 @@
 # frozen_string_literal: true
 
-require File.expand_path('../lib/interactor/contracts/version', __FILE__)
+require File.expand_path('lib/interactor/contracts/version', __dir__)
 
 Gem::Specification.new do |spec|
   spec.name    = 'interactor-contracts'
   spec.version = Interactor::Contracts::VERSION
   spec.authors = ['Michael Herold']
-  spec.email   = ['michael.j.herold@gmail.com']
+  spec.email   = ['opensource@michaeljherold.com']
 
-  spec.summary     = 'Add contacts to your interactors'
-  spec.description = 'Add contacts to your interactors'
+  spec.summary     = 'Add contracts to your interactors'
+  spec.description = <<~DESC
+    Interactors are a pattern for structuring your business logic into units.
+    They have a flexible context that they pass between them, which makes them
+    easy-to-write, but hard-to-understand after you've written them. Much of
+    this confusion comes from not knowing what the interactor is supposed to
+    take as input and what it's expected to produce.
+
+    Enter contracts. Contracts allow you define, up front, a contract both for
+    the input of an interactor, known as expectations, and the output of it,
+    known as promises. Additionally, you can define a handler for what happens
+    when an interactor violates its contracts, known as a breach.
+
+    Declaring these contracts can help define your interface and make it easier
+    to understand how to use an interactor. They form both documentation and
+    validation for your business logic.
+  DESC
   spec.homepage    = 'https://github.com/michaelherold/interactor-contracts'
   spec.license     = 'MIT'
 
@@ -18,7 +33,14 @@ Gem::Specification.new do |spec|
   spec.files += Dir['lib/**/*.rb']
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'dry-validation', '~> 0.10'
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/michaelherold/interactor-contracts/issues',
+    'changelog_uri' => 'https://github.com/michaelherold/interactor-contracts/blob/master/CHANGELOG.md',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/interactor-contracts',
+    'source_code_uri' => 'https://github.com/michaelherold/interactor-contracts'
+  }
+
+  spec.add_dependency 'dry-validation', '~> 1.0'
   spec.add_dependency 'interactor', '~> 3'
 
   spec.add_development_dependency 'bundler', '> 1.11'

data/lib/interactor/contracts/breach_set.rb

@@ -18,7 +18,7 @@ module Interactor
       #       required(:password).filled
       #     end
       #
-      #     assures do
+      #     promises do
       #       required(:user).filled
       #       required(:token).filled
       #     end

data/lib/interactor/contracts/contract.rb

@@ -4,35 +4,35 @@ require 'interactor/contracts/terms'
 
 module Interactor
   module Contracts
-    # Contains the assurances, expectations, and consequences of an
+    # Contains the promises, expectations, and consequences of an
     # interactor's contract.
     class Contract
-      # Instantiates a new Contract with the given contraints
+      # Instantiates a new Contract with the given constraints
       #
       # @example
       #   Interactor::Contracts::Contract.new
       #
       # @api semipublic
-      # @param [Terms] assurances the Contract's assurances
+      # @param [Terms] promises the Contract's promises
       # @param [Terms] expectations the Contract's expectations
       # @param [Array<#call>] consequences the Contract's consequences
       # rubocop:disable Metrics/LineLength
-      def initialize(assurances: Terms.new, expectations: Terms.new, consequences: [])
-        @assurances = assurances
+      def initialize(promises: Terms.new, expectations: Terms.new, consequences: [])
+        @promises = promises
         @consequences = consequences
         @expectations = expectations
       end
       # rubocop:enable Metrics/LineLength
 
-      # The assurances the Contract will fulfill
+      # The promises the Contract will fulfill
       #
       # @example
       #   contract = Interactor::Contracts::Contract.new
-      #   contract.assurances  #=> <#Interactor::Contracts::Terms>
+      #   contract.promises  #=> <#Interactor::Contracts::Terms>
       #
       # @api semipublic
-      # @return [Terms] the terms for the assurances
-      attr_reader :assurances
+      # @return [Terms] the terms for the promises
+      attr_reader :promises
 
       # The expectations for arguments passed into the Interactor
       #
@@ -44,19 +44,19 @@ module Interactor
       # @return [Terms] the terms for the expectations
       attr_reader :expectations
 
-      # Adds an assurance to the Contract's set of assurances
+      # Adds an promise to the Contract's set of promises
       #
       # @example
       #   contract = Interactor::Contracts::Contract.new
-      #   contract.add_assurance do
+      #   contract.add_promise do
       #     required(:name).filled
       #   end
       #
       # @api semipublic
-      # @param [Block] term the assurance as a block of arity 0
+      # @param [Block] term the promise as a block of arity 0
       # @return [void]
-      def add_assurance(&term)
-        assurances.add(&term)
+      def add_promise(&term)
+        promises.add(&term)
       end
 
       # Adds a consequence to the Contract's set of consequences
@@ -89,6 +89,16 @@ module Interactor
         expectations.add(&term)
       end
 
+      # Configures the underlying contracts for the validation schemata
+      #
+      # @api private
+      # @private
+      # @return [void]
+      def config(&block)
+        promises.config(&block)
+        expectations.config(&block)
+      end
+
       # The consequences for the Contract
       #
       # @example

data/lib/interactor/contracts/dsl.rb

@@ -6,14 +6,14 @@ module Interactor
   module Contracts
     # Defines the class-level DSL that enables Interactor contracts.
     module DSL
-      # Defines the assurances of an Interactor and creates an after hook
+      # Defines the promises of an Interactor and creates an after hook
       #
       # @example
       #   class CreatePerson
       #     include Interactor
       #     include Interactor::Contracts
       #
-      #     assures do
+      #     promises do
       #       required(:person).filled
       #     end
       #
@@ -23,11 +23,33 @@ module Interactor
       #   end
       #
       # @api public
-      # @param [Block] block the block defining the assurances
+      # @param [Block] block the block defining the promises
       # @return [void]
-      def assures(&block)
-        contract.add_assurance(&block)
-        define_assurances_hook
+      def promises(&block)
+        contract.add_promise(&block)
+        define_promises_hook
+      end
+      alias assures promises
+
+      # Sends configuration set up to the underlying contracts in the terms
+      #
+      # @example
+      #   class CreatePerson
+      #     include Interactor
+      #     include Interactor::Contracts
+      #
+      #     config do
+      #       messages.backend = :i18n
+      #       messages.top_namespace = :my_app
+      #       messages.load_paths << File.join(__dir__, '..', 'errors.yml')
+      #     end
+      #   end
+      #
+      # @api public
+      # @param [Block] block the block to execute for the underlying contracts
+      # @return [void]
+      def config(&block)
+        contract.config(&block)
       end
 
       # The Contract to enforce on calls to the Interactor
@@ -37,7 +59,7 @@ module Interactor
       #     include Interactor
       #     include Interactor::Contracts
       #
-      #     assures do
+      #     promises do
       #       required(:person).filled
       #     end
       #
@@ -77,15 +99,18 @@ module Interactor
         define_expectations_hook
       end
 
-      # Sets contract to given one and calls hooks
-      # define_assurances_hook and define_expectations_hook
+      # Allows for the inheritance of contracts in subclasses
       #
-      # @api semipublic
+      # @api private
       # @param [Contract] contract
       # @return [void]
       def inherit_contract(contract)
-        @contract = contract
-        define_assurances_hook
+        @contract = Contract.new(
+          promises: contract.promises.clone,
+          expectations: contract.expectations.clone,
+          consequences: contract.consequences.clone
+        )
+        define_promises_hook
         define_expectations_hook
       end
 
@@ -120,12 +145,12 @@ module Interactor
 
       private
 
-      # Flags whether the assurances hook has been defined
+      # Flags whether the promises hook has been defined
       #
       # @api private
       # @return [TrueClass, FalseClass] true if the hook is defined
-      attr_reader :defined_assurances_hook
-      alias defined_assurances_hook? defined_assurances_hook
+      attr_reader :defined_promises_hook
+      alias defined_promises_hook? defined_promises_hook
 
       # Flags whether the expectations hook has been defined
       #
@@ -139,12 +164,12 @@ module Interactor
       # @api private
       # @raise [Interactor::Failure] if the input fails to meet its contract.
       # @return [void]
-      def define_assurances_hook
-        return if defined_assurances_hook?
+      def define_promises_hook
+        return if defined_promises_hook?
 
-        after { enforce_contracts(contract.assurances) }
+        after { enforce_contracts(contract.promises) }
 
-        @defined_assurances_hook = true
+        @defined_promises_hook = true
       end
 
       # Defines a before hook that validates the Interactor's input

data/lib/interactor/contracts/outcome.rb

@@ -10,7 +10,7 @@ module Interactor
     class Outcome
       extend Forwardable
 
-      # Instantiantes a new Outcome based on the results of a Terms enforcement
+      # Instantiates a new Outcome based on the results of a Terms enforcement
       #
       # @api private
       # @param [Dry::Validation::Result] result
@@ -48,7 +48,7 @@ module Interactor
       # @api semipublic
       # @return [Array<Breach>] the breaches of the Terms' constraints
       def breaches
-        BreachSet.new(result.messages(full: true).map do |property, messages|
+        BreachSet.new(result.errors(full: true).to_h.map do |property, messages|
           Breach.new(property, messages)
         end)
       end

data/lib/interactor/contracts/terms.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
-require 'dry-validation'
 require 'interactor/contracts/outcome'
 
 module Interactor
   module Contracts
-    # The terms of a contract, either for assurances or expectations
+    # The terms of a contract, either for promises or expectations
     class Terms
       # Instantiates a new set of terms
       #
@@ -13,8 +12,8 @@ module Interactor
       #   terms = Interactor::Contracts::Terms.new
       #
       # @api public
-      # @param [Dry::Validation::Schema] terms the terms to start with
-      def initialize(terms = Class.new(Dry::Validation::Schema))
+      # @param [Dry::Validation::Contract] terms the terms to start with
+      def initialize(terms = Class.new(Dry::Validation::Contract))
         @terms = terms
       end
 
@@ -30,7 +29,13 @@ module Interactor
       # @param [Block] term the term to add to the terms
       # @return [void]
       def add(&term)
-        @terms = Dry::Validation.Schema(@terms, { build: false }, &term)
+        @terms = Class.new(Dry::Validation::Contract).tap do |new_terms|
+          new_terms.instance_variable_set(
+            :@config,
+            @terms.instance_variable_get(:@config).dup
+          )
+          new_terms.params(@terms.schema, &term)
+        end
       end
 
       # Validates the terms against a given context
@@ -46,8 +51,32 @@ module Interactor
       # @param [#to_h] context the context to validate the terms against
       # @return [Outcome]
       def call(context)
+        define_empty_schema
+
         Outcome.new(@terms.new.call(context.to_h))
       end
+
+      # Configures the underlying contracts within the terms
+      #
+      # @api private
+      # @private
+      # @return [void]
+      def config(&block)
+        @terms.config.instance_exec(&block)
+      end
+
+      private
+
+      # Defines a no-op schema as a base to extend upon
+      #
+      # This prevents the raising of a `Dry::Validation::SchemaMissingError`
+      # exception.
+      #
+      # @api private
+      # @return [void]
+      def define_empty_schema
+        @terms.params.nil? && @terms.params {}
+      end
     end
   end
 end

data/lib/interactor/contracts/version.rb

@@ -2,6 +2,6 @@
 
 module Interactor
   module Contracts
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactor-contracts
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Herold
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-28 00:00:00.000000000 Z
+date: 2019-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: interactor
   requirement: !ruby/object:Gem::Requirement
@@ -52,9 +52,23 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: '1.11'
-description: Add contacts to your interactors
+description: |
+  Interactors are a pattern for structuring your business logic into units.
+  They have a flexible context that they pass between them, which makes them
+  easy-to-write, but hard-to-understand after you've written them. Much of
+  this confusion comes from not knowing what the interactor is supposed to
+  take as input and what it's expected to produce.
+
+  Enter contracts. Contracts allow you define, up front, a contract both for
+  the input of an interactor, known as expectations, and the output of it,
+  known as promises. Additionally, you can define a handler for what happens
+  when an interactor violates its contracts, known as a breach.
+
+  Declaring these contracts can help define your interface and make it easier
+  to understand how to use an interactor. They form both documentation and
+  validation for your business logic.
 email:
-- michael.j.herold@gmail.com
+- opensource@michaeljherold.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -77,7 +91,11 @@ files:
 homepage: https://github.com/michaelherold/interactor-contracts
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/michaelherold/interactor-contracts/issues
+  changelog_uri: https://github.com/michaelherold/interactor-contracts/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/interactor-contracts
+  source_code_uri: https://github.com/michaelherold/interactor-contracts
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -93,8 +111,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
-summary: Add contacts to your interactors
+summary: Add contracts to your interactors
 test_files: []