pathway 0.0.17 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f7e4c097fd9029a04f2a89b3cd08f5cc1bf1d04
-  data.tar.gz: 8ba11ece82c8df606d7a2550fd107c8738ed595a
+  metadata.gz: 51bd7ec68ed98d860f4f2703fd052a0649060c3b
+  data.tar.gz: 7431743f7a87a6a477520f65a9df64b4702959a8
 SHA512:
-  metadata.gz: bbe7728807988d4312337795ab6cb8d203b47541cc210dd3e18e34eb279aa2332a2f48b779312878fb00042ea0339386db5374d9d0ca527b6d8dd6df30a48131
-  data.tar.gz: 0de4b1d09b9753a8bfb5c6002b789b65d8e28248082c91c43aa6b78b12e857967cb3c2d20d238896068b72dc0bec0a3b349ddf2c63d03a580858f8dbf6f24cb9
+  metadata.gz: bca57cec6205c20f2868cda4a35fa764bb1debe0496e76e72cfd00669b2ae6dd19a8d7ee279d37786f3aa61e9f623a6518504c2e7da357d9c380167ea34933d4
+  data.tar.gz: 4c62b4c47cf3337f87366032219f9937ef16b7683664fe191067787ebac964b8947c4d278fe86b1b26e32fd4e0427b215cbac81748e267b5e455ea91477baf30

data/README.md

@@ -4,9 +4,7 @@
 [![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)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/pathway`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Pathway allows you to encapsulate your app's business logic into operation objects (also known as application services on the DDD lingo).
 
 ## Installation
 
@@ -24,9 +22,113 @@ Or install it yourself as:
 
     $ gem install pathway
 
+## Introduction
+
+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.
+
+
+Pathway also aims to be easy to use, stay lightweight and modular, avoid unnecessary heavy dependencies, keep the core classes clean from monkey patching and help yielding an organized and uniform codebase.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Core API and concepts
+
+As mentioned earlier the operation is a crucial concept Pathway leverages upon. Operations not only structure your code (using steps as will be explained latter) 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.
+
+
+Operations should ideally don't contain any business rules but instead orchestrate and delegate to other more specific subsystems and services. The only logic present then should be glue code or any adaptations required to make interactions with the inner system layers possible.
+
+#### Function object protocol (the `call` method)
+
+Operations works as function objects, they are callable and hold no state, as such, any object that responds to `call` and returns a result object can be a valid operation and that's the minimal protocol they needs to follow.
+The result object must follow its own protocol as well (and a helper class is provided for that end) but we'll talk about that in a minute.
+
+Let's see an example:
+
+```ruby
+class MyFirstOperation
+  def call(params)
+    result = Repository.create(params)
+
+    if result.valid?
+      Pathway::Result.success(result)
+    else
+      Pathway::Result.failure(:create_error)
+    end
+  end
+end
+
+result = MyFirstOperation.new.call(foo: 'foobar')
+if result.success?
+  puts result.value.inspect
+else
+  puts "Error: #{result.error}"
+end
+
+```
+
+Note first we are not inheriting from any class nor including any module. This won't be the case in general as `pathway` provides classes to help build your operations, but it serves to illustrate how little is needed to implement one.
+
+Also, let's ignore the specifics about `Repository.create(...)`, we just need to know that is some backend service which can return a value.
+
+
+We now provide a `call` method for our class. It will just check if the result is available and then wrap it into a successful `Result` object when is ok, or a failing one when is not.
+And that's it, you can then call the operation object, check whether it was completed correctly with `success?` and get the resulting value.
+
+By following this protocol, you will be able to uniformly apply the same pattern on every HTTP endpoint (or whatever means your app has to communicates with the outside world). The upper layer of the application is now offloading all the domain logic to the operation and only needs to focus on the data transmission details.
+
+Maintaining always the same operation protocol will also be very useful when composing them.
+
+
+#### Operation result
+
+As should be evident by now an operation should always return either a successful or failed result. This concepts are represented by following a simple protocol, which `Pathway::Result` subclasses comply.
+
+As we seen before, by querying `success?` on the result we can see if the operation we just ran went well, you can also call to `failure?` for a negated version.
+
+The actual result value produced by the operation is be accessible at the `value` method and the error description (if there's any) at `error` when the operation fails.
+
+To return wrapped values or errors from your operation you can must call to `Pathway::Result.success(value)` or `Pathway::Result.failure(error)`.
+
+
+It is worth mentioning that when you inherit from `Pathway::Operation` you'll have helper methods at your disposal to create result objects easier, for instance the previous section's example could be written as follows:
+
+
+```ruby
+class MyFirstOperation < Pathway::Operation
+  def call(params)
+    result = Repository.create(params)
+
+    result.valid? ? success(result) : failure(:create_error)
+  end
+end
+```
+
+#### Error objects
+#### Initialization and context
+#### Steps
+
+Finally the steps, these are the heart of the `Operation` class and the main reason you will want to inherit your own classes from `Pathway::Operation`.
+
+#### Execution process state
+#### Alternative invocation syntaxes and pattern matching DSL
+
+### Plugins
+#### Plugin architecture
+
+#### `SimpleAuth` plugin
+#### `DryValidation` plugin
+#### `SequelModels` plugin
+#### `Responder` plugin
+
+### Testing tools
+#### Rspec config
+#### Rspec matchers
+
+## Best practices
+### Operation object design and organization
+### Testing recomendations
 
 ## Development
 

data/lib/pathway/plugins/sequel_models.rb

@@ -24,7 +24,7 @@ module Pathway
       module ClassMethods
         attr_accessor :model_class, :search_field
 
-        def model(model_class, search_by: :id, set_result_key: true)
+        def model(model_class, search_by: model_class.primary_key, set_result_key: true)
           self.model_class  = model_class
           self.search_field = search_by
           self.result_key   = Inflecto.underscore(model_class.name.split('::').last).to_sym if set_result_key

data/lib/pathway/version.rb

@@ -1,3 +1,3 @@
 module Pathway
-  VERSION = '0.0.17'
+  VERSION = '0.0.18'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pathway
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.18
 platform: ruby
 authors:
 - Pablo Herrero
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-25 00:00:00.000000000 Z
+date: 2017-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflecto