flows 0.3.0 → 0.4.0

data/lib/flows/railway/step_list.rb

@@ -0,0 +1,38 @@
+module Flows
+  class Railway
+    # @api private
+    class StepList
+      def initialize
+        @list = []
+      end
+
+      def initialize_dup(_other)
+        @list = @list.map(&:dup)
+      end
+
+      def add(name:, lambda: nil)
+        step = Step.new(name: name, lambda: lambda)
+        last_step = @list.last
+
+        last_step.next_step = name if last_step
+
+        @list << step
+
+        self
+      end
+
+      def first_step_name
+        @list.first.name
+      end
+
+      # `:reek:FeatureEnvy` is false positive here.
+      def to_node_map(method_source)
+        @list.map { |step| [step.name, step.to_node(method_source)] }.to_h
+      end
+
+      def empty?
+        @list.empty?
+      end
+    end
+  end
+end

data/lib/flows/result.rb

@@ -1,11 +1,197 @@
 module Flows
-  # Result object with context
+  # @abstract
+  #
+  # 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/1.3/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 is a [bad way](https://martinfowler.com/articles/replaceThrowWithNotification.html)
+  #   of handling 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.
+  # * Use `case` and `===` (case equality) for matching results and writing routing logic.
+  # * Provide helpers for convenient creation and matching of Result Objects ({Helpers}).
+  # * 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 `:ok` and `:err`.
+  # * Result may have metadata ({#meta}).
+  #   Metadata is something unrelated to your business logic
+  #   (execution time, for example, or some info about who created this result).
+  #   This data must not be used in business logic, it's for a library code.
+  # * Different accessors for successful and failure results -
+  #   prevents treating failure results as successful and vice versa.
+  #
+  # ## General Recommendations
+  #
+  # Let's assume that you have some code returning Result Object.
+  #
+  # * if an error happened and may be handled somehow - return failure result.
+  # * if an 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.
+  #
+  # @example Creating Result Objects
+  #   # Successful result with data {a: 1}
+  #   x = Flows::Result::Ok.new(a: 1)
+  #
+  #   # Failure result with data {msg: 'error'}
+  #   x = Flows::Result::Err.new(msg: 'error')
+  #
+  #   # Successful result with data {a: 1} and status `:done`
+  #   x = Flows::Result::Ok.new({ a: 1 }, status: :done)
+  #
+  #   # Failure result with data {msg: 'error'} and status `:http_error`
+  #   x = Flows::Result::Err.new({ msg: 'error' }, status: :http_error)
+  #
+  #   # Successful result with data {a: 1} and metadata { time: 123 }
+  #   x = Flows::Result::Ok.new({ a: 1 }, meta: { time: 123 })
+  #
+  #   # Failure result with data {msg: 'error'} and metadata { time: 123 }
+  #   x = Flows::Result::Err.new({ msg: 'error' }, meta: { time: 123 })
+  #
+  # @example Create Result Objects using helpers
+  #   class Demo
+  #     # 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.
+  #     include Flows::Result::Helpers
+  #
+  #     def demo
+  #       # Successful result with data {a: 1}
+  #       x = ok(a: 1)
+  #
+  #       # Failure result with data {msg: 'error'}
+  #       x = err(msg: 'error')
+  #
+  #       # Successful result with data {a: 1} and status `:done`
+  #       x = ok(:done, a: 1)
+  #
+  #       # Failure result with data {msg: 'error'} and status `:http_error`
+  #       x = err(:http_error, msg: 'error')
+  #     end
+  #   end
+  #
+  # @example Inspecting Result Objects
+  #   # Behaviour of any result object:
+  #   result.status # returns status, example: `:ok`
+  #   result.meta # returns metadata, example: `{}`
+  #
+  #   # Behaviour specific to successful results:
+  #   result.ok? # true
+  #   result.err? # false
+  #   result.unwrap # returns result data
+  #   result.error # raises exception
+  #
+  #   # Behaviour specific to failure results:
+  #   result.ok? # false
+  #   result.err? # true
+  #   result.unwrap # raises exception
+  #   result.error # returns result data
+  #
+  # @example Matching Results with case
+  #   case result
+  #   when Flows::Result::Ok then do_job
+  #   when Flows::Result::Err then give_up
+  #   end
+  #
+  # @example Matching Results with case and helpers
+  #   class Demo
+  #     include Flows::Result::Helpers
+  #
+  #     def simple_usage
+  #       case result
+  #       when match_ok then do_job
+  #       when match_err then give_up
+  #       end
+  #     end
+  #
+  #     def with_status_matching
+  #       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
+  #     end
+  #   end
+  #
+  # @!method ok?
+  #   @abstract
+  #   @return [Boolean] `true` if result is successful
+  # @!method err?
+  #   @abstract
+  #   @return [Boolean] `true` if result is failure
+  # @!method unwrap
+  #   @abstract
+  #   @return [Object] result data
+  #   @raise [AccessError] if called on failure object
+  # @!method error
+  #   @abstract
+  #   @return [Object] result data
+  #   @raise [AccessError] if called on successful object
+  #
+  # @since 0.4.0
   class Result
-    attr_reader :status, :meta
+    # @return [Symbol] status of Result Object, default is `:ok` for successful results
+    #   and `:err` for failure results.
+    attr_reader :status
 
+    # @return [Hash] metadata, don't use it to store business data
+    attr_reader :meta
+
+    # Direct creation of this abstract class is forbidden.
+    #
+    # @raise [StandardError] you will get an error
     def initialize(**)
       raise 'Use Flows::Result::Ok or Flows::Result::Err for build result objects'
     end
+
+    # Results are equal if have same type and data.
+    #
+    # Metadata is ignored in comparison.
+    #
+    # @return [Boolean]
+    def ==(other)
+      return false if self.class != other.class
+
+      (status == other.status) && (data == other.send(:data))
+    end
+
+    private
+
+    attr_accessor :data
   end
 end
 

data/lib/flows/result/do.rb

@@ -1,29 +1,173 @@
 module Flows
   class Result
-    # Do-notation for Result Objects
+    # Do-notation for Result Objects.
+    #
+    # 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/1.3/do-notation/)
+    # and [Haskell do keyword](https://wiki.haskell.org/Keywords#do).
+    #
+    # Sometimes you have to write something like this:
+    #
+    #     class Something
+    #       include Flows::Result::Helpers
+    #
+    #       def perform
+    #         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:
+    #
+    #     class SomethingWithDoNotation
+    #       include Flows::Result::Helpers
+    #       extend Flows::Result::Do # enable Do Notation
+    #
+    #       do_notation(:perform) # changes behaviour of `yield` in this method
+    #       def perform
+    #         user = yield(fetch_user)[:user] # yield here returns array of one element
+    #         data = yield fetch_data # yield here returns a Hash
+    #
+    #         ok(
+    #           data: yield(calculation(user, data))[:some_field]
+    #         )
+    #       end
+    #
+    #       # private method definitions
+    #     end
+    #
+    # `do_notation(:perform)` makes some wrapping here and allows you to use `yield`
+    # inside the `perform` method in a non standard way:
+    # to unpack results or instantly leave a method if a failed result was provided.
+    #
+    # ## How to use it
+    #
+    # First of all, you have to include `Flows::Result::Do` mixin into your class or module.
+    # It adds `do_notation` class method.
+    # `do_notation` accepts method name as an argument and changes behaviour of `yield` inside this method.
+    # By the way, when you are using `do_notation` you cannot pass a block to modified method anymore.
+    #
+    #     class MyClass
+    #       extend Flows::Result::Do
+    #
+    #       do_notation(:my_method_1)
+    #       def my_method_1
+    #         # some code
+    #       end
+    #
+    #       do_notation(:my_method_2)
+    #       def my_method_2
+    #         # some code
+    #       end
+    #     end
+    #
+    # `yield` in such methods is working by the following rules:
+    #
+    #     ok_result = Flows::Result::Ok.new(a: 1, b: 2)
+    #     err_result = Flows::Result::Err.new(x: 1, y: 2)
+    #
+    #     # the following three lines are equivalent
+    #     yield(ok_result)
+    #     ok_result.unwrap
+    #     { a: 1, b: 2 }
+    #
+    #     # the following three lines are equivalent
+    #     yield(:a, :b, ok_result)
+    #     ok_result.unwrap.values_at(:a, :b)
+    #     [1, 2]
+    #
+    #     # the following three lines are equivalent
+    #     return err_result
+    #     yield(err_result)
+    #     yield(:x, :y, 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 `do_notation(:method_name)` adds special wrapper method to the prepended module.
+    # So, when you perform call to `YourClassOrModule#method_name` - you're executing wrapper in
+    # the prepended module.
     module Do
-      # DSL for Do-notation
-      module DSL
-        def do_for(method_name)
-          @flows_result_do_module.define_method(method_name) do |*args|
-            super(*args) do |*fields, result|
-              case result
-              when Flows::Result::Ok
-                fields.any? ? result.unwrap.values_at(*fields) : result.unwrap
-              when Flows::Result::Err then return result
-              else raise "Unexpected result: #{result.inspect}. Should be a Flows::Result"
+      MOD_VAR_NAME = :@flows_result_module_for_do
+
+      # Utility functions for Flows::Result::Do.
+      #
+      # Isolated location prevents polluting user classes with unnecessary methods.
+      #
+      # @api private
+      module Util
+        class << self
+          def fetch_and_prepend_module(mod)
+            module_for_do = mod.instance_variable_get(MOD_VAR_NAME)
+            mod.prepend(module_for_do)
+            module_for_do
+          end
+
+          # `:reek:TooManyStatements:` - allowed because we have no choice here.
+          #
+          # `:reek:NestedIterators` - allowed here because here are no iterators.
+          def define_wrapper(mod, method_name) # rubocop:disable Metrics/MethodLength
+            mod.define_method(method_name) do |*args|
+              super(*args) do |*fields, result|
+                case result
+                when Flows::Result::Ok
+                  data = result.unwrap
+                  fields.any? ? data.values_at(*fields) : data
+                when Flows::Result::Err then return result
+                else raise "Unexpected result: #{result.inspect}. Should be a Flows::Result"
+                end
               end
             end
           end
         end
       end
 
-      def self.included(mod)
-        patch_mod = Module.new
+      # @api private
+      def self.extended(mod)
+        ::Flows::Util::InheritableSingletonVars::IsolationStrategy.call(
+          mod,
+          MOD_VAR_NAME => -> { Module.new }
+        )
+      end
+
+      def do_notation(method_name)
+        prepended_mod = Util.fetch_and_prepend_module(self)
 
-        mod.instance_variable_set(:@flows_result_do_module, patch_mod)
-        mod.prepend(patch_mod)
-        mod.extend(DSL)
+        Util.define_wrapper(prepended_mod, method_name)
       end
     end
   end

data/lib/flows/result/err.rb

@@ -1,25 +1,31 @@
 module Flows
   class Result
-    # Wrapper for failure results
+    # Result Object for failure results.
+    #
+    # @see Flows::Result behaviour described here
     class Err < Result
-      attr_reader :error
-
-      def initialize(data, status: :failure, meta: {})
-        @error = data
+      def initialize(data, status: :err, meta: {})
+        @data = data
         @status = status
         @meta = meta
       end
 
+      def error
+        @data
+      end
+
+      # @return [false]
       def ok?
         false
       end
 
+      # @return [true]
       def err?
         true
       end
 
       def unwrap
-        raise UnwrapError.new(@status, @data, @meta)
+        raise AccessError, self
       end
     end
   end