typed_operation 1.0.0.beta3 → 1.0.0.beta4

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,33 +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_properties.filter_map { |property| property.name if property.positional? }
       end
 
+      #: () -> Array[Symbol]
       def keyword_parameters
         literal_properties.filter_map { |property| property.name if property.keyword? }
       end
 
+      #: () -> Array[Literal::_Property]
       def required_parameters
         literal_properties.filter { |property| property.required? }
       end
 
+      #: () -> Array[Symbol]
       def required_positional_parameters
         required_parameters.filter_map { |property| property.name if property.positional? }
       end
 
+      #: () -> Array[Symbol]
       def required_keyword_parameters
         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,9 +1,12 @@
+# 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
+      # This is called by Literal on initialization of underlying Struct/Data.
+      #: () -> void
       def after_initialize
         prepare if respond_to?(:prepare)
       end

data/lib/typed_operation/operations/parameters.rb

@@ -1,3 +1,4 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
@@ -5,6 +6,7 @@ module TypedOperation
     # Method to define parameters for your operation.
     module Parameters
       # 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:)
@@ -13,25 +15,29 @@ module TypedOperation
         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
+      # 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)
         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

@@ -1,25 +1,43 @@
+# 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] # Wraps signature in NilableType
-        @positional = options[:positional] # Changes kind to positional
+        @optional = options[:optional]
+        @positional = options[:positional]
         @reader = options[:reader] || :public
-        @default_key = options.key?(:default)
+        @has_default = options.key?(:default)
         @default = options[:default]
 
-        prepare_type_signature_for_literal
+        prepare_type_signature
       end
 
+      #: () { (untyped) -> untyped } -> void
+      #: () -> void
       def define(&converter)
-        # If nilable, then converter should not attempt to call the type converter block if the value is nil
         coerce_by = if type_nilable? && converter
-          ->(v) { (v == Literal::Null || v.nil?) ? v : converter.call(v) }
+          ->(value) { (value == Literal::Null || value.nil?) ? value : converter.call(value) }
         else
           converter
         end
@@ -27,7 +45,7 @@ module TypedOperation
           @name,
           @signature,
           @positional ? :positional : :keyword,
-          default: default_value_for_literal,
+          default: resolved_default,
           reader: @reader,
           &coerce_by
         )
@@ -35,43 +53,49 @@ module TypedOperation
 
       private
 
-      def prepare_type_signature_for_literal
+      #: () -> 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_params! if @positional
+        validate_positional_order! if @positional
       end
 
-      # If already wrapped in a Nilable then don't wrap again
+      #: () -> bool
       def needs_to_be_nilable?
-        @optional && !type_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 = Literal::Types::UnionType.new(@signature, NilClass) if has_default_value_nil?
-      end
-
-      def has_default_value_nil?
-        default_provided? && @default.nil?
+        @signature = _Union(@signature, NilClass) if has_nil_default?
       end
 
-      def validate_positional_order_params!
-        # Optional ones can always be added after required ones, or before any others, but required ones must be first
+      #: () -> 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?
-        @default_key
+        @has_default
+      end
+
+      #: () -> bool
+      def has_nil_default?
+        default_provided? && @default.nil?
       end
 
-      def default_value_for_literal
-        if has_default_value_nil? || type_nilable?
-          -> {}
+      #: () -> (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

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

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