typed_operation 1.0.0.beta3 → 1.0.0.beta4

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::Lifecycle
-    include Operations::Callable
     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

data/lib/typed_operation/instrumentation.rb

@@ -0,0 +1,214 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "instrumentation/trace"
+require_relative "instrumentation/tree_formatter"
+
+module TypedOperation
+  # Provides runtime tracing and debugging capabilities for operations.
+  #
+  # Usage:
+  #   # Trace a single operation call
+  #   result = MyOperation.explain(param: value)
+  #   # Prints execution tree to stdout, returns the operation result
+  #
+  #   # Trace with partial application
+  #   result = MyOperation.with(partial: value).explain(rest: value)
+  #
+  #   # Trace a block of code (captures all instrumented operations)
+  #   TypedOperation::Instrumentation.explaining do
+  #     MyOperation.call(params)
+  #     AnotherOperation.call(other_params)
+  #   end
+  #
+  #   # Configure output and color
+  #   TypedOperation::Instrumentation.with_output(my_io, color: false) do
+  #     MyOperation.explain(param: value)
+  #   end
+  #
+  module Instrumentation
+    THREAD_KEY = :typed_operation_trace_stack #: Symbol
+    CHAIN_CONTEXT_KEY = :typed_operation_chain_context #: Symbol
+    OUTPUT_KEY = :typed_operation_output #: Symbol
+    COLOR_KEY = :typed_operation_color #: Symbol
+
+    class << self
+      # Execute a block with custom output and color settings.
+      #: [T] (IO, ?color: bool?) { () -> T } -> T
+      def with_output(io, color: nil, &block)
+        old_output = Thread.current[OUTPUT_KEY]
+        old_color = Thread.current[COLOR_KEY]
+        Thread.current[OUTPUT_KEY] = io
+        Thread.current[COLOR_KEY] = color
+        yield
+      ensure
+        Thread.current[OUTPUT_KEY] = old_output
+        Thread.current[COLOR_KEY] = old_color
+      end
+
+      # Execute a block with tracing enabled, printing the trace tree afterward.
+      #: [T] () { () -> T } -> T
+      def explaining(&block)
+        trace_root = Trace.new(operation_class: BlockExecution, params: {})
+        push_trace(trace_root)
+
+        result = nil
+        exception = nil
+        begin
+          result = block.call
+        rescue => e
+          exception = e
+        end
+
+        trace_root.finish!(result: result, exception: exception)
+        pop_trace
+
+        formatter = TreeFormatter.new(color: color)
+        trace_root.children.each do |child_trace|
+          output.puts formatter.format(child_trace)
+        end
+
+        raise exception if exception
+        result
+      end
+
+      #: () -> IO
+      def output
+        Thread.current[OUTPUT_KEY] || $stdout
+      end
+
+      #: () -> bool
+      def color
+        val = Thread.current[COLOR_KEY]
+        val.nil? || val
+      end
+
+      #: () -> Trace?
+      def current_trace
+        stack = Thread.current[THREAD_KEY]
+        stack&.last
+      end
+
+      #: () -> bool
+      def tracing?
+        !current_trace.nil?
+      end
+
+      #: (Trace) -> void
+      def push_trace(trace)
+        Thread.current[THREAD_KEY] ||= []
+        parent = current_trace
+        parent&.add_child(trace)
+        Thread.current[THREAD_KEY].push(trace)
+      end
+
+      #: () -> Trace?
+      def pop_trace
+        stack = Thread.current[THREAD_KEY]
+        stack&.pop
+        Thread.current[THREAD_KEY] = nil if stack&.empty?
+      end
+
+      #: () -> void
+      def clear_trace!
+        Thread.current[THREAD_KEY] = nil
+        Thread.current[CHAIN_CONTEXT_KEY] = nil
+      end
+
+      #: (pass_mode: Symbol, ?extracted_params: Array[Symbol]?, ?fallback_used: bool) -> void
+      def set_chain_context(pass_mode:, extracted_params: nil, fallback_used: false)
+        Thread.current[CHAIN_CONTEXT_KEY] = {
+          pass_mode: pass_mode,
+          extracted_params: extracted_params,
+          fallback_used: fallback_used
+        }
+      end
+
+      #: () -> Hash[Symbol, untyped]?
+      def take_chain_context
+        ctx = Thread.current[CHAIN_CONTEXT_KEY]
+        Thread.current[CHAIN_CONTEXT_KEY] = nil
+        ctx
+      end
+    end
+
+    # Placeholder class for block-based tracing
+    class BlockExecution; end
+
+    # Module to be prepended to operation classes to enable tracing.
+    # This is automatically included when using `explain`.
+    module Traceable
+      #: () -> untyped
+      def execute_operation
+        return super unless Instrumentation.tracing?
+
+        trace = Trace.new(
+          operation_class: self.class,
+          params: extract_params_for_trace
+        )
+
+        # Apply chain context if available
+        if (chain_ctx = Instrumentation.take_chain_context)
+          trace.pass_mode = chain_ctx[:pass_mode]
+          trace.extracted_params = chain_ctx[:extracted_params]
+          trace.fallback_used = chain_ctx[:fallback_used]
+        end
+
+        Instrumentation.push_trace(trace)
+
+        result = nil
+        exception = nil
+        begin
+          result = super
+        rescue => e
+          exception = e
+        end
+
+        trace.finish!(result: result, exception: exception)
+        Instrumentation.pop_trace
+
+        raise exception if exception
+        result
+      end
+
+      private
+
+      #: () -> Hash[Symbol, untyped]
+      def extract_params_for_trace
+        self.class.literal_properties.keys.each_with_object({}) do |key, hash|
+          hash[key] = send(key)
+        end
+      rescue
+        {}
+      end
+    end
+
+    # Class methods added to operations for the `explain` entry point.
+    module Explainable
+      #: (*untyped, **untyped) ?{ () -> untyped } -> untyped
+      def explain(*args, **kwargs, &block)
+        trace = Trace.new(operation_class: self, params: kwargs.merge(positional: args))
+        Instrumentation.push_trace(trace)
+
+        result = nil
+        exception = nil
+        begin
+          result = call(*args, **kwargs, &block)
+        rescue => e
+          exception = e
+        end
+
+        trace.finish!(result: result, exception: exception)
+        Instrumentation.pop_trace
+
+        formatter = TreeFormatter.new(color: Instrumentation.color)
+        Instrumentation.output.puts formatter.format(trace)
+
+        Instrumentation.clear_trace!
+
+        raise exception if exception
+        result
+      end
+    end
+  end
+end