flows 0.3.0 → 0.4.0

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,216 @@
+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/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
+  #
+  # ## Callbacks
+  #
+  # 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.
+  # To achieve this you can use callbacks:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       before_all do |klass, context|
+  #         # you can modify execution context here
+  #         # return value will be ignored
+  #       end
+  #
+  #       after_all do |klass, pipeline_result|
+  #         # you must provide final result object for pipeline here
+  #         # if no modifications needed - just return provided pipeline_result
+  #       end
+  #
+  #       before_each do |klass, step_name, context|
+  #         # you can modify context here
+  #         # return value will be ignored
+  #       end
+  #
+  #       after_each do |klass, step_name, context, step_result|
+  #         # you can modify context here
+  #         # you must not modify step_result
+  #         # context already has data from step_result at the moment of execution
+  #         # return value will be ignored
+  #       end
+  #     end
+  class SharedContextPipeline
+    extend ::Flows::Plugin::ImplicitInit
+
+    include ::Flows::Result::Helpers
+    extend ::Flows::Result::Helpers
+
+    extend DSL
+
+    def initialize
+      klass = self.class
+      tracks = klass.tracks
+
+      raise NoStepsError, klass if tracks.main_track_empty?
+
+      @__flow = Flows::Flow.new(
+        start_node: tracks.first_step_name,
+        node_map: tracks.to_node_map(self)
+      )
+    end
+
+    # Executes pipeline with provided keyword arguments, returns Result Object.
+    #
+    # @return [Flows::Result]
+    def call(**kwargs) # rubocop:disable Metrics/MethodLength
+      klass = self.class
+      context = { data: kwargs, class: klass }
+
+      klass.before_all_callbacks.each do |callback|
+        callback.call(klass, context[:data])
+      end
+
+      flow_result = @__flow.call(nil, context: context)
+
+      final_result = flow_result.class.new(
+        context[:data],
+        status: flow_result.status,
+        meta: { last_step: context[:last_step] }
+      )
+
+      klass.after_all_callbacks.reduce(final_result) do |result, callback|
+        callback.call(klass, result)
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/dsl.rb

@@ -0,0 +1,63 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    module DSL
+      attr_reader :tracks
+      attr_reader :before_all_callbacks
+      attr_reader :after_all_callbacks
+      attr_reader :before_each_callbacks
+      attr_reader :after_each_callbacks
+
+      DEFAULT_ROUTER_DEF = RouterDefinition.new(
+        Flows::Result::Ok => :next,
+        Flows::Result::Err => :end
+      )
+
+      Flows::Util::InheritableSingletonVars::DupStrategy.call(
+        self,
+        '@tracks' => TrackList.new,
+        '@before_all_callbacks' => [],
+        '@after_all_callbacks' => [],
+        '@before_each_callbacks' => [],
+        '@after_each_callbacks' => []
+      )
+
+      def step(name, router_def = DEFAULT_ROUTER_DEF, &lambda)
+        tracks.add_step(name: name, lambda: lambda, router_def: router_def)
+      end
+
+      def mut_step(name, router_def = DEFAULT_ROUTER_DEF, &lambda)
+        tracks.add_mutation_step(name: name, lambda: lambda, router_def: router_def)
+      end
+
+      def track(name, &block)
+        track_before = tracks.current_track
+
+        tracks.switch_track(name)
+        instance_exec(&block)
+        tracks.switch_track(track_before)
+      end
+
+      # :reek:UtilityFunction is allowed here
+      def routes(routes_def)
+        RouterDefinition.new(routes_def)
+      end
+
+      def before_all(&callback)
+        before_all_callbacks << callback
+      end
+
+      def after_all(&callback)
+        after_all_callbacks << callback
+      end
+
+      def before_each(&callback)
+        before_each_callbacks << callback
+      end
+
+      def after_each(&callback)
+        after_each_callbacks << callback
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/errors.rb

@@ -0,0 +1,17 @@
+module Flows
+  class SharedContextPipeline
+    # Base error class for {SharedContextPipeline} errors.
+    class Error < StandardError; end
+
+    # Raised when initializing {SharedContextPipeline} with no steps.
+    class NoStepsError < Error
+      def initialize(klass)
+        @klass = klass
+      end
+
+      def message
+        "No steps defined for main track in #{@klass}"
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/mutation_step.rb

@@ -0,0 +1,31 @@
+module Flows
+  class SharedContextPipeline
+    EMPTY_HASH = {}.freeze
+    EMPTY_OK = Flows::Result::Ok.new(nil).freeze
+    EMPTY_ERR = Flows::Result::Err.new(nil).freeze
+
+    # @api private
+    class MutationStep < Step
+      NODE_PREPROCESSOR = lambda do |_input, context, meta|
+        context[:last_step] = meta[:name]
+
+        context[:class].before_each_callbacks.each do |callback|
+          callback.call(context[:class], meta[:name], context[:data])
+        end
+
+        [[context[:data]], EMPTY_HASH]
+      end
+
+      NODE_POSTPROCESSOR = lambda do |output, context, meta|
+        case output
+        when Flows::Result then output
+        else output ? EMPTY_OK : EMPTY_ERR
+        end.tap do |result|
+          context[:class].after_each_callbacks.each do |callback|
+            callback.call(context[:class], meta[:name], context[:data], result)
+          end
+        end
+      end
+    end
+  end
+end