pathway 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '074681d0fda0240e14f6a8157716f872c6af54a8'
-  data.tar.gz: 3405a3f3c338bda484efa7b9221601d24c2dd35e
+  metadata.gz: 04ddcc9225aeeabdd7e65aecad90097af5fd702f
+  data.tar.gz: 6814518d323632b5d65c0991ae84e286fd02678d
 SHA512:
-  metadata.gz: d0f049e84677b12d58d4e53d7781ae80bba9e6859c9d25f46f10e4e7c25c3eea0f13cd1c6ca436a20e3ad910f3b9d31b3c21c8a6e47e07a8382fab0268524cd1
-  data.tar.gz: 9df6468ce430ea9c640ad088f8b0e1e37ff69379b30d9002bca705bd5c3b989648a221b2d8d95939e50b94168d8217adbfb8b15b845546829ea0abeb68af68e6
+  metadata.gz: 9ee6f6f6254eb3c615e473c3ff6ba000df3d5538a8d31849d5d9161718fec3d79c9ba47ff9620658dbd3a7726d604fd858eb76f58f6f697640b35e9b1db246b2
+  data.tar.gz: 359b11969cd277940be18a94c7709acf514808b8816aa3172a2474932ad5f03c0ffcdb26e613e85be1acca685bc5a540e3e3db2a0e5948bb7ada94a519c09fcd

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.5.0] - 2017-11-6
+### Changed
+- Change base class for `Pathway::Error` from `StandardError` to `Object`
+
 ## [0.4.0] - 2017-10-31
 ### Changed
 - Renamed `:authorization` plugin to `:simple_auth`

data/README.md

@@ -4,35 +4,22 @@
 [![CircleCI](https://circleci.com/gh/pabloh/pathway/tree/master.svg?style=shield)](https://circleci.com/gh/pabloh/pathway/tree/master)
 [![Coverage Status](https://coveralls.io/repos/github/pabloh/pathway/badge.svg?branch=master)](https://coveralls.io/github/pabloh/pathway?branch=master)
 
-Pathway allows you to encapsulate your app's business logic into operation objects (also known as application services on the DDD lingo).
+Pathway encapsulates your business logic into simple operation objects (AKA application services on the [DDD](https://en.wikipedia.org/wiki/Domain-driven_design) lingo).
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'pathway'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
     $ gem install pathway
 
-## Introduction
+## Description
 
 Pathway helps you separate your business logic from the rest of your application; regardless if is an HTTP backend, a background processing daemon, etc.
-The main concept Pathway relies upon to build domain logic modules is the operation, this important concept will be explained in detail in the following sections.
-
+The main concept Pathway relies upon to build domain logic modules is the operation, this important concept will be explained in detail the following sections.
 
 Pathway also aims to be easy to use, stay lightweight and extensible (by the use of plugins), avoid unnecessary dependencies, keep the core classes clean from monkey patching and help yielding an organized and uniform codebase.
 
 ## Usage
 
-### Core API and concepts
+### Main concepts and API
 
 As mentioned earlier the operation is a crucial concept Pathway leverages upon. Operations not only structure your code (using steps as will be explained later) but also express meaningful business actions. Operations can be thought as use cases too: they represent an activity -to be perform by an actor interacting with the system- which should be understandable by anyone familiar with the business regardless of their technical expertise.
 
@@ -492,7 +479,7 @@ end
 ```
 
 As you can see above you can also customize the search field (`:search_by`) and indicate if you want to override the result key (`:set_result_key`) when calling to `model`.
-These two options aren't mandatory, and by default pathway will set the search field to the class model primary key, and override the result key to a snake cased version of the model name (ignoring namespaces if contained inside a class or module).
+These two options aren't mandatory, and by default Pathway will set the search field to the class model primary key, and override the result key to a snake cased version of the model name (ignoring namespaces if contained inside a class or module).
 
 Let's now take a look at the provided extensions:
 
@@ -583,10 +570,182 @@ As you can see is almost identical as the previous example only that this time y
 
 ### Plugin architecture
 
+Going a bit deeper now, we'll explain how to implement your own plugins. As was mention before `pathway` follows a very similar approach to the [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/) plugin systems, which is reflected on its implementation.
+
+Each plugin must be defined in a file placed within the `pathway/plugins/` directory of your gem or application, so `pathway` can require the file; and must be implemented as a module inside the `Pathway::Plugins` namespace module. Inside your plugin module, three extra modules can be define to extend the operation API `ClassMethods`, `InstanceMethods` and `DSLMethods`; plus a class method `apply` for plugin initialization when needed.
+
+If you are familiar with the aforementioned plugin mechanism (or other as well), the function of each module is probably starting to feel evident: `ClassMethods` will be used to extend the operation class, so any class methods should be defined here; `InstanceMethods` will be included on the operation so all the instance methods you need to add to the operation should be here, this include every custom step you need to add; and finally `DSLMethods` will be included on the `Operation::DSL` class, which holds all the DSL methods like `step` or `set`.
+The `apply` method will simply be run whenever the plugin is included, taking the operation class on the first argument and all then arguments the call to `plugin` received (excluding the plugin name).
+
+Lets explain with more detail using a complete example:
+
+```ruby
+# lib/pathway/plugins/active_record.rb
+
+module Pathway
+  module Plugins
+    module ActiveRecord
+      module ClassMethods
+        attr_accessor :model, :pk
+
+        def inherited(subclass)
+          super
+          subclass.model = self.model
+          subclass.pk    = self.pk
+        end
+      end
+
+      module InstanceMethods
+        delegate :model, :pk, to: :class
+
+        # This plugin will conflict will :sequel_models so you mustn't load them in the same operation
+        def fetch_model(state, column: pk)
+          current_pk = state[:input][column]
+          result     = model.first(column => current_pk)
+
+          if result
+            state.update(result_key => result)
+          else
+            error(:not_found)
+          end
+        end
+      end
+
+      module DSLMethods
+        # This method also conflicts with :sequel_models, so don't use them as once.
+        def transaction(&steps)
+          transactional_seq = -> seq, _state do
+            ActiveRecord::Base.transaction do
+              seq.call
+            end
+          end
+
+          sequence(transactional_seq, &steps)
+        end
+      end
+
+      def self.apply(operation, model: nil, pk: nil)
+        operation.model = model
+        opertaion.pk    = pk || model&.primary_key
+      end
+    end
+  end
+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.
+
+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.
+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.
+
+Moving on to the `ClassMethods` module, we can see the accessors `model` and `pk` are defined for the operation's class to allow configuration.
+Also, the `inherited` hook is defined, this will simply be another class method at the operation and as such will be executed normally when the operation class is inherited. In our implementation we just call to `super` (which is extremely important since other modules or parent classes could be using this hook), and then copy the `model` and `pk` options from the parent to the subclass in order to propagate the configuration downwards.
+
+At the end of the `ActiveRecord` module definition you can see the `apply` method. It will receive the operation class and the parameters passed when the `plugin` method is invoked. This method is usually used for loading dependencies of just setting up config parameters as we do in this particular example.
+
+`InstanceMethods` first defines a few delegator methods to the class itself to use later.
+Then the `fetch_model` step is defined (remember steps are but operation instance methods). Its first parameter is the state itself, as in the other steps we've seen before, and the remaining parameters are the options we can pass when calling `step :fetch_model` (mind you, this is also valid for steps defined in operations classes). Here we only take a single keyword argument: `column: pk`, with a default value; this will allow us to change the look up column when using the step, and is the only parameter we can use, passing other keyword arguments or extra positional parameters when invoking the step will raise errors.
+
+Let's now examine the `fetch_model` step body, is not really that much different from other steps, here we extract the model primary key from `state[:input][column]` and use it to perform a search. If nothing is found an error is returned, otherwise the state is updated on the result key to hold the model we just fetched from the DB.
+
+We finally see a `DSLMethods` module defined to extend the process DSL.
+For this plugin we'll define a way to group steps within an `ActiveRecord` transaction, much in the same way the `:sequel_models` plugin already does for `Sequel`.
+To this end we define a `transaction` method to expect a steps block and pass it down to the `sequence` helper below which expects a callable (like a `Proc`) and a step list block. As you can see the lambda we pass on the first parameter is the one that makes sure the steps are being run inside a transaction.
+
+The `sequence` method is a low level tool available to help extending the process DSL and it may seem a bit daunting at first glance but it usage is quite simple, the block is just a step list like the ones we find inside the `process` call; and the parameter is a callable (usually a lambda), that will take 2 arguments, an object from which we can run the step list by invoking `call` (and is the only thing it can do), and the current state. From here we can examine the state and decide upon whether to run the steps, how many times (if any) or run some code before and/or after doing so, like what we need to do in our example to surround the steps within a DB transaction.
+
 ### Testing tools
+
+As of right now only `rspec` is supported, that is, you can obviously test your operations with any framework you want, but all the provided matchers are designed for `rspec`.
+
 #### Rspec config
+
+In order to load Pathway's operation matchers you must add the following line to your `spec_helper.rb` file, after loading `rspec`:
+
+```ruby
+require 'pathway/rspec'
+```
+
 #### Rspec matchers
 
+Pathway provide 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
+# create_nugget.rb
+
+class CreateNugget < Pathway::Operation
+  plugin :dry_validation
+
+  form do
+    required(:owner).filled(:str?)
+    required(:price).filled(:int?)
+    optional(:disabled).maybe(:bool?)
+  end
+
+  process do
+    step :validate
+    set  :create_nugget
+  end
+
+  def create_nugget(params:,**)
+    Nugget.create(params)
+  end
+end
+
+
+# create_nugget_spec.rb
+
+describe CreateNugget do
+  describe '#call' do
+    subject(:operation) { CreateNugget.new }
+
+    context 'when the input is valid' do
+      let(:input) { owner: 'John Smith', value: '11230' }
+
+      it { is_expected.to succeed_on(input).returning(an_instace_of(Nugget)) }
+    end
+
+    context 'when the input is invalid' do
+      let(:input) { owner: '', value: '11230' }
+
+      it { is_expected.to fail_on(input).
+             with_type(:validation).
+             message('Is not valid').
+             and_details(owner: ['must be present']) }
+    end
+  end
+
+  describe '.form' do
+    subject(:form) { CreateNugget.form }
+
+    it { is_expected.to require_fields(:owner, :price) }
+    it { is_expected.to accept_optional_field(:disabled) }
+  end
+end
+```
+
+##### `succeed_on` matcher
+
+This first matcher works on the operation itself and that's why we could set `subject` with the operation instance and use `is_expected.to succeed_on(...)` on the example.
+The assertion it performs is simply is that the operation was successful, also you can optionally chain `returning(...)` if you want to test the returning value, this method allows nesting matchers as is the case in the example.
+
+##### `fail_on` matcher
+
+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
+
+Finally we can see that we are also testing the operation's 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.
+
+These matchers are only useful when using `dry-validation` and will very likely be extracted to its own gem in the future.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/pathway/version.rb

@@ -1,3 +1,3 @@
 module Pathway
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/pathway.rb

@@ -27,7 +27,7 @@ module Pathway
     end
   end
 
-  class Error < StandardError
+  class Error
     attr_reader :type, :message, :details
     singleton_class.send :attr_accessor, :default_messages
 
@@ -95,18 +95,15 @@ module Pathway
       module InstanceMethods
         extend Forwardable
 
-        def result_key
-          self.class.result_key
-        end
+        delegate :result_key => 'self.class'
+        delegate %i[result success failure] => Result
+
+        alias :wrap :result
 
         def call(*)
           fail "must implement at subclass"
         end
 
-        delegate %i[result success failure] => Result
-
-        alias :wrap :result
-
         def error(type, message: nil, details: nil)
           failure Error.new(type: type, message: message, details: details)
         end
@@ -155,18 +152,18 @@ module Pathway
           @result = @result.then(bl)
         end
 
-        def sequence(with_seq, &bl)
+        def sequence(steps_wrapper, &steps)
           @result.then do |state|
-            seq = -> { @result = dup.run(&bl) }
-            _callable(with_seq).call(seq, state)
+            seq = -> { @result = dup.run(&steps) }
+            _callable(steps_wrapper).call(seq, state)
           end
         end
 
-        def guard(cond, &bl)
+        def guard(cond, &steps)
           cond = _callable(cond)
           sequence(-> seq, state {
             seq.call if cond.call(state)
-          }, &bl)
+          }, &steps)
         end
 
         private

data/pathway.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Pablo Herrero"]
   spec.email         = ["pablodherrero@gmail.com"]
 
-  spec.summary       = %q{Define your bussines logic in simple steps.}
-  spec.description   = %q{Define your bussines logic in simple steps.}
+  spec.summary       = %q{Define your business logic in simple steps.}
+  spec.description   = %q{Define your business logic in simple steps.}
   #spec.homepage     = "TODO: Put your gem's website or public repo URL here."
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pathway
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Pablo Herrero
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-31 00:00:00.000000000 Z
+date: 2017-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflecto
@@ -150,7 +150,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Define your bussines logic in simple steps.
+description: Define your business logic in simple steps.
 email:
 - pablodherrero@gmail.com
 executables: []
@@ -210,5 +210,5 @@ rubyforge_project:
 rubygems_version: 2.6.9
 signing_key: 
 specification_version: 4
-summary: Define your bussines logic in simple steps.
+summary: Define your business logic in simple steps.
 test_files: []