flows 0.2.0 → 0.6.0

data/lib/flows/shared_context_pipeline/dsl.rb

@@ -0,0 +1,12 @@
+require_relative 'dsl/tracks'
+require_relative 'dsl/callbacks'
+
+module Flows
+  class SharedContextPipeline
+    # @api private
+    module DSL
+      include Tracks
+      include Callbacks
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/dsl/callbacks.rb

@@ -0,0 +1,35 @@
+module Flows
+  class SharedContextPipeline
+    module DSL
+      # @api private
+      module Callbacks
+        SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+          '@before_all_callbacks' => [],
+          '@after_all_callbacks' => [],
+          '@before_each_callbacks' => [],
+          '@after_each_callbacks' => []
+        )
+
+        include SingletonVarsSetup
+
+        attr_reader :before_all_callbacks, :after_all_callbacks, :before_each_callbacks, :after_each_callbacks
+
+        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
+end

data/lib/flows/shared_context_pipeline/dsl/tracks.rb

@@ -0,0 +1,52 @@
+module Flows
+  class SharedContextPipeline
+    module DSL
+      # @api private
+      module Tracks
+        DEFAULT_ROUTER_DEF = RouterDefinition.new(
+          Flows::Result::Ok => :next,
+          Flows::Result::Err => :end
+        )
+
+        SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+          '@tracks' => TrackList.new
+        )
+
+        include SingletonVarsSetup
+
+        attr_reader :tracks
+
+        def step(name, router_def = DEFAULT_ROUTER_DEF, body: nil)
+          tracks.add_step(
+            Step.new(name: name, body: body, router_def: router_def)
+          )
+        end
+
+        def mut_step(name, router_def = DEFAULT_ROUTER_DEF, body: nil)
+          tracks.add_step(
+            MutationStep.new(name: name, body: body, router_def: router_def)
+          )
+        end
+
+        def wrap(name, router_def = DEFAULT_ROUTER_DEF, &tracks_definitions)
+          tracks.add_step(
+            Wrap.new(method_name: name, router_def: router_def, &tracks_definitions)
+          )
+        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
+      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,30 @@
+module Flows
+  class SharedContextPipeline
+    EMPTY_HASH = {}.freeze
+    EMPTY_OK = Flows::Result::Ok.new({}.freeze).freeze
+    EMPTY_ERR = Flows::Result::Err.new({}.freeze).freeze
+
+    # @api private
+    class MutationStep < Step
+      NODE_PREPROCESSOR = lambda do |_input, context, node_meta|
+        context[:class].before_each_callbacks.each do |callback|
+          context[:instance].instance_exec(context[:class], node_meta[:name], context[:data], context[:meta], &callback)
+        end
+
+        [[context[:data]], EMPTY_HASH]
+      end
+
+      NODE_POSTPROCESSOR = lambda do |output, context, node_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|
+            context[:instance]
+              .instance_exec(context[:class], node_meta[:name], result, context[:data], context[:meta], &callback)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/router_definition.rb

@@ -0,0 +1,21 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    class RouterDefinition
+      def initialize(routes = {})
+        @routes = routes
+      end
+
+      # :reek:ControlParameter is false positive here
+      def to_router(next_step)
+        final_routes = @routes.transform_values do |route|
+          next route unless route == :next
+
+          next_step || :end
+        end
+
+        ::Flows::Flow::Router::Custom.new(final_routes)
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/step.rb

@@ -0,0 +1,55 @@
+module Flows
+  class SharedContextPipeline
+    EMPTY_ARRAY = [].freeze
+
+    # @api private
+    Step = Struct.new(:name, :body, :router_def, :next_step, keyword_init: true) do
+      # :reek:ManualDispatch
+      def initialize(name:, body: nil, **rest)
+        if name.respond_to?(:call)
+          body = name
+          name = "#{body}+Step-Object-ID-#{object_id}"
+        end
+
+        super(name: name, body: body, **rest)
+      end
+
+      def to_node(pipeline_class)
+        klass = self.class
+
+        Flows::Flow::Node.new(
+          body: body || pipeline_class.method(name),
+          router: router_def.to_router(next_step),
+          meta: { name: name },
+          preprocessor: klass::NODE_PREPROCESSOR,
+          postprocessor: klass::NODE_POSTPROCESSOR
+        )
+      end
+    end
+
+    Step.const_set(
+      :NODE_PREPROCESSOR,
+      lambda do |_input, context, node_meta|
+        context[:class].before_each_callbacks.each do |callback|
+          context[:instance].instance_exec(context[:class], node_meta[:name], context[:data], context[:meta], &callback)
+        end
+
+        [EMPTY_ARRAY, context[:data]]
+      end
+    )
+
+    Step.const_set(
+      :NODE_POSTPROCESSOR,
+      lambda do |result, context, node_meta|
+        context[:data].merge!(result.instance_variable_get(:@data))
+
+        context[:class].after_each_callbacks.each do |callback|
+          context[:instance]
+            .instance_exec(context[:class], node_meta[:name], result, context[:data], context[:meta], &callback)
+        end
+
+        result
+      end
+    )
+  end
+end

data/lib/flows/shared_context_pipeline/track.rb

@@ -0,0 +1,54 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    class Track
+      TRACK_ENTRY_ROUTER_DEF = RouterDefinition.new(
+        Flows::Result::Ok => :next,
+        Flows::Result::Err => :end
+      )
+
+      def initialize(name)
+        @name = name
+        @step_list = []
+      end
+
+      def initialize_dup(_other)
+        @step_list = @step_list.map(&:dup)
+      end
+
+      def add_step(step)
+        last_step = @step_list.last
+        last_step.next_step = step.name if last_step
+
+        @step_list << step
+
+        self
+      end
+
+      def first_step_name
+        @step_list.first.name
+      end
+
+      def empty?
+        @step_list.empty?
+      end
+
+      def to_node_map(method_source)
+        @step_list.each_with_object(@name => make_track_entry_node) do |step, node_map|
+          node_map[step.name] = step.to_node(method_source)
+        end
+      end
+
+      private
+
+      def make_track_entry_node
+        MutationStep.new(
+          name: @name,
+          body: proc { true },
+          router_def: TRACK_ENTRY_ROUTER_DEF,
+          next_step: first_step_name
+        ).to_node(nil)
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/track_list.rb

@@ -0,0 +1,51 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    class TrackList
+      attr_reader :current_track
+
+      def initialize
+        @tracks = { main: Track.new(:main) }
+        @current_track = :main
+      end
+
+      def initialize_dup(_other)
+        @tracks = @tracks.transform_values(&:dup)
+      end
+
+      def switch_track(track_name)
+        @tracks[track_name] ||= Track.new(track_name)
+        @current_track = track_name
+      end
+
+      def add_step(step)
+        @tracks[@current_track].add_step(step)
+      end
+
+      def first_step_name
+        @tracks[:main].first_step_name
+      end
+
+      def main_track_empty?
+        @tracks[:main].empty?
+      end
+
+      def to_node_map(method_source)
+        @tracks.reduce({}) do |node_map, (_, track)|
+          node_map.merge!(
+            track.to_node_map(method_source)
+          )
+        end
+      end
+
+      def to_flow(method_source)
+        raise NoStepsError, method_source if main_track_empty?
+
+        Flows::Flow.new(
+          start_node: first_step_name,
+          node_map: to_node_map(method_source)
+        )
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline/wrap.rb

@@ -0,0 +1,73 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    class Wrap
+      attr_reader :router_def, :tracks_definitions
+
+      # :reek:Attribute
+      attr_accessor :next_step
+
+      EMPTY_HASH = {}.freeze
+
+      NODE_PREPROCESSOR = lambda do |_input, context, _node_meta|
+        [[context], EMPTY_HASH]
+      end
+
+      NODE_POSTPROCESSOR = lambda do |result, context, _node_meta|
+        context[:data].merge!(result.instance_variable_get(:@data))
+
+        result
+      end
+
+      def initialize(method_name:, router_def:, &tracks_definitions)
+        @method_name = method_name
+        @router_def = router_def
+        @tracks_definitions = tracks_definitions
+
+        singleton_class.extend DSL::Tracks
+        singleton_class.extend Result::Helpers
+
+        singleton_class.instance_exec(&tracks_definitions)
+      end
+
+      # on `#dup` we're getting new empty singleton class
+      # so we need to initialize it like original one
+      def initialize_dup(other)
+        singleton_class.extend DSL::Tracks
+        singleton_class.extend Result::Helpers
+        singleton_class.instance_exec(&other.tracks_definitions)
+      end
+
+      def name
+        singleton_class.tracks.first_step_name
+      end
+
+      def to_node(method_source)
+        Flows::Flow::Node.new(
+          body: make_body(method_source),
+          router: router_def.to_router(next_step),
+          meta: { wrap_name: @method_name },
+          preprocessor: NODE_PREPROCESSOR,
+          postprocessor: NODE_POSTPROCESSOR
+        )
+      end
+
+      private
+
+      def make_flow(method_source)
+        singleton_class.tracks.to_flow(method_source)
+      end
+
+      def make_body(method_source)
+        flow = make_flow(method_source)
+        wrapper = method_source.method(@method_name)
+
+        lambda do |context|
+          wrapper.call(context[:data], context[:meta]) do
+            flow.call(nil, context: context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/util.rb

@@ -0,0 +1,17 @@
+module Flows
+  # Namespace for low-level purely technical OOP helpers.
+  #
+  # Implementations here are relatively complex and require
+  # advanced understanding of Ruby's OOP and runtime.
+  #
+  # This module implements "hidden complexity" approach:
+  # hide most non-trivial parts of implementation inside
+  # small well-documented classes and modules.
+  #
+  # @since 0.4.0
+  module Util
+  end
+end
+
+require_relative 'util/prepend_to_class'
+require_relative 'util/inheritable_singleton_vars'

data/lib/flows/util/inheritable_singleton_vars.rb

@@ -0,0 +1,86 @@
+module Flows
+  module Util
+    # Namespace for utility classes which allows you to define specific behaviour for
+    # [singleton variables](https://medium.com/@leo_hetsch/demystifying-singleton-classes-in-ruby-caf3fa4c9d91)
+    # in the context of inheritance.
+    #
+    # When you're writing some abstraction in Ruby one of the ways is to provide some base class and
+    # allow child classes to configure behaviour through class-level DSL. Something like that:
+    #
+    #     class UserModel < BaseModel
+    #       field :name
+    #       field :username
+    #     end
+    #
+    # The first problem here is where to store configuration values?
+    # In the most cases of such DSL it's singleton variables.
+    #
+    # But what will happen if we do something like this:
+    #
+    #     class AdminModel < UserModel
+    #       field :pgp_key
+    #     end
+    #
+    # Which fields are defined for admin? `:name`, `:username` and `:pgp_key`?
+    # Or `:pgp_key` only? Both options are possible and can be implemented.
+    # But working with singleton variables is confusing and related code is confusing also.
+    # So, it's better to implement set of utility modules to define expected behaviour
+    # in a human-friendly format.
+    #
+    # The second problem is default values for singleton variables.
+    # In case of instance variables everything is simple:
+    # you have a constructor (`#initializer`) and it's the right place to set instance variables defaults.
+    # In case of singleton variables you can do it in `.extended` or `.included` callbacks.
+    # But this callback will not be executed on child classes. So, we have to add `.inherited` callback to the mix.
+    # Confusing? Yes. So, it's better to not think about it each time and
+    # use some helpers to explicitly define behaviour.
+    #
+    # Modules under this namespace provide helpers for defining defaults and inheritance strategy for your
+    # singleton variables.
+    #
+    # Each strategy here is using following way of injecting into yours abstract classes:
+    #
+    #     class BaseSomething
+    #       SingletonVarsSetup = Flows::Util::InheritableSingletonVars::SomeStrategy.make_module(
+    #         **options_here
+    #       )
+    #
+    #       include SingeltonVarsSetup # extend also will work
+    #     end
+    #
+    # In case of extensions and mixins:
+    #
+    #     module MyExtension
+    #       SingletonVarsSetup = Flows::Util::InheritableSingletonVars::SomeStrategy.make_module(
+    #         **options_here
+    #       )
+    #
+    #       include SingeltonVarsSetup # extend also will work
+    #     end
+    #
+    #     class SomethingA
+    #       extend MyExtension
+    #     end
+    #
+    #     module MyMixin
+    #       SingletonVarsSetup = Flows::Util::InheritableSingletonVars::SomeStrategy.make_module(
+    #         **options_here
+    #       )
+    #
+    #       include SingeltonVarsSetup # extend also will work
+    #     end
+    #
+    #     class SomethingB
+    #       include MyMixin
+    #     end
+    #
+    # Moreover, you can use multiple strategies in the same class.
+    #
+    # @since 0.4.0
+    module InheritableSingletonVars
+    end
+  end
+end
+
+require_relative './inheritable_singleton_vars/dup_strategy'
+require_relative './inheritable_singleton_vars/isolation_strategy'