typed_operation 1.0.0.beta3 → 1.0.0.beta4

data/lib/typed_operation/pipeline.rb

@@ -0,0 +1,176 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "pipeline/step_wrapper"
+require_relative "pipeline/empty_pipeline_chain"
+require_relative "pipeline/chainable_wrapper"
+require_relative "pipeline/builder"
+
+module TypedOperation
+  # DSL for building declarative pipelines of operations.
+  # Pipeline is syntactic sugar over the composition/chaining system.
+  # Internally builds chains, adding named steps, conditions, and error attribution.
+  class Pipeline
+    # @rbs @chain: untyped
+
+    attr_reader :steps #: Array[Hash[Symbol, untyped]]
+    attr_reader :failure_handler #: (^(untyped, Symbol) -> untyped)?
+
+    # Build a new pipeline using the DSL.
+    #: () { () -> void } -> Pipeline
+    def self.build(&block)
+      builder = Builder.new
+      builder.instance_eval(&block)
+      new(builder.steps, builder.failure_handler)
+    end
+
+    #: (?Array[Hash[Symbol, untyped]], ?(^(untyped, Symbol) -> untyped)?) -> void
+    def initialize(steps = [], failure_handler = nil)
+      @steps = steps.freeze
+      @failure_handler = failure_handler
+      @chain = nil
+    end
+
+    # Execute the pipeline by delegating to the internal chain.
+    #: (*untyped, **untyped) -> untyped
+    def call(*args, **kwargs)
+      chain.call(*args, **kwargs)
+    end
+
+    # Append an operation as a new step, returning a new Pipeline.
+    #: (untyped, ?name: Symbol?, ?if: (^(untyped) -> boolish)?) -> Pipeline
+    def append(operation, name: nil, if: nil)
+      condition = binding.local_variable_get(:if)
+      new_step = {
+        type: :step,
+        name: name || derive_name(operation),
+        operation: operation,
+        condition: condition
+      }
+      self.class.new(@steps + [new_step], @failure_handler)
+    end
+
+    # Compose with another pipeline, merging steps.
+    #: (Pipeline, ?on_failure: (:left | :right | ^(untyped, Symbol) -> untyped)?) -> Pipeline
+    def compose(other, on_failure: nil)
+      handler = resolve_failure_handlers(other, on_failure)
+      self.class.new(@steps + other.steps, handler)
+    end
+
+    # Smart composition operator.
+    #: (Pipeline | untyped) -> Pipeline
+    def +(other)
+      case other
+      when Pipeline
+        compose(other)
+      else
+        append(other)
+      end
+    end
+
+    # Convert to a bare chain for full Composition flexibility.
+    #: () -> ChainableWrapper
+    def to_chain
+      ChainableWrapper.new(self)
+    end
+
+    private
+
+    #: () -> untyped
+    def chain
+      @chain ||= build_chain
+    end
+
+    #: () -> untyped
+    def build_chain
+      return EmptyPipelineChain.new if @steps.empty?
+
+      @steps.each_with_index.reduce(nil) do |current_chain, (step, index)|
+        is_first = index == 0
+        wrapped = wrap_step(step, first_step: is_first)
+
+        if current_chain.nil?
+          wrapped
+        else
+          combine_into_chain(current_chain, step, wrapped)
+        end
+      end
+    end
+
+    #: (untyped, Hash[Symbol, untyped], untyped) -> untyped
+    def combine_into_chain(current_chain, step, wrapped)
+      case step[:type]
+      when :fallback
+        FallbackChain.new(current_chain, wrapped)
+      when :transform
+        MapChain.new(current_chain, wrapped)
+      else
+        SequenceChain.new(current_chain, wrapped)
+      end
+    end
+
+    #: (Hash[Symbol, untyped], ?first_step: bool) -> untyped
+    def wrap_step(step, first_step: false)
+      case step[:type]
+      when :transform
+        step[:operation]
+      when :fallback
+        wrap_fallback(step)
+      else
+        StepWrapper.new(
+          step[:operation],
+          name: step[:name],
+          condition: step[:condition],
+          failure_handler: @failure_handler,
+          first_step: first_step
+        )
+      end
+    end
+
+    #: (Hash[Symbol, untyped]) -> untyped
+    def wrap_fallback(step)
+      if step[:operation].is_a?(Proc)
+        step[:operation]
+      else
+        StepWrapper.new(
+          step[:operation],
+          name: step[:name] || :fallback,
+          condition: nil,
+          failure_handler: @failure_handler
+        )
+      end
+    end
+
+    #: (Pipeline, (:left | :right | ^(untyped, Symbol) -> untyped)?) -> (^(untyped, Symbol) -> untyped)?
+    def resolve_failure_handlers(other, on_failure)
+      return @failure_handler if other.failure_handler.nil?
+      return other.failure_handler if @failure_handler.nil?
+
+      case on_failure
+      when :left then @failure_handler
+      when :right then other.failure_handler
+      when Proc then on_failure
+      when nil
+        raise ArgumentError,
+          "Both pipelines have failure handlers. Specify on_failure: :left, :right, or a Proc"
+      else
+        raise ArgumentError, "Invalid on_failure option: #{on_failure.inspect}"
+      end
+    end
+
+    #: (untyped) -> Symbol
+    def derive_name(operation)
+      return :anonymous if operation.nil?
+      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

data/lib/typed_operation/prepared.rb

@@ -1,13 +1,26 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module TypedOperation
+  # Represents an operation with all required parameters provided and ready for execution.
+  # Created when a PartiallyApplied operation receives its final required parameters.
   class Prepared < PartiallyApplied
+    #: () -> TypedOperation::Base
     def operation
       operation_class.new(*@positional_args, **@keyword_args)
     end
 
+    #: () -> true
     def prepared?
       true
     end
+
+    #: () -> untyped
+    def explain
+      unless operation_class.respond_to?(:explain)
+        raise InvalidOperationError, "#{operation_class.name} does not support .explain. Include TypedOperation::Explainable in your operation class."
+      end
+      operation_class.explain(*@positional_args, **@keyword_args)
+    end
   end
 end

data/lib/typed_operation/railtie.rb

@@ -1,4 +1,8 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
 module TypedOperation
+  # Rails integration for TypedOperation, registers generators.
   class Railtie < ::Rails::Railtie
     generators do
       require "generators/typed_operation/install/install_generator"

data/lib/typed_operation/result/adapters/built_in.rb

@@ -0,0 +1,28 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    module Adapters
+      # Default adapter using built-in Success/Failure classes.
+      class BuiltIn
+        # Create a Success result.
+        #: (untyped) -> Result::Success
+        def success(value)
+          Result::Success.new(value)
+        end
+
+        # Create a Failure result.
+        #: (untyped) -> Result::Failure
+        def failure(error)
+          Result::Failure.new(error)
+        end
+
+        #: () -> String
+        def name
+          "TypedOperation::Result (built-in)"
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/result/adapters/dry_monads.rb

@@ -0,0 +1,36 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    module Adapters
+      # Adapter for Dry::Monads Result type.
+      # Requires the dry-monads gem to be available.
+      # This is a lazy-loading adapter that only loads dry-monads when instantiated.
+      class DryMonads
+        #: () -> void
+        def initialize
+          require "dry-monads"
+          extend Dry::Monads[:result]
+        end
+
+        # Create a Success result using Dry::Monads.
+        #: (untyped) -> untyped
+        def success(value)
+          Success(value)
+        end
+
+        # Create a Failure result using Dry::Monads.
+        #: (untyped) -> untyped
+        def failure(error)
+          Failure(error)
+        end
+
+        #: () -> String
+        def name
+          "Dry::Monads::Result"
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/result/failure.rb

@@ -0,0 +1,78 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  # Error raised when trying to unwrap a Failure result.
+  class UnwrapError < StandardError; end
+
+  module Result
+    # Represents a failed result. Immutable value object.
+    class Failure
+      # @rbs @error: untyped
+
+      attr_reader :error #: untyped
+
+      #: (untyped) -> void
+      def initialize(error)
+        @error = error
+        freeze
+      end
+
+      #: () -> false
+      def success?
+        false
+      end
+
+      #: () -> true
+      def failure?
+        true
+      end
+
+      # Raises UnwrapError since this is a Failure.
+      #: () -> bot
+      def value!
+        raise UnwrapError, "Cannot unwrap Failure: #{@error.inspect}"
+      end
+
+      # Returns the wrapped error.
+      #: () -> untyped
+      def failure
+        @error
+      end
+
+      # Pattern matching support - array destructuring.
+      #: () -> Array[untyped]
+      def deconstruct
+        @error.is_a?(::Array) ? @error : [@error]
+      end
+
+      # Pattern matching support - hash destructuring.
+      # Delegates to the inner error if it responds to deconstruct_keys.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(keys)
+        if @error.respond_to?(:deconstruct_keys)
+          @error.deconstruct_keys(keys)
+        else
+          {error: @error, failure: @error}
+        end
+      end
+
+      #: (untyped) -> bool
+      def ==(other)
+        other.is_a?(Failure) && other.error == @error
+      end
+      alias_method :eql?, :==
+
+      #: () -> Integer
+      def hash
+        [self.class, @error].hash
+      end
+
+      #: () -> String
+      def inspect
+        "Failure(#{@error.inspect})"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/typed_operation/result/mixin.rb

@@ -0,0 +1,24 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    # Mixin providing Success/Failure factory methods to chain classes.
+    # Include this module to call Success(value) and Failure(error) directly.
+    module Mixin
+      private
+
+      # Create a Success result using the configured adapter.
+      #: (untyped) -> (Result::Success | untyped)
+      def Success(value)
+        TypedOperation.configuration.result_adapter.success(value)
+      end
+
+      # Create a Failure result using the configured adapter.
+      #: (untyped) -> (Result::Failure | untyped)
+      def Failure(error)
+        TypedOperation.configuration.result_adapter.failure(error)
+      end
+    end
+  end
+end

data/lib/typed_operation/result/success.rb

@@ -0,0 +1,75 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module TypedOperation
+  module Result
+    # Represents a successful result. Immutable value object.
+    class Success
+      # @rbs @value: untyped
+
+      attr_reader :value #: untyped
+
+      #: (untyped) -> void
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      #: () -> true
+      def success?
+        true
+      end
+
+      #: () -> false
+      def failure?
+        false
+      end
+
+      # Returns the wrapped value.
+      #: () -> untyped
+      def value!
+        @value
+      end
+
+      # Returns nil for Success.
+      #: () -> nil
+      def failure
+        nil
+      end
+
+      # Pattern matching support - array destructuring.
+      #: () -> Array[untyped]
+      def deconstruct
+        @value.is_a?(::Array) ? @value : [@value]
+      end
+
+      # Pattern matching support - hash destructuring.
+      # Delegates to the inner value if it responds to deconstruct_keys.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(keys)
+        if @value.respond_to?(:deconstruct_keys)
+          @value.deconstruct_keys(keys)
+        else
+          {value: @value}
+        end
+      end
+
+      #: (untyped) -> bool
+      def ==(other)
+        other.is_a?(Success) && other.value == @value
+      end
+      alias_method :eql?, :==
+
+      #: () -> Integer
+      def hash
+        [self.class, @value].hash
+      end
+
+      #: () -> String
+      def inspect
+        "Success(#{@value.inspect})"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/typed_operation/result.rb

@@ -0,0 +1,39 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "result/success"
+require_relative "result/failure"
+require_relative "result/adapters/built_in"
+require_relative "result/adapters/dry_monads"
+require_relative "result/mixin"
+
+module TypedOperation
+  # Result types for representing success and failure outcomes.
+  #
+  # TypedOperation provides built-in Success and Failure types that work
+  # out of the box. You can also configure it to use Dry::Monads or a
+  # custom adapter.
+  #
+  # @example Default usage (built-in types)
+  #   result = MyPipeline.call(input)
+  #   result.success?  # => true or false
+  #   result.value!    # => the value (raises on failure)
+  #
+  # @example Configure to use Dry::Monads
+  #   TypedOperation.configure do |config|
+  #     config.result_adapter = :dry_monads
+  #   end
+  #
+  # @example Pattern matching
+  #   case result
+  #   in Success[value]
+  #     handle_success(value)
+  #   in Failure[error]
+  #     handle_failure(error)
+  #   end
+  #
+  module Result
+    # Alias for easy access to UnwrapError from Result module
+    UnwrapError = TypedOperation::UnwrapError
+  end
+end

data/lib/typed_operation/version.rb

@@ -1,3 +1,7 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
 module TypedOperation
-  VERSION = "1.0.0.beta3"
+  #: String
+  VERSION = "1.0.0.beta4"
 end

data/lib/typed_operation.rb

@@ -1,20 +1,37 @@
+# rbs_inline: enabled
+
 require "literal"
 
 require "typed_operation/version"
 require "typed_operation/railtie" if defined?(Rails::Railtie)
+require "typed_operation/result"
+require "typed_operation/configuration"
 require "typed_operation/operations/introspection"
 require "typed_operation/operations/parameters"
 require "typed_operation/operations/partial_application"
-require "typed_operation/operations/callable"
 require "typed_operation/operations/lifecycle"
 require "typed_operation/operations/property_builder"
 require "typed_operation/operations/executable"
+require "typed_operation/operations/composition"
 require "typed_operation/curried"
+require "typed_operation/instrumentation"
+require "typed_operation/explainable"
 require "typed_operation/immutable_base"
 require "typed_operation/base"
 require "typed_operation/partially_applied"
 require "typed_operation/prepared"
+require "typed_operation/callable_resolver"
+require "typed_operation/chains/chained_operation"
+require "typed_operation/chains/sequence_chain"
+require "typed_operation/chains/splat_chain"
+require "typed_operation/chains/smart_chain"
+require "typed_operation/chains/map_chain"
+require "typed_operation/chains/fallback_chain"
+require "typed_operation/context"
+require "typed_operation/pipeline"
 
+# TypedOperation provides a framework for defining type-safe, composable operations
+# with support for partial application, currying, and parameter validation.
 module TypedOperation
   class InvalidOperationError < StandardError; end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: typed_operation
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta3
+  version: 1.0.0.beta4
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 bindir: bin
 cert_chain: []
-date: 2025-04-07 00:00:00.000000000 Z
+date: 2025-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: literal
@@ -49,9 +49,22 @@ files:
 - lib/typed_operation.rb
 - lib/typed_operation/action_policy_auth.rb
 - lib/typed_operation/base.rb
+- lib/typed_operation/callable_resolver.rb
+- lib/typed_operation/chains/chained_operation.rb
+- lib/typed_operation/chains/fallback_chain.rb
+- lib/typed_operation/chains/map_chain.rb
+- lib/typed_operation/chains/sequence_chain.rb
+- lib/typed_operation/chains/smart_chain.rb
+- lib/typed_operation/chains/splat_chain.rb
+- lib/typed_operation/configuration.rb
+- lib/typed_operation/context.rb
 - lib/typed_operation/curried.rb
+- lib/typed_operation/explainable.rb
 - lib/typed_operation/immutable_base.rb
-- lib/typed_operation/operations/callable.rb
+- lib/typed_operation/instrumentation.rb
+- lib/typed_operation/instrumentation/trace.rb
+- lib/typed_operation/instrumentation/tree_formatter.rb
+- lib/typed_operation/operations/composition.rb
 - lib/typed_operation/operations/executable.rb
 - lib/typed_operation/operations/introspection.rb
 - lib/typed_operation/operations/lifecycle.rb
@@ -59,8 +72,19 @@ files:
 - lib/typed_operation/operations/partial_application.rb
 - lib/typed_operation/operations/property_builder.rb
 - lib/typed_operation/partially_applied.rb
+- lib/typed_operation/pipeline.rb
+- lib/typed_operation/pipeline/builder.rb
+- lib/typed_operation/pipeline/chainable_wrapper.rb
+- lib/typed_operation/pipeline/empty_pipeline_chain.rb
+- lib/typed_operation/pipeline/step_wrapper.rb
 - lib/typed_operation/prepared.rb
 - lib/typed_operation/railtie.rb
+- lib/typed_operation/result.rb
+- lib/typed_operation/result/adapters/built_in.rb
+- lib/typed_operation/result/adapters/dry_monads.rb
+- lib/typed_operation/result/failure.rb
+- lib/typed_operation/result/mixin.rb
+- lib/typed_operation/result/success.rb
 - lib/typed_operation/version.rb
 homepage: https://github.com/stevegeek/typed_operation
 licenses:

data/lib/typed_operation/operations/callable.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module TypedOperation
-  module Operations
-    module Callable
-      def self.included(base)
-        base.extend(CallableMethods)
-      end
-
-      module CallableMethods
-        def call(...)
-          new(...).call
-        end
-
-        def to_proc
-          method(:call).to_proc
-        end
-      end
-
-      include CallableMethods
-    end
-  end
-end