flows 0.3.0 → 0.4.0

data/lib/flows/plugin/output_contract/dsl.rb

@@ -0,0 +1,36 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # DSL for OutputContract plugin.
+      module DSL
+        # Hash of contracts for successful results.
+        attr_reader :success_contracts
+
+        # Hash of contracts for failure results.
+        attr_reader :failure_contracts
+
+        Flows::Util::InheritableSingletonVars::DupStrategy.call(
+          self,
+          '@success_contracts' => {},
+          '@failure_contracts' => {}
+        )
+
+        # Defines a contract for a successful result with specific status.
+        #
+        # @param status [Symbol] Corresponding result status.
+        # @param contract_block [Proc] This block will be passed to {Contract.make} to get a contract.
+        def success_with(status, &contract_block)
+          success_contracts[status] = Flows::Contract.make(&contract_block)
+        end
+
+        # Defines a contract for a failure result with specific status.
+        #
+        # @param status [Symbol] Corresponding result status.
+        # @param contract_block [Proc] This block will be passed to {Contract.make} to get a contract.
+        def failure_with(status, &contract_block)
+          failure_contracts[status] = Flows::Contract.make(&contract_block)
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/output_contract/errors.rb

@@ -0,0 +1,74 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # Base error class for output contract errors.
+      class Error < StandardError; end
+
+      # Raised when no single contract for successful results is defined
+      class NoContractError < Error
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def message
+          "No single success contract defined for #{@klass}"
+        end
+      end
+
+      # Raised when result's data violates contract
+      class ContractError < Error
+        def initialize(klass, result, error)
+          @klass = klass
+          @result = result
+          @error = error
+        end
+
+        def message
+          shifted_error = @error.split("\n").map { |str| '  ' + str }.join("\n")
+
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          "#{shifted_error}"
+        end
+      end
+
+      # Raised when no contract found for result
+      class StatusError < Error
+        def initialize(klass, result, allowed_statuses)
+          @klass = klass
+          @result = result
+          @allowed_statuses = allowed_statuses
+        end
+
+        def message
+          allowed_statuses_str = @allowed_statuses.map { |st| "`#{st.inspect}`" }.join(', ')
+
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          "  has unexpected status `#{@result.status.inspect}`\n" \
+          "  allowed statuses for `#{@result.class}` are: #{allowed_statuses_str}"
+        end
+      end
+
+      # Raised when not a result object returned
+      class ResultTypeError < Error
+        def initialize(klass, result)
+          @klass = klass
+          @result = result
+        end
+
+        def message
+          "Output contract for #{@klass} is violated.\n" \
+          "Result:\n" \
+          "  `#{@result.inspect}`\n" \
+          "Contract Error:\n" \
+          '  result must be instance of `Flows::Result`'
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/output_contract/wrapper.rb

@@ -0,0 +1,53 @@
+module Flows
+  module Plugin
+    module OutputContract
+      # Contains wrappers for initializer and `#call` methods.
+      #
+      # @api private
+      module Wrapper
+        def initialize(*args, &block)
+          super(*args, &block)
+          klass = self.class
+          raise NoContractError, klass if klass.success_contracts.empty?
+        end
+
+        def call(*args, &block)
+          result = super(*args, &block)
+          klass = self.class
+
+          contract = Util.contract_for(klass, result)
+
+          Util.transform_result(klass, contract, result)
+
+          result
+        end
+
+        # Helper methods for {Wrapper} are extracted to this
+        # module as singleton methods to not pollute user classes.
+        #
+        # @api private
+        module Util
+          class << self
+            def contract_for(klass, result)
+              raise ResultTypeError.new(klass, result) unless result.is_a?(Flows::Result)
+
+              status = result.status
+              contracts = result.ok? ? klass.success_contracts : klass.failure_contracts
+
+              contracts[status] || raise(StatusError.new(klass, result, contracts.keys))
+            end
+
+            def transform_result(klass, contract, result)
+              data = result.send(:data)
+
+              transformed_result = contract.transform(data)
+              raise ContractError.new(klass, result, transformed_result.error) if transformed_result.err?
+
+              result.send(:'data=', transformed_result.unwrap)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/railway.rb

@@ -1,51 +1,154 @@
-require_relative './railway/errors'
-
-require_relative './railway/dsl'
-require_relative './railway/builder'
-require_relative './railway/executor'
-
-require_relative './implicit_build'
+require_relative 'railway/errors'
+require_relative 'railway/step'
+require_relative 'railway/step_list'
+require_relative 'railway/dsl'
 
 module Flows
-  # Railway DSL
-  module Railway
-    def self.included(mod)
-      mod.extend ::Flows::Railway::DSL
-      mod.extend ::Flows::ImplicitBuild
-    end
+  # Flows::Railway is an implementation of a Railway Programming pattern.
+  #
+  # You may read about this pattern in the following articles:
+  #
+  # * [Programming on rails: Railway Oriented Programming](http://sandordargo.com/blog/2017/09/27/railway_oriented_programming).
+  #   It's not about Ruby on Rails.
+  # * [Railway Oriented Programming: A powerful Functional Programming pattern](https://medium.com/@naveenkumarmuguda/railway-oriented-programming-a-powerful-functional-programming-pattern-ab454e467f31)
+  # * [Railway Oriented Programming in Elixir with Pattern Matching on Function Level and Pipelining](https://medium.com/elixirlabs/railway-oriented-programming-in-elixir-with-pattern-matching-on-function-level-and-pipelining-e53972cede98)
+  #
+  # Let's review a simple task and solve it using {Flows::Railway}:
+  #
+  # * you have to get a user by ID
+  # * get all user's blog posts
+  # * and convert it to an array of HTML-strings
+  #
+  # In such situation, we have to implement three parts of our task and compose it into something we can call,
+  # for example, from a Rails controller.
+  # Also, the first and third steps may fail (user not found, conversion to HTML failed).
+  # And if a step failed - we have to return failure info immediately.
+  #
+  #     class RenderUserBlogPosts < Flows::Railway
+  #       step :fetch_user
+  #       step :get_blog_posts
+  #       step :convert_to_html
+  #
+  #       def fetch_user(id:)
+  #         user = User.find_by_id(id)
+  #         user ? ok(user: user) : err(message: "User #{id} not found")
+  #       end
+  #
+  #       def get_blog_posts(user:)
+  #         ok(posts: User.posts)
+  #       end
+  #
+  #       def convert_to_html(posts:)
+  #         posts_html = post.map(&:text).map do |text|
+  #           html = convert(text)
+  #           return err(message: "cannot convert to html: #{text}")
+  #         end
+  #
+  #         ok(posts_html: posts_html)
+  #       end
+  #
+  #       private
+  #
+  #       # returns String or nil
+  #       def convert(text)
+  #         # some implementation here
+  #       end
+  #     end
+  #
+  #     RenderUserBlogPosts.call(id: 10)
+  #     # result object returned
+  #
+  # Let's describe how it works.
+  #
+  # First of all you have to inherit your railway from `Flows::Railway`.
+  #
+  # Then you must define list of your steps using `step` DSL method.
+  # Steps will be executed in the given order.
+  #
+  # The you have to provide step implementations. It should be done by using
+  # public methods with the corresponding names.
+  # _Please write your step implementations in the step definition order._
+  # _It will make your railway easier to read by other engineers._
+  #
+  # Each step should return {Flows::Result} Object.
+  # If Result Object is successful - next step will be called or
+  # this object becomes a railway execution result in the case of last step.
+  # If Result Object is failure - this object becomes execution result immediately.
+  #
+  # Place all the helpers methods in the private section of the class.
+  #
+  # To help with writing methods {Flows::Result::Helpers} is already included.
+  #
+  # {Railway} is a very simple but not very flexible abstraction.
+  # It has a good performance and a small overhead.
+  #
+  # ## `Flows::Railway` execution rules
+  #
+  # * steps execution happens from the first to the last step
+  # * input arguments (`Railway#call(...)`) becomes the input of the first step
+  # * each step should return Result Object (`Flows::Result::Helpers` already included)
+  # * if step returns failed result - execution stops and failed Result Object returned from Railway
+  # * if step returns successful result - result data becomes arguments of the following step
+  # * if the last step returns successful result - it becomes a result of a Railway execution
+  #
+  # ## Step definitions
+  #
+  # Two ways of step definition exist. First is by using an instance method:
+  #
+  #     step :do_something
+  #
+  #     def do_something(**arguments)
+  #       # some implementation
+  #       # Result Object as return value
+  #     end
+  #
+  # Second is by using lambda:
+  #
+  #     step :do_something, ->(**arguments) { ok(some: 'data') }
+  #
+  # Definition with lambda exists for debugging/testing purposes, it has higher priority than method implementation.
+  # _Do not use lambda implementations for your business logic!_
+  #
+  # __Think about Railway as about small book: you have a "table of contents"
+  # in a form of step definitions and actual "chapters" in the same order
+  # in a form of public methods. And your private methods becomes something like "appendix".__
+  #
+  # ## Advanced initialization
+  #
+  # In a simple case you can just invoke `YourRailway.call(..)`. Under the hood it works like `.new.call(...)`,
+  # but `.new` part will be executed ones and memoized ({Flows::Plugin::ImplicitInit} included).
+  #
+  # You can include {Flows::Plugin::DependencyInjector} into your Railway and in this case you will
+  # need to do `.new(...).call` manually.
+  class Railway
+    extend ::Flows::Plugin::ImplicitInit
 
     include ::Flows::Result::Helpers
+    extend ::Flows::Result::Helpers
 
-    def initialize(method_source: nil, deps: {})
-      _flows_do_checks
+    extend DSL
 
-      flow = _flows_make_flow(method_source || self, deps)
-      @_flows_executor = _flows_make_executor(flow)
-    end
+    def initialize
+      klass = self.class
+      steps = klass.steps
 
-    def call(**params)
-      @_flows_executor.call(**params)
-    end
+      raise NoStepsError, klass if steps.empty?
 
-    private
-
-    def _flows_do_checks
-      raise NoStepsError if self.class.steps.empty?
+      @__flows_railway_flow = Flows::Flow.new(
+        start_node: steps.first_step_name,
+        node_map: steps.to_node_map(self)
+      )
     end
 
-    def _flows_make_flow(method_source, deps)
-      ::Flows::Railway::Builder.new(
-        steps: self.class.steps,
-        method_source: method_source,
-        deps: deps
-      ).call
-    end
+    # Executes Railway with provided keyword arguments, returns Result Object
+    #
+    # @return [Flows::Result]
+    def call(**kwargs)
+      context = {}
 
-    def _flows_make_executor(flow)
-      ::Flows::Railway::Executor.new(
-        flow: flow,
-        class_name: self.class.name
-      )
+      @__flows_railway_flow.call(ok(**kwargs), context: context).tap do |result|
+        result.meta[:last_step] = context[:last_step]
+      end
     end
   end
 end

data/lib/flows/railway/dsl.rb

@@ -1,27 +1,16 @@
 module Flows
-  module Railway
-    # DSL methods for Railway
+  class Railway
+    # @api private
     module DSL
       attr_reader :steps
 
-      def self.extended(mod, steps = nil)
-        mod.instance_variable_set(:@steps, steps || [])
+      Flows::Util::InheritableSingletonVars::DupStrategy.call(
+        self,
+        '@steps' => StepList.new
+      )
 
-        mod.class_exec do
-          def self.inherited(subclass)
-            ::Flows::Railway::DSL.extended(subclass, steps.map(&:dup))
-            super
-          end
-        end
-      end
-
-      include Flows::Result::Helpers
-
-      def step(name, custom_body = nil)
-        @steps << {
-          name: name,
-          custom_body: custom_body
-        }
+      def step(name, lambda = nil)
+        steps.add(name: name, lambda: lambda)
       end
     end
   end

data/lib/flows/railway/errors.rb

@@ -1,21 +1,17 @@
 module Flows
-  module Railway
-    # rubocop:disable Style/Documentation
-    class NoStepsError < ::Flows::Error
-      def message
-        'No steps defined'
-      end
-    end
+  class Railway
+    # Base class for Railway errors
+    class Error < StandardError; end
 
-    class NoStepImplementationError < ::Flows::Error
-      def initialize(step_name)
-        @step_name = step_name
+    # Raised when initializing Railway with no steps
+    class NoStepsError < Error
+      def initialize(klass)
+        @klass = klass
       end
 
       def message
-        "Missing step definition: #{@step_name}"
+        "No steps defined for #{@klass}"
       end
     end
-    # rubocop:enable Style/Documentation
   end
 end

data/lib/flows/railway/step.rb

@@ -0,0 +1,24 @@
+module Flows
+  class Railway
+    # @api private
+    Step = Struct.new(:name, :lambda, :next_step, keyword_init: true) do
+      NODE_PREPROCESSOR = ->(input, _, _) { [[], input.unwrap] }
+
+      NODE_POSTPROCESSOR = lambda do |output, context, meta|
+        context[:last_step] = meta[:name]
+
+        output
+      end
+
+      def to_node(method_source)
+        Flows::Flow::Node.new(
+          body: lambda || method_source.method(name),
+          router: Flows::Flow::Router::Simple.new(next_step || :end, :end),
+          meta: { name: name },
+          preprocessor: NODE_PREPROCESSOR,
+          postprocessor: NODE_POSTPROCESSOR
+        )
+      end
+    end
+  end
+end