pathway 0.9.1 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f95391a7c8c39954f8ffb8bbaa8c06294bd28c3553e595d4f91e3b44a109b3ee
-  data.tar.gz: 22118f62ae34e871d6258a59111614e83643d6557bde5cb1fb5381edff2fcab5
+  metadata.gz: f136383bd165f1ff88c16e5cb70fb16342b84e5b4e8b76bd49bf0fd91707e2ab
+  data.tar.gz: b4b5cc55ea74d704c66976004e968f72d721c928af86bc8e5660ede8c8d61073
 SHA512:
-  metadata.gz: 942055689e4836b0556f9b1d1b2aa010b5391c322a3948598047be7ee1b06c83e19bb026efd90f6388aed035a2c37784a26350fa991fe28cf53a7d7f91c4cf9f
-  data.tar.gz: 971070c4f8eec9bede60e354926a7114107b68cd2ead43083c319f7de709b62dd5013294344e105e64965598865cc8d91185462e5a15c880eefee051ca9ffdd3
+  metadata.gz: b83238e83c8f2835f5fa817b6c7e9bc91d68dd9362b97a371d2d22e5ff9a7f8695c26ac4a03fda5b23afebc4d6474744db85ad713c0f49eb2fec95b5696f206e
+  data.tar.gz: b8fd39d4709179ecacd79c89741e6402610afad146117acc82eea7ba2f0376fefcfd5d990a848bd55c0acfdccd64b5313e2497893078818091d8c28b136dd8e2

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,3 +1,25 @@
+## [0.11.3] - 2020-07-22
+### Changed
+- Use default error message on `:fetch_model` step, at `:sequel_models` plugin, if model type cannot be determined
+
+## [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.

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,25 +431,33 @@ 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 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
   plugin :dry_validation
 
   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.
@@ -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