flowy 0.1.0

data/lib/flowy/concern/step_runner.rb

@@ -0,0 +1,135 @@
+module Flowy
+  module Concern
+    # Internal runtime that wraps a step with hooks, dispatches keyword args
+    # from result.data, and converts raised errors into Failures according to
+    # the rescue: / on_error: / rescue_errors: contract.
+    module StepRunner
+      private
+
+      # Execution order around each step:
+      #   global before  →  class before  →  per-step before
+      #     global around [ class around [ per-step around [ step ] ] ]
+      #   per-step after  →  class after  →  global after
+      def call_step_with_hooks(step_def, previous_result, rescue_errors:)
+        is_tap    = step_def[:tap]
+        step_name = step_def[:name]
+
+        (Flowy::Concern._flowy_global_before_hooks + self.class._flowy_before_hooks).each do |hook|
+          hook.call(step_name, previous_result)
+        end
+        if (ps_before = step_def[:before_step])
+          resolve_hook(ps_before).call(step_name, previous_result)
+        end
+
+        innermost = lambda do
+          raw = call_step(step_def, previous_result, rescue_errors: rescue_errors)
+          is_tap ? previous_result : raw
+        end
+
+        all_around = Flowy::Concern._flowy_global_around_hooks + self.class._flowy_around_hooks
+        all_around += [resolve_hook(step_def[:around_step])] if step_def[:around_step]
+
+        chain = all_around.reverse.reduce(innermost) do |inner, hook|
+          lambda { hook.call(step_name, previous_result) { inner.call } }
+        end
+
+        result = chain.call
+
+        unless result.is_a?(Flowy::Result)
+          raise TypeError,
+            "around_step hook for '#{step_name}' must return a Flowy::Success or Flowy::Failure, got #{result.class}"
+        end
+
+        if (ps_after = step_def[:after_step])
+          resolve_hook(ps_after).call(step_name, result)
+        end
+        (self.class._flowy_after_hooks + Flowy::Concern._flowy_global_after_hooks).each do |hook|
+          hook.call(step_name, result)
+        end
+
+        result
+      end
+
+      def resolve_hook(hook)
+        hook.is_a?(Symbol) ? method(hook) : hook
+      end
+
+      # `:previous_result` is a reserved keyword: when declared by a step, it
+      # always receives the Flowy::Result object, regardless of any value with
+      # the same key in previous_result.data.
+      def build_step_kwargs(name, previous_result)
+        m      = method(name)
+        params = m.parameters   # [[:keyreq, :age], [:key, :name], [:keyrest, :opts], ...]
+
+        kwargs       = {}
+        has_keyrest  = params.any? { |type, _| type == :keyrest }
+        explicit_keys = params
+                          .select { |type, _| type == :keyreq || type == :key }
+                          .map    { |type, pname| [pname, type == :keyreq] }
+
+        explicit_keys.each do |pname, required|
+          if pname == :previous_result
+            kwargs[:previous_result] = previous_result
+          elsif required
+            unless previous_result.data.key?(pname)
+              raise ArgumentError,
+                "Step '#{name}' requires key #{pname.inspect} but it is missing from result.data " \
+                "(available: #{previous_result.data.keys.inspect})"
+            end
+            kwargs[pname] = previous_result.data[pname]
+          else
+            # optional keyword (has a default): pass it only if present in data,
+            # otherwise let Ruby apply the declared default.
+            kwargs[pname] = previous_result.data[pname] if previous_result.data.key?(pname)
+          end
+        end
+
+        if has_keyrest
+          declared_names = explicit_keys.map(&:first).reject { |p| p == :previous_result }
+          data_keys_to_pass = previous_result.data.keys - declared_names
+          data_keys_to_pass.each { |k| kwargs[k] = previous_result.data[k] }
+        end
+
+        kwargs
+      end
+
+      def call_step(step_def, previous_result, rescue_errors:)
+        name     = step_def[:name]
+        is_tap   = step_def[:tap]
+        rescues  = step_def[:rescue]
+        on_error = step_def[:on_error]
+
+        result =
+          if name.is_a?(Symbol)
+            public_send(name, **build_step_kwargs(name, previous_result))
+          elsif name.is_a?(Flowy::Pipeline)
+            name.call(starting_data: previous_result.data, rescue_errors: rescue_errors, context: self)
+          elsif name.respond_to?(:call)
+            name.call(previous_result: previous_result)
+          else
+            raise ArgumentError, "Step must be a Symbol, Flowy::Pipeline or callable, got #{name.class}"
+          end
+
+        return previous_result if is_tap
+
+        unless result.is_a?(Flowy::Success) || result.is_a?(Flowy::Failure)
+          raise TypeError, "Step '#{name}' must return a Flowy::Success or Flowy::Failure, got #{result.class}"
+        end
+
+        result
+      rescue StandardError => e
+        in_rescues = rescues.any? { |klass| e.is_a?(klass) }
+        raise unless in_rescues || rescue_errors
+
+        if in_rescues && on_error
+          public_send(on_error, e, previous_result: previous_result)
+        else
+          failure(
+            error_code: :step_raised_error,
+            error_data: { step: name.is_a?(Symbol) ? name : name.class.name, message: e.message }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/flowy/concern.rb

@@ -0,0 +1,144 @@
+require_relative 'concern/step_runner'
+
+module Flowy
+  module Concern
+    @_flowy_global_around_hooks = []
+    @_flowy_global_before_hooks = []
+    @_flowy_global_after_hooks  = []
+
+    class << self
+      attr_reader :_flowy_global_around_hooks,
+                  :_flowy_global_before_hooks,
+                  :_flowy_global_after_hooks
+
+      def included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Block signature: |step_name, previous_result, &call|
+      def around_step(&block)
+        @_flowy_global_around_hooks << block
+      end
+
+      # Block signature: |step_name, previous_result|
+      def before_step(&block)
+        @_flowy_global_before_hooks << block
+      end
+
+      # Block signature: |step_name, result|
+      def after_step(&block)
+        @_flowy_global_after_hooks << block
+      end
+
+      def clear_global_hooks!
+        @_flowy_global_around_hooks = []
+        @_flowy_global_before_hooks = []
+        @_flowy_global_after_hooks  = []
+      end
+    end
+
+    DEFAULT_STEP_DEF = {
+      tap:         false,
+      rescue:      [].freeze,
+      on_error:    nil,
+      before_step: nil,
+      after_step:  nil,
+      around_step: nil
+    }.freeze
+    private_constant :DEFAULT_STEP_DEF
+
+    def self._build_step_def(name, **overrides)
+      DEFAULT_STEP_DEF.merge(name: name, **overrides)
+    end
+
+    module ClassMethods
+
+      def success(**kwargs)
+        Flowy::Result.success(**kwargs)
+      end
+
+      def failure(**kwargs)
+        Flowy::Result.failure(**kwargs)
+      end
+
+      # `rescue:` is captured via **opts because `rescue` is a Ruby reserved
+      # word and cannot be referenced as a bare local variable inside a method.
+      def step(name, on_error: nil, before_step: nil, after_step: nil, around_step: nil, **opts)
+        unknown = opts.keys - [:rescue]
+        raise ArgumentError, "unknown keyword: #{unknown.first}" if unknown.any?
+
+        _flowy_steps << Flowy::Concern._build_step_def(
+          name,
+          rescue:      Array(opts[:rescue]),
+          on_error:    on_error,
+          before_step: before_step,
+          after_step:  after_step,
+          around_step: around_step
+        )
+      end
+
+      def tap_step(name, before_step: nil, after_step: nil, around_step: nil)
+        _flowy_steps << Flowy::Concern._build_step_def(
+          name,
+          tap:         true,
+          before_step: before_step,
+          after_step:  after_step,
+          around_step: around_step
+        )
+      end
+
+      def _flowy_steps
+        @_flowy_steps ||= []
+      end
+
+      # Block signature: |step_name, previous_result, &call|
+      def around_step(&block)
+        _flowy_around_hooks << block
+      end
+
+      # Block signature: |step_name, previous_result|
+      def before_step(&block)
+        _flowy_before_hooks << block
+      end
+
+      # Block signature: |step_name, result|
+      def after_step(&block)
+        _flowy_after_hooks << block
+      end
+
+      def _flowy_around_hooks
+        @_flowy_around_hooks ||= []
+      end
+
+      def _flowy_before_hooks
+        @_flowy_before_hooks ||= []
+      end
+
+      def _flowy_after_hooks
+        @_flowy_after_hooks ||= []
+      end
+    end
+
+    include StepRunner
+
+    def success(**kwargs)
+      self.class.success(**kwargs)
+    end
+
+    def failure(**kwargs)
+      self.class.failure(**kwargs)
+    end
+
+    def run_steps(starting_data: {}, steps: nil, rescue_errors: false)
+      initial    = success(data: starting_data)
+      step_list  = steps ? steps.map { |s| Flowy::Concern._build_step_def(s) }
+                         : self.class._flowy_steps
+
+      step_list.reduce(initial) do |current_result, step_def|
+        break current_result if current_result.failure?
+
+        call_step_with_hooks(step_def, current_result, rescue_errors: rescue_errors)
+      end
+    end
+  end
+end

data/lib/flowy/enumerable.rb

@@ -0,0 +1,29 @@
+module Enumerable
+  # On failure produces `error_code: :partial_failure`.
+  def all_success(&block)
+    results = Flowy::Result._collect_results(self, &block)
+
+    if results.all?(&:success?)
+      Flowy::Result.success(data: { results: results })
+    else
+      Flowy::Failure.new(
+        error_code: :partial_failure,
+        error_data: { results: results }
+      )
+    end
+  end
+
+  # On failure produces `error_code: :all_failed`.
+  def any_success(&block)
+    results = Flowy::Result._collect_results(self, &block)
+
+    if results.any?(&:success?)
+      Flowy::Result.success(data: { results: results })
+    else
+      Flowy::Failure.new(
+        error_code: :all_failed,
+        error_data: { results: results }
+      )
+    end
+  end
+end

data/lib/flowy/error.rb

@@ -0,0 +1,47 @@
+module Flowy
+  class Error < StandardError
+    
+    attr_reader :code, :title, :detail, :meta
+    
+    def self.initialize_from_failure(failure:)
+      unless failure.is_a?(Flowy::Failure)
+        raise ArgumentError, "Flowy::Error requires a Flowy::Failure instance, got #{failure.class}"
+      end
+
+      new(
+        code: failure.error_code,
+        title: failure.error_title,
+        detail: failure.error_description,
+        meta: failure.error_data
+      )
+    end
+    
+    def initialize(code:, title: nil, detail: nil, meta: nil)
+      @code = code
+      @title = title
+      @detail = detail
+      @meta = meta
+      super(build_message(code, title, detail))
+    end
+    
+    def to_failure
+      Flowy::Failure.new(
+        error_code: code,
+        error_data: meta || {},
+        error_title: title,
+        error_description: detail
+      )
+    end
+
+    def to_hash
+      to_failure.to_hash
+    end
+
+    private
+
+    def build_message(code, title, detail)
+      description = [title, detail].compact.map(&:to_s).reject(&:empty?).join(': ')
+      [code.to_s, description].reject(&:empty?).join(' - ')
+    end
+  end
+end

data/lib/flowy/failure.rb

@@ -0,0 +1,120 @@
+module Flowy
+  class Failure
+    include Flowy::Result
+
+    attr_reader :error_code, :error_data, :error_title, :error_description, :parent_failure
+
+    def initialize(error_code:, error_data: {}, error_title: nil, error_description: nil, parent_failure: nil)
+      @error_code = error_code
+      @error_data = error_data
+      @error_title = error_title
+      @error_description = error_description
+      @parent_failure = parent_failure
+    end
+
+    def to_hash
+      {
+        success: false,
+        error_code: error_code,
+        error_data: error_data,
+        error_title: error_title,
+        error_description: error_description
+      }
+    end
+
+    def is?(error_code:)
+      self.error_code == error_code
+    end
+
+    def raise!
+      raise Flowy::Error.initialize_from_failure(failure: self)
+    end
+
+    def success?
+      false
+    end
+
+    def failure?
+      true
+    end
+
+    def on_success
+      self
+    end
+
+    def on_failure
+      yield self
+      self
+    end
+
+    def and_then
+      self
+    end
+
+    def or_else
+      result = yield self
+      unless result.is_a?(Flowy::Success) || result.is_a?(Flowy::Failure)
+        raise TypeError, "or_else block must return a Flowy::Success or Flowy::Failure, got #{result.class}"
+      end
+
+      result
+    end
+
+    def tap
+      yield self
+      self
+    end
+
+    def failures_chain
+      return [self] unless parent_failure
+
+      parent_failure.failures_chain + [self]
+    end
+
+    # In block form, when the block-returned Failure omits parent_failure,
+    # self is wired in as parent_failure so the chain is never broken.
+    def map_failure(error_code: nil, error_data: {}, error_title: nil, error_description: nil)
+      if block_given?
+        result = yield self
+        unless result.is_a?(Flowy::Failure)
+          raise TypeError,
+            "map_failure block must return a Flowy::Failure, got #{result.class}"
+        end
+        if result.parent_failure.nil?
+          result.class.new(
+            error_code:        result.error_code,
+            error_data:        result.error_data,
+            error_title:       result.error_title,
+            error_description: result.error_description,
+            parent_failure:    self
+          )
+        else
+          result
+        end
+      else
+        raise ArgumentError, 'map_failure requires either a block or error_code:' if error_code.nil?
+
+        self.class.new(
+          error_code:        error_code,
+          error_data:        error_data,
+          error_title:       error_title,
+          error_description: error_description,
+          parent_failure:    self
+        )
+      end
+    end
+
+    def merge_data(extra = nil)
+      extra = block_given? ? yield(error_data) : extra
+      raise ArgumentError, 'merge_data requires a Hash' unless extra.is_a?(Hash)
+
+      self.class.new(
+        error_code: error_code,
+        error_data: Flowy::Result._deep_merge(error_data, extra),
+        error_title: error_title,
+        error_description: error_description,
+        parent_failure: parent_failure
+      )
+    end
+  end
+end

data/lib/flowy/pipeline.rb

@@ -0,0 +1,194 @@
+module Flowy
+  class Pipeline
+    class BranchBuilder
+      attr_reader :_branches, :_otherwise
+
+      def initialize
+        @_branches   = {}
+        @_otherwise  = nil
+      end
+
+      def when(key, &block)
+        @_branches[key] = block
+        self
+      end
+
+      def otherwise(&block)
+        @_otherwise = block
+        self
+      end
+    end
+    private_constant :BranchBuilder
+
+    def initialize(steps: [])
+      @steps = steps.freeze
+    end
+
+    # Two forms: block form (`step(:name) { |prev| ... }`) and symbolic form
+    # (`step(:name)` with no block, resolved against `context:` at call time).
+    def step(name, &callable)
+      new_step =
+        if callable
+          { type: :step, name: name, callable: callable }
+        elsif name.is_a?(Symbol)
+          { type: :step, name: name, symbolic: true }
+        else
+          raise ArgumentError, "step requires a block or a Symbol name"
+        end
+
+      self.class.new(steps: @steps + [new_step.freeze])
+    end
+
+    def branch(on:, &builder_block)
+      raise ArgumentError, "branch requires a block" unless builder_block
+
+      builder = BranchBuilder.new
+      builder_block.call(builder)
+
+      new_step = {
+        type:      :branch,
+        name:      :"branch(#{on.is_a?(Symbol) ? on : 'λ'})",
+        on:        on,
+        branches:  builder._branches.transform_values(&:call).freeze,
+        otherwise: builder._otherwise&.call
+      }.freeze
+
+      self.class.new(steps: @steps + [new_step])
+    end
+
+    def tap_step(name, &callable)
+      raise ArgumentError, "tap_step requires a block" unless callable
+
+      new_step = { type: :tap_step, name: name, callable: callable }.freeze
+      self.class.new(steps: @steps + [new_step])
+    end
+
+    def >>(other)
+      raise TypeError, ">> requires a Flowy::Pipeline, got #{other.class}" unless other.is_a?(Flowy::Pipeline)
+
+      self.class.new(steps: @steps + other._raw_steps)
+    end
+
+    def call(starting_data: {}, rescue_errors: false, context: nil)
+      initial = Flowy::Result.success(data: starting_data)
+
+      @steps.reduce(initial) do |current, step_def|
+        break current if current.failure?
+
+        execute_step(step_def, current, rescue_errors: rescue_errors, context: context)
+      end
+    end
+
+    def steps
+      @steps.map do |s|
+        case s[:type]
+        when :branch
+          {
+            type:      :branch,
+            name:      s[:name],
+            on:        s[:on],
+            branches:  s[:branches].transform_values { |sub| sub.is_a?(Flowy::Pipeline) ? sub.steps : sub },
+            otherwise: s[:otherwise].is_a?(Flowy::Pipeline) ? s[:otherwise].steps : s[:otherwise]
+          }
+        else
+          { type: s[:type], name: s[:name] }
+        end
+      end
+    end
+
+    def size
+      @steps.size
+    end
+
+    def empty?
+      @steps.empty?
+    end
+
+    # Exposed to support composition via #>>.
+    def _raw_steps
+      @steps
+    end
+
+    protected :_raw_steps
+
+    private
+
+    def execute_step(step_def, previous_result, rescue_errors:, context:)
+      case step_def[:type]
+      when :step
+        invoke_callable(step_def, previous_result, rescue_errors: rescue_errors, context: context)
+      when :tap_step
+        invoke_callable(step_def, previous_result, rescue_errors: rescue_errors, context: context, must_return_flowy_result: false)
+        previous_result
+      when :branch
+        execute_branch(step_def, previous_result, rescue_errors: rescue_errors, context: context)
+      else
+        raise ArgumentError, "Unknown step type: #{step_def[:type]}"
+      end
+    end
+
+    # must_return_flowy_result: set to false by tap_step, whose return is
+    # discarded and therefore should not be type-checked.
+    def invoke_callable(step_def, previous_result, rescue_errors:, context:, must_return_flowy_result: true)
+      result =
+        if step_def[:symbolic]
+          unless context
+            raise ArgumentError,
+              "symbolic step :#{step_def[:name]} requires a `context:` to be passed to #call"
+          end
+          context.send(step_def[:name], previous_result: previous_result)
+        else
+          callable = step_def[:callable]
+          context ? callable.call(previous_result, context) : callable.call(previous_result)
+        end
+
+      if must_return_flowy_result && !result.is_a?(Flowy::Result)
+        raise TypeError,
+          "Step '#{step_def[:name]}' must return a Flowy::Success or Flowy::Failure, got #{result.class}"
+      end
+
+      result
+    rescue StandardError => e
+      raise unless rescue_errors
+
+      Flowy::Failure.new(
+        error_code: :step_raised_error,
+        error_data: { step: step_def[:name], message: e.message }
+      )
+    end
+
+    def execute_branch(step_def, previous_result, rescue_errors:, context:)
+      key = resolve_branch_key(step_def[:on], previous_result.data)
+
+      sub_pipeline = step_def[:branches][key] || step_def[:otherwise]
+
+      unless sub_pipeline
+        return Flowy::Failure.new(
+          error_code: :unmatched_branch,
+          error_data: { branch: step_def[:name], key: key }
+        )
+      end
+
+      unless sub_pipeline.is_a?(Flowy::Pipeline)
+        raise TypeError,
+          "Branch '#{step_def[:name]}' value for key #{key.inspect} must be a Flowy::Pipeline, got #{sub_pipeline.class}"
+      end
+
+      sub_pipeline.call(
+        starting_data: previous_result.data,
+        rescue_errors:  rescue_errors,
+        context:        context
+      )
+    end
+
+    def resolve_branch_key(on, data)
+      if on.is_a?(Symbol)
+        data[on]
+      elsif on.respond_to?(:call)
+        on.call(data)
+      else
+        raise ArgumentError, "branch `on:` must be a Symbol or callable, got #{on.class}"
+      end
+    end
+  end
+end