flows 0.2.0 → 0.6.0

data/lib/flows/result/do.rb

@@ -1,29 +1,171 @@
 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
+
+      SingletonVarsSetup = ::Flows::Util::InheritableSingletonVars::IsolationStrategy.make_module(
+        MOD_VAR_NAME => -> { Module.new }
+      )
+
+      include SingletonVarsSetup
+
+      # 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
+      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

data/lib/flows/result/errors.rb

@@ -1,29 +1,41 @@
 module Flows
   class Result
-    # Error for unwrapping non-successful result object
-    class UnwrapError < Flows::Error
-      def initialize(status, data, meta)
-        @status = status
-        @data = data
-        @meta = meta
+    # Base class for Result errors.
+    class Error < ::Flows::Error; end
+
+    # Error for invalid data access cases
+    class AccessError < Flows::Error
+      def initialize(result)
+        @result = result
       end
 
       def message
-        "You're trying to unwrap non-successful result with status `#{@status.inspect}` and data `#{@data.inspect}`\n\
-Result metadata: `#{@meta.inspect}`"
+        [
+          base_msg,
+          "  Result status: `#{@result.status.inspect}`",
+          "  Result data:   `#{data.inspect}`",
+          "  Result meta:   `#{@result.meta.inspect}`"
+        ].join("\n")
       end
-    end
 
-    # Error for dealing with failure result as success one
-    class NoErrorError < Flows::Error
-      def initialize(status, data)
-        @status = status
-        @data = data
+      private
+
+      def base_msg
+        case @result
+        when Flows::Result::Ok
+          'Data in a successful result must be retrieved using `#unwrap` method, not `#error`.'
+        when Flows::Result::Err
+          'Data in a failure result must be retrieved using `#error` method, not `#unwrap`.'
+        end
       end
 
-      def message
-        "You're trying to get error data for successful result with status \
-`#{@status.inspect}` and data `#{@data.inspect}`"
+      def data
+        case @result
+        when Flows::Result::Ok
+          @result.unwrap
+        when Flows::Result::Err
+          @result.error
+        end
       end
     end
   end

data/lib/flows/result/helpers.rb

@@ -1,14 +1,36 @@
 module Flows
   class Result
-    # Shortcuts for building result objects
+    # Shortcuts for building and matching result objects.
+    #
+    # `:reek:UtilityFunction` and `:reek:FeatureEnvy` checks should be disabled here
+    # because this module is intended to contain private utility methods only.
+    #
+    # This module defines the following private methods:
+    #
+    # * `ok(status = :ok, **data)` - for building successful results from a hash of keyword arguments.
+    # * `ok_data(data, status: :ok)` - for building successful results from any data.
+    # * `err(status = :err, **data)` - for building failure results from a hash of keyword arguments.
+    # * `err_data(data, status: :err)` - for building failure results from any data.
+    # * `match_ok(status = nil)` - for case matching against successful results.
+    # * `match_err(status = nil)` - for case matching against failure results.
+    #
+    # @see Flows::Result usage examples provided here
     module Helpers
       private
 
-      def ok(status = :success, **data)
+      def ok(status = :ok, **data)
         Flows::Result::Ok.new(data, status: status)
       end
 
-      def err(status = :failure, **data)
+      def ok_data(data, status: :ok)
+        Flows::Result::Ok.new(data, status: status)
+      end
+
+      def err(status = :err, **data)
+        Flows::Result::Err.new(data, status: status)
+      end
+
+      def err_data(data, status: :err)
         Flows::Result::Err.new(data, status: status)
       end
 

data/lib/flows/result/ok.rb

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

data/lib/flows/shared_context_pipeline.rb

@@ -0,0 +1,342 @@
+require_relative 'shared_context_pipeline/errors'
+require_relative 'shared_context_pipeline/router_definition'
+require_relative 'shared_context_pipeline/step'
+require_relative 'shared_context_pipeline/mutation_step'
+require_relative 'shared_context_pipeline/track'
+require_relative 'shared_context_pipeline/track_list'
+require_relative 'shared_context_pipeline/wrap'
+require_relative 'shared_context_pipeline/dsl'
+
+module Flows
+  # Abstraction for organizing calculations in a shared data context.
+  #
+  # Let's start with example. Let's say we have to calculate `(a + b) * (a - b)`:
+  #
+  #     class Claculation < Flows::SharedContextPipeline
+  #       step :calc_left_part
+  #       step :calc_right_part
+  #       step :calc_result
+  #
+  #       def calc_left_part(a:, b:, **)
+  #         ok(left: a + b)
+  #       end
+  #
+  #       def calc_right_part(a:, b:, **)
+  #         ok(right: a - b)
+  #       end
+  #
+  #       def calc_result(left:, right:, **)
+  #         ok(result: left * right)
+  #       end
+  #     end
+  #
+  #     x = Calculation.call(a: 1, b: 2)
+  #     # x is a `Flows::Result::Ok`
+  #
+  #     x.unwrap
+  #     # => { a: 1, b: 2, left: 3, right: -1, result: -3 }
+  #
+  # It works by the following rules:
+  #
+  # * execution context is a Hash with Symbol keys.
+  # * input becomes initial execution context.
+  # * steps are executed in a provided order.
+  # * actual execution context becomes a step input.
+  # * step implementation is a public method with the same name.
+  # * step implementation must return {Flows::Result} ({Flows::Result::Helpers} already included).
+  # * Result Object data will be merged to shared context after each step execution.
+  # * If returned Result Object is successful - next step will be executed,
+  #   in the case of the last step a calculation will be finished
+  # * If returned Result Object is failure - a calculation will be finished
+  # * When calculation is finished a Result Object will be returned:
+  #     * result will have the same type and status as in the last executed step result
+  #     * result wull have a full execution context as data
+  #
+  # ## Mutation Steps
+  #
+  # You may use a different step definition way:
+  #
+  #     class MyClass < Flows::SharedContextPipeline
+  #       mut_step :hello
+  #
+  #       def hello(ctx)
+  #         ctx[:result] = 'hello'
+  #       end
+  #     end
+  #
+  # When you use `mut_step` DSL method you define a step with different rules for implementation:
+  #
+  # * step implementation receives _one_ argument and it's your execution context in a form of a mutable Hash
+  # * step implementation can modify execution context
+  # * if step implementation returns
+  #     * "truly" value - it makes step successful with default status `:ok`
+  #     * "falsey" value - it makes step failure with default status `:err`
+  #     * {Result} - it works like for standard step, but data is ignored. Only result type and status have effect.
+  #
+  # ## Tracks & Routes
+  #
+  # In some situations you may want some branching in a mix. Let's provide an example for a common problem
+  # when you have to do some additional steps in case of multiple types of errors.
+  # Let's say report to some external system:
+  #
+  #     class SafeFetchComment < Flows::SharedContextPipeline
+  #       step :fetch_post, routes(
+  #         match_ok => :next,
+  #         match_err => :handle_error
+  #       )
+  #       step :fetch_comment, routes(
+  #         match_ok => :next,
+  #         match_err => :handle_error
+  #       )
+  #
+  #       track :handle_error do
+  #         step :report_to_external_system
+  #         step :write_logs
+  #       end
+  #
+  #       # steps implementations here
+  #     end
+  #
+  # Let's describe how `routes(...)` and `track` DSL methods work.
+  #
+  # Each step has a router. Router is defined by a hash and `router(...)` method itself is
+  # a (almost) shortcut to {Flows::Flow::Router::Custom} constructor. By default each step has the following
+  # router definition:
+  #
+  #     {
+  #       match_ok => :next, # next step is calculated by DSL, this symbol will be substituted in a final router
+  #       match_err => :end  # `:end` means stop execution
+  #     }
+  #
+  # Hash provided in `router(...)` method will override default hash to make a final router.
+  #
+  # Because of symbols with special behavior (`:end`, `:next`) you cannot name your steps or tracks
+  # `:next` or `:end`. And this is totally ok because it is reserved words in Ruby.
+  #
+  # By the way, you can route not only to tracks, but also to steps. And by using `match_ok(status)` and
+  # `match_err(status)` you can have different routes for different statuses of successful or failure results.
+  #
+  # Steps defined inside a track are fully isolated. The simple way is to think about track as a totally
+  # separate pipeline. You have to explicitly enter to it. And explicitly return from it to root-level steps
+  # if you want to continue execution.
+  #
+  # If you feel it's too much verbose to route many steps to the same track you can do something like this:
+  #
+  #     class SafeFetchComment < Flows::SharedContextPipeline
+  #       def self.safe_step(name)
+  #         step name, routes(
+  #           match_ok => :next,
+  #           match_err => :handle_error
+  #         )
+  #       end
+  #
+  #       safe_step :fetch_post
+  #       safe_step :fetch_comment
+  #
+  #       track :handle_error do
+  #         step :report_to_external_system
+  #         step :write_logs
+  #       end
+  #
+  #       # steps implementations here
+  #     end
+  #
+  # ## Simple injecting of nested pipelines
+  #
+  # If you provide some object which responds to `#call` instead of step name - this object will be used as a step body.
+  #
+  #     class SubOperation < Flows::SharedContextPipeline
+  #       step :hello
+  #
+  #       def hello(**)
+  #         ok(data: 'some data')
+  #       end
+  #     end
+  #
+  #     class MainOperation < Flows::SharedContextPipeline
+  #       step :init
+  #       step SubOperation
+  #
+  #       def init(**)
+  #         ok(generated_by_init: true)
+  #       end
+  #     end
+  #
+  #     MainOperation.call
+  #     # => ok(generated_by_init: true, data: 'some data')
+  #
+  # You can use the same object multiple times in the same pipeline:
+  #
+  #     step SubOperation
+  #     step SubOperation
+  #
+  # If you need any input or output processing - refactor such step definition into normal step.
+  #
+  # This way has disadvantage: you cannot route to a such step because it has no explicit name.
+  # To handle this you can use alternative syntax:
+  #
+  #     step :do_something, body: SubOperation
+  #
+  # Same features can be used with `mut_step`.
+  #
+  # This feature is primarily intended to simplify refactoring of big pipelines into smaller ones.
+  #
+  # ## Wrappers
+  #
+  # Sometimes you have to execute some steps inside SQL-transaction or something like this.
+  # Most frameworks allow to do it in the following approach:
+  #
+  #     SQLDataBase.transaction do
+  #       # your steps are executed here
+  #       # special error must be executed to cancel the transaction
+  #     end
+  #
+  # It's impossible to do with just step or track DSL. That's why `wrap` DSL method has been added.
+  # Let's review it on example:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       step :some_preparations
+  #       wrap :in_transaction do
+  #         step :action_a
+  #         step :action_b
+  #       end
+  #
+  #       def in_transaction(ctx, meta, &block)
+  #         result = nil
+  #
+  #         ActiveRecord::Base.transaction do
+  #           result = block.call
+  #
+  #           raise ActiveRecord::Rollback if result.err?
+  #         end
+  #
+  #         result
+  #       end
+  #
+  #       # step implementations here
+  #     end
+  #
+  # `wrap` DSL method receives name and block. Inside block you can define steps and tracks.
+  #
+  # `wrap` makes an isolated track and step structure.
+  # You cannot route between wrapped and unwrapped steps and tracks.
+  # One exception - you can route to the first wrapped step.
+  #
+  # The same wrapper with the same name can be used multiple times in the same operation:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       step :some_preparations
+  #       wrap :in_transaction do
+  #         step :action_a
+  #         step :action_b
+  #       end
+  #       step :some_calculations
+  #       wrap :in_transaction do
+  #         step :action_c
+  #         step :action_d
+  #       end
+  #
+  #       # ...
+  #     end
+  #
+  # Unlike step implementations wrapper implementation has access to a shared meta (can be useful for plugins).
+  #
+  # You may think about steps and tracks inside wrapper as a nested pipeline.
+  # Wrapper implementation receives mutable data context, metadata and block.
+  # Block execution (`block.call`) returns a result object of the executed "nested pipeline".
+  #
+  # When you route to `:end` inside wrapper - you're leaving wrapper, **not** the whole pipeline.
+  #
+  # From the execution perspective wrapper is a single step. The step name is the first wrapped step name.
+  #
+  # `wrap` itself also can have overriden routes table:
+  #
+  #     wrap :in_transaction, routes(match_ok => :next, match_err => :end) do
+  #       # steps...
+  #     end
+  #
+  # Like a step, wrapper implementation must return {Flows::Result}.
+  # Result is processed with the same approach as for normal step.
+  # **Do not modify result returned from block - build a new one if needed.
+  # Otherwise mutation steps can be broken.**
+  #
+  # ## Callbacks and metadata
+  #
+  # You may want to have some logic to execute before all steps, or after all, or before each, or after each.
+  # For example to inject generalized execution process logging.
+  #
+  # These callbacks are executed via `instance_exec` (in the context of instance).
+  #
+  # To achieve this you can use callbacks:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       before_all do |klass, data, meta|
+  #         # you can modify execution data context and metadata here
+  #         # return value will be ignored
+  #       end
+  #
+  #       after_all do |klass, pipeline_result, data, meta|
+  #         # you can modify execution data context and metadata here
+  #         # you must return a final result object here
+  #         # if no modifications needed - just return provided pipeline_result
+  #       end
+  #
+  #       before_each do |klass, step_name, data, meta|
+  #         # you can modify execution data context and metadata here
+  #         # return value will be ignored
+  #       end
+  #
+  #       after_each do |klass, step_name, step_result, data, meta|
+  #         # you can modify execution data context and metadata here
+  #         # return value will be ignored
+  #         #
+  #         # callback executed after context is updated with result data
+  #         # (in the case of normal steps, mutation steps update context directly)
+  #         #
+  #         # DO NOT MODIFY RESULT OBJECT HERE - IT CAN BROKE MUTATION STEPS
+  #       end
+  #     end
+  #
+  # Metadata - is a Hash which is shared between step executions.
+  # This hash becomes metadata of a final {Flows::Result}.
+  #
+  # Metadata is designed to store non-business data such as execution times,
+  # some library specific data, and so on.
+  class SharedContextPipeline
+    extend ::Flows::Plugin::ImplicitInit
+
+    include ::Flows::Result::Helpers
+    extend ::Flows::Result::Helpers
+
+    extend DSL
+
+    def initialize
+      @__flow = self.class.tracks.to_flow(self)
+    end
+
+    # Executes pipeline with provided keyword arguments, returns Result Object.
+    #
+    # @return [Flows::Result]
+    def call(**data) # rubocop:disable Metrics/MethodLength
+      klass = self.class
+      meta = {}
+      context = { data: data, meta: meta, class: klass, instance: self }
+
+      klass.before_all_callbacks.each do |callback|
+        instance_exec(klass, data, meta, &callback)
+      end
+
+      flow_result = @__flow.call(nil, context: context)
+
+      final_result = flow_result.class.new(
+        data,
+        status: flow_result.status,
+        meta: meta
+      )
+
+      klass.after_all_callbacks.reduce(final_result) do |result, callback|
+        instance_exec(klass, result, data, meta, &callback)
+      end
+    end
+  end
+end