flows 0.2.0 → 0.6.0

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.

data/lib/flows/node.rb

@@ -1,27 +0,0 @@
-module Flows
-  # Representation of FSM node.
-  class Node
-    attr_reader :name, :meta
-
-    def initialize(name:, body:, router:, meta: {}, preprocessor: nil, postprocessor: nil)
-      @name = name
-      @body = body
-      @router = router
-
-      @meta = meta.freeze
-
-      @preprocessor = preprocessor
-      @postprocessor = postprocessor
-    end
-
-    def call(input, context:)
-      input  = @preprocessor.call(input, context, @meta) if @preprocessor
-      output = @body.call(input)
-      output = @postprocessor.call(output, context, @meta) if @postprocessor
-
-      route = @router.call(output, context: context, meta: @meta)
-
-      [output, route]
-    end
-  end
-end

data/lib/flows/operation.rb

@@ -1,52 +0,0 @@
-require_relative 'operation/errors'
-
-require_relative 'operation/dsl'
-require_relative 'operation/builder'
-require_relative 'operation/executor'
-
-module Flows
-  # Operation DSL
-  module Operation
-    def self.included(mod)
-      mod.extend ::Flows::Operation::DSL
-    end
-
-    include ::Flows::Result::Helpers
-
-    def initialize(method_source: nil, deps: {})
-      _flows_do_checks
-
-      flow = _flows_make_flow(method_source || self, deps)
-
-      @_flows_executor = _flows_make_executor(flow)
-    end
-
-    def call(**params)
-      @_flows_executor.call(**params)
-    end
-
-    private
-
-    def _flows_do_checks
-      raise NoStepsError if self.class.steps.empty?
-      raise NoSuccessShapeError, self if self.class.ok_shapes.nil?
-    end
-
-    def _flows_make_flow(method_source, deps)
-      ::Flows::Operation::Builder.new(
-        steps: self.class.steps,
-        method_source: method_source,
-        deps: deps
-      ).call
-    end
-
-    def _flows_make_executor(flow)
-      ::Flows::Operation::Executor.new(
-        flow: flow,
-        ok_shapes: self.class.ok_shapes,
-        err_shapes: self.class.err_shapes,
-        class_name: self.class.name
-      )
-    end
-  end
-end

data/lib/flows/operation/builder.rb

@@ -1,130 +0,0 @@
-require_relative './builder/build_router'
-
-module Flows
-  module Operation
-    # Flow builder
-    class Builder
-      attr_reader :steps, :method_source, :deps
-
-      def initialize(steps:, method_source:, deps:)
-        @method_source = method_source
-        @steps = steps
-        @deps = deps
-
-        @step_names = @steps.map { |s| s[:name] }
-      end
-
-      def call
-        resolve_wiring!
-        resolve_bodies!
-
-        nodes = build_nodes
-        Flows::Flow.new(start_node: nodes.first.name, nodes: nodes)
-      end
-
-      private
-
-      def resolve_wiring! # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        # we have to disable some linters for performance reasons
-        # this method can be simplified using `map.with_index`, but while loops is about
-        # 2x faster for such cases.
-        index = 0
-
-        while index < @steps.length
-          current_step = @steps[index]
-          next_step_name = nil
-
-          inner_index = index + 1
-          while inner_index < @steps.length
-            candidate = @steps[inner_index]
-            candidate_last_track = candidate[:track_path].last
-
-            if candidate[:track_path] == [] || current_step[:track_path].include?(candidate_last_track)
-              next_step_name = candidate[:name]
-              break
-            end
-
-            inner_index += 1
-          end
-
-          current_step[:next_step] = next_step_name || :term
-
-          index += 1
-        end
-      end
-
-      def resolve_bodies!
-        @steps.each do |step|
-          step.merge!(
-            body: step[:custom_body] || resolve_body_from_source(step[:name])
-          )
-        end
-      end
-
-      def resolve_body_from_source(name)
-        return @deps[name] if @deps.key?(name)
-
-        raise(::Flows::Operation::NoStepImplementationError, name) unless @method_source.respond_to?(name)
-
-        @method_source.method(name)
-      end
-
-      def build_nodes
-        @nodes = @steps.map do |step|
-          Flows::Node.new(
-            name: step[:name],
-            body: build_final_body(step),
-            preprocessor: method(:node_preprocessor),
-            postprocessor: method(:node_postprocessor),
-            router: BuildRouter.call(step[:custom_routes], step[:next_step], @step_names),
-            meta: build_meta(step)
-          )
-        end
-      end
-
-      def build_final_body(step)
-        case step[:type]
-        when :step
-          step[:body]
-        when :wrapper
-          build_wrapper_body(step[:body], step[:block])
-        end
-      end
-
-      def build_wrapper_body(wrapper, block)
-        suboperation_class = Class.new do
-          include ::Flows::Operation
-        end
-
-        suboperation_class.instance_exec(&block)
-        suboperation_class.no_shape
-
-        suboperation = suboperation_class.new(method_source: @method_source, deps: @deps)
-
-        lambda do |**options|
-          wrapper.call(**options) { suboperation.call(**options) }
-        end
-      end
-
-      def build_meta(step)
-        {
-          type: step[:type],
-          name: step[:name],
-          track_path: step[:track_path]
-        }
-      end
-
-      def node_preprocessor(_input, context, _meta)
-        context[:data]
-      end
-
-      def node_postprocessor(output, context, meta)
-        output_data = output.ok? ? output.unwrap : output.error
-        context[:data].merge!(output_data)
-        context[:last_step] = meta[:name]
-
-        output
-      end
-    end
-  end
-end