flows 0.3.0 → 0.4.0

data/docs/railway/basic_usage.md

@@ -1,232 +0,0 @@
-# Railway :: Basic Usage
-
-`Flows::Railway` is an implementation of a Railway Programming pattern. You may read about this pattern in the following articles:
-
-* [Programming on rails: Railway Oriented Programming](http://sandordargo.com/blog/2017/09/27/railway_oriented_programming) // it's not about Ruby on Rails
-* [Railway Oriented Programming: A powerful Functional Programming pattern](https://medium.com/@naveenkumarmuguda/railway-oriented-programming-a-powerful-functional-programming-pattern-ab454e467f31)
-* [Railway Oriented Programming in Elixir with Pattern Matching on Function Level and Pipelining](https://medium.com/elixirlabs/railway-oriented-programming-in-elixir-with-pattern-matching-on-function-level-and-pipelining-e53972cede98)
-
-Let's review a simple task and solve it using `Flows::Railway`: you have to get a user by ID, get all user's blog posts and convert it to an array of HTML-strings. In such situation, we have to implement three parts of our task and compose it into something we can call, for example, from a Rails controller. Also, the first and third steps may fail (user not found, conversion to HTML failed). And if a step failed - we have to return failure info immediately. Let's draw this using a UML activity diagram:
-
-```plantuml
-@startuml
-|Success Path|
-start
--> id: Integer;
-:fetch_user;
-if (success?) then (yes)
-  -> user: User;
-  :get_blog_posts;
-  -> posts: Array<Post>;
-  :convert_to_html;
-  if (success?) then (yes)
-    -> posts_html: Array<String>;
-    stop
-  else (no)
-    |Failure|
-    -> message: String;
-    end
-  endif
-else (no)
-  |Failure|
-  -> message: String;
-  end
-endif
-@enduml
-```
-
-And implement using `Flows::Railway`:
-
-```ruby
-class RenderUserBlogPosts
-  include Flows::Railway
-
-  step :fetch_user
-  step :get_blog_posts
-  step :convert_to_html
-
-  def fetch_user(id:)
-    user = User.find_by_id(id)
-    user ? ok(user: user) : err(message: "User #{id} not found")
-  end
-
-  def get_blog_posts(user:)
-    ok(posts: User.posts)
-  end
-
-  def convert_to_html(posts:)
-    posts_html = post.map(&:text).map do |text|
-      html = convert(text)
-      return err(message: "cannot convert to html: #{text}")
-    end
-
-    ok(posts_html: posts_html)
-  end
-
-  private
-
-  # returns String or nil
-  def convert(text)
-    # some implementation here
-  end
-end
-```
-
-And execute it:
-
-```ruby
-# User with id = 1 exists and with id = 2 - doesn't
-
-RenderUserBlogPosts.new.call(id: 1)
-# => Flows::Result::Ok.new(posts_html: [...])
-
-RenderUserBlogPosts.new.call(id: 2)
-# => Flows::Result::Err.new(message: 'User 2 not found')
-```
-
-## Flows::Railway rules
-
-* steps execution happens from the first to the last step
-* input arguments (`Railway#call(...)`) becomes the input of the first step
-* each step should return Result Object (`Flows::Result::Helpers` already included)
-* if step returns failed result - execution stops and failed Result Object returned from Railway
-* if step returns successful result - result data becomes arguments of the following step
-* if the last step returns successful result - it becomes a result of a Railway execution
-
-## Defining Steps
-
-Two ways of step definition exist. First is by using an instance method:
-
-```ruby
-step :do_something
-
-def do_something(**arguments)
-  # some implementation
-  # Result Object as return value
-end
-```
-
-Second is by using lambda:
-
-```ruby
-step :do_something, ->(**arguments) { ok(some: 'data') }
-```
-
-Definition with lambda exists primarily for debugging/testing purposes. I recommend you to use method-based implementations for all your business logic. Also, this is good for consistency, readability, and maintenance. __Think about Railway as about small book: you have a "table of contents" in a form of step definitions and actual "chapters" in the same order in a form of public methods. And your private methods becomes something like "appendix".__
-
-## Dependency Injection
-
-By default, we search for step implementation methods in a class instance. But you may override method source and inject your own:
-
-```ruby
-class SayOk
-  include Flows::Railway
-
-  step :do_job
-end
-
-module Loud
-  extend Flows::Result::Helpers
-
-  def self.do_job
-    ok(text: 'OOOOKKKK!!!!')
-  end
-end
-
-module Normal
-  extend Flows::Result::Helpers
-
-  def self.do_job
-    ok(text: 'ok')
-  end
-end
-
-SayOk.new(method_source: Loud).call.unwrap
-# => { text: 'OOOOKKKK!!!!' }
-
-SayOk.new(method_source: Normal).call.unwrap
-# => { text: 'ok' }
-```
-
-When you change your method source original class is no longer used for methods lookup. But what if we want to just override one of the steps? We can:
-
-```ruby
-class SayOk
-  include Flows::Railway
-
-  step :do_job
-
-  def do_job
-    ok(text: 'ok')
-  end
-end
-
-say_loud = -> { ok(text: 'OOOOKKKK!!!!') } # or anything with implemented #call method
-
-SayOk.new.call.unwrap
-# => { text: 'OOOOKKKK!!!!' }
-
-SayOk.new(deps: { do_job: say_loud }).call.unwrap
-# => { text: 'ok' }
-```
-
-Moreover, you can mix both approaches. Injecting using `deps:` has higher priority.
-
-## Pre-building and Performance
-
-As mentioned before, railway execution consists of two phases: build (`.new`) and run (`#call`). And the build phase is expensive. You may compare overheads when you build a railway each time:
-
-```
-$ WITH_RW=1 bin/benchmark
-
---------------------------------------------------
-- task: A + B, one step implementation
---------------------------------------------------
-Warming up --------------------------------------
-Flows::Railway (build once)
-                        30.995k i/100ms
-Flows::Railway (build each time)
-                        11.553k i/100ms
-Calculating -------------------------------------
-Flows::Railway (build once)
-                        347.682k (± 2.1%) i/s -      1.767M in   5.083828s
-Flows::Railway (build each time)
-                        122.908k (± 4.2%) i/s -    623.862k in   5.085459s
-
-Comparison:
-Flows::Railway (build once):   347681.6 i/s
-Flows::Railway (build each time):   122908.0 i/s - 2.83x  slower
-
-
---------------------------------------------------
-- task: ten steps returns successful result
---------------------------------------------------
-Warming up --------------------------------------
-Flows::Railway (build once)
-                         6.130k i/100ms
-Flows::Railway (build each time)
-                         2.168k i/100ms
-Calculating -------------------------------------
-Flows::Railway (build once)
-                         63.202k (± 1.6%) i/s -    318.760k in   5.044862s
-Flows::Railway (build each time)
-                         21.645k (± 3.6%) i/s -    108.400k in   5.014725s
-
-Comparison:
-Flows::Railway (build once):    63202.5 i/s
-Flows::Railway (build each time):    21645.2 i/s - 2.92x  slower
-```
-
-As the benchmark shows your infrastructure code overhead from Flows will be almost three times lower when you build your railways at 'compile' time. I mean something like that:
-
-```ruby
-class MyClass
-  MY_RAILWAY = MyRailway.new # this string will be executed on a class loading stage
-
-  def my_method
-    MY_RAILWAY.call
-  end
-end
-```
-
-But if you don't care much about performance - build each time will be fast enough. Check out [Performance](overview/performance.md) page to see a bigger picture.

data/docs/result_objects/basic_usage.md

@@ -1,196 +0,0 @@
-# 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

@@ -1,139 +0,0 @@
-# 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.