flows 0.1.0 → 0.5.1

data/lib/flows/plugin/profiler/report/flat/method_report.rb

@@ -0,0 +1,81 @@
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        class Flat < Tree
+          # @api private
+          class MethodReport
+            attr_reader :root_node
+            attr_reader :calculated_nodes
+
+            def initialize(root_node, *calculated_nodes)
+              @root_node = root_node
+              @calculated_nodes = calculated_nodes
+
+              raise 'no single node provided' if calculated_nodes.empty?
+              raise 'calculated_nodes must be about the same subject' unless nodes_have_same_subject
+            end
+
+            def subject
+              @subject ||= calculated_nodes.first.subject
+            end
+
+            def count
+              @count ||= calculated_nodes.map(&:count).sum
+            end
+
+            def total_self_ms
+              @total_self_ms ||= calculated_nodes.map(&:total_self_ms).sort.sum
+            end
+
+            def total_self_percentage
+              @total_self_percentage ||= calculated_nodes
+                                         .map { |node| node.total_self_percentage(root_node) }
+                                         .sort
+                                         .sum
+            end
+
+            def avg_self_ms
+              @avg_self_ms ||= total_self_ms / count
+            end
+
+            def direct_subcalls
+              @direct_subcalls ||= calculated_nodes
+                                   .flat_map { |node| node.children.map(&:subject) }
+                                   .uniq
+            end
+
+            def to_h
+              @to_h ||= {
+                subject: subject,
+                count: count,
+                total_self_ms: total_self_ms,
+                total_self_percentage: total_self_percentage,
+                avg_self_ms: avg_self_ms,
+                direct_subcalls: direct_subcalls
+              }
+            end
+
+            def to_s
+              [
+                '',
+                "- #{subject} -",
+                "called:                      #{count} time(s)",
+                "total self execution time:   #{total_self_ms.truncate(2)}ms",
+                "total self percentage:       #{total_self_percentage.truncate(2)}%",
+                "average self execution time: #{avg_self_ms.truncate(2)}ms",
+                "direct subcalls:             #{direct_subcalls.join(', ')}"
+              ]
+            end
+
+            private
+
+            def nodes_have_same_subject
+              calculated_nodes.all? { |node| node.subject == subject }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/report/raw.rb

@@ -0,0 +1,15 @@
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        # Raw report. Preserves events as is.
+        class Raw < Report
+          # @see Report#to_s
+          def to_s
+            raw_data.map(&:to_s).join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/report/tree.rb

@@ -0,0 +1,98 @@
+require_relative 'tree/node'
+require_relative 'tree/calculated_node'
+
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        # Tree report. Merges similar calls, saves execution structure (who called whom).
+        #
+        # @example
+        #     Flows::Plugin::Profiler.profile(:tree) do
+        #       # some code here
+        #     end
+        #
+        #     puts Flows::Plugin::Profiler.last_report
+        class Tree < Report
+          # Returns tree report as Ruby data structs.
+          #
+          # @return [Array<Hash>] tree report.
+          #
+          # @example
+          #   [
+          #     {
+          #       subject: 'MyClass#call',
+          #       count: 2,
+          #       total_ms: 100.0,
+          #       total_self_ms: 80.0,
+          #       total_self_percentage: 80.0,
+          #       avg_ms: 50.0,
+          #       avg_self_ms: 40.0,
+          #       nested: [
+          #         {
+          #           subject: 'MyClass#another_method',
+          #           count: 1,
+          #           total_ms: 20.0,
+          #           total_self_ms: 20.0,
+          #           total_self_percentage: 20.0,
+          #           avg_ms: 20.0,
+          #           avg_self_ms: 20.0,
+          #           nested: []
+          #         }
+          #       ]
+          #     }
+          #   ]
+          def to_a
+            root_calculated_node.children.map { |node| node.to_h(root_calculated_node) }
+          end
+
+          def add(*)
+            forget_memoized_values
+            super
+          end
+
+          def to_s
+            root_calculated_node.children.map { |node| node.to_s(root_calculated_node) }.join
+          end
+
+          private
+
+          def forget_memoized_values
+            @root_node = nil
+            @root_calculated_node = nil
+          end
+
+          def root_calculated_node
+            @root_calculated_node ||= CalculatedNode.new(root_node)
+          end
+
+          def root_node
+            @root_node ||= Node.new(subject: :ROOT).tap do |root_node|
+              events.each_with_object([root_node]) do |event, node_path|
+                current_node = node_path.last
+
+                case event
+                when StartEvent then process_start_event(node_path, current_node, event)
+                when FinishEvent then process_finish_event(node_path, current_node, event)
+                end
+              end
+            end
+          end
+
+          # :reek:UtilityFunction
+          def process_start_event(node_path, current_node, event)
+            node_path << current_node[event.subject]
+          end
+
+          # :reek:UtilityFunction :reek:FeatureEnvy
+          def process_finish_event(node_path, current_node, event)
+            raise 'Invalid profiling events detected' if event.subject != current_node.subject
+
+            current_node.register_execution(event.data)
+            node_path.pop
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/report/tree/calculated_node.rb

@@ -0,0 +1,116 @@
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        class Tree < Report
+          # @api private
+          class CalculatedNode
+            MICROSECONDS_IN_MILLISECOND = 1000.0
+
+            attr_reader :children
+
+            def initialize(node)
+              @node = node
+              @children = node.children
+                              .map { |child| self.class.new(child) }
+                              .sort_by(&:total_ms)
+                              .reverse
+            end
+
+            def subject
+              @node.subject
+            end
+
+            def count
+              @count ||= @node.executions.count
+            end
+
+            def total_ms
+              @total_ms ||= @node.executions.sort.sum / MICROSECONDS_IN_MILLISECOND
+            end
+
+            def avg_ms
+              @avg_ms ||= total_ms / count
+            end
+
+            def children_ms
+              @children_ms ||= children.map(&:total_ms).sort.sum
+            end
+
+            def total_self_ms
+              @total_self_ms ||= total_ms - children_ms
+            end
+
+            def total_self_percentage(root_node = self)
+              @total_self_percentage ||= total_self_ms / root_node.children_ms * 100.0
+            end
+
+            def total_percentage(root_node = self)
+              @total_percentage ||= total_ms / root_node.children_ms * 100.0
+            end
+
+            def avg_self_ms
+              @avg_self_ms ||= total_self_ms / count
+            end
+
+            def to_h(root_node = self) # rubocop:disable Metrics/MethodLength
+              @to_h ||= {
+                subject: subject,
+                count: count,
+                total_ms: total_ms,
+                total_percentage: total_percentage(root_node),
+                total_self_ms: total_self_ms,
+                total_self_percentage: total_self_percentage(root_node),
+                avg_ms: avg_ms,
+                avg_self_ms: avg_self_ms,
+                nested: children.map { |node| node.to_h(root_node) }
+              }
+            end
+
+            def to_s(root_node = self)
+              @to_s ||= (base_text_list(root_node) + childeren_text_list(root_node)).join("\n")
+            end
+
+            # :reek:DuplicateMethodCall
+            # :reek:NestedIterators
+            def group_by_subject
+              @group_by_subject ||= (
+                [children.group_by(&:subject)] + children.map(&:group_by_subject)
+              ).each_with_object({}) do |group, result|
+                group.each do |subject, nodes|
+                  result[subject] ||= []
+                  result[subject] += nodes
+                end
+              end
+            end
+
+            private
+
+            def base_text_list(root_node) # rubocop:disable Metrics/MethodLength
+              [
+                '',
+                "- #{subject} -",
+                "called:                      #{count} time(s)",
+                "total execution time:        #{total_ms.truncate(2)}ms",
+                "total percentage:            #{total_percentage(root_node).truncate(2)}%",
+                "total self execution time:   #{total_self_ms.truncate(2)}ms",
+                "total self percentage:       #{total_self_percentage(root_node).truncate(2)}%",
+                "average execution time:      #{avg_ms.truncate(2)}ms",
+                "average self execution time: #{avg_self_ms.truncate(2)}ms"
+              ]
+            end
+
+            def childeren_text_list(root_node)
+              return [] if @children.empty?
+
+              children.map { |node| node.to_s(root_node) }
+                      .join("\n")
+                      .split("\n")
+                      .map { |str| '|    ' + str }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/profiler/report/tree/node.rb

@@ -0,0 +1,35 @@
+module Flows
+  module Plugin
+    module Profiler
+      class Report
+        class Tree < Report
+          # @api private
+          class Node
+            attr_reader :subject
+            attr_reader :executions
+
+            def initialize(subject:)
+              @subject = subject
+              @children = {}
+              @cache = {}
+
+              @executions = []
+            end
+
+            def [](subject)
+              @children[subject] ||= Node.new(subject: subject)
+            end
+
+            def children
+              @children.values
+            end
+
+            def register_execution(microseconds)
+              @executions << microseconds
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module Flows
+  module Plugin
+    module Profiler
+      # @api private
+      module Wrapper
+        class << self
+          def make_instance_wrapper(method_name) # rubocop:disable Metrics/MethodLength
+            Module.new.tap do |mod|
+              mod.define_method(method_name) do |*args, &block| # rubocop:disable Metrics/MethodLength
+                thread = Thread.current
+                klass = self.class
+
+                return super(*args, &block) unless thread[THREAD_VAR_FLAG]
+
+                report = thread[THREAD_VAR_REPORT]
+                report.add(:started, klass, :instance, method_name, nil)
+
+                before = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_microsecond)
+                super(*args, &block)
+              ensure
+                if before
+                  after = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_microsecond)
+                  report.add(:finished, klass, :instance, method_name, after - before)
+                end
+              end
+            end
+          end
+
+          def make_singleton_wrapper(method_name) # rubocop:disable Metrics/MethodLength
+            Module.new.tap do |mod|
+              mod.define_method(method_name) do |*args, &block| # rubocop:disable Metrics/MethodLength
+                thread = Thread.current
+
+                return super(*args, &block) unless thread[THREAD_VAR_FLAG]
+
+                report = thread[THREAD_VAR_REPORT]
+                report.add(:started, self, :singleton, method_name, nil)
+
+                before = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_microsecond)
+                super(*args, &block)
+              ensure
+                if before
+                  after = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_microsecond)
+                  report.add(:finished, self, :singleton, method_name, after - before)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/railway.rb

@@ -0,0 +1,154 @@
+require_relative 'railway/errors'
+require_relative 'railway/step'
+require_relative 'railway/step_list'
+require_relative 'railway/dsl'
+
+module Flows
+  # 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
+
+    extend DSL
+
+    def initialize
+      klass = self.class
+      steps = klass.steps
+
+      raise NoStepsError, klass if steps.empty?
+
+      @__flows_railway_flow = Flows::Flow.new(
+        start_node: steps.first_step_name,
+        node_map: steps.to_node_map(self)
+      )
+    end
+
+    # Executes Railway with provided keyword arguments, returns Result Object
+    #
+    # @return [Flows::Result]
+    def call(**kwargs)
+      context = {}
+
+      @__flows_railway_flow.call(ok(**kwargs), context: context).tap do |result|
+        result.meta[:last_step] = context[:last_step]
+      end
+    end
+  end
+end