simple_flow 0.1.0

data/lib/simple_flow/pipeline.rb

@@ -0,0 +1,405 @@
+module SimpleFlow
+  ##
+  # The Pipeline class facilitates the creation and execution of a sequence of steps (or operations),
+  # with the possibility of inserting middleware to modify or handle the processing in a flexible way.
+  # This allows for a clean and modular design where components can be easily added, removed, or replaced
+  # without affecting the overall logic flow. It is particularly useful for scenarios where a set of operations
+  # needs to be performed in a specific order, and you want to maintain the capability to inject additional
+  # behavior (like logging, authorization, or input/output transformations) at any point in this sequence.
+  #
+  # Example Usage:
+  # pipeline = SimpleFlow::Pipeline.new do
+  #   use_middleware SomeMiddlewareClass, option: value
+  #   step ->(input) { do_something_with(input) }
+  #   step AnotherCallableObject
+  # end
+  #
+  # result = pipeline.call(initial_data)
+  #
+  # Parallel Execution with Named Steps:
+  # pipeline = SimpleFlow::Pipeline.new do
+  #   step :fetch_user, ->(result) { ... }, depends_on: :none
+  #   step :fetch_orders, ->(result) { ... }, depends_on: [:fetch_user]
+  #   step :fetch_products, ->(result) { ... }, depends_on: [:fetch_user]
+  #   step :calculate, ->(result) { ... }, depends_on: [:fetch_orders, :fetch_products]
+  # end
+  #
+  # result = pipeline.call_parallel(initial_data)  # Auto-detects parallelism
+  #
+  # Note: You can use either depends_on: [] or depends_on: :none for clarity
+  #
+  # Explicit Parallel Blocks:
+  # pipeline = SimpleFlow::Pipeline.new do
+  #   step ->(result) { ... }
+  #   parallel do
+  #     step ->(result) { ... }
+  #     step ->(result) { ... }
+  #   end
+  #   step ->(result) { ... }
+  # end
+  #
+  class Pipeline
+    attr_reader :steps, :middlewares, :named_steps, :step_dependencies, :concurrency, :parallel_groups
+
+    # Initializes a new Pipeline object. A block can be provided to dynamically configure the pipeline,
+    # allowing the addition of steps and middleware.
+    # @param concurrency [Symbol] concurrency model to use (:auto, :threads, :async)
+    #   - :auto (default) - uses async if available, falls back to threads
+    #   - :threads - always uses Ruby threads
+    #   - :async - uses async gem (raises error if not available)
+    def initialize(concurrency: :auto, &config)
+      @steps = []
+      @middlewares = []
+      @named_steps = {}
+      @step_dependencies = {}
+      @parallel_groups = {}
+      @concurrency = concurrency
+
+      validate_concurrency!
+
+      instance_eval(&config) if block_given?
+    end
+
+    # Registers a middleware to be applied to each step. Middlewares can be provided as Proc objects or any
+    # object that responds to `.new` with the callable to be wrapped and options hash.
+    # @param [Proc, Class] middleware the middleware to be used
+    # @param [Hash] options any options to be passed to the middleware upon initialization
+    def use_middleware(middleware, options = {})
+      @middlewares << [middleware, options]
+    end
+
+    # Adds a step to the pipeline. Supports both named and unnamed steps.
+    #
+    # Named steps with dependencies (for automatic parallel detection):
+    #   step :fetch_user, ->(result) { ... }, depends_on: []
+    #   step :process_data, ->(result) { ... }, depends_on: [:fetch_user]
+    #
+    # Unnamed steps (traditional usage):
+    #   step ->(result) { ... }
+    #   step { |result| ... }
+    #
+    # @param [Symbol, Proc, Object] name_or_callable step name (Symbol) or callable object
+    # @param [Proc, Object] callable an object responding to call (if first param is a name)
+    # @param [Hash] options options including :depends_on for dependency declaration
+    # @param block [Block] a block to use as the step if no callable is provided
+    # @raise [ArgumentError] if neither a callable nor block is given, or if the provided object does not respond to call
+    # @return [self] so that calls can be chained
+    def step(name_or_callable = nil, callable = nil, depends_on: [], &block)
+      # Handle different calling patterns
+      if name_or_callable.is_a?(Symbol)
+        # Named step: step :name, ->(result) { ... }, depends_on: [...]
+        name = name_or_callable
+        callable ||= block
+
+        # Validate step name
+        if [:none, :nothing].include?(name)
+          raise ArgumentError, "Step name '#{name}' is reserved. Please use a different name."
+        end
+
+        raise ArgumentError, "Step must respond to #call" unless callable.respond_to?(:call)
+
+        callable = apply_middleware(callable)
+        @named_steps[name] = callable
+        # Filter out reserved dependency symbols :none and :nothing, and expand parallel group names
+        @step_dependencies[name] = expand_dependencies(Array(depends_on).reject { |dep| [:none, :nothing].include?(dep) })
+        @steps << { name: name, callable: callable, type: :named }
+      else
+        # Unnamed step: step ->(result) { ... } or step { |result| ... }
+        callable = name_or_callable || block
+        raise ArgumentError, "Step must respond to #call" unless callable.respond_to?(:call)
+
+        callable = apply_middleware(callable)
+        @steps << { callable: callable, type: :unnamed }
+      end
+
+      self
+    end
+
+    # Defines a parallel execution block. Steps within this block will execute concurrently.
+    # @param name [Symbol, nil] optional name for the parallel group
+    # @param depends_on [Symbol, Array] dependencies for this parallel group
+    # @param block [Block] block containing step definitions
+    # @return [self]
+    # @example Named parallel group with dependencies
+    #   parallel :fetch_data, depends_on: :validate do
+    #     step :fetch_orders, ->(result) { ... }
+    #     step :fetch_products, ->(result) { ... }
+    #   end
+    #   step :process, ->(result) { ... }, depends_on: :fetch_data
+    def parallel(name = nil, depends_on: :none, &block)
+      # Validate name if provided
+      if name && [:none, :nothing].include?(name)
+        raise ArgumentError, "Parallel group name '#{name}' is reserved. Please use a different name."
+      end
+
+      # Filter and expand dependencies
+      filtered_deps = expand_dependencies(Array(depends_on).reject { |dep| [:none, :nothing].include?(dep) })
+
+      # Create and evaluate the parallel block
+      group = ParallelBlock.new(self)
+      group.instance_eval(&block)
+
+      if name
+        # Named parallel group - track it for dependency resolution
+        step_names = group.steps.map { |s| s[:name] }.compact
+        @parallel_groups[name] = {
+          steps: step_names,
+          dependencies: filtered_deps
+        }
+
+        # Add dependencies from the parallel group to its contained steps
+        step_names.each do |step_name|
+          @step_dependencies[step_name] = filtered_deps
+        end
+      end
+
+      @steps << { steps: group.steps, type: :parallel, name: name }
+      self
+    end
+
+    # Internal: Applies registered middlewares to a callable.
+    # @param [Proc, Object] callable the target callable to wrap with middleware
+    # @return [Object] the callable wrapped with all registered middleware
+    def apply_middleware(callable)
+      @middlewares.reverse_each do |middleware, options|
+        if middleware.is_a?(Proc)
+          callable = middleware.call(callable)
+        else
+          callable = middleware.new(callable, **options)
+        end
+      end
+      callable
+    end
+
+    # Executes the pipeline with a given initial result. Each step is called in order, and the result of a step
+    # is passed to the next. Execution can be short-circuited by a step returning an object that does not
+    # satisfy a `continue?` condition.
+    # @param result [Object] the initial data/input to be passed through the pipeline
+    # @return [Object] the result of executing the pipeline
+    def call(result)
+      steps.reduce(result) do |res, step_def|
+        return res if res.respond_to?(:continue?) && !res.continue?
+
+        case step_def
+        when Hash
+          execute_step_def(step_def, res)
+        else
+          # Backward compatibility with old format
+          step_def.call(res)
+        end
+      end
+    end
+
+    # Executes the pipeline with parallel execution where possible.
+    # For named steps with dependencies, automatically detects which steps can run in parallel.
+    # For explicit parallel blocks, executes them concurrently.
+    # @param result [Object] the initial data/input to be passed through the pipeline
+    # @param strategy [Symbol] :auto (automatic detection) or :explicit (only explicit parallel blocks)
+    # @return [Object] the result of executing the pipeline
+    def call_parallel(result, strategy: :auto)
+      if strategy == :auto && has_named_steps?
+        execute_with_dependency_graph(result)
+      else
+        execute_with_explicit_parallelism(result)
+      end
+    end
+
+    # Check if async gem is available for parallel execution
+    # @return [Boolean]
+    def async_available?
+      ParallelExecutor.async_available?
+    end
+
+    # Get the dependency graph for this pipeline
+    # @return [DependencyGraph, nil] dependency graph if pipeline has named steps
+    def dependency_graph
+      return nil unless has_named_steps?
+      DependencyGraph.new(@step_dependencies)
+    end
+
+    # Create a visualizer for this pipeline's dependency graph
+    # @return [DependencyGraphVisualizer, nil] visualizer if pipeline has named steps
+    def visualize
+      graph = dependency_graph
+      return nil unless graph
+      DependencyGraphVisualizer.new(graph)
+    end
+
+    # Print ASCII visualization of the pipeline's dependency graph
+    # @param show_groups [Boolean] whether to show parallel execution groups
+    # @return [String, nil] ASCII visualization or nil if no named steps
+    def visualize_ascii(show_groups: true)
+      visualizer = visualize
+      return nil unless visualizer
+      visualizer.to_ascii(show_groups: show_groups)
+    end
+
+    # Export pipeline visualization to DOT format
+    # @param include_groups [Boolean] whether to color-code parallel groups
+    # @param orientation [String] graph orientation: 'TB' or 'LR'
+    # @return [String, nil] DOT format or nil if no named steps
+    def visualize_dot(include_groups: true, orientation: 'TB')
+      visualizer = visualize
+      return nil unless visualizer
+      visualizer.to_dot(include_groups: include_groups, orientation: orientation)
+    end
+
+    # Export pipeline visualization to Mermaid format
+    # @return [String, nil] Mermaid format or nil if no named steps
+    def visualize_mermaid
+      visualizer = visualize
+      return nil unless visualizer
+      visualizer.to_mermaid
+    end
+
+    # Get execution plan for this pipeline
+    # @return [String, nil] execution plan or nil if no named steps
+    def execution_plan
+      visualizer = visualize
+      return nil unless visualizer
+      visualizer.to_execution_plan
+    end
+
+    private
+
+    # Expands parallel group names in dependencies to all steps in those groups
+    # @param deps [Array<Symbol>] array of dependency symbols
+    # @return [Array<Symbol>] expanded array with parallel groups replaced by their steps
+    def expand_dependencies(deps)
+      deps.flat_map do |dep|
+        if @parallel_groups.key?(dep)
+          # This is a parallel group name - expand to all steps in the group
+          @parallel_groups[dep][:steps]
+        else
+          # Regular step name
+          dep
+        end
+      end
+    end
+
+    def validate_concurrency!
+      valid_options = [:auto, :threads, :async]
+      unless valid_options.include?(@concurrency)
+        raise ArgumentError, "Invalid concurrency option: #{@concurrency.inspect}. Valid options: #{valid_options.inspect}"
+      end
+
+      if @concurrency == :async && !ParallelExecutor.async_available?
+        raise ArgumentError, "Concurrency set to :async but async gem is not available. Install with: gem 'async', '~> 2.0'"
+      end
+    end
+
+    def has_named_steps?
+      @named_steps.any?
+    end
+
+    def execute_step_def(step_def, result)
+      case step_def[:type]
+      when :named, :unnamed
+        step_def[:callable].call(result)
+      when :parallel
+        execute_parallel_group(step_def[:steps], result)
+      end
+    end
+
+    def execute_parallel_group(steps, result)
+      callables = steps.map { |s| s[:callable] }
+      results = ParallelExecutor.execute_parallel(callables, result, concurrency: @concurrency)
+
+      # Return the first halted result, or the last result if all continued
+      results.find { |r| r.respond_to?(:continue?) && !r.continue? } || results.last
+    end
+
+    def execute_with_dependency_graph(result)
+      require_relative 'dependency_graph'
+
+      graph = DependencyGraph.new(@step_dependencies)
+      parallel_groups = graph.parallel_order
+
+      current_result = result
+      step_results = {}
+
+      parallel_groups.each do |group|
+        if group.size == 1
+          # Single step, execute sequentially
+          step_name = group.first
+          current_result = @named_steps[step_name].call(current_result)
+          step_results[step_name] = current_result
+          return current_result if current_result.respond_to?(:continue?) && !current_result.continue?
+        else
+          # Multiple steps, execute in parallel
+          callables = group.map { |name| @named_steps[name] }
+          results = ParallelExecutor.execute_parallel(callables, current_result, concurrency: @concurrency)
+
+          # Check if any step halted
+          halted_result = results.find { |r| r.respond_to?(:continue?) && !r.continue? }
+          return halted_result if halted_result
+
+          # Merge contexts and errors from all parallel results
+          merged_context = {}
+          merged_errors = {}
+          results.each do |r|
+            merged_context.merge!(r.context) if r.respond_to?(:context)
+            if r.respond_to?(:errors)
+              r.errors.each do |key, messages|
+                merged_errors[key] ||= []
+                merged_errors[key].concat(messages)
+              end
+            end
+          end
+
+          # Store results and create merged result
+          group.each_with_index do |name, idx|
+            step_results[name] = results[idx]
+          end
+
+          # Use the last result's value but with merged context/errors
+          last_result = results.last
+          current_result = Result.new(
+            last_result.value,
+            context: merged_context,
+            errors: merged_errors
+          )
+        end
+      end
+
+      current_result
+    end
+
+    def execute_with_explicit_parallelism(result)
+      steps.reduce(result) do |res, step_def|
+        return res if res.respond_to?(:continue?) && !res.continue?
+        execute_step_def(step_def, res)
+      end
+    end
+
+    # Helper class for building parallel blocks
+    class ParallelBlock
+      attr_reader :steps
+
+      def initialize(pipeline)
+        @pipeline = pipeline
+        @steps = []
+      end
+
+      def step(name_or_callable = nil, callable = nil, depends_on: [], &block)
+        if name_or_callable.is_a?(Symbol)
+          name = name_or_callable
+          callable ||= block
+          raise ArgumentError, "Step must respond to #call" unless callable.respond_to?(:call)
+          callable = @pipeline.send(:apply_middleware, callable)
+          # Register the step in the pipeline's named_steps
+          @pipeline.instance_variable_get(:@named_steps)[name] = callable
+          @steps << { name: name, callable: callable, type: :named }
+        else
+          callable = name_or_callable || block
+          raise ArgumentError, "Step must respond to #call" unless callable.respond_to?(:call)
+          callable = @pipeline.send(:apply_middleware, callable)
+          @steps << { callable: callable, type: :unnamed }
+        end
+        self
+      end
+    end
+  end
+end
+
+

data/lib/simple_flow/result.rb

@@ -0,0 +1,88 @@
+module SimpleFlow
+  ##
+  # This class represents the result of an operation within a simple flow system.
+  #
+  # It encapsulates the operation's outcome (value), contextual data (context),
+  # and any errors occurred during the operation (errors). Its primary purpose
+  # is to facilitate flow control and error handling in a clean and predictable
+  # manner. The class provides mechanisms to update context and errors, halt 
+  # the flow, and conditionally continue based on the operation state. This
+  # promotes creating a chainable, fluent interface for managing operation
+  # results in complex processes or workflows.
+  #
+  class Result
+    # The outcome of the operation.
+    attr_reader :value
+
+    # Contextual data related to the operation.
+    attr_reader :context
+
+    # Errors occurred during the operation.
+    attr_reader :errors
+
+    # Initializes a new Result instance.
+    # @param value [Object] the outcome of the operation.
+    # @param context [Hash, optional] contextual data related to the operation.
+    # @param errors [Hash, optional] errors occurred during the operation.
+    def initialize(value, context: {}, errors: {})
+      @value = value
+      @context = context
+      @errors = errors
+      @continue = true
+    end
+
+    # Adds or updates context to the result.
+    # @param key [Symbol] the key to store the context under.
+    # @param value [Object] the value to store.
+    # @return [Result] a new Result instance with updated context.
+    def with_context(key, value)
+      result = self.class.new(@value, context: @context.merge(key => value), errors: @errors)
+      result.instance_variable_set(:@continue, @continue)
+      result
+    end
+
+    # Adds an error message under a specific key.
+    # If the key already exists, it appends the message to the existing errors.
+    # @param key [Symbol] the key under which the error should be stored.
+    # @param message [String] the error message.
+    # @return [Result] a new Result instance with updated errors.
+    def with_error(key, message)
+      result = self.class.new(@value, context: @context, errors: @errors.merge(key => [*@errors[key], message]))
+      result.instance_variable_set(:@continue, @continue)
+      result
+    end
+
+    # Halts the flow, optionally updating the result's value.
+    # @param new_value [Object, nil] the new value to set, if any.
+    # @return [Result] a new Result instance with continue set to false.
+    def halt(new_value = nil)
+      result = new_value ? with_value(new_value) : self.class.new(@value, context: @context, errors: @errors)
+      result.instance_variable_set(:@continue, false)
+      result
+    end
+
+    # Continues the flow, updating the result's value.
+    # @param new_value [Object] the new value to set.
+    # @return [Result] a new Result instance with the new value.
+    def continue(new_value)
+      with_value(new_value)
+    end
+
+    # Checks if the operation should continue.
+    # @return [Boolean] true if the operation should continue, else false.
+    def continue?
+      @continue
+    end
+
+    private
+
+    # Creates a new Result instance with updated value.
+    # @param new_value [Object] the new value for the result.
+    # @return [Result] a new Result instance.
+    def with_value(new_value)
+      result = self.class.new(new_value, context: @context, errors: @errors)
+      result.instance_variable_set(:@continue, @continue)
+      result
+    end
+  end
+end

data/lib/simple_flow/step_tracker.rb

@@ -0,0 +1,58 @@
+require 'delegate'
+
+# This Ruby module is called SimpleFlow and it provides a simple workflow management utility. 
+# The key component demonstrated here is the StepTracker class, which is used to track the 
+# execution of steps within a workflow. This class utilizes the decorator pattern by inheriting 
+# from SimpleDelegator, allowing it to wrap around any object that responds to #call, and 
+# enhancing its behavior without modifying the original object's class.
+module SimpleFlow
+  
+  ##
+  # The StepTracker class serves as a wrapper around any callable object, typically representing
+  # a step in a workflow. Its primary purpose is to execute the wrapped object's call method
+  # and then decide what to do based on the outcome. If the result of the call indicates that 
+  # the process can continue, it simply returns the result. However, if the process should halt, 
+  # it enriches the result with additional context before returning it.
+  #
+  # This enables a mechanism for both executing steps in a workflow and conditionally handling
+  # situations where a step decides the flow should not continue. The enriched context can then
+  # be used downstream to understand why the flow was halted, and potentially take corrective action.
+  #
+  # Example usage:
+  # 
+  #  class ExampleStep
+  #    def call(result)
+  #      result.do_something
+  #      if result.success?
+  #        result.with_continue(true)
+  #      else
+  #        result.with_continue(false)
+  #      end
+  #    end
+  #  end
+  #
+  #  result = SomeResult.new
+  #  wrapped_step = SimpleFlow::StepTracker.new(ExampleStep.new)
+  #  final_result = wrapped_step.call(result)
+  #  
+  #  if final_result.continue
+  #    # proceed with workflow
+  #  else
+  #    # handle halted workflow
+  #  end
+  class StepTracker < SimpleDelegator
+    
+    # Calls the wrapped object's call method with the given result. Depending on the outcome 
+    # of this call, it either returns the result as-is (to continue the workflow) or enriches 
+    # the result with context indicating that this particular step is where the workflow was 
+    # halted.
+    # 
+    # @param result [Object] The result object that is being passed through the workflow steps.
+    # @return [Object] The modified result object, potentially enriched with additional context.
+    def call(result)
+      result = __getobj__.call(result)
+      result.continue? ? result : result.with_context(:halted_step, __getobj__)
+    end
+  end
+end
+

data/lib/simple_flow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleFlow
+  VERSION = "0.1.0"
+end

data/lib/simple_flow.rb

@@ -0,0 +1,41 @@
+#
+# SimpleFlow is a modular, configurable processing framework designed for constructing and
+# managing sequences of operations in a streamlined and efficient manner. It allows for the easy
+# integration of middleware components to augment functionality, such as logging and
+# instrumentation, ensuring that actions within the pipeline are executed seamlessly. By
+# defining steps as callable objects, SimpleFlow facilitates the customized processing of data,
+# offering granular control over the flow of execution and enabling conditional continuation
+# based on the outcome of each step. This approach makes SimpleFlow ideal for complex workflows
+# where the orchestration of tasks, error handling, and context management are crucial.
+#
+
+require 'delegate'
+require 'logger'
+
+require_relative 'simple_flow/version'
+require_relative 'simple_flow/result'
+require_relative 'simple_flow/middleware'
+require_relative 'simple_flow/dependency_graph'
+require_relative 'simple_flow/dependency_graph_visualizer'
+require_relative 'simple_flow/parallel_executor'
+require_relative 'simple_flow/pipeline'
+
+module SimpleFlow
+end
+
+__END__
+
+require_relative './simple_flow'
+
+# Usage example
+pipeline = SimpleFlow::Pipeline.new do
+  use_middleware SimpleFlow::MiddleWare::Instrumentation, api_key: '1234'
+  use_middleware SimpleFlow::MiddleWare::Logging
+  step ->(result) { puts "Processing: #{result.value}"; result }
+  step ->(result) { result.continue(result.value + 1) }
+end
+
+initial_result = SimpleFlow::Result.new(0)
+result = pipeline.call(initial_result)
+puts "Final Result: #{result.value}"
+