typed_operation 1.0.0.beta3 → 1.0.0.beta4

data/lib/generators/typed_operation/install/install_generator.rb

@@ -3,7 +3,10 @@
 require "rails/generators/base"
 
 module TypedOperation
+  # Contains installation-related generators for TypedOperation.
   module Install
+    # Rails generator for installing TypedOperation into a Rails application.
+    # Creates an ApplicationOperation base class with optional dry-monads or action_policy support.
     class InstallGenerator < Rails::Generators::Base
       class_option :dry_monads, type: :boolean, default: false
       class_option :action_policy, type: :boolean, default: false

data/lib/generators/typed_operation_generator.rb

@@ -2,19 +2,23 @@
 
 require "rails/generators/named_base"
 
+# Rails generator for creating new typed operation files and their tests.
 class TypedOperationGenerator < Rails::Generators::NamedBase
   source_root File.expand_path("templates", __dir__)
 
   class_option :path, type: :string, default: "app/operations"
 
   def generate_operation
+    source_root = self.class.source_root
+    operation_path = options[:path]
+
     template(
-      File.join(self.class.source_root, "operation.rb"),
-      File.join(options[:path], "#{file_name}.rb")
+      File.join(source_root, "operation.rb"),
+      File.join(operation_path, "#{file_name}.rb")
     )
     template(
-      File.join(self.class.source_root, "operation_test.rb"),
-      File.join("test/", options[:path].gsub(/\Aapp\//, ""), "#{file_name}_test.rb")
+      File.join(source_root, "operation_test.rb"),
+      File.join("test/", operation_path.gsub(/\Aapp\//, ""), "#{file_name}_test.rb")
     )
   end
 

data/lib/typed_operation/action_policy_auth.rb

@@ -1,13 +1,14 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require "action_policy"
 
-# An optional module to include in your operation to enable authorization via ActionPolicies
+# An optional module to include in your operation to enable authorization via ActionPolicies.
 module TypedOperation
   class MissingAuthentication < StandardError; end
 
   module ActionPolicyAuth
-    # Base class for any action policy classes used by operations
+    # Base class for any action policy classes used by operations.
     class OperationPolicy
       include ActionPolicy::Policy::Core
       include ActionPolicy::Policy::Authorization
@@ -19,15 +20,24 @@ module TypedOperation
       include ActionPolicy::Policy::CachedApply
     end
 
+    #: (Module) -> void
     def self.included(base)
       base.include ::ActionPolicy::Behaviour
       base.extend ClassMethods
     end
 
+    # Class-level methods for configuring authorization on operations.
     module ClassMethods
-      # Configure the operation to use ActionPolicy for authorization
+      # @rbs @_authorized_via_param: Array[Symbol]?
+      # @rbs @_policy_method: Symbol?
+      # @rbs @_policy_class: Class?
+      # @rbs @_to_authorize_param: Symbol?
+      # @rbs @_action_type: Symbol?
+      # @rbs @_verify_authorized: bool?
+
+      # Configure the operation to use ActionPolicy for authorization.
+      #: (*Symbol, ?with: Class?, ?to: Symbol?, ?record: Symbol?) ?{ () -> bool } -> void
       def authorized_via(*via, with: nil, to: nil, record: nil, &auth_block)
-        # If a block is provided, you must not provide a policy class or method
         raise ArgumentError, "You must not provide a policy class or method when using a block" if auth_block && (with || to)
 
         parameters = positional_parameters + keyword_parameters
@@ -35,10 +45,8 @@ module TypedOperation
         @_authorized_via_param = via
 
         action_type_method = :"#{action_type}?" if action_type
-        # If an method name is provided, use it
         policy_method = to || action_type_method || raise(::TypedOperation::InvalidOperationError, "You must provide an action type or policy method name")
         @_policy_method = policy_method
-        # If a policy class is provided, use it
         @_policy_class = if with
           with
         elsif auth_block
@@ -60,44 +68,52 @@ module TypedOperation
           @_to_authorize_param = record
         end
 
-        # Configure action policy to use the param named in via as the context when instantiating the policy
-        # ::ActionPolicy::Behaviour does not provide a authorize(*ids) method, so we have call once per param
+        # Configure action policy to use the param named in via as the context when instantiating the policy.
+        # ::ActionPolicy::Behaviour does not provide a authorize(*ids) method, so we have call once per param.
         via.each do |param|
           authorize param
         end
       end
 
+      #: (?Symbol?) -> Symbol?
       def action_type(type = nil)
         @_action_type = type.to_sym if type
         @_action_type
       end
 
+      #: () -> Symbol?
       def operation_policy_method
         @_policy_method
       end
 
+      #: () -> Class?
       def operation_policy_class
         @_policy_class
       end
 
+      #: () -> Symbol?
       def operation_record_to_authorize
         @_to_authorize_param
       end
 
+      #: () -> bool
       def checks_authorization?
         !(@_authorized_via_param.nil? || @_authorized_via_param.empty?)
       end
 
-      # You can use this on an operation base class to ensure and subclasses always enable authorization
+      # You can use this on an operation base class to ensure subclasses always enable authorization.
+      #: () -> void
       def verify_authorized!
         return if verify_authorized?
         @_verify_authorized = true
       end
 
+      #: () -> bool
       def verify_authorized?
         @_verify_authorized
       end
 
+      #: (Class) -> void
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@_authorized_via_param, @_authorized_via_param)
@@ -110,31 +126,35 @@ module TypedOperation
 
     private
 
-    # Redefine it as private
+    #: () -> untyped
     def execute_operation
-      if self.class.verify_authorized? && !self.class.checks_authorization?
-        raise ::TypedOperation::MissingAuthentication, "Operation #{self.class.name} must authorize. Remember to use `.authorize_via`"
+      operation_class = self.class
+      checks_auth = operation_class.checks_authorization?
+      if operation_class.verify_authorized? && !checks_auth
+        raise ::TypedOperation::MissingAuthentication, "Operation #{operation_class.name} must authorize. Remember to use `.authorize_via`"
       end
-      operation_check_authorized! if self.class.checks_authorization?
+      operation_check_authorized! if checks_auth
       super
     end
 
+    #: () -> void
     def operation_check_authorized!
-      policy = self.class.operation_policy_class
-      raise "No Action Policy policy class provided, or no #{self.class.name}::Policy found for this action" unless policy
-      policy_method = self.class.operation_policy_method
-      raise "No policy method provided or action_type not set for #{self.class.name}" unless policy_method
+      operation_class = self.class
+      policy = operation_class.operation_policy_class
+      raise "No Action Policy policy class provided, or no #{operation_class.name}::Policy found for this action" unless policy
+      raise "No policy method provided or action_type not set for #{operation_class.name}" unless operation_class.operation_policy_method
       # Record to authorize, if nil then action policy tries to work it out implicitly
-      record_to_authorize = send(self.class.operation_record_to_authorize) if self.class.operation_record_to_authorize
+      record_to_authorize = send(operation_class.operation_record_to_authorize) if operation_class.operation_record_to_authorize
 
-      authorize! record_to_authorize, to: policy_method, with: policy
-    rescue ::ActionPolicy::Unauthorized => e
-      on_authorization_failure(e)
-      raise e
+      authorize! record_to_authorize, to: operation_class.operation_policy_method, with: policy
+    rescue ::ActionPolicy::Unauthorized => error
+      on_authorization_failure(error)
+      raise error
     end
 
-    # A hook for subclasses to override to do something on an authorization failure
-    def on_authorization_failure(authorization_error)
+    # A hook for subclasses to override to do something on an authorization failure.
+    #: (ActionPolicy::Unauthorized) -> void
+    def on_authorization_failure(_authorization_error)
       # noop
     end
   end

data/lib/typed_operation/base.rb

@@ -1,13 +1,16 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Mutable base class for operations, built on Literal::Struct.
+  # Use this when operation state can be modified after initialization.
   class Base < Literal::Struct
     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/callable_resolver.rb

@@ -0,0 +1,30 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Utility module for resolving callable objects (operations, procs, chains)
+  # and determining how to invoke them (kwargs vs positional).
+  module CallableResolver
+    #: (_Callable) -> untyped
+    def extract_operation_class(operation)
+      case operation
+      when Class then operation
+      when TypedOperation::PartiallyApplied then operation.operation_class
+      when TypedOperation::ChainedOperation then extract_operation_class(operation.instance_variable_get(:@left))
+      when Proc then nil
+      else operation.class
+      end
+    end
+
+    #: (_Callable) -> bool
+    def uses_kwargs?(operation)
+      op_class = extract_operation_class(operation)
+      return false unless op_class.respond_to?(:positional_parameters)
+
+      positional = op_class.positional_parameters
+      keywords = op_class.keyword_parameters
+
+      keywords.any? && positional.empty?
+    end
+  end
+end

data/lib/typed_operation/chains/chained_operation.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Base class for operation chains.
+  #
+  # Values flow through chains as-is - no implicit splatting.
+  # If you need to convert a value to kwargs for the next operation,
+  # use .then_passes { |v| NextOp.call(**v) } or .transform to reshape first.
+  class ChainedOperation
+    include Operations::Composition
+
+    # @rbs @left: _Callable
+    # @rbs @right: _Callable
+
+    #: (_Callable, _Callable) -> void
+    def initialize(left, right)
+      @left = left
+      @right = right
+    end
+
+    #: (*untyped, **untyped) -> _Result[untyped, untyped]
+    def call(...)
+      raise NotImplementedError, "Subclasses must implement #call"
+    end
+  end
+end

data/lib/typed_operation/chains/fallback_chain.rb

@@ -0,0 +1,32 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Fallback chain created by .or_else
+  # Calls the fallback only when the left operation fails.
+  # Passes through success unchanged.
+  #
+  # For blocks: passes the failure value.
+  # For operations: passes the original call arguments (so fallback can retry).
+  class FallbackChain < ChainedOperation
+    #: (*untyped, **untyped) -> _Result[untyped, untyped]
+    def call(*args, **kwargs)
+      result = @left.call(*args, **kwargs)
+      return result if result.success?
+
+      if Instrumentation.tracing?
+        Instrumentation.set_chain_context(
+          pass_mode: :fallback,
+          extracted_params: nil,
+          fallback_used: true
+        )
+      end
+
+      if @right.is_a?(Proc)
+        @right.call(result.failure)
+      else
+        @right.call(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/typed_operation/chains/map_chain.rb

@@ -0,0 +1,37 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Functor map chain created by .transform
+  # Block receives context, return value replaces context (wrapped in Success).
+  # Short-circuits on failure.
+  class MapChain < 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)
+
+      # Transform replaces context entirely (no merge)
+      transformed = @right.call(context)
+      Success(transformed)
+    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
+        {_value: value}
+      end
+    end
+  end
+end

data/lib/typed_operation/chains/sequence_chain.rb

@@ -0,0 +1,54 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Sequential composition chain used by .then_passes
+  # Passes the success value (context) to the right operation/block.
+  # The result is merged back into context.
+  # Short-circuits on failure.
+  class SequenceChain < 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
+        {_value: value}
+      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/chains/smart_chain.rb

@@ -0,0 +1,161 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Smart chain created by .then
+  # Accumulates context across chain steps and extracts required params for each operation.
+  class SmartChain < ChainedOperation
+    include Result::Mixin
+    include CallableResolver
+
+    # @rbs @extra_kwargs: Hash[Symbol, untyped]
+    # @rbs @uses_kwargs: bool
+    # @rbs @required_params: Array[Symbol]
+    # @rbs @prefilled_params: Hash[Symbol, untyped]
+
+    #: (_Callable, _Callable, ?Hash[Symbol, untyped]) -> void
+    def initialize(left, right, extra_kwargs = {})
+      super(left, right)
+      @extra_kwargs = extra_kwargs
+      @uses_kwargs = uses_kwargs?(right)
+      @required_params = extract_required_params(right)
+      @prefilled_params = extract_prefilled_params(right)
+    end
+
+    #: (*untyped, **untyped) -> _Result[untyped, untyped]
+    def call(*args, **kwargs)
+      # Execute left side
+      result = @left.call(*args, **kwargs)
+      return result if result.failure?
+
+      # Build context from left's result
+      left_value = result.value!
+      context = to_context(left_value)
+
+      # Call right side with appropriate params
+      right_result = call_right(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
+        {_value: value}
+      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
+
+    #: (Hash[Symbol, untyped]) -> _Result[untyped, untyped]
+    def call_right(context)
+      if @uses_kwargs
+        # Extract only the params the operation needs from context
+        extracted = extract_from_context(context, @required_params)
+
+        # Merge: extracted from context < prefilled from .with < extra kwargs from .then
+        call_kwargs = extracted.merge(@prefilled_params).merge(@extra_kwargs)
+
+        # Check for missing required params
+        validate_required_params!(call_kwargs)
+
+        # Set trace context if tracing
+        if Instrumentation.tracing?
+          Instrumentation.set_chain_context(
+            pass_mode: :kwargs_splat,
+            extracted_params: extracted.keys
+          )
+        end
+
+        @right.call(**call_kwargs)
+      else
+        # Positional param operation - pass full context
+        if Instrumentation.tracing?
+          Instrumentation.set_chain_context(
+            pass_mode: :single_value,
+            extracted_params: nil
+          )
+        end
+
+        @right.call(context)
+      end
+    end
+
+    #: (Hash[Symbol, untyped], Array[Symbol]) -> Hash[Symbol, untyped]
+    def extract_from_context(context, params)
+      result = {} #: Hash[Symbol, untyped]
+      params.each do |key|
+        result[key] = context[key] if context.key?(key)
+      end
+      result
+    end
+
+    #: (Hash[Symbol, untyped]) -> void
+    def validate_required_params!(kwargs)
+      op_class = extract_operation_class(@right)
+      return unless op_class.respond_to?(:required_keyword_parameters)
+
+      required = op_class.required_keyword_parameters
+      missing = required - kwargs.keys
+
+      if missing.any?
+        raise ArgumentError,
+          "Missing required parameters for #{op_class.name}: #{missing.join(", ")}. " \
+          "Available in context or provide via .with or .then(op, key: value)"
+      end
+    end
+
+    #: (_Callable) -> bool
+    def uses_kwargs?(operation)
+      op_class = extract_operation_class(operation)
+      return false unless op_class.respond_to?(:positional_parameters)
+
+      positional = op_class.positional_parameters
+      keywords = op_class.keyword_parameters
+
+      if positional.any? && keywords.any?
+        raise ArgumentError,
+          "Cannot chain to operation with both positional and keyword params. Use .transform to adapt."
+      end
+
+      super
+    end
+
+    #: (_Callable) -> Array[Symbol]
+    def extract_required_params(operation)
+      op_class = extract_operation_class(operation)
+      return [] unless op_class.respond_to?(:keyword_parameters)
+      op_class.keyword_parameters
+    end
+
+    #: (_Callable) -> Hash[Symbol, untyped]
+    def extract_prefilled_params(operation)
+      case operation
+      when TypedOperation::PartiallyApplied
+        operation.keyword_args
+      else
+        {}
+      end
+    end
+  end
+end

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