typed_operation 1.0.0.pre2 → 1.0.0

data/lib/typed_operation/pipeline/builder.rb

@@ -0,0 +1,88 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  class Pipeline
+    # Builder class for the Pipeline DSL.
+    class Builder
+      # @rbs @steps: Array[Hash[Symbol, untyped]]
+      # @rbs @failure_handler: (^(untyped, Symbol) -> untyped)?
+
+      attr_reader :steps #: Array[Hash[Symbol, untyped]]
+      attr_reader :failure_handler #: (^(untyped, Symbol) -> untyped)?
+
+      #: () -> void
+      def initialize
+        @steps = []
+        @failure_handler = nil
+      end
+
+      # Define a step in the pipeline.
+      #: (Symbol | untyped, ?untyped, ?if: (^(untyped) -> boolish)?) -> void
+      def step(name_or_operation, operation = nil, if: nil)
+        condition = binding.local_variable_get(:if)
+
+        @steps << if operation
+          {
+            type: :step,
+            name: name_or_operation,
+            operation: operation,
+            condition: condition
+          }
+        else
+          {
+            type: :step,
+            name: derive_name(name_or_operation),
+            operation: name_or_operation,
+            condition: condition
+          }
+        end
+      end
+
+      # Define a transform step that maps the success value.
+      #: () { (untyped) -> untyped } -> void
+      def transform(&block)
+        @steps << {
+          type: :transform,
+          name: :transform,
+          operation: block,
+          condition: nil
+        }
+      end
+
+      # Define a fallback for error recovery.
+      #: (?untyped) ?{ (untyped) -> untyped } -> void
+      def fallback(operation = nil, &block)
+        @steps << {
+          type: :fallback,
+          name: operation ? derive_name(operation) : :fallback,
+          operation: operation || block,
+          condition: nil
+        }
+      end
+      alias_method :or_else, :fallback
+
+      # Define a failure handler for the pipeline.
+      #: () { (untyped, Symbol) -> untyped } -> void
+      def on_failure(&block)
+        @failure_handler = block
+      end
+
+      private
+
+      #: (untyped) -> Symbol
+      def derive_name(operation)
+        return :anonymous unless operation.respond_to?(:name) && operation.name
+
+        operation.name
+          .split("::")
+          .last
+          .gsub(/Operation$/, "")
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
+    end
+  end
+end

data/lib/typed_operation/pipeline/chainable_wrapper.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  class Pipeline
+    # Wrapper that exposes full Composition methods while delegating to Pipeline.
+    class ChainableWrapper
+      include Operations::Composition
+
+      # @rbs @pipeline: Pipeline
+
+      #: (Pipeline) -> void
+      def initialize(pipeline)
+        @pipeline = pipeline
+      end
+
+      #: (*untyped, **untyped) -> untyped
+      def call(...)
+        @pipeline.call(...)
+      end
+    end
+  end
+end

data/lib/typed_operation/pipeline/empty_pipeline_chain.rb

@@ -0,0 +1,25 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  class Pipeline
+    # Handles empty pipelines - just passes through input as Success.
+    class EmptyPipelineChain
+      include Result::Mixin
+
+      #: (*untyped, **untyped) -> untyped
+      def call(*args, **kwargs)
+        value = if kwargs.any?
+          kwargs
+        elsif args.size == 1
+          args.first
+        elsif args.any?
+          args
+        else
+          {}
+        end
+        Success(value)
+      end
+    end
+  end
+end

data/lib/typed_operation/pipeline/step_wrapper.rb

@@ -0,0 +1,94 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  class Pipeline
+    # Wraps a step operation to handle conditions and error attribution.
+    class StepWrapper
+      include Result::Mixin
+      include CallableResolver
+
+      # @rbs @operation: untyped
+      # @rbs @name: Symbol
+      # @rbs @condition: (^(untyped) -> bool)?
+      # @rbs @failure_handler: (^(untyped, Symbol) -> untyped)?
+      # @rbs @first_step: bool
+      # @rbs @uses_kwargs: bool
+
+      #: (untyped, name: Symbol, condition: (^(untyped) -> bool)?, failure_handler: (^(untyped, Symbol) -> untyped)?, ?first_step: bool) -> void
+      def initialize(operation, name:, condition:, failure_handler:, first_step: false)
+        @operation = operation
+        @name = name
+        @condition = condition
+        @failure_handler = failure_handler
+        @first_step = first_step
+        @uses_kwargs = uses_kwargs?(operation)
+      end
+
+      #: (*untyped, **untyped) -> untyped
+      def call(*args, **kwargs)
+        if @first_step
+          call_first_step(*args, **kwargs)
+        else
+          call_subsequent_step(args.first)
+        end
+      end
+
+      private
+
+      #: (*untyped, **untyped) -> untyped
+      def call_first_step(*args, **kwargs)
+        context = kwargs.any? ? kwargs : (args.first || {})
+
+        if (condition = @condition) && !condition.call(context)
+          return Success(context)
+        end
+
+        result = if args.empty? && kwargs.any?
+          @operation.call(**kwargs)
+        elsif args.any? && kwargs.empty?
+          @operation.call(*args)
+        elsif args.any? && kwargs.any?
+          @operation.call(*args, **kwargs)
+        else
+          @operation.call
+        end
+
+        handle_failure(result)
+      end
+
+      #: (untyped) -> untyped
+      def call_subsequent_step(input)
+        context = normalize_input(input)
+
+        if (condition = @condition) && !condition.call(context)
+          return Success(context)
+        end
+
+        result = if @uses_kwargs && context.is_a?(Hash)
+          @operation.call(**context)
+        else
+          @operation.call(context)
+        end
+        handle_failure(result)
+      end
+
+      #: (untyped) -> untyped
+      def handle_failure(result)
+        if result.failure? && @failure_handler
+          return @failure_handler.call(result.failure, @name)
+        end
+        result
+      end
+
+      #: (untyped) -> untyped
+      def normalize_input(input)
+        case input
+        when Hash then input
+        when nil then {}
+        else input
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/pipeline.rb

@@ -0,0 +1,176 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "pipeline/step_wrapper"
+require_relative "pipeline/empty_pipeline_chain"
+require_relative "pipeline/chainable_wrapper"
+require_relative "pipeline/builder"
+
+module TypedOperation
+  # DSL for building declarative pipelines of operations.
+  # Pipeline is syntactic sugar over the composition/chaining system.
+  # Internally builds chains, adding named steps, conditions, and error attribution.
+  class Pipeline
+    # @rbs @chain: untyped
+
+    attr_reader :steps #: Array[Hash[Symbol, untyped]]
+    attr_reader :failure_handler #: (^(untyped, Symbol) -> untyped)?
+
+    # Build a new pipeline using the DSL.
+    #: () { () -> void } -> Pipeline
+    def self.build(&block)
+      builder = Builder.new
+      builder.instance_eval(&block)
+      new(builder.steps, builder.failure_handler)
+    end
+
+    #: (?Array[Hash[Symbol, untyped]], ?(^(untyped, Symbol) -> untyped)?) -> void
+    def initialize(steps = [], failure_handler = nil)
+      @steps = steps.freeze
+      @failure_handler = failure_handler
+      @chain = nil
+    end
+
+    # Execute the pipeline by delegating to the internal chain.
+    #: (*untyped, **untyped) -> untyped
+    def call(*args, **kwargs)
+      chain.call(*args, **kwargs)
+    end
+
+    # Append an operation as a new step, returning a new Pipeline.
+    #: (untyped, ?name: Symbol?, ?if: (^(untyped) -> boolish)?) -> Pipeline
+    def append(operation, name: nil, if: nil)
+      condition = binding.local_variable_get(:if)
+      new_step = {
+        type: :step,
+        name: name || derive_name(operation),
+        operation: operation,
+        condition: condition
+      }
+      self.class.new(@steps + [new_step], @failure_handler)
+    end
+
+    # Compose with another pipeline, merging steps.
+    #: (Pipeline, ?on_failure: (:left | :right | ^(untyped, Symbol) -> untyped)?) -> Pipeline
+    def compose(other, on_failure: nil)
+      handler = resolve_failure_handlers(other, on_failure)
+      self.class.new(@steps + other.steps, handler)
+    end
+
+    # Smart composition operator.
+    #: (Pipeline | untyped) -> Pipeline
+    def +(other)
+      case other
+      when Pipeline
+        compose(other)
+      else
+        append(other)
+      end
+    end
+
+    # Convert to a bare chain for full Composition flexibility.
+    #: () -> ChainableWrapper
+    def to_chain
+      ChainableWrapper.new(self)
+    end
+
+    private
+
+    #: () -> untyped
+    def chain
+      @chain ||= build_chain
+    end
+
+    #: () -> untyped
+    def build_chain
+      return EmptyPipelineChain.new if @steps.empty?
+
+      @steps.each_with_index.reduce(nil) do |current_chain, (step, index)|
+        is_first = index == 0
+        wrapped = wrap_step(step, first_step: is_first)
+
+        if current_chain.nil?
+          wrapped
+        else
+          combine_into_chain(current_chain, step, wrapped)
+        end
+      end
+    end
+
+    #: (untyped, Hash[Symbol, untyped], untyped) -> untyped
+    def combine_into_chain(current_chain, step, wrapped)
+      case step[:type]
+      when :fallback
+        FallbackChain.new(current_chain, wrapped)
+      when :transform
+        MapChain.new(current_chain, wrapped)
+      else
+        SequenceChain.new(current_chain, wrapped)
+      end
+    end
+
+    #: (Hash[Symbol, untyped], ?first_step: bool) -> untyped
+    def wrap_step(step, first_step: false)
+      case step[:type]
+      when :transform
+        step[:operation]
+      when :fallback
+        wrap_fallback(step)
+      else
+        StepWrapper.new(
+          step[:operation],
+          name: step[:name],
+          condition: step[:condition],
+          failure_handler: @failure_handler,
+          first_step: first_step
+        )
+      end
+    end
+
+    #: (Hash[Symbol, untyped]) -> untyped
+    def wrap_fallback(step)
+      if step[:operation].is_a?(Proc)
+        step[:operation]
+      else
+        StepWrapper.new(
+          step[:operation],
+          name: step[:name] || :fallback,
+          condition: nil,
+          failure_handler: @failure_handler
+        )
+      end
+    end
+
+    #: (Pipeline, (:left | :right | ^(untyped, Symbol) -> untyped)?) -> (^(untyped, Symbol) -> untyped)?
+    def resolve_failure_handlers(other, on_failure)
+      return @failure_handler if other.failure_handler.nil?
+      return other.failure_handler if @failure_handler.nil?
+
+      case on_failure
+      when :left then @failure_handler
+      when :right then other.failure_handler
+      when Proc then on_failure
+      when nil
+        raise ArgumentError,
+          "Both pipelines have failure handlers. Specify on_failure: :left, :right, or a Proc"
+      else
+        raise ArgumentError, "Invalid on_failure option: #{on_failure.inspect}"
+      end
+    end
+
+    #: (untyped) -> Symbol
+    def derive_name(operation)
+      return :anonymous if operation.nil?
+      return :anonymous unless operation.respond_to?(:name) && operation.name
+
+      operation.name
+        .split("::")
+        .last
+        .gsub(/Operation$/, "")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+        .to_sym
+    end
+  end
+end

data/lib/typed_operation/prepared.rb

@@ -1,13 +1,26 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Represents an operation with all required parameters provided and ready for execution.
+  # Created when a PartiallyApplied operation receives its final required parameters.
   class Prepared < PartiallyApplied
+    #: () -> TypedOperation::Base
     def operation
       operation_class.new(*@positional_args, **@keyword_args)
     end
 
+    #: () -> true
     def prepared?
       true
     end
+
+    #: () -> untyped
+    def explain
+      unless operation_class.respond_to?(:explain)
+        raise InvalidOperationError, "#{operation_class.name} does not support .explain. Include TypedOperation::Explainable in your operation class."
+      end
+      operation_class.explain(*@positional_args, **@keyword_args)
+    end
   end
 end

data/lib/typed_operation/railtie.rb

@@ -1,4 +1,8 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
 module TypedOperation
+  # Rails integration for TypedOperation, registers generators.
   class Railtie < ::Rails::Railtie
     generators do
       require "generators/typed_operation/install/install_generator"

data/lib/typed_operation/result/adapters/built_in.rb

@@ -0,0 +1,28 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    module Adapters
+      # Default adapter using built-in Success/Failure classes.
+      class BuiltIn
+        # Create a Success result.
+        #: (untyped) -> Result::Success
+        def success(value)
+          Result::Success.new(value)
+        end
+
+        # Create a Failure result.
+        #: (untyped) -> Result::Failure
+        def failure(error)
+          Result::Failure.new(error)
+        end
+
+        #: () -> String
+        def name
+          "TypedOperation::Result (built-in)"
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/result/adapters/dry_monads.rb

@@ -0,0 +1,36 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    module Adapters
+      # Adapter for Dry::Monads Result type.
+      # Requires the dry-monads gem to be available.
+      # This is a lazy-loading adapter that only loads dry-monads when instantiated.
+      class DryMonads
+        #: () -> void
+        def initialize
+          require "dry-monads"
+          extend Dry::Monads[:result]
+        end
+
+        # Create a Success result using Dry::Monads.
+        #: (untyped) -> untyped
+        def success(value)
+          Success(value)
+        end
+
+        # Create a Failure result using Dry::Monads.
+        #: (untyped) -> untyped
+        def failure(error)
+          Failure(error)
+        end
+
+        #: () -> String
+        def name
+          "Dry::Monads::Result"
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/result/failure.rb

@@ -0,0 +1,78 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Error raised when trying to unwrap a Failure result.
+  class UnwrapError < StandardError; end
+
+  module Result
+    # Represents a failed result. Immutable value object.
+    class Failure
+      # @rbs @error: untyped
+
+      attr_reader :error #: untyped
+
+      #: (untyped) -> void
+      def initialize(error)
+        @error = error
+        freeze
+      end
+
+      #: () -> false
+      def success?
+        false
+      end
+
+      #: () -> true
+      def failure?
+        true
+      end
+
+      # Raises UnwrapError since this is a Failure.
+      #: () -> bot
+      def value!
+        raise UnwrapError, "Cannot unwrap Failure: #{@error.inspect}"
+      end
+
+      # Returns the wrapped error.
+      #: () -> untyped
+      def failure
+        @error
+      end
+
+      # Pattern matching support - array destructuring.
+      #: () -> Array[untyped]
+      def deconstruct
+        @error.is_a?(::Array) ? @error : [@error]
+      end
+
+      # Pattern matching support - hash destructuring.
+      # Delegates to the inner error if it responds to deconstruct_keys.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(keys)
+        if @error.respond_to?(:deconstruct_keys)
+          @error.deconstruct_keys(keys)
+        else
+          {error: @error, failure: @error}
+        end
+      end
+
+      #: (untyped) -> bool
+      def ==(other)
+        other.is_a?(Failure) && other.error == @error
+      end
+      alias_method :eql?, :==
+
+      #: () -> Integer
+      def hash
+        [self.class, @error].hash
+      end
+
+      #: () -> String
+      def inspect
+        "Failure(#{@error.inspect})"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/typed_operation/result/mixin.rb

@@ -0,0 +1,24 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    # Mixin providing Success/Failure factory methods to chain classes.
+    # Include this module to call Success(value) and Failure(error) directly.
+    module Mixin
+      private
+
+      # Create a Success result using the configured adapter.
+      #: (untyped) -> (Result::Success | untyped)
+      def Success(value)
+        TypedOperation.configuration.result_adapter.success(value)
+      end
+
+      # Create a Failure result using the configured adapter.
+      #: (untyped) -> (Result::Failure | untyped)
+      def Failure(error)
+        TypedOperation.configuration.result_adapter.failure(error)
+      end
+    end
+  end
+end

data/lib/typed_operation/result/success.rb

@@ -0,0 +1,75 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    # Represents a successful result. Immutable value object.
+    class Success
+      # @rbs @value: untyped
+
+      attr_reader :value #: untyped
+
+      #: (untyped) -> void
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      #: () -> true
+      def success?
+        true
+      end
+
+      #: () -> false
+      def failure?
+        false
+      end
+
+      # Returns the wrapped value.
+      #: () -> untyped
+      def value!
+        @value
+      end
+
+      # Returns nil for Success.
+      #: () -> nil
+      def failure
+        nil
+      end
+
+      # Pattern matching support - array destructuring.
+      #: () -> Array[untyped]
+      def deconstruct
+        @value.is_a?(::Array) ? @value : [@value]
+      end
+
+      # Pattern matching support - hash destructuring.
+      # Delegates to the inner value if it responds to deconstruct_keys.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(keys)
+        if @value.respond_to?(:deconstruct_keys)
+          @value.deconstruct_keys(keys)
+        else
+          {value: @value}
+        end
+      end
+
+      #: (untyped) -> bool
+      def ==(other)
+        other.is_a?(Success) && other.value == @value
+      end
+      alias_method :eql?, :==
+
+      #: () -> Integer
+      def hash
+        [self.class, @value].hash
+      end
+
+      #: () -> String
+      def inspect
+        "Success(#{@value.inspect})"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end