flows 0.1.0 → 0.2.0

data/docs/result_objects/basic_usage.md

@@ -0,0 +1,196 @@
+# Result Object :: Basic Usage
+
+Result Object is a way of presenting the result of a calculation. The result may be successful or failed.
+For example, if you calculate expression `a / b`:
+
+* for `a = 6` and `b = 2` result will be successful with data `3`.
+* for `a = 6` and `b = 0` result will be failed with data, for example, `"Cannot divide by zero"`.
+
+Examples of such approach may be found in other libraries and languages:
+
+* [Either Monad](https://hackage.haskell.org/package/category-extras-0.52.0/docs/Control-Monad-Either.html) in Haskell
+* [Result Type](https://doc.rust-lang.org/std/result/enum.Result.html) in Rust
+* [Faraday gem](https://www.rubydoc.info/gems/faraday/Faraday/Response) has `Faraday::Response` object which contains data and status
+* [dry-rb Result Monad](https://dry-rb.org/gems/dry-monads/result/) has `Dry::Monads::Result`
+
+So, why do you need Result Object? Why not just return `nil` on a failure or raise an error (like in the standard library)? Here are several reasons:
+
+* raising errors and exceptions isn't a very convenient and explicit way to handle errors. Moreover, it is slow and looks like `goto`. However, it is still a good way to abort execution on an unexpected error.
+* returning `nil` does not work when you have to deal with different types of errors or an error has some data payload.
+* using specific Result Objects (like `Faraday::Response`) brings inconsistency - you have to learn how to deal with each new type of Result.
+
+That's why `Flows` should have Result Object implementation. If any executable Flows entity will return Result Object with the same API - composing your app components becomes trivial. Result Objects should also be as fast and lightweight as possible.
+
+Flows' implementation is inspired mainly by [Rust Result Type](https://doc.rust-lang.org/std/result/enum.Result.html) and focused on following features:
+
+* use idiomatic Ruby: no methods named with first capital letter (`Name(1, 2)`), etc.
+* provide convenient helpers for `case` and `===` (case equality) for matching results and writing routing logic
+* provide helpers for convenient creation of Result Objects
+* Result Object may be successful (`Ok`) or failure (`Err`)
+* Result Object has an status (some symbol: `:saved`, `:zero_division_error`)
+* status usage is optional. Default statuses for successful and failure results are `:success` and `:failure`
+* result may have metadata. Metadata is something unrelated to your business logic (execution time, for example, or some info about who created this result).
+* different accessors for successful and failure results - prevents treating failure results as successful and vice versa.
+
+## Class Diagram
+
+Class UML diagram describing current implementation:
+
+```plantuml
+@startuml
+class Flows::Result<Abstract Class> {
+  .. Constructor ..
+  {static} new(Symbol status, Hash data, Hash metadata)
+  .. Success checks ..
+  {abstract} bool ok?()
+  {abstract} bool err?()
+  .. Result data access ..
+  Symbol status()
+  {abstract} Hash unwrap()
+  {abstract} Hash error()
+  .. Metadata ..
+  Hash meta()
+}
+
+class Flows::Result::Ok {
+  true ok?()
+  false err?()
+  ..
+  Hash unwrap()
+  [raise exception] error()
+}
+
+class Flows::Result::Err {
+  false ok?()
+  true err?()
+  ..
+  [raise exception] unwrap()
+  Hash error()
+}
+
+Flows::Result --> Flows::Result::Ok
+Flows::Result --> Flows::Result::Err
+@enduml
+```
+
+## Creating Results
+
+Most flexible and verbose way of creating Result Objects is creating via `.new`:
+
+```ruby
+# Successful result with data {a: 1}
+Flows::Result::Ok.new(a: 1)
+
+# Failure result with data {msg: 'error'}
+Flows::Result::Err.new(msg: 'error')
+
+# Successful result with data {a: 1} and status `:done`
+Flows::Result::Ok.new({ a: 1 }, status: :done)
+
+# Failure result with data {msg: 'error'} and status `:http_error`
+Flows::Result::Err.new({ msg: 'error' }, status: :http_error)
+
+# Successful result with data {a: 1} and metadata `{ time: 123 }`
+Flows::Result::Ok.new({ a: 1 }, meta: { time: 123 })
+
+# Failure result with data {msg: 'error'} and metadata `{ time: 123 }`
+Flows::Result::Err.new({ msg: 'error' }, meta: { time: 123 })
+```
+
+More convenient and short way is to use helpers:
+
+```ruby
+include Flows::Result::Helpers
+
+# Successful result with data {a: 1}
+ok(a: 1)
+
+# Failure result with data {msg: 'error'}
+err(msg: 'error')
+
+# Successful result with data {a: 1} and status `:done`
+ok(:done, a: 1)
+
+# Failure result with data {msg: 'error'} and status `:http_error`
+err(:http_error, msg: 'error')
+```
+
+You cannot provide metadata using helpers and it's ok: you shouldn't populate metadata in your business code.
+Metadata is designed to use in library code and when you have to provide some metadata from your library - just use `.new` instead of helpers.
+
+## Inspecting Results
+
+Behaviour of any result object:
+
+```ruby
+result.status # returns status, example: `:success`
+
+result.meta # returns metadata, example: `{}`
+```
+
+Behaviour specific to successful results:
+
+```ruby
+result.ok? # true
+
+result.err? # false
+
+result.unwrap # returns result data
+
+result.error # raises exception
+```
+
+Behaviour specific to failure results:
+
+```ruby
+result.ok? # false
+
+result.err? # true
+
+result.unwrap # raises exception
+
+result.error # returns result data
+```
+
+## Matching Results
+
+Basic matching results using `case`:
+
+```ruby
+case result
+when Flows::Result::Ok then do_job
+when Flows::Results::Err then give_up
+end
+```
+
+But this is too verbose. For this case helpers has methods for matching. Example above may be rewritten like this:
+
+```ruby
+include Flows::Result::Helpers
+
+case result
+when match_ok then do_job
+when match_err then give_up
+end
+```
+
+Moreover, you may specify status when using helper matchers:
+
+```ruby
+include Flows::Result::Helpers
+
+case result
+when match_ok(:create) then do_create
+when match_ok(:update) then do_update
+when match_err(:http_error) then retry
+when match_err then give_up
+end
+```
+
+## General Recommendations
+
+Let's assume that you have some code returning Result Object.
+
+* if error happened and may be handled somehow - return failure result
+* if error happened and cannot be handled - raise exception to abort execution
+* if you don't handle any errors for now - don't check result type and use `#unwrap` to access data. It will raise exception when called on a failure result.

data/docs/result_objects/do_notation.md

@@ -0,0 +1,139 @@
+# Result Object :: Do Notation
+
+This functionality aims to simplify common control flow pattern: when you have to stop execution on a first failure and return this failure.
+Do Notation inspired by [Do Notation in dry-rb](https://dry-rb.org/gems/dry-monads/do-notation/) and [Haskell do keyword](https://wiki.haskell.org/Keywords#do).
+
+Sometimes you have to write something like this:
+
+```ruby
+class Something
+  include Flows::Result::Helpers
+
+  def do_job
+    user_result = fetch_user
+    return user_result if user_result.err?
+
+    data_result = fetch_data
+    return data_result if data_result.err?
+
+    calculation_result = calculation(user_result.unwrap[:user], data_result.unwrap)
+    return calculation_result if user_result.err?
+
+    ok(data: calculation_result.unwrap[:some_field])
+  end
+
+  private
+
+  def fetch_user
+    # returns Ok or Err
+  end
+
+  def fetch_data
+    # returns Ok or Err
+  end
+
+  def calculation(_user, _data)
+    # returns Ok or Err
+  end
+end
+```
+
+The main idea of the code above is to stop method execution and return failed Result Object if one of the sub-operations is failed. At the moment of failure.
+
+By using Do Notation feature you may rewrite it like this:
+
+```ruby
+class SomethingWithDoNotation
+  include Flows::Result::Helpers
+  include Flows::Result::Do # enable Do Notation
+
+  do_for(:do_job) # changes behaviour of `yield` in this method
+  def do_job
+    user, = yield :user, fetch_user # yield here returns array of one element
+    data = yield fetch_data # yield here returns a Hash
+
+    ok(data: yield(:some_field, calculation(user, data))[0])
+  end
+
+  # private method definitions
+end
+```
+
+or like this:
+
+```ruby
+do_for(:do_job)
+def do_job
+  user = yield(fetch_user)[:user] # yield here and below returns a Hash
+  data = yield fetch_data
+
+  ok(data: yield(calculation(user, data))[:some_field])
+end
+```
+
+`do_for(:do_job)` makes some simple magic here and allows you to use `yield` inside `do_job` in a non standard way:
+to unpack results or instantly leave a method if a failed result provided.
+
+## How to use it
+
+First of all, you have to include `Flows::Result::Do` mixin into your class or module. It adds `do_for` class method.
+`do_for` accepts method name as an argument and changes behaviour of `yield` inside this method. By the way, when you are using
+`do_for` you cannot pass a block to modified method anymore.
+
+Then `do_for` method should be used to enable Do Notation for certain methods.
+
+```ruby
+class MyClass
+  include Flows::Result::Do
+
+  do_for(:my_method_1)
+  def my_method_1
+    # some code
+  end
+
+  do_for(:my_method_2)
+  def my_method_2
+    # some code
+  end
+end
+```
+
+`yield` in such methods starts working by following rules:
+
+```ruby
+ok_result = Flows::Result::Ok.new(a: 1, b: 2)
+err_result = Flows::Result::Err.new(x: 1, y: 2)
+
+# following three lines are equivalent
+yield(ok_result)
+ok_result.unwrap
+{ a: 1, b: 2 }
+
+# following three lines are equivalent
+yield(:a, :b, ok_result)
+ok_result.unwrap.values_at(:a, :b)
+[1, 2]
+
+# following two lines are equivalent
+yield(err_result)
+return err_result
+
+# following two lines are equivalent
+yield(:x, :y, err_result)
+return err_result
+```
+
+As you may see, `yield` has two forms of usage:
+
+* `yield(result_value)` - returns unwrapped data Hash for successful results or,
+  in case of failed result, stops method execution and returns failed `result_value` as a method result.
+* `yield(*keys, result_value)` - returns unwrapped data under provided keys as Array for successful results or,
+  in case of failed result, stops method execution and returns failed `result_value` as a method result.
+
+## How it works
+
+Under the hood `Flows::Result::Do` creates a module and prepends it to your class or module.
+Invoking of `do_for(:method_name)` adds special wrapper method to the prepended module. So, when you perform call to
+`YourClassOrModule#method_name` - you execute wrapper in the prepended module.
+
+Check out source code for implementation details.

data/flows.gemspec

@@ -25,7 +25,9 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
+  spec.add_development_dependency 'forspell', '~> 0.0.8'
   spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-md'
   spec.add_development_dependency 'rubocop-performance'
   spec.add_development_dependency 'rubocop-rspec'
 

data/forspell.dict

@@ -0,0 +1,8 @@
+# Format: one word per line. Empty lines and #-comments are supported too.
+# If you want to add word with its forms, you can write 'word: example' (without quotes) on the line,
+# where 'example' is existing word with the same possible forms (endings) as your word.
+# Example: deduplicate: duplicate
+linter
+linters
+matchers
+superset

data/lefthook.yml

@@ -0,0 +1,12 @@
+pre-commit:
+  parallel: true
+  commands:
+    rubocop:
+      glob: "{*.rb,*.md,*.gemspec,Gemfile,Rakefile}"
+      run: bundle exec rubocop {staged_files}
+    markdownlinter:
+      glob: "*.md"
+      run: bundle exec mdl {staged_files}
+    forspell:
+      glob: "{*.md,*.rb}"
+      run: bundle exec forspell {staged_files}

data/lib/flows.rb

@@ -6,8 +6,10 @@ require 'flows/version'
 
 require 'flows/router'
 require 'flows/result_router'
+
 require 'flows/node'
 require 'flows/flow'
 
 require 'flows/result'
+require 'flows/railway'
 require 'flows/operation'

data/lib/flows/flow.rb

@@ -1,5 +1,5 @@
 module Flows
-  # Simple sequentional flow
+  # Simple sequential flow
   class Flow
     def initialize(start_node:, nodes:)
       @start_node = start_node

data/lib/flows/operation.rb

@@ -5,11 +5,9 @@ require_relative 'operation/builder'
 require_relative 'operation/executor'
 
 module Flows
-  # Operaion DSL
+  # Operation DSL
   module Operation
     def self.included(mod)
-      mod.instance_variable_set(:@steps, [])
-      mod.instance_variable_set(:@track_path, [])
       mod.extend ::Flows::Operation::DSL
     end
 

data/lib/flows/operation/builder.rb

@@ -54,8 +54,8 @@ module Flows
       end
 
       def resolve_bodies!
-        @steps.map! do |step|
-          step.merge(
+        @steps.each do |step|
+          step.merge!(
             body: step[:custom_body] || resolve_body_from_source(step[:name])
           )
         end

data/lib/flows/operation/dsl.rb

@@ -4,6 +4,20 @@ module Flows
     module DSL
       attr_reader :steps, :ok_shapes, :err_shapes
 
+      def self.extended(mod, steps = nil, ok_shapes = nil, err_shapes = nil)
+        mod.instance_variable_set(:@steps, steps || [])
+        mod.instance_variable_set(:@track_path, [])
+        mod.instance_variable_set(:@ok_shapes, ok_shapes)
+        mod.instance_variable_set(:@err_shapes, err_shapes)
+
+        mod.class_exec do
+          def self.inherited(subclass)
+            ::Flows::Operation::DSL.extended(subclass, steps.map(&:dup), ok_shapes, err_shapes)
+            super
+          end
+        end
+      end
+
       include Flows::Result::Helpers
 
       def step(name, custom_body_or_routes = nil, custom_routes = nil)
@@ -30,6 +44,13 @@ module Flows
         @track_path = track_path_before
       end
 
+      def routes(routes_hash)
+        routes_hash
+      end
+
+      alias when_ok match_ok
+      alias when_err match_err
+
       def wrap(name, custom_body = nil, &block)
         @steps << make_step(name, type: :wrapper, custom_body: custom_body, block: block)
       end