typed_operation 1.0.0.pre3 → 1.0.0

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

data/lib/typed_operation/operations/composition.rb

@@ -0,0 +1,41 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Provides composition methods for chaining operations together.
+    # Included in operation classes and composed operations (ChainedOperation, Pipeline).
+    module Composition
+      # Smart sequential composition with context accumulation.
+      # Auto-detects whether to spread kwargs or pass as single value.
+      #: (?(singleton(Base) | Proc), **untyped) ?{ (untyped) -> untyped } -> SmartChain
+      def then(operation = nil, **extra_kwargs, &block)
+        SmartChain.new(self, operation || block, extra_kwargs)
+      end
+
+      # Spreads the context as **kwargs to the next operation.
+      #: (?(singleton(Base) | Proc)) ?{ (untyped) -> untyped } -> SplatChain
+      def then_spreads(operation = nil, &block)
+        SplatChain.new(self, operation || block)
+      end
+
+      # Passes the context as a single positional argument to the next operation.
+      #: (?(singleton(Base) | Proc)) ?{ (untyped) -> untyped } -> SequenceChain
+      def then_passes(operation = nil, &block)
+        SequenceChain.new(self, operation || block)
+      end
+
+      # Transforms the success value, replacing the context entirely.
+      #: () { (untyped) -> untyped } -> MapChain
+      def transform(&block)
+        MapChain.new(self, block)
+      end
+
+      # Provides a fallback when the operation fails.
+      #: (?(singleton(Base) | Proc)) ?{ (untyped) -> untyped } -> FallbackChain
+      def or_else(fallback = nil, &block)
+        FallbackChain.new(self, fallback || block)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/executable.rb

@@ -1,26 +1,52 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
   module Operations
+    # Defines the execution lifecycle for operations with before/after hooks.
+    # Operations must implement #perform to define their core logic.
     module Executable
+      #: (Module) -> void
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # @rbs!
+        #   def new: (*untyped, **untyped) -> untyped
+
+        #: (*untyped, **untyped) -> untyped
+        def call(...) = new(...).call
+
+        #: () -> Proc
+        def to_proc = method(:call).to_proc
+      end
+
+      #: () -> untyped
       def call
         execute_operation
       end
 
+      #: () -> Proc
+      def to_proc = method(:call).to_proc
+
+      #: () -> untyped
       def execute_operation
         before_execute_operation
         retval = perform
         after_execute_operation(retval)
       end
 
+      #: () -> void
       def before_execute_operation
-        # noop
       end
 
+      #: (untyped) -> untyped
       def after_execute_operation(retval)
         retval
       end
 
+      #: () -> untyped
       def perform
         raise InvalidOperationError, "Operation #{self.class} does not implement #perform"
       end

data/lib/typed_operation/operations/introspection.rb

@@ -1,35 +1,41 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
   module Operations
-    # Introspection methods
+    # Introspection methods for querying operation parameters.
     module Introspection
+      #: () -> Array[Symbol]
       def positional_parameters
-        literal_attributes.filter_map { |name, attribute| name if attribute.positional? }
+        literal_properties.filter_map { |property| property.name if property.positional? }
       end
 
+      #: () -> Array[Symbol]
       def keyword_parameters
-        literal_attributes.filter_map { |name, attribute| name unless attribute.positional? }
+        literal_properties.filter_map { |property| property.name if property.keyword? }
       end
 
+      #: () -> Array[Literal::_Property]
       def required_parameters
-        literal_attributes.filter do |name, attribute|
-          attribute.default.nil? # Any optional parameters will have a default value/proc in their Literal::Attribute
-        end
+        literal_properties.filter { |property| property.required? }
       end
 
+      #: () -> Array[Symbol]
       def required_positional_parameters
-        required_parameters.filter_map { |name, attribute| name if attribute.positional? }
+        required_parameters.filter_map { |property| property.name if property.positional? }
       end
 
+      #: () -> Array[Symbol]
       def required_keyword_parameters
-        required_parameters.filter_map { |name, attribute| name unless attribute.positional? }
+        required_parameters.filter_map { |property| property.name if property.keyword? }
       end
 
+      #: () -> Array[Symbol]
       def optional_positional_parameters
         positional_parameters - required_positional_parameters
       end
 
+      #: () -> Array[Symbol]
       def optional_keyword_parameters
         keyword_parameters - required_keyword_parameters
       end

data/lib/typed_operation/operations/lifecycle.rb

@@ -1,10 +1,13 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
   module Operations
+    # Hooks into Literal's initialization lifecycle to call #prepare if defined.
     module Lifecycle
-      # This is called by Literal on initialization of underlying Struct/Data
-      def after_initialization
+      # This is called by Literal on initialization of underlying Struct/Data.
+      #: () -> void
+      def after_initialize
         prepare if respond_to?(:prepare)
       end
     end

data/lib/typed_operation/operations/parameters.rb

@@ -1,28 +1,43 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
   module Operations
     # Method to define parameters for your operation.
     module Parameters
-      # Parameter for keyword argument, or a positional argument if you use positional: true
-      # Required, but you can set a default or use optional: true if you want optional
+      # Override literal `prop` to prevent creating writers (Literal::Data does this by default)
+      #: (Symbol, Literal::Types::_Matchable, ?Symbol, ?reader: Symbol, ?writer: Symbol | bool, ?default: untyped) -> void
+      def prop(name, type, kind = :keyword, reader: :public, writer: :public, default: nil)
+        if self < ImmutableBase
+          super(name, type, kind, reader:, default:)
+        else
+          super(name, type, kind, reader:, writer: false, default:)
+        end
+      end
+
+      # Parameter for keyword argument, or a positional argument if you use positional: true.
+      # Required, but you can set a default or use optional: true if you want optional.
+      #: (Symbol, ?Literal::Types::_Matchable, **untyped) ?{ (untyped) -> untyped } -> void
       def param(name, signature = :any, **options, &converter)
-        AttributeBuilder.new(self, name, signature, options).define(&converter)
+        PropertyBuilder.new(self, name, signature, options).define(&converter)
       end
 
       # Alternative DSL
 
-      # Parameter for positional argument
+      # Parameter for positional argument.
+      #: (Symbol, ?Literal::Types::_Matchable, **untyped) ?{ (untyped) -> untyped } -> void
       def positional_param(name, signature = :any, **options, &converter)
         param(name, signature, **options.merge(positional: true), &converter)
       end
 
-      # Parameter for a keyword or named argument
+      # Parameter for a keyword or named argument.
+      #: (Symbol, ?Literal::Types::_Matchable, **untyped) ?{ (untyped) -> untyped } -> void
       def named_param(name, signature = :any, **options, &converter)
         param(name, signature, **options.merge(positional: false), &converter)
       end
 
-      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation
+      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation.
+      #: (Literal::Types::_Matchable) -> Literal::Types::NilableType
       def optional(type_signature)
         Literal::Types::NilableType.new(type_signature)
       end

data/lib/typed_operation/operations/partial_application.rb

@@ -1,13 +1,17 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
   module Operations
+    # Enables partial application of operation parameters via #with and currying via #curry.
     module PartialApplication
+      #: (*untyped, **untyped) -> PartiallyApplied
       def with(...)
         PartiallyApplied.new(self, ...).with
       end
       alias_method :[], :with
 
+      #: () -> Curried
       def curry
         Curried.new(self)
       end

data/lib/typed_operation/operations/property_builder.rb

@@ -0,0 +1,105 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Builds typed properties for operations, handling optional parameters,
+    # defaults, and type conversions with Literal types.
+    #
+    # @rbs generic D -- type of default value
+    class PropertyBuilder
+      include Literal::Types
+
+      # @rbs @typed_operation: untyped
+      # @rbs @name: Symbol
+      # @rbs @signature: untyped
+      # @rbs @optional: bool?
+      # @rbs @positional: bool?
+      # @rbs @reader: Symbol
+      # @rbs @has_default: bool
+      # @rbs @default: untyped
+
+      #: (singleton(Base) | singleton(ImmutableBase), Symbol, Literal::Types::_Matchable, Hash[Symbol, untyped]) -> void
+      def initialize(typed_operation, parameter_name, type_signature, options)
+        @typed_operation = typed_operation
+        @name = parameter_name
+        @signature = type_signature
+        @optional = options[:optional]
+        @positional = options[:positional]
+        @reader = options[:reader] || :public
+        @has_default = options.key?(:default)
+        @default = options[:default]
+
+        prepare_type_signature
+      end
+
+      #: () { (untyped) -> untyped } -> void
+      #: () -> void
+      def define(&converter)
+        coerce_by = if type_nilable? && converter
+          ->(value) { (value == Literal::Undefined || value.nil?) ? value : converter.call(value) }
+        else
+          converter
+        end
+        @typed_operation.prop(
+          @name,
+          @signature,
+          @positional ? :positional : :keyword,
+          default: resolved_default,
+          reader: @reader,
+          &coerce_by
+        )
+      end
+
+      private
+
+      #: () -> void
+      def prepare_type_signature
+        @signature = Literal::Types::NilableType.new(@signature) if needs_to_be_nilable?
+        union_with_nil_to_support_nil_default
+        validate_positional_order! if @positional
+      end
+
+      #: () -> bool
+      def needs_to_be_nilable?
+        !!(@optional && !type_nilable?)
+      end
+
+      #: () -> bool
+      def type_nilable?
+        @signature.is_a?(Literal::Types::NilableType)
+      end
+
+      #: () -> void
+      def union_with_nil_to_support_nil_default
+        @signature = _Union(@signature, NilClass) if has_nil_default?
+      end
+
+      #: () -> void
+      def validate_positional_order!
+        unless type_nilable? || @typed_operation.optional_positional_parameters.empty?
+          raise ParameterError, "Cannot define required positional parameter '#{@name}' after optional positional parameters"
+        end
+      end
+
+      #: () -> bool
+      def default_provided?
+        @has_default
+      end
+
+      #: () -> bool
+      def has_nil_default?
+        default_provided? && @default.nil?
+      end
+
+      #: () -> (D | Proc | nil)
+      def resolved_default
+        if has_nil_default? || (type_nilable? && !default_provided?)
+          -> {} # 'nil' as in a proc that returns nil
+        else
+          @default
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/partially_applied.rb

@@ -1,13 +1,28 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Represents an operation with some, but not all, required parameters provided.
+  # Allows incrementally building operation arguments before execution.
   class PartiallyApplied
+    include Operations::Composition
+
+    # @rbs @operation_class: untyped
+    # @rbs @positional_args: Array[untyped]
+    # @rbs @keyword_args: Hash[Symbol, untyped]
+
+    attr_reader :positional_args #: Array[untyped]
+    attr_reader :keyword_args #: Hash[Symbol, untyped]
+    attr_reader :operation_class #: untyped
+
+    #: (untyped, *untyped, **untyped) -> void
     def initialize(operation_class, *positional_args, **keyword_args)
       @operation_class = operation_class
       @positional_args = positional_args
       @keyword_args = keyword_args
     end
 
+    #: (*untyped, **untyped) -> (PartiallyApplied | Prepared)
     def with(*positional, **keyword)
       all_positional = positional_args + positional
       all_kw_args = keyword_args.merge(keyword)
@@ -22,62 +37,70 @@ module TypedOperation
     end
     alias_method :[], :with
 
+    #: () -> Curried
     def curry
       Curried.new(operation_class, self)
     end
 
+    #: (*untyped, **untyped) -> untyped
     def call(...)
       prepared = with(...)
       return prepared.operation.call if prepared.is_a?(Prepared)
-      raise MissingParameterError, "Cannot call PartiallyApplied operation #{operation_class.name} (key: #{operation_class.name}), are you expecting it to be Prepared?"
+      raise MissingParameterError, "Cannot call PartiallyApplied operation #{operation_class.name}, are you expecting it to be Prepared?"
     end
 
+    #: () -> untyped
     def operation
-      raise MissingParameterError, "Cannot instantiate Operation #{operation_class.name} (key: #{operation_class.name}), as it is only partially applied."
+      raise MissingParameterError, "Cannot instantiate Operation #{operation_class.name}, as it is only partially applied."
     end
 
+    #: () -> false
     def prepared?
       false
     end
 
+    #: () -> Proc
     def to_proc
       method(:call).to_proc
     end
 
+    #: () -> Array[untyped]
     def deconstruct
       positional_args + keyword_args.values
     end
 
+    #: (Array[Symbol]?) -> Hash[Symbol, untyped]
     def deconstruct_keys(keys)
-      h = keyword_args.dup
-      positional_args.each_with_index { |v, i| h[positional_parameters[i]] = v }
-      keys ? h.slice(*keys) : h
+      hash = keyword_args.dup
+      positional_args.each_with_index { |value, index| hash[positional_parameters[index]] = value }
+      keys ? hash.slice(*keys) : hash
     end
 
-    attr_reader :positional_args, :keyword_args
-
     private
 
-    attr_reader :operation_class
-
+    #: () -> Array[Symbol]
     def required_positional_parameters
       @required_positional_parameters ||= operation_class.required_positional_parameters
     end
 
+    #: () -> Array[Symbol]
     def required_keyword_parameters
       @required_keyword_parameters ||= operation_class.required_keyword_parameters
     end
 
+    #: () -> Array[Symbol]
     def positional_parameters
       @positional_parameters ||= operation_class.positional_parameters
     end
 
+    #: (Integer) -> void
     def validate_positional_arg_count!(count)
       if count > positional_parameters.size
-        raise ArgumentError, "Too many positional arguments provided for #{operation_class.name} (key: #{operation_class.name})"
+        raise ArgumentError, "Too many positional arguments provided for #{operation_class.name}"
       end
     end
 
+    #: (Array[untyped], Hash[Symbol, untyped]) -> bool
     def partially_applied?(all_positional, all_kw_args)
       missing_positional = required_positional_parameters.size - all_positional.size
       missing_keys = required_keyword_parameters - all_kw_args.keys