pathway 0.9.0 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d286f1d75ae6776baa9113bd4dae0da6f30685723173cee2a971a02d134223f6
-  data.tar.gz: ab88b4c578bde709d3dbeff0dd6e97f5f2da884cb9151a73303e08b9888f60a6
+  metadata.gz: f5a986bfc55b57eb310d22891427f8d26473f34f9704d639f164cdba1e2318e7
+  data.tar.gz: 88fada6e7d1fd07ab3be7c2383c48984b38efa478721fd23d966a36b4fc3677c
 SHA512:
-  metadata.gz: 41c27065b1bba5907eab6b00fc76799fa17f89a0d9e292e58b9eff2a1a06f8813a737c08ca5b13e5c8aad62a60442f8135c56df1b301b205ad6aeabe8f92189d
-  data.tar.gz: df7cc1e6293f27135cbfa25f0aed776afd637f62128182c1caaf961b08189ffc322f1e12beb8e572e68ab1624808a6549803559582d87d4a6870d52388054df4
+  metadata.gz: c7c7294f4b8731a06a3dfd5649391f53526181d3e5d18333534e450d531a56206e9ff19cf7a91ef76238955c9c994c19acf10128d1ac12ec37ea17f7bfc5ca2d
+  data.tar.gz: 374f040438a17db333211d852a5e0e742d9eedd067deebfdbed5bc7f4a6a1c6898451ca31c7ab7d61d666723fcfdfd5e735440d846113d0e9a4fe6864983c526

data/.circleci/config.yml

@@ -0,0 +1,38 @@
+version: 2.0
+shared: &shared
+    steps:
+      - checkout
+      - run:
+          name: Bundle gems
+          command: |
+            echo '--no-rdoc --no-ri' > '.gemrc'
+            bundle install --jobs=4 --retry=3 --path vendor/bundle
+      - run:
+          name: Run tests
+          command: bundle exec rspec --format documentation --color --format progress spec
+
+jobs:
+  "ruby-2.4":
+    <<: *shared
+    docker:
+      - image: circleci/ruby:2.4
+
+  "ruby-2.5":
+    <<: *shared
+    docker:
+      - image: circleci/ruby:2.5
+
+  "ruby-2.6":
+    <<: *shared
+    docker:
+      - image: circleci/ruby:2.6
+        environment:
+          REPORT_COVERAGE: 'true'
+
+workflows:
+  version: 2
+  build:
+    jobs:
+      - "ruby-2.4"
+      - "ruby-2.5"
+      - "ruby-2.6"

data/CHANGELOG.md

@@ -1,4 +1,26 @@
-## [0.9.0] - 2019-04-01
+## [0.11.2] - 2020-07-22
+### Changed
+- Improve `from:` option for `:fetch_model` step, at `:sequel_models` plugin, to also accept a Sequel Dataset
+
+## [0.11.1] - 2020-01-09
+### Changed
+- Improve custom `rspec` matchers for testing field presence on schemas
+
+## [0.11.0] - 2020-01-02
+### Changed
+- Add support for `dry-validation` 1.0 and above
+
+## [0.10.0] - 2019-10-06
+### Changed
+- Restrict support for `dry-validation` from 0.11.0 up to (excluding) 1.0.0
+- Changed behavior for `:transaction` step wrapper, on `:sequel_models` plugin, to allow to take a single step name instead of block.
+- Changed behavior for `:after_commit` step wrapper, on `:sequel_models` plugin, to allow to take a single step name instead of block.
+
+## [0.9.1] - 2019-02-18
+### Changed
+- Various improvements on documentation and gemspec.
+
+## [0.9.0] - 2019-02-04
 ### Changed
 - Changed behavior for `:after_commit` step wrapper, on `:sequel_models` plugin, to capture current state and reuse it later when executing.
 

data/Gemfile

@@ -1,5 +1,3 @@
-ruby '2.5.1'
-
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in pathway.gemspec

data/README.md

@@ -91,36 +91,37 @@ end
 #### Error objects
 
 `Pathway::Error` is a helper class to represent the error description from an failed operation execution (and can be used also for pattern matching as we'll see later).
-It's use is completely optional, but provides you with a basic schema to communicate what when wrong. You can instantiate it by calling `new` on the class itself or using the helper method `error` provided in the operation class:
+Its use is completely optional, but provides you with a basic schema to communicate what when wrong. You can instantiate it by calling `new` on the class itself or using the helper method `error` provided by the operation class:
 
 ```ruby
 class CreateNugget < Pathway::Operation
   def call(input)
-    validation = Form.call(input)
+    validation = Validator.call(input)
 
     if validation.ok?
       success(Nugget.create(validation.values))
     else
-      error(type: :validation, message: 'Invalid input', details: validation.errors)
+      error(:validation, message: 'Invalid input', details: validation.errors)
     end
   end
 end
 ```
 
-As you can see `error(...)` expects `type:`, `message:` and `details` keyword arguments; `type:` is the only mandatory, the other ones can be omitted and have default values. Also `type` should be a `Symbol`, `message:` a `String` and `details:` can be a `Hash` or any other structure you see fit.
+As you can see `error(...)` expects the `type` as the first parameter (and only the mandatory) then `message:` and `details` keyword arguments; these 2 last ones can be omitted and have default values. The type parameter must be a `Symbol`, `message:` a `String` and `details:` can be a `Hash` or any other structure you see fit.
 
-You then have accessors available on the error object to get the values back:
+Finally, the `Error` object have three accessors available to get the values back:
 
 ```ruby
 result = CreateNugget.new.call(foo: 'foobar')
 if result.failure?
   puts "#{result.error.type} error: #{result.error.message}"
+  puts "Error details: #{result.error.details}"
 end
 
 ```
 
 Mind you, `error(...)` creates an `Error` object wrapped into a `Pathway::Failure` so you don't have to do it yourself.
-If you decide to use `Pathway::Error.new(...)` directly, the expected arguments will be the same, but you will have to wrap the object before returning it.
+If you decide to use `Pathway::Error.new(...)` directly, you will have to pass all the arguments as keywords (including `type:`), and you will have to wrap the object before returning it.
 
 #### Initialization context
 
@@ -135,7 +136,7 @@ class CreateNugget < Pathway::Operation
   context :current_user, notify: false
 
   def call(input)
-    validation = Form.call(input)
+    validation = Validator.call(input)
 
     if validation.valid?
       nugget = Nugget.create(owner: current_user, **validation.values)
@@ -143,7 +144,7 @@ class CreateNugget < Pathway::Operation
       Notifier.notify(:new_nugget, nugget) if @notify
       success(nugget)
     else
-      error(type: :validation, message: 'Invalid input', details: validation.errors)
+      error(:validation, message: 'Invalid input', details: validation.errors)
     end
   end
 end
@@ -266,7 +267,7 @@ class CreateNugget < Pathway::Operation
     if validation.ok?
       state[:params] = validation.values
     else
-      error(type: :validation, details: validation.errors)
+      error(:validation, details: validation.errors)
     end
   end
 
@@ -313,8 +314,8 @@ class SomeOperation < BaseOperation
 end
 ```
 
-The plugin name must be specified as a `Symbol` (or also as the `Module` where is implemented, but more on that later), and can it take parameters next to the plugin's name.
-When activated it will enrich your operations with new instance and class methods plus extra customs step for the process DSL.
+The plugin name must be specified as a `Symbol` (or also as the `Module` where is implemented, but more on that later), and it can take parameters next to the plugin's name.
+When activated it will enrich your operations with new instance and class methods plus extra customs step for the `process` DSL.
 
 Mind you, if you wish to activate a plugin for a number of operations you can activate it for all of them directly on the `Pathway::Operation` class, or you can create your own base operation and all its descendants will inherit the base class' plugins.
 
@@ -322,21 +323,23 @@ Mind you, if you wish to activate a plugin for a number of operations you can ac
 
 This plugin provides integration with the [dry-validation](http://dry-rb.org/gems/dry-validation/) gem. I won't explain in detail how to use this library since is already extensively documented on its official website, but instead I'll assume certain knowledge of it, nonetheless, as you'll see in a moment, its API pretty self-explanatory.
 
-`dry-validation` provides a very simple way to define form (or schema) objects to process and validate our input. The provided custom `:validate` step allows you to run your input though a form to check your data is valid before continuing. When the input is invalid it will return an error object with type `:validation` and the reasons the validation failed on the `details` attribute. Is commonly the first step any operation runs.
+`dry-validation` provides a very simple way to define contract objects (conceptually very similar to form objects) to process and validate input. The provided custom `:validate` step allows you to run your input though a contract to check if your data is valid before carrying on. When the input is invalid it will return an error object of type `:validation` and the reasons the validation failed will be available at the `details` attribute. Is usually the first step an operation runs.
 
-When using this plugin we'll have to provide an already defined form to the step to use or we can also define one inline.
+When using this plugin we can provide an already defined contract to the step to use or we can also define it within the operation.
 Let's see a few examples:
 
 ```ruby
-NuggetForm = Dry::Validation.Form do
-  required(:owner).filled(:str?)
-  required(:price).filled(:int?)
+class NuggetContract < Dry::Validation::Contract
+  params do
+    required(:owner).filled(:string)
+    required(:price).filled(:integer)
+  end
 end
 
 class CreateNugget < Pathway::Operation
   plugin :dry_validation
 
-  form NuggetForm
+  contract NuggetContract
 
   process do
     step :validate
@@ -347,15 +350,17 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-As it can be seen at the code above, the form is first created elsewhere, then is configured to be used by the operation (by calling `form NuggetForm`), and validate the input at the process block by calling `step :validate`.
+As is is shown above, the contract is defined first, then is configured it will be used by the operation by calling `contract NuggetContract`, and validate the input at the process block by placing the step `step :validate` inside the `process` block.
 
 ```ruby
 class CreateNugget < Pathway::Operation
   plugin :dry_validation
 
-  form do
-    required(:owner).filled(:str?)
-    required(:price).filled(:int?)
+  contract do
+    params do
+      required(:owner).filled(:string)
+      required(:price).filled(:integer)
+    end
   end
 
   process do
@@ -367,16 +372,36 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-Now, this second example is equivalent to the first one, but here we call `form` with a block instead and no parameter; this block will be use as definition body for a form object that will be stored internally. Thus keeping the form and operation at the same place, this is convenient when you have a rather simpler form and don't need to reuse it.
+Now, this second example is equivalent to the first one, but here we call `contract` with a block instead and no parameter; this block will be used as definition body for a contract class that will be stored internally. Thus keeping the contract and operation code at the same place, this is convenient when you have a rather simpler contract and don't need to reuse it.
+
+One interesting nuance to keep in mind regarding the inline block contract is that, when doing operation inheritance, if the parent operation already has a contract, the child operation will define a new one inheriting from the parent's. This is very useful to share validation logic among related operations in the same class hierarchy.
+
+As a side note, if your contract is simple enough and only have params, you can call the `params` method directly instead, the following code is essentially equivalent to previous example:
+
+```ruby
+class CreateNugget < Pathway::Operation
+  plugin :dry_validation
+
+  params do
+    required(:owner).filled(:string)
+    required(:price).filled(:integer)
+  end
+
+  process do
+    step :validate
+    step :create_nugget
+  end
 
-One interesting nuance to keep in mind regarding the inline block form is that, when doing operation inheritance, if the parent operation already has a form, the child operation will define a new one extending from the parent's. This is very useful to share form functionality among related operations in the same class hierarchy.
+  # ...
+end
+```
 
-##### Form options
+##### Contract options
 
-If you are familiar with `dry-validation` you probably know it provides a way to [inject options](http://dry-rb.org/gems/dry-validation/basics/working-with-schemas/#injecting-external-dependencies) before calling the form instance.
+If you are familiar with `dry-validation` you probably know it provides a way to [inject options](https://dry-rb.org/gems/dry-validation/1.4/external-dependencies/) before calling the contract.
 
-On those scenarios you must either use the `auto_wire_options: true` plugin argument, or specify how to map options from the execution state to the form when calling `step :validate`.
-Lets see and example for each case:
+On those scenarios you must either use the `auto_wire_options: true` plugin argument, or specify how to map options from the execution state to the contract when calling `step :validate`.
+Lets see and example for the first case:
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -384,11 +409,17 @@ class CreateNugget < Pathway::Operation
 
   context :user_name
 
-  form do
-    configure { option :user_name }
+  contract do
+    option :user_name
 
-    required(:owner).filled(:str?, :eql?: user_name)
-    required(:price).filled(:int?)
+    params do
+      required(:owner).filled(:string)
+      required(:price).filled(:integer)
+    end
+
+    rule(:owner) do
+      key.failure("invalid owner") unless user_name == values[:owner]
+    end
   end
 
   process do
@@ -400,9 +431,11 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-Here the defined form needs a `:user_name` option, so we tell the operation to grab the attribute with the same name from the state by activating `:auto_wire_options`, afterwards, when the validation runs, the form will already have the user name available.
+Here the defined contract needs a `:user_name` option, so we tell the operation to grab the attribute with the same name from the state by activating `:auto_wire_options`, afterwards, when the validation runs, the contract will already have the user name available.
 
-Mind you, this option is `false` by default, so be sure to set it to `true` at `Pathway::Operation` if you'd rather have it for all your operations.
+Mind you, this option is `false` by default, so be sure to set it to `true` at `Pathway::Operation` if you'd rather have it enabled for all your operations.
+
+On the other hand, if for some reason the name of the contract's option and state attribute don't match, we can just pass `with: {...}` when calling to `step :validate`, indicating how to wire the attributes, the following example illustrates just that:
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -410,15 +443,21 @@ class CreateNugget < Pathway::Operation
 
   context :current_user_name
 
-  form do
-    configure { option :user_name }
+  contract do
+    option :user_name
+
+    params do
+      required(:owner).filled(:string)
+      required(:price).filled(:integer)
+    end
 
-    required(:owner).filled(:str?, :eql?: user_name)
-    required(:price).filled(:int?)
+    rule(:owner) do
+      key.failure("invalid owner") unless user_name == values[:owner]
+    end
   end
 
   process do
-    step :validate, with: { user_name: :current_user_name } # Inject :user_name to the form object with the state's :current_user_name
+    step :validate, with: { user_name: :current_user_name } # Inject :user_name to the contract object with the state's :current_user_name
     step :create_nugget
   end
 
@@ -426,10 +465,12 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-On the other hand, if for some reason the name of the form's option and state attribute don't match, we can just pass `with: {...}` when calling to `step :validate`, indicating how to wire the attributes, the example above illustrates just that.
-
 The `with:` parameter can always be specified, at `step :validate`, and allows you to override the default mapping regardless if auto-wiring is active or not.
 
+##### Older versions of `dry-validation`
+
+Pathway supports the `dry-validation` gem down to version `0.11` (inclusive) in case you still have unmigrated code. When using versions bellow `1.0` the concept of contract is not present and instead of calling the `contract` method to setup your validation logic you must use the `form` method. Everything else remains the same except, obviously, that you would have to use `dry-definition`'s [old API](https://dry-rb.org/gems/dry-validation/0.13/) which is a bit different from the current one.
+
 #### `SimpleAuth` plugin
 
 This very simple plugin adds a custom step called `:authorize`, that can be used to check for permissions and halt the operation with a `:forbidden` error when they aren't fulfilled.
@@ -599,7 +640,7 @@ module Pathway
       module InstanceMethods
         delegate :model, :pk, to: :class
 
-        # This plugin will conflict will :sequel_models so you mustn't load them in the same operation
+        # This method will conflict with :sequel_models so you mustn't load both plugins in the same operation
         def fetch_model(state, column: pk)
           current_pk = state[:input][column]
           result     = model.first(column => current_pk)
@@ -613,7 +654,7 @@ module Pathway
       end
 
       module DSLMethods
-        # This method also conflicts with :sequel_models, so don't use them as once.
+        # This method also conflicts with :sequel_models, so don't use them at once
         def transaction(&steps)
           transactional_seq = -> seq, _state do
             ActiveRecord::Base.transaction do
@@ -635,10 +676,10 @@ end
 ```
 
 The code above implements a plugin to provide basic interaction with the [ActiveRecord](http://guides.rubyonrails.org/active_record_basics.html) gem.
-Even though is a very simply plugin, it shows all the essentials to develop more complex plugin.
+Even though is a very simple plugin, it shows all the essentials to develop more complex ones.
 
-First as is pointed out in the code, some of the methods implemented here (`fetch_model` and `transmission`) collide with methods defined for the `:sequel_models`, so as a consequence these two plugin's are not compatible with each other an cannot be activated at the same time on the same operation (although you can still do it for different operation within the same application).
-You must be mindful about colliding method names when mixing plugins, since `Pathway` can't book keep compatibility among every plugin that exists of will ever exist.
+As is pointed out in the code, some of the methods implemented here (`fetch_model` and `transmission`) collide with methods defined for `:sequel_models`, so as a consequence, these two plugin's are not compatible with each other and cannot be activated for the same operation (although you can still do it for different operations within the same application).
+You must be mindful about colliding method names when mixing plugins, since `Pathway` can't bookkeep compatibility among every plugin that exists of will ever exist.
 Is a good practice to document known incompatibilities on the plugin definition itself when they are known.
 
 The whole plugin is completely defined within the `ActiveRecord` module inside the `Pathway::Plugins` namespace, also the file is placed at the load path in `pathway/plugin/active_record.rb` (assuming `lib/` is listed in `$LOAD_PATH`). This will ensure, when calling `plugin :active_record` inside an operation, the correct file will be loaded and the correct plugin module will be applied to the current operation.
@@ -673,7 +714,7 @@ require 'pathway/rspec'
 
 #### Rspec matchers
 
-Pathway provide a few matchers in order to tests your operation easier.
+Pathway provides a few matchers in order to tests your operation easier.
 Let's go through a full example and break it up in the following subsections:
 
 ```ruby
@@ -682,10 +723,10 @@ Let's go through a full example and break it up in the following subsections:
 class CreateNugget < Pathway::Operation
   plugin :dry_validation
 
-  form do
-    required(:owner).filled(:str?)
-    required(:price).filled(:int?)
-    optional(:disabled).maybe(:bool?)
+  params do
+    required(:owner).filled(:string)
+    required(:price).filled(:integer)
+    optional(:disabled).maybe(:bool)
   end
 
   process do
@@ -721,8 +762,8 @@ describe CreateNugget do
     end
   end
 
-  describe '.form' do
-    subject(:form) { CreateNugget.form }
+  describe '.contract' do
+    subject(:contract) { CreateNugget.build_contract }
 
     it { is_expected.to require_fields(:owner, :price) }
     it { is_expected.to accept_optional_field(:disabled) }
@@ -739,13 +780,13 @@ The assertion it performs is simply is that the operation was successful, also y
 
 This second matcher is analog to `succeed_on` but it asserts that operation execution was a failure instead. Also if you return an error object, and you need to, you can assert the error type using the `type` chain method (aliased as `and_type` and `with_type`); the error message (`and_message`, `with_message` or `message`); and the error details (`and_details`, `with_details` or `details`). Mind you, the chain methods for the message and details accept nested matchers while the `type` chain can only test by equality.
 
-##### form matchers
+##### contract/form matchers
 
-Finally we can see that we are also testing the operation's form, implemented here with the `dry-validation` gem.
+Finally we can see that we are also testing the operation's contract (or form), implemented here with the `dry-validation` gem.
 
-Two more matchers are provided when we use this gem: `require_fields` (aliased `require_field`) to test when form is expected to define a required set of fields, and `accept_optional_fields` (aliased `accept_optional_field`) to test when a form must define certain set of optional fields.
+Two more matchers are provided: `require_fields` (aliased `require_field`) to test when a contract is expected to define a required set of fields, and `accept_optional_fields` (aliased `accept_optional_field`) to test when a contract must define a certain set of optional fields, both the contract class (at operation class method `contract_class`) or an instance (operation class method `build_contract`) can be provided.
 
-These matchers are only useful when using `dry-validation` and will very likely be extracted to its own gem in the future.
+These matchers are only useful when using `dry-validation` (on every version newer or equal to `0.11.0`) and will probably be extracted to their own gem in the future.
 
 ## Development
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/lib/pathway.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 require 'dry/inflector'
 require 'contextualizer'
@@ -107,7 +109,7 @@ module Pathway
         alias :wrap :result
 
         def call(*)
-          fail "must implement at subclass"
+          fail 'must implement at subclass'
         end
 
         def error(type, message: nil, details: nil)

data/lib/pathway/plugins/dry_validation.rb

@@ -1,99 +1,25 @@
+# frozen_string_literal: true
+
 require 'dry/validation'
 
 module Pathway
   module Plugins
     module DryValidation
-      module ClassMethods
-        attr_reader :form_class, :form_options
-        attr_accessor :auto_wire_options
-
-        def form(base = nil, **opts, &block)
-          if block_given?
-            base ||= _base_form
-            self.form_class = _block_definition(base, opts, &block)
-          elsif base
-            self.form_class = _form_class(base)
-          else
-            raise ArgumentError, 'Either a form class or a block must be provided'
-          end
-        end
-
-        def form_class= klass
-          @builded_form = klass.options.empty? ? klass.new : nil
-          @form_class = klass
-          @form_options = klass.options.keys
-        end
-
-        def build_form(opts = {})
-          @builded_form || form_class.new(opts)
-        end
-
-        def inherited(subclass)
-          super
-          subclass.form_class = form_class
-          subclass.auto_wire_options = auto_wire_options
-        end
-
-        private
-
-        def _base_form
-          superclass.respond_to?(:form_class) ? superclass.form_class : DefaultFormClass
-        end
-
-        def _form_class(form)
-          form.is_a?(Class) ? form : form.class
-        end
-
-        def _form_opts(opts = {})
-          opts.merge(build: false)
-        end
-      end
-
-      module InstanceMethods
-        extend Forwardable
-
-        delegate %i[build_form form_options auto_wire_options] => 'self.class'
-        alias :form :build_form
-
-        def validate(state, with: nil)
-          if auto_wire_options && form_options.any?
-            with ||= form_options.zip(form_options).to_h
-          end
-          opts = Hash(with).map { |opt, key| [opt, state[key]] }.to_h
-          validate_with(state[:input], opts)
-            .then { |params| state.update(params: params) }
-        end
-
-        def validate_with(params, opts = {})
-          val = form(opts).call(params)
-
-          val.success? ? wrap(val.output) : error(:validation, details: val.messages)
-        end
-      end
-
-      def self.apply(operation, auto_wire_options: false)
-        operation.form_class = DefaultFormClass
-        operation.auto_wire_options = auto_wire_options
-      end
-
-      if Gem.loaded_specs['dry-validation'].version >= Gem::Version.new('0.12')
-        DefaultFormClass = Dry::Validation::Schema::Params
-
-        module ClassMethods
-          private
-          def _block_definition(base, opts, &block)
-            Dry::Validation.Params(_form_class(base), _form_opts(opts), &block)
-          end
-        end
-      else
-        DefaultFormClass = Dry::Validation::Schema::Form
-
-        module ClassMethods
-          private
-          def _block_definition(base, opts, &block)
-            Dry::Validation.Form(_form_class(base), _form_opts(opts), &block)
-          end
-        end
+      def self.apply(operation, **kwargs)
+        #:nocov:
+        if Gem.loaded_specs['dry-validation'].version < Gem::Version.new('0.11')
+          fail 'unsupported dry-validation gem version'
+        elsif Gem.loaded_specs['dry-validation'].version < Gem::Version.new('0.12')
+          require 'pathway/plugins/dry_validation/v0_11'
+          operation.plugin(Plugins::DryValidation::V0_11, **kwargs)
+        elsif Gem.loaded_specs['dry-validation'].version < Gem::Version.new('1.0')
+          require 'pathway/plugins/dry_validation/v0_12'
+          operation.plugin(Plugins::DryValidation::V0_12, **kwargs)
+        else
+          require 'pathway/plugins/dry_validation/v1_0'
+          operation.plugin(Plugins::DryValidation::V1_0, **kwargs)
+        end
+        #:nocov:
       end
     end
   end