flows 0.3.0 → 0.4.0

data/lib/flows/contract/transformer.rb

@@ -0,0 +1,50 @@
+module Flows
+  class Contract
+    # Adds transformation to an existing contract.
+    #
+    # If original contract already has a transform -
+    # final transformation will be composition of original and new one.
+    #
+    # You MUST obey Transformation Laws (see {Contract} documentation for details).
+    #
+    # @example Upcase strings
+    #     up_str = Flows::Contract::Transformer.new(String) { |str| str.upcase }
+    #
+    #     up_str.transform!('megatron')
+    #     # => 'MEGATRON'
+    #
+    #     up_str.transform(:megatron).error
+    #     # => 'must match `String`'
+    #
+    # @example Strip and upcase strings
+    #     strip_str =  Flows::Contract::Transformer.new(String, &:strip)
+    #     up_stip_str = Flows::Contract::Transformer.new(strip_str, &:upcase)
+    #
+    #     up_str.transform!('   megatron   ')
+    #     # => 'MEGATRON'
+    #
+    #     up_str.cast(:megatron).error
+    #     # => 'must match `String`'
+    class Transformer < Contract
+      # @param contract [Contract, Object] in case of non-contract argument {CaseEq} is automatically applied.
+      # @yield [object] transform implementation
+      # @yieldreturn [object] result of transform. Must obey transformation laws.
+      def initialize(contract, &transform_proc)
+        @contract = to_contract(contract)
+        @transform = transform_proc
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        @contract.check!(other)
+      end
+
+      # @see Contract#transform!
+      def transform!(other)
+        @transform.call(
+          @contract.transform!(other)
+        )
+      end
+    end
+  end
+end

data/lib/flows/contract/tuple.rb

@@ -0,0 +1,70 @@
+module Flows
+  class Contract
+    # Makes a contract fixed size array.
+    #
+    # Underlying contracts' transformations are applied.
+    #
+    # @example
+    #     name_age = Flows::Contract::Tuple.new(String, Integer)
+    #
+    #     name_age === ['Roman', 29]
+    #     # => true
+    #
+    #     name_age === [10, 20]
+    #     # => false
+    class Tuple < Contract
+      ARRAY_CONTRACT = CaseEq.new(::Array)
+
+      # @param contracts [Array<Contract, Object>] contract list. {CaseEq} applied to non-contract values.
+      def initialize(*contracts)
+        @contracts = contracts.map(&method(:to_contract))
+      end
+
+      # @see Contract#check!
+      def check!(other)
+        ARRAY_CONTRACT.check!(other)
+        check_length(other)
+
+        errors = collect_errors(other)
+        return true if errors.empty?
+
+        raise Error.new(other, render_errors(other, errors))
+      end
+
+      # @see Contract#transform!
+      def transform!(other)
+        check!(other)
+
+        other.map.with_index do |elem, index|
+          @contracts[index].transform!(elem)
+        end
+      end
+
+      private
+
+      def check_length(other)
+        return if other.length == @contracts.length
+
+        raise Error.new(other, "array length mismatch: must be #{@contracts.length}, got #{other.length}")
+      end
+
+      def collect_errors(other)
+        other.each_with_object({}).with_index do |(elem, errors), index|
+          result = @contracts[index].check(elem)
+
+          errors[index] = result.error if result.err?
+        end
+      end
+
+      def render_errors(other, errors)
+        errors.map do |index, err|
+          elem = other[index]
+          merge_nested_errors(
+            "array element `#{elem.inspect}` with index #{index} is invalid:",
+            err
+          )
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/flows/flow.rb

@@ -1,18 +1,86 @@
+require_relative 'flow/node'
+require_relative 'flow/router'
+
 module Flows
-  # Simple sequential flow
+  # Abstraction for build [deterministic finite-state machine](https://www.freecodecamp.org/news/state-machines-basics-of-computer-science-d42855debc66/)-like
+  # execution objects.
+  #
+  # Let's refer to 'deterministic finite-state machine' as DFSM.
+  #
+  # It's NOT an implementation of DFSM. It just shares a lot of
+  # structural ideas. You can also think about {Flow} as an [oriented graph](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)#Oriented_graph),
+  # where:
+  #
+  # * you have the one and only one initial node
+  # * you start execution from the initial node
+  # * after node execution your are going to some next node or stop execution.
+  #
+  # And edges formed by possible next nodes.
+  #
+  # DFSM has a very important property:
+  #
+  # > From any state, there is only one transition for any allowed input.
+  #
+  # So, we represent DFSM states as {Node}s. Each {Node}, basing on input (input includes execution context also)
+  # performs some side effects and returns output and next {Node} name (DFSM state).
+  #
+  # Side effects here can be spitted into two types:
+  #
+  # * modification of execution context
+  # * rest of them: working with 3rd party libraries, printing to STDOUT, etc.
+  #
+  # Final state represented by special symbol `:end`.
+  #
+  # @note You should not use {Flow} in your business code. It's designed to be underlying execution engine
+  #   for high-level abstractions. In other words - it's for libraries, not applications.
+  #
+  # @example Calculates sum of elements in array. If sum more than 10 prints 'Big', otherwise prints 'Small'.
+  #
+  #     flow = Flows::Flow.new(
+  #       start_node: :sum_list,
+  #       node_map: {
+  #         sum_list: Flows::Flow::Node.new(
+  #           body: ->(list) { list.sum },
+  #           router: Flows::Flow::Router::Custom.new(
+  #             ->(x) { x > 10 } => :print_big,
+  #             ->(x) { x <= 10 } => :print_small
+  #           )
+  #         ),
+  #         print_big: Flows::Flow::Node.new(
+  #           body: ->(_) { puts 'Big' },
+  #           router: Flows::Flow::Router::Custom.new(
+  #             nil => :end # puts returns nil.
+  #           )
+  #         ),
+  #         print_small: Flows::Flow::Node.new(
+  #           body: ->(_) { puts 'Small' },
+  #           router: Flows::Flow::Router::Custom.new(
+  #             nil => :end # puts returns nil.
+  #           )
+  #         )
+  #       }
+  #     )
+  #
+  #     flow.call([1, 2, 3, 4, 5], context: {})
+  #     # prints 'Big' and returns nil
   class Flow
-    def initialize(start_node:, nodes:)
+    # @param start_node [Symbol] name of the entry node.
+    # @param node_map [Hash<Symbol, Node>] keys are node names, values are nodes.
+    def initialize(start_node:, node_map:)
       @start_node = start_node
-      @nodes = Hash[
-        nodes.map { |node| [node.name, node] }
-      ]
+      @node_map = node_map
     end
 
+    # Executes a flow.
+    #
+    # @param input [Object] initial input
+    # @param context [Hash] mutable execution context
+    # @return [Object] execution result
     def call(input, context:)
       current_node_name = @start_node
 
-      while current_node_name != :term
-        input, current_node_name = @nodes[current_node_name].call(input, context: context)
+      while current_node_name != :end
+        input, current_node_name = @node_map[current_node_name].call(input, context: context)
       end
 
       input

data/lib/flows/flow/node.rb

@@ -0,0 +1,131 @@
+module Flows
+  class Flow
+    # Node is the main building block for {Flow}.
+    #
+    # Node is an object which can be executed ({#call}) with some input and execution context
+    # and produce output and the next route.
+    #
+    # Node execution consists of 4 sequential parts:
+    #
+    # 1. Pre-processor execution (if pre-processor defined).
+    #   Allows to modify input which will be transferred to the node's body.
+    #   Allows to modify execution context.
+    #   Has access to the node's metadata.
+    # 2. Body execution. Body is a lambda which receives input and returns output.
+    # 3. Post-processor execution (if post-processor defined).
+    #   Allows to modify output which was produced by the node's body.
+    #   Allows to modify execution context.
+    #   Has access to the node's metadata.
+    # 4. {Router} execution to determine next node name.
+    #
+    # Execution result consists of 2 parts: output and next route.
+    #
+    # ## Pre/postprocessors
+    #
+    # Both have similar signatures:
+    #
+    #     preprocessor = lambda do |node_input, context, meta|
+    #       # returns input for the BODY
+    #       # format [args, kwargs]
+    #     end
+    #
+    #     postprocessor = lambda do |body_output, context, meta|
+    #       # returns output of the NODE
+    #     end
+    #
+    # Types for body input and `body_output` is under your control.
+    # It allows you to adopt node for very different kinds of bodies.
+    #
+    # Without pre-processor `input` from {#call} becomes the first and single argument for the body.
+    # In the cases when your body expects several arguments or keyword arguments
+    # you must use pre-processor. Pre-processor returns array of 2 elements -
+    # arguments and keyword arguments. There are some examples of a post-processor return
+    # and the corresponding body call:
+    #
+    #     [[1, 2], {}]
+    #     body.call(1, 2)
+    #
+    #     [[], { a: 1, b: 2}]
+    #     body.call(a: 1, b: 2)
+    #
+    #     [[1, 2], { x: 3, y: 4 }]
+    #     body.call(1, 2, x: 3, y: 4)
+    #
+    #     [[1, 2, { 'a' => 3}], {}]
+    #     body.call(1, 2, 'a' => 3)
+    #
+    # There were simpler solutions, but after [this](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
+    # it's the most clear one.
+    #
+    # `context` and `meta` are expected to be Ruby Hashes.
+    #
+    # * `context` - is an execution context and it's mutable.
+    #   Execution context is defined outside and not controlled by a node.
+    #   Therefore, your mutations will be visible after a node execution.
+    # * `meta` - is node execution metadata and it's immutable, read only and node-local.
+    #   Designed to store purely technical information like
+    #   node name or, maybe, some dependency injection entities.
+    #
+    # ## Metadata and node names
+    #
+    # As you may see any Node instance has no name.
+    # It's done for the reason: name is not part of a node;
+    # it allows to use the same node instance under different names.
+    # In the most cases we don't need this, but it's nice to have such ability.
+    #
+    # In some cases we want to have a node name inside pre/postprocessors.
+    # For such cases `meta` is the right place to store node name:
+    #
+    #     Flows::Flow::Node.new(body: body, router: router, meta: { name: :step_a })
+    #
+    # @see Flows::Flow some examples here
+    class Node
+      # Node metadata, a frozen Ruby Hash.
+      attr_reader :meta
+
+      # @param body [Proc] node body
+      # @param router [Router] node router
+      # @param meta [Hash] node metadata
+      # @param preprocessor [Proc, nil] pre-processor for the node's body
+      # @param postprocessor [Proc, nil] post-processor for the node's body
+      def initialize(body:, router:, meta: {}, preprocessor: nil, postprocessor: nil)
+        @body = body
+        @router = router
+
+        @meta = meta.freeze
+
+        @preprocessor = preprocessor
+        @postprocessor = postprocessor
+      end
+
+      # Executes the node.
+      #
+      # @param input [Object] input for a node. In the context of {Flow}
+      #   it's initial input or output of the previously executed node.
+      #
+      # @param context [Hash] execution context. In case of {Flow}
+      #   shared between node executions.
+      #
+      # @return [Array<(Object, Symbol)>] output of a node and next route.
+      #
+      # `:reek:TooManyStatements` is disabled for this method because even
+      # one more call to a private method impacts performance here.
+      def call(input, context:)
+        output =
+          if @preprocessor
+            args, kwargs = @preprocessor.call(input, context, @meta)
+
+            # https://bugs.ruby-lang.org/issues/14415
+            kwargs.empty? ? @body.call(*args) : @body.call(*args, **kwargs)
+          else
+            @body.call(input)
+          end
+        output = @postprocessor.call(output, context, @meta) if @postprocessor
+
+        route = @router.call(output)
+
+        [output, route]
+      end
+    end
+  end
+end

data/lib/flows/flow/router.rb

@@ -0,0 +1,25 @@
+module Flows
+  class Flow
+    # @abstract
+    #
+    # Node router: defines rules to calculate next {Node} to execute inside a particular {Flow}.
+    #
+    # Router receives {Flows::Result} Object, execution context and execution metadata.
+    # Basing on this information a router must decide what to execute next or
+    # decide to stop execution of a flow.
+    #
+    # If router returns `:end` - it stops an execution process.
+    #
+    # @!method call( result )
+    #   @abstract
+    #   @param result [Flows::Result] Result Object, output of a {Node} execution.
+    #   @return [Symbol] name of the next node or  a special symbol `:end`.
+    #   @raise [NoRouteError] if cannot determine a route.
+    class Router
+    end
+  end
+end
+
+require_relative 'router/errors'
+require_relative 'router/simple'
+require_relative 'router/custom'

data/lib/flows/flow/router/custom.rb

@@ -0,0 +1,54 @@
+module Flows
+  class Flow
+    class Router
+      # Router with custom rules.
+      #
+      # Expects routes table in a special format:
+      #
+      #     {
+      #       ->(x) { x.ok? } => :step_a,
+      #       ->(x) { x.err? && x.status == :validation_error } => :end,
+      #       ->(x) { x.err? } => :handle_error
+      #     }
+      #
+      # Yes, it's confusing. But by including {Flows::Result::Helpers} you can (and should) rewrite it like this:
+      #
+      #     {
+      #       match_ok => :route_a,                 # on success go to step_a
+      #       match_err(:validation_error) => :end, # on failure with status `:validation_error` - stop execution
+      #       match_err => :handle_error            # on any other failure go to the step handle_error
+      #     }
+      #
+      # So, your routes table is an ordered set of pairs `predicate => route` in form of Ruby Hash.
+      #
+      # Any time you writing a router table you can imagine that you're writing `case`:
+      #
+      #     case step_result
+      #     when match_ok then :route_a                  # on success go to step_a
+      #     when match_err(:validation_error) then :end  # on failure with status `:validation_error` - stop execution
+      #     when match_err then :handle_error            # on any other failure go to the step handle_error
+      #     end
+      #
+      # @see Flows::Flow some examples here
+      #
+      # @see Flows::Flow::Node Pre/postprocessing of data must be done inside Node.
+      class Custom < Router
+        # Creates a new custom router from a route table.
+        #
+        # @param routes [Hash<Proc, Symbol>] route table.
+        def initialize(routes)
+          @routes = routes
+        end
+
+        # @see Flows::Flow::Router#call
+        def call(result)
+          @routes.each_pair do |predicate, route|
+            return route if predicate === result # rubocop:disable Style/CaseEquality
+          end
+
+          raise NoRouteError, "no route found for: `#{result.inspect}`"
+        end
+      end
+    end
+  end
+end

data/lib/flows/flow/router/errors.rb

@@ -0,0 +1,11 @@
+module Flows
+  class Flow
+    class Router
+      # Base class for {Flows::Router} error.
+      class Error < Flows::Error; end
+
+      # Raised when no route found basing on provided data.
+      class NoRouteError < Error; end
+    end
+  end
+end

data/lib/flows/flow/router/simple.rb

@@ -0,0 +1,20 @@
+module Flows
+  class Flow
+    class Router
+      # Router with static paths for successful and failure results.
+      class Simple < Router
+        # @param success_route [Symbol] route for any successful results.
+        # @param failure_route [Symbol] route for any failure results.
+        def initialize(success_route, failure_route)
+          @success_route = success_route
+          @failure_route = failure_route
+        end
+
+        # @see Flows::Flow::Router#call
+        def call(result)
+          result.ok? ? @success_route : @failure_route
+        end
+      end
+    end
+  end
+end