typed_operation 1.0.0.pre2 → 1.0.0

data/lib/typed_operation/chains/splat_chain.rb

@@ -0,0 +1,53 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Kwargs spreading chain created by .then_spreads
+  # Always splats the full context as **kwargs to the next operation.
+  # Accumulates result into context.
+  class SplatChain < ChainedOperation
+    include Result::Mixin
+
+    #: (*untyped, **untyped) -> _Result[untyped, untyped]
+    def call(...)
+      result = @left.call(...)
+      return result if result.failure?
+
+      left_value = result.value!
+      context = to_context(left_value)
+
+      right_result = @right.call(**context)
+      return right_result if right_result.failure?
+
+      # Merge right's output into context
+      right_value = right_result.value!
+      merged = merge_into_context(context, right_value)
+
+      Success(merged)
+    end
+
+    private
+
+    #: (untyped) -> Hash[Symbol, untyped]
+    def to_context(value)
+      if value.respond_to?(:to_hash)
+        value.to_hash
+      elsif value.respond_to?(:to_h)
+        value.to_h
+      else
+        raise ArgumentError, "Cannot splat #{value.class} as kwargs - must respond to #to_hash or #to_h"
+      end
+    end
+
+    #: (Hash[Symbol, untyped], untyped) -> Hash[Symbol, untyped]
+    def merge_into_context(context, value)
+      if value.respond_to?(:to_hash)
+        context.merge(value.to_hash)
+      elsif value.respond_to?(:to_h)
+        context.merge(value.to_h)
+      else
+        context.merge(_value: value)
+      end
+    end
+  end
+end

data/lib/typed_operation/configuration.rb

@@ -0,0 +1,52 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Global configuration for TypedOperation.
+  class Configuration
+    # @rbs @result_adapter: (Result::Adapters::BuiltIn | Result::Adapters::DryMonads | untyped)?
+
+    #: () -> void
+    def initialize
+      @result_adapter = nil
+    end
+
+    # Get the current result adapter. Defaults to BuiltIn.
+    #: () -> (Result::Adapters::BuiltIn | Result::Adapters::DryMonads | untyped)
+    def result_adapter
+      @result_adapter ||= Result::Adapters::BuiltIn.new
+    end
+
+    # Set the result adapter.
+    #: (:built_in | :dry_monads | untyped) -> void
+    def result_adapter=(adapter)
+      @result_adapter = case adapter
+      when :built_in then Result::Adapters::BuiltIn.new
+      when :dry_monads then Result::Adapters::DryMonads.new
+      else adapter
+      end
+    end
+  end
+
+  class << self
+    # @rbs @configuration: Configuration?
+
+    # Get the global configuration instance.
+    #: () -> Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure TypedOperation with a block.
+    #: () { (Configuration) -> void } -> void
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults. Mainly for testing.
+    #: () -> void
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

data/lib/typed_operation/context.rb

@@ -0,0 +1,193 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Context objects are for passing data through pipelines and chains.
+  #
+  # This particular implementation wraps a Hash but provides dot access for cleaner syntax.
+  # Its underlying store is mutable.
+  #
+  # Users can subclass or provide their own context that implements the same interface.
+  #
+  # Required interface for custom contexts:
+  #   - #[](key)        - read a value
+  #   - #[]=(key, value) - write a value (if mutable)
+  #   - #key?(key)      - check if key exists
+  #   - #to_h           - convert to Hash (for kwargs extraction)
+  #   - #merge(other)   - combine with another context/hash, returns new context
+  #
+  # Dot access is not required. It's up to you if you prefer to have it in your operation usage.
+  #
+  class Context
+    # @rbs @data: Hash[Symbol, untyped]
+
+    #: (?Hash[Symbol | String, untyped] | Context | _ToH) -> void
+    def initialize(data = {})
+      @data = coerce_to_hash(data).transform_keys(&:to_sym)
+    end
+
+    #: (Symbol | String) -> untyped
+    def [](key)
+      read_value(key.to_sym)
+    end
+
+    #: (Symbol | String, untyped) -> untyped
+    def []=(key, value)
+      write_value(key.to_sym, value)
+    end
+
+    #: (Symbol | String) -> bool
+    def key?(key)
+      @data.key?(key.to_sym)
+    end
+    alias_method :has_key?, :key?
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      @data.dup
+    end
+    alias_method :to_hash, :to_h
+
+    #: (Hash[Symbol | String, untyped] | Context | _ToH) -> Context
+    def merge(other)
+      self.class.new(@data.merge(coerce_to_hash(other)))
+    end
+
+    #: (Symbol | String) -> untyped
+    #: [T] (Symbol | String, T) -> (untyped | T)
+    #: [T] (Symbol | String) { (Symbol) -> T } -> (untyped | T)
+    def fetch(key, *args, &block)
+      @data.fetch(key.to_sym, *args, &block)
+    end
+
+    #: () -> Array[Symbol]
+    def keys
+      @data.keys
+    end
+
+    #: () -> Array[untyped]
+    def values
+      @data.values
+    end
+
+    #: () -> Enumerator[[Symbol, untyped], self]
+    #: () { ([Symbol, untyped]) -> void } -> self
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      @data.each(&block)
+      self
+    end
+
+    #: () { (Symbol, untyped) -> boolish } -> Context
+    def select(&block)
+      self.class.new(@data.select(&block))
+    end
+
+    #: () { (Symbol, untyped) -> boolish } -> Context
+    def reject(&block)
+      self.class.new(@data.reject(&block))
+    end
+
+    #: () { (untyped) -> untyped } -> Context
+    def transform_values(&block)
+      self.class.new(@data.transform_values(&block))
+    end
+
+    #: (*(Symbol | String)) -> Context
+    def slice(*keys)
+      self.class.new(@data.slice(*keys.map(&:to_sym)))
+    end
+
+    #: (*(Symbol | String)) -> Context
+    def except(*keys)
+      self.class.new(@data.except(*keys.map(&:to_sym)))
+    end
+
+    #: () -> bool
+    def empty?
+      @data.empty?
+    end
+
+    #: () -> Integer
+    def size
+      @data.size
+    end
+    alias_method :length, :size
+
+    #: (untyped) -> bool
+    def ==(other)
+      case other
+      when Context
+        @data == other.to_h
+      when Hash
+        @data == other.transform_keys(&:to_sym)
+      else
+        false
+      end
+    end
+
+    # Provide dot access for reading and writing values.
+    #: (Symbol, *untyped) ?{ (*untyped) -> untyped } -> untyped
+    def method_missing(name, *args, &block)
+      name_str = name.to_s
+
+      if name_str.end_with?("=")
+        key = name_str.chomp("=").to_sym
+        write_value(key, args.first)
+      elsif name_str.end_with?("?")
+        key = name_str.chomp("?").to_sym
+        !!read_value(key)
+      elsif args.empty? && !block
+        read_value(name)
+      else
+        super
+      end
+    end
+
+    #: (Symbol, ?bool) -> bool
+    def respond_to_missing?(name, include_private = false)
+      name_str = name.to_s
+      name_str.end_with?("=", "?") ||
+        key?(name) ||
+        super
+    end
+
+    #: () -> String
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    private
+
+    #: (Symbol) -> untyped
+    def read_value(key)
+      @data[key]
+    end
+
+    #: (Symbol, untyped) -> untyped
+    def write_value(key, value)
+      @data[key] = value
+    end
+
+    # @rbs!
+    #   interface _ToH
+    #     def to_h: () -> Hash[untyped, untyped]
+    #   end
+
+    #: (untyped) -> Hash[untyped, untyped]
+    def coerce_to_hash(obj)
+      case obj
+      when Hash
+        obj
+      when Context
+        obj.to_h
+      when ->(o) { o.respond_to?(:to_h) }
+        obj.to_h
+      else
+        raise ArgumentError, "Cannot coerce #{obj.class} to Hash"
+      end
+    end
+  end
+end

data/lib/typed_operation/curried.rb

@@ -1,19 +1,29 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Wraps an operation to support automatic currying, allowing parameters to be
+  # provided one at a time. Returns a new Curried instance until all required
+  # parameters are satisfied, then executes the operation.
   class Curried
+    # @rbs @operation_class: untyped
+    # @rbs @partial_operation: PartiallyApplied | Prepared
+
+    #: (untyped, ?(PartiallyApplied | Prepared)) -> void
     def initialize(operation_class, partial_operation = nil)
       @operation_class = operation_class
       @partial_operation = partial_operation || operation_class.with
     end
 
+    #: (untyped) -> (Curried | untyped)
     def call(arg)
       raise ArgumentError, "A prepared operation should not be curried" if @partial_operation.prepared?
 
       next_partially_applied = if next_parameter_positional?
         @partial_operation.with(arg)
       else
-        @partial_operation.with(next_keyword_parameter => arg)
+        key = next_keyword_parameter or raise ArgumentError, "No keyword parameter available"
+        @partial_operation.with(key => arg)
       end
       if next_partially_applied.prepared?
         next_partially_applied.call
@@ -22,17 +32,20 @@ module TypedOperation
       end
     end
 
+    #: () -> Proc
     def to_proc
       method(:call).to_proc
     end
 
     private
 
+    #: () -> Symbol?
     def next_keyword_parameter
       remaining = @operation_class.required_keyword_parameters - @partial_operation.keyword_args.keys
       remaining.first
     end
 
+    #: () -> bool
     def next_parameter_positional?
       @partial_operation.positional_args.size < @operation_class.required_positional_parameters.size
     end

data/lib/typed_operation/explainable.rb

@@ -0,0 +1,14 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Include this module in your operation base class to enable the `.explain` method
+  # for runtime tracing and debugging.
+  module Explainable
+    #: (Module) -> void
+    def self.included(base)
+      base.extend(Instrumentation::Explainable)
+      base.prepend(Instrumentation::Traceable)
+    end
+  end
+end

data/lib/typed_operation/immutable_base.rb

@@ -1,13 +1,16 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Immutable base class for operations, built on Literal::Data.
+  # Use this when operation state should not be modified after initialization.
   class ImmutableBase < Literal::Data
     extend Operations::Introspection
     extend Operations::Parameters
     extend Operations::PartialApplication
+    extend Operations::Composition
 
-    include Operations::Callable
     include Operations::Lifecycle
-    include Operations::Deconstruct
+    include Operations::Executable
   end
 end

data/lib/typed_operation/instrumentation/trace.rb

@@ -0,0 +1,71 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Instrumentation
+    # Represents a single operation execution trace with timing and result data.
+    # Supports nested traces for operations that call other operations.
+    class Trace
+      attr_reader :operation_class #: untyped
+      attr_reader :params #: Hash[Symbol, untyped]
+      attr_reader :start_time #: Float
+      attr_reader :children #: Array[Trace]
+      attr_accessor :end_time #: Float?
+      attr_accessor :result #: untyped
+      attr_accessor :exception #: Exception?
+      attr_accessor :pass_mode #: Symbol?
+      attr_accessor :extracted_params #: Array[Symbol]?
+      attr_accessor :fallback_used #: bool
+
+      #: (operation_class: untyped, ?params: Hash[Symbol, untyped]) -> void
+      def initialize(operation_class:, params: {})
+        @operation_class = operation_class
+        @params = params
+        @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @end_time = nil
+        @result = nil
+        @exception = nil
+        @children = []
+        @pass_mode = nil
+        @extracted_params = nil
+        @fallback_used = false
+      end
+
+      #: (?result: untyped, ?exception: Exception?) -> self
+      def finish!(result: nil, exception: nil)
+        @end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @result = result
+        @exception = exception
+        self
+      end
+
+      #: () -> (Float | Integer | nil)
+      def duration_ms
+        return nil unless end_time
+        ((end_time - start_time) * 1000).round(2)
+      end
+
+      #: () -> bool
+      def success?
+        return false if exception
+        return result.success? if result.respond_to?(:success?)
+        true
+      end
+
+      #: () -> bool
+      def failure?
+        !success?
+      end
+
+      #: (Trace) -> void
+      def add_child(trace)
+        @children << trace
+      end
+
+      #: () -> String
+      def operation_name
+        operation_class.name || operation_class.to_s
+      end
+    end
+  end
+end

data/lib/typed_operation/instrumentation/tree_formatter.rb

@@ -0,0 +1,141 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Instrumentation
+    # Formats execution traces as a visual chain for console output.
+    # Shows operation flow with arrows and pass mode indicators.
+    class TreeFormatter
+      ARROW = "→" #: String
+      FALLBACK_ARROW = "⤷" #: String
+
+      SUCCESS_MARK = "✓" #: String
+      FAILURE_MARK = "✗" #: String
+      SKIPPED_MARK = "○" #: String
+
+      PASS_MODES = {
+        kwargs_splat: "**ctx",
+        single_value: "ctx",
+        transform: "transform",
+        fallback: "fallback"
+      }.freeze #: Hash[Symbol, String]
+
+      COLORS = {
+        green: "\e[32m",
+        red: "\e[31m",
+        yellow: "\e[33m",
+        cyan: "\e[36m",
+        dim: "\e[2m",
+        bold: "\e[1m",
+        reset: "\e[0m"
+      }.freeze #: Hash[Symbol, String]
+
+      # @rbs @color: bool
+
+      #: (?color: bool?) -> void
+      def initialize(color: nil)
+        @color = color.nil? ? detect_color_support : color
+      end
+
+      #: (Trace) -> String
+      def format(trace)
+        lines = [] #: Array[String]
+        format_chain(trace, lines)
+        lines.join("\n")
+      end
+
+      private
+
+      #: (Trace, Array[String], ?depth: Integer, ?is_fallback: bool) -> void
+      def format_chain(trace, lines, depth: 0, is_fallback: false)
+        indent = "  " * depth
+
+        status = format_status(trace)
+        duration = format_duration(trace.duration_ms)
+        pass_info = format_pass_mode(trace)
+
+        op_name = trace.operation_name
+        if is_fallback
+          op_name = "#{colorize(FALLBACK_ARROW, :yellow)} #{op_name}"
+        end
+
+        line = "#{indent}#{op_name} #{duration} #{status}"
+
+        if pass_info
+          line = "#{line} #{pass_info}"
+        end
+
+        extracted = trace.extracted_params
+        if extracted&.any?
+          params_str = extracted.join(", ")
+          line = "#{line} #{colorize("← [#{params_str}]", :dim)}"
+        end
+
+        lines << line
+
+        if trace.exception
+          lines << "#{indent}  #{colorize("└ Exception: #{trace.exception.class}: #{trace.exception.message}", :red)}"
+        elsif trace.failure? && trace.result.respond_to?(:failure)
+          failure_info = trace.result.failure
+          lines << "#{indent}  #{colorize("└ Failure: #{failure_info.inspect}", :red)}"
+        end
+
+        trace.children.each_with_index do |child, index|
+          is_child_fallback = child.fallback_used
+
+          if index == 0 || is_child_fallback
+            arrow = is_child_fallback ? FALLBACK_ARROW : ARROW
+            arrow_color = is_child_fallback ? :yellow : :dim
+            lines << "#{indent}  #{colorize(arrow, arrow_color)}"
+          else
+            lines << "#{indent}  #{colorize(ARROW, :dim)}"
+          end
+
+          format_chain(child, lines, depth: depth, is_fallback: is_child_fallback)
+        end
+      end
+
+      #: (Trace) -> String
+      def format_status(trace)
+        if trace.exception
+          colorize(FAILURE_MARK, :red)
+        elsif trace.failure?
+          colorize(FAILURE_MARK, :red)
+        else
+          colorize(SUCCESS_MARK, :green)
+        end
+      end
+
+      #: (Float | Integer | nil) -> String
+      def format_duration(ms)
+        return colorize("[--ms]", :dim) unless ms
+        colorize("[#{ms}ms]", :dim)
+      end
+
+      #: (Trace) -> String?
+      def format_pass_mode(trace)
+        return nil unless trace.pass_mode
+        mode_str = PASS_MODES[trace.pass_mode] || trace.pass_mode.to_s
+        colorize("(#{mode_str})", :cyan)
+      end
+
+      #: (Exception?) -> String
+      def format_exception(exception)
+        return "" unless exception
+        colorize("(#{exception.class}: #{exception.message})", :red)
+      end
+
+      #: (String, Symbol) -> String
+      def colorize(text, color)
+        return text unless @color
+        "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+      end
+
+      #: () -> bool
+      def detect_color_support
+        return false unless $stdout.respond_to?(:tty?)
+        $stdout.tty? && ENV["TERM"] != "dumb" && !ENV["NO_COLOR"]
+      end
+    end
+  end
+end