typed_operation 1.0.0.pre3 → 1.0.0

data/lib/generators/typed_operation/install/USAGE

@@ -12,6 +12,7 @@ rails generate typed_operation:install
 Options:
 --------
 --dry_monads: if specified the ApplicationOperation will include dry-monads Result and Do notation.
+--action_policy: if specified the ApplicationOperation will include action_policy authorization integration.
 
 Example:
 --------

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

@@ -3,9 +3,13 @@
 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
 
       source_root File.expand_path("templates", __dir__)
 
@@ -18,6 +22,10 @@ module TypedOperation
       def include_dry_monads?
         options[:dry_monads]
       end
+
+      def include_action_policy?
+        options[:action_policy]
+      end
     end
   end
 end

data/lib/generators/typed_operation/install/templates/application_operation.rb

@@ -1,14 +1,36 @@
 # frozen_string_literal: true
 
 class ApplicationOperation < ::TypedOperation::Base
+<% if include_action_policy? -%>
+  include TypedOperation::ActionPolicyAuth
+
+<% end -%>
 <% if include_dry_monads? -%>
-  include Dry::Monads[:result, :do]
+  include Dry::Monads[:result]
+  include Dry::Monads::Do.for(:perform)
 
+  # Helper to execute then unwrap a successful result or raise an exception
   def call!
     call.value!
   end
 
 <% end -%>
   # Other common parameters & methods for Operations of this application...
-  # ...
+  # Some examples:
+  #
+  #   def self.operation_key
+  #     name.underscore.to_sym
+  #   end
+  #
+  #   def operation_key
+  #     self.class.operation_key
+  #   end
+  #
+  #   # Translation and localization
+  #
+  #   def translate(key, **)
+  #     key = "operations.#{operation_key}.#{key}" if key.start_with?(".")
+  #     I18n.t(key, **)
+  #   end
+  #   alias_method :t, :translate
 end

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

@@ -0,0 +1,161 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "action_policy"
+
+# 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.
+    class OperationPolicy
+      include ActionPolicy::Policy::Core
+      include ActionPolicy::Policy::Authorization
+      include ActionPolicy::Policy::PreCheck
+      include ActionPolicy::Policy::Reasons
+      include ActionPolicy::Policy::Aliases
+      include ActionPolicy::Policy::Scoping
+      include ActionPolicy::Policy::Cache
+      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
+      # @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)
+        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
+        raise ArgumentError, "authorize_via must be called with a valid param name" unless via.all? { |param| parameters.include?(param) }
+        @_authorized_via_param = via
+
+        action_type_method = :"#{action_type}?" if action_type
+        policy_method = to || action_type_method || raise(::TypedOperation::InvalidOperationError, "You must provide an action type or policy method name")
+        @_policy_method = policy_method
+        @_policy_class = if with
+          with
+        elsif auth_block
+          policy_class = Class.new(OperationPolicy) do
+            authorize(*via)
+
+            define_method(policy_method, &auth_block)
+          end
+          const_set(:Policy, policy_class)
+          policy_class
+        else
+          raise ::TypedOperation::InvalidOperationError, "You must provide either a policy class or a block"
+        end
+
+        if record
+          unless parameters.include?(record) || method_defined?(record) || private_method_defined?(record)
+            raise ArgumentError, "to_authorize must be called with a valid param or method name"
+          end
+          @_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.
+        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 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)
+        subclass.instance_variable_set(:@_verify_authorized, @_verify_authorized)
+        subclass.instance_variable_set(:@_policy_class, @_policy_class)
+        subclass.instance_variable_set(:@_policy_method, @_policy_method)
+        subclass.instance_variable_set(:@_action_type, @_action_type)
+      end
+    end
+
+    private
+
+    #: () -> untyped
+    def execute_operation
+      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 checks_auth
+      super
+    end
+
+    #: () -> void
+    def operation_check_authorized!
+      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(operation_class.operation_record_to_authorize) if operation_class.operation_record_to_authorize
+
+      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.
+    #: (ActionPolicy::Unauthorized) -> void
+    def on_authorization_failure(_authorization_error)
+      # noop
+    end
+  end
+end

data/lib/typed_operation/base.rb

@@ -1,25 +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::Deconstruct
     include Operations::Executable
-
-    class << self
-      def attribute(name, type, special = nil, reader: :public, writer: :public, positional: false, default: nil)
-        super(name, type, special, reader:, writer: false, positional:, default:)
-      end
-    end
-
-    def with(...)
-      # copy to new operation with new attrs
-      self.class.new(**attributes.merge(...))
-    end
   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