bcdd-result 0.5.0 → 0.7.0

data/lib/bcdd/result/context/expectations/mixin.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  module Expectations::Mixin
+    METHODS = <<~RUBY
+      def Success(...)
+        _Result::Success(...)
+      end
+
+      def Failure(...)
+        _Result::Failure(...)
+      end
+
+      private
+
+      def _Result
+        @_Result ||= Result.with(subject: self)
+      end
+    RUBY
+
+    module Addons
+      module Continuable
+        private def Continue(**value)
+          Success.new(type: :continued, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
+    end
+  end
+end

data/lib/bcdd/result/context/expectations.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  class Expectations
+    require_relative 'expectations/mixin'
+
+    def self.mixin(success: nil, failure: nil, with: nil)
+      addons = Mixin::Addons.options(with)
+
+      mod = ::BCDD::Result::Expectations::Mixin.module!
+      mod.const_set(:Result, new(success: success, failure: failure).freeze)
+      mod.module_eval(Mixin::METHODS)
+      mod.send(:include, *addons) unless addons.empty?
+      mod
+    end
+
+    def initialize(subject: nil, success: nil, failure: nil, contract: nil)
+      @subject = subject
+
+      @contract = contract if contract.is_a?(::BCDD::Result::Contract::Evaluator)
+
+      @contract ||= ::BCDD::Result::Contract.new(success: success, failure: failure).freeze
+    end
+
+    def Success(type, **value)
+      Success.new(type: type, value: value, subject: subject, expectations: contract)
+    end
+
+    def Failure(type, **value)
+      Failure.new(type: type, value: value, subject: subject, expectations: contract)
+    end
+
+    def with(subject:)
+      self.class.new(subject: subject, contract: contract)
+    end
+
+    private
+
+    attr_reader :subject, :contract
+  end
+end

data/lib/bcdd/result/context/failure.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context::Failure < BCDD::Result::Context
+  include BCDD::Result::Failure::Methods
+
+  def and_expose(_type, _keys)
+    self
+  end
+end

data/lib/bcdd/result/context/mixin.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  module Mixin
+    module Methods
+      def Success(type, **value)
+        Success.new(type: type, value: value, subject: self)
+      end
+
+      def Failure(type, **value)
+        Failure.new(type: type, value: value, subject: self)
+      end
+    end
+
+    module Addons
+      module Continuable
+        private def Continue(**value)
+          Success.new(type: :continued, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
+    end
+  end
+
+  def self.mixin(with: nil)
+    addons = Mixin::Addons.options(with)
+
+    mod = ::BCDD::Result::Mixin.module!
+    mod.send(:include, Mixin::Methods)
+    mod.send(:include, *addons) unless addons.empty?
+    mod
+  end
+end

data/lib/bcdd/result/context/success.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context::Success < BCDD::Result::Context
+  include ::BCDD::Result::Success::Methods
+
+  def and_expose(type, keys)
+    unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
+      raise ::ArgumentError, 'keys must be an Array of Symbols'
+    end
+
+    exposed_value = acc.merge(value).slice(*keys)
+
+    self.class.new(type: type, value: exposed_value, subject: subject)
+  end
+end

data/lib/bcdd/result/context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Context < self
+    require_relative 'context/failure'
+    require_relative 'context/success'
+    require_relative 'context/mixin'
+    require_relative 'context/expectations'
+
+    def self.Success(type, **value)
+      Success.new(type: type, value: value)
+    end
+
+    def self.Failure(type, **value)
+      Failure.new(type: type, value: value)
+    end
+
+    def initialize(type:, value:, subject: nil, expectations: nil)
+      value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
+
+      @acc = {}
+
+      super
+    end
+
+    def and_then(method_name = nil, **context_data, &block)
+      super(method_name, context_data, &block)
+    end
+
+    protected
+
+    attr_reader :acc
+
+    private
+
+    SubjectMethodArity = ->(method) do
+      return 0 if method.arity.zero?
+      return 1 if method.parameters.map(&:first).all?(/\Akey/)
+
+      -1
+    end
+
+    def call_subject_method(method_name, context)
+      method = subject.method(method_name)
+
+      acc.merge!(value.merge(context))
+
+      result =
+        case SubjectMethodArity[method]
+        when 0 then subject.send(method_name)
+        when 1 then subject.send(method_name, **acc)
+        else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 1)
+        end
+
+      ensure_result_object(result, origin: :method)
+    end
+
+    def ensure_result_object(result, origin:)
+      raise_unexpected_outcome_error(result, origin) unless result.is_a?(Context)
+
+      return result.tap { _1.acc.merge!(acc) } if result.subject.equal?(subject)
+
+      raise Error::InvalidResultSubject.build(given_result: result, expected_subject: subject)
+    end
+
+    EXPECTED_OUTCOME = 'BCDD::Result::Context::Success or BCDD::Result::Context::Failure'
+
+    def raise_unexpected_outcome_error(result, origin)
+      raise Error::UnexpectedOutcome.build(outcome: result, origin: origin, expected: EXPECTED_OUTCOME)
+    end
+
+    private_constant :SubjectMethodArity, :EXPECTED_OUTCOME
+  end
+end

data/lib/bcdd/result/{expectations/contract → contract}/disabled.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
+class BCDD::Result
   module Contract::Disabled
     extend Contract::Interface
 
-    EMPTY_SET = Set.new.freeze
+    EMPTY_SET = ::Set.new.freeze
 
     def self.allowed_types
       EMPTY_SET

data/lib/bcdd/result/{expectations → contract}/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations::Error < BCDD::Result::Error
+class BCDD::Result::Contract::Error < BCDD::Result::Error
   class UnexpectedType < self
     def self.build(type:, allowed_types:)
       new("type :#{type} is not allowed. Allowed types: #{allowed_types.map(&:inspect).join(', ')}")
@@ -8,8 +8,10 @@ class BCDD::Result::Expectations::Error < BCDD::Result::Error
   end
 
   class UnexpectedValue < self
-    def self.build(type:, value:)
-      new("value #{value.inspect} is not allowed for :#{type} type")
+    def self.build(type:, value:, cause: nil)
+      cause_message = " (#{cause.message})" if cause
+
+      new("value #{value.inspect} is not allowed for :#{type} type#{cause_message}")
     end
   end
 end

data/lib/bcdd/result/{expectations/contract → contract}/evaluator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
+class BCDD::Result
   class Contract::Evaluator
     include Contract::Interface
 
@@ -25,7 +25,7 @@ class BCDD::Result::Expectations
     def type!(type)
       return type if type?(type)
 
-      raise Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
+      raise Contract::Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
     end
 
     def type_and_value!(data)

data/lib/bcdd/result/{expectations/contract → contract}/for_types.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
+class BCDD::Result
   class Contract::ForTypes
     include Contract::Interface
 
@@ -17,7 +17,7 @@ class BCDD::Result::Expectations
     def type!(type)
       return type if type?(type)
 
-      raise Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
+      raise Contract::Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
     end
 
     def type_and_value!(data)

data/lib/bcdd/result/{expectations/contract → contract}/for_types_and_values.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
+class BCDD::Result
   class Contract::ForTypesAndValues
     include Contract::Interface
 
@@ -23,15 +23,17 @@ class BCDD::Result::Expectations
     end
 
     def type_and_value!(data)
-      type = data.type
-      value = data.value
-      allowed_value = @types_and_values[type!(type)]
+      type, value = data.type, data.value
 
-      return value if allowed_value === value
+      value_checking = @types_and_values[type!(type)]
 
-      raise Error::UnexpectedValue.build(type: type, value: value)
-    rescue NoMatchingPatternError
-      raise Error::UnexpectedValue.build(type: data.type, value: data.value)
+      checking_result = value_checking === value
+
+      return value if checking_result || (Contract.nil_as_valid_value_checking? && checking_result.nil?)
+
+      raise Contract::Error::UnexpectedValue.build(type: type, value: value)
+    rescue ::NoMatchingPatternError => e
+      raise Contract::Error::UnexpectedValue.build(type: data.type, value: data.value, cause: e)
     end
   end
 end

data/lib/bcdd/result/contract/interface.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Contract::Interface
+    def allowed_types
+      raise Error::NotImplemented
+    end
+
+    def type?(_type)
+      raise Error::NotImplemented
+    end
+
+    def type!(_type)
+      raise Error::NotImplemented
+    end
+
+    def type_and_value!(_data)
+      raise Error::NotImplemented
+    end
+  end
+end

data/lib/bcdd/result/{expectations → contract}/type_checker.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
+module BCDD::Result::Contract
   class TypeChecker
     attr_reader :result_type, :expectations
 

data/lib/bcdd/result/contract.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Contract
+  require_relative 'contract/error'
+  require_relative 'contract/type_checker'
+  require_relative 'contract/interface'
+  require_relative 'contract/evaluator'
+  require_relative 'contract/disabled'
+  require_relative 'contract/for_types'
+  require_relative 'contract/for_types_and_values'
+
+  NONE = Evaluator.new(Disabled, Disabled).freeze
+
+  def self.evaluate(data, contract)
+    contract ||= NONE
+
+    contract.type_and_value!(data)
+
+    TypeChecker.new(data.type, expectations: contract)
+  end
+
+  ToEnsure = ->(spec) do
+    return Disabled if spec.nil?
+
+    spec.is_a?(::Hash) ? ForTypesAndValues.new(spec) : ForTypes.new(Array(spec))
+  end
+
+  def self.new(success:, failure:)
+    Evaluator.new(ToEnsure[success], ToEnsure[failure])
+  end
+
+  @nil_as_valid_value_checking = false
+
+  def self.nil_as_valid_value_checking!(enabled: true)
+    @nil_as_valid_value_checking = enabled
+  end
+
+  def self.nil_as_valid_value_checking?
+    @nil_as_valid_value_checking
+  end
+
+  private_constant :ToEnsure
+end

data/lib/bcdd/result/error.rb

@@ -15,16 +15,14 @@ class BCDD::Result::Error < StandardError
   end
 
   class UnexpectedOutcome < self
-    def self.build(outcome:, origin:)
-      message =
-        "Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by " \
-        'BCDD::Result::Success or BCDD::Result::Failure'
+    def self.build(outcome:, origin:, expected: nil)
+      expected ||= 'BCDD::Result::Success or BCDD::Result::Failure'
 
-      new(message)
+      new("Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by #{expected}")
     end
   end
 
-  class WrongResultSubject < self
+  class InvalidResultSubject < self
     def self.build(given_result:, expected_subject:)
       message =
         "You cannot call #and_then and return a result that does not belong to the subject!\n" \
@@ -36,9 +34,9 @@ class BCDD::Result::Error < StandardError
     end
   end
 
-  class WrongSubjectMethodArity < self
-    def self.build(subject:, method:)
-      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0 or 1.")
+  class InvalidSubjectMethodArity < self
+    def self.build(subject:, method:, max_arity:)
+      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
     end
   end
 

data/lib/bcdd/result/expectations/mixin.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Expectations::Mixin
+    METHODS = <<~RUBY
+      def Success(...)
+        _Result.Success(...)
+      end
+
+      def Failure(...)
+        _Result.Failure(...)
+      end
+
+      private
+
+      def _Result
+        @_Result ||= Result.with(subject: self)
+      end
+    RUBY
+
+    module Addons
+      module Continuable
+        private def Continue(value)
+          Success.new(type: :continued, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
+    end
+
+    def self.module!
+      ::Module.new do
+        def self.included(base); base.const_set(:ResultExpectationsMixin, self); end
+        def self.extended(base); base.const_set(:ResultExpectationsMixin, self); end
+      end
+    end
+  end
+end

data/lib/bcdd/result/expectations.rb

@@ -1,62 +1,41 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Expectations
-  require_relative 'expectations/error'
-  require_relative 'expectations/contract'
-  require_relative 'expectations/type_checker'
-
-  MIXIN_METHODS = <<~RUBY
-    def Success(...)
-      _expected_result::Success(...)
+class BCDD::Result
+  class Expectations
+    require_relative 'expectations/mixin'
+
+    def self.mixin(success: nil, failure: nil, with: nil)
+      addons = Mixin::Addons.options(with)
+
+      mod = Mixin.module!
+      mod.const_set(:Result, new(success: success, failure: failure).freeze)
+      mod.module_eval(Mixin::METHODS)
+      mod.send(:include, *addons) unless addons.empty?
+      mod
     end
 
-    def Failure(...)
-      _expected_result::Failure(...)
-    end
+    def initialize(subject: nil, success: nil, failure: nil, contract: nil)
+      @subject = subject
 
-    private
+      @contract = contract if contract.is_a?(Contract::Evaluator)
 
-    def _expected_result
-      @_expected_result ||= Expected.with(subject: self)
+      @contract ||= Contract.new(success: success, failure: failure).freeze
     end
-  RUBY
-
-  def self.mixin(success: nil, failure: nil)
-    mod = Module.new
-    mod.const_set(:Expected, new(success: success, failure: failure).freeze)
-    mod.module_eval(MIXIN_METHODS)
-    mod
-  end
-
-  def self.evaluate(data, expectations)
-    expectations ||= Contract::NONE
-
-    expectations.type_and_value!(data)
-
-    TypeChecker.new(data.type, expectations: expectations)
-  end
-
-  def initialize(subject: nil, success: nil, failure: nil, contract: nil)
-    @subject = subject
 
-    @contract = contract if contract.is_a?(Contract::Evaluator)
+    def Success(type, value = nil)
+      Success.new(type: type, value: value, subject: subject, expectations: contract)
+    end
 
-    @contract ||= Contract.new(success: success, failure: failure).freeze
-  end
+    def Failure(type, value = nil)
+      Failure.new(type: type, value: value, subject: subject, expectations: contract)
+    end
 
-  def Success(type, value = nil)
-    ::BCDD::Result::Success.new(type: type, value: value, subject: subject, expectations: contract)
-  end
+    def with(subject:)
+      self.class.new(subject: subject, contract: contract)
+    end
 
-  def Failure(type, value = nil)
-    ::BCDD::Result::Failure.new(type: type, value: value, subject: subject, expectations: contract)
-  end
+    private
 
-  def with(subject:)
-    self.class.new(subject: subject, contract: contract)
+    attr_reader :subject, :contract
   end
-
-  private
-
-  attr_reader :subject, :contract
 end

data/lib/bcdd/result/failure/methods.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Failure::Methods
+  def success?(_type = nil)
+    false
+  end
+
+  def failure?(type = nil)
+    type.nil? || type_checker.allow_failure?([type])
+  end
+
+  def value_or
+    yield(value)
+  end
+
+  private
+
+  def name
+    :failure
+  end
+end

data/lib/bcdd/result/failure.rb

@@ -2,23 +2,9 @@
 
 class BCDD::Result
   class Failure < self
-    def success?(_type = nil)
-      false
-    end
+    require_relative 'failure/methods'
 
-    def failure?(type = nil)
-      type.nil? || type_checker.allow_failure?([type])
-    end
-
-    def value_or
-      yield
-    end
-
-    private
-
-    def name
-      :failure
-    end
+    include Methods
   end
 
   def self.Failure(type, value = nil)

data/lib/bcdd/result/mixin.rb

@@ -2,12 +2,44 @@
 
 class BCDD::Result
   module Mixin
-    def Success(type, value = nil)
-      Success.new(type: type, value: value, subject: self)
+    module Methods
+      def Success(type, value = nil)
+        Success.new(type: type, value: value, subject: self)
+      end
+
+      def Failure(type, value = nil)
+        Failure.new(type: type, value: value, subject: self)
+      end
+    end
+
+    module Addons
+      module Continuable
+        private def Continue(value)
+          Success(:continued, value)
+        end
+      end
+
+      OPTIONS = { Continue: Continuable }.freeze
+
+      def self.options(names)
+        Array(names).filter_map { |name| OPTIONS[name] }
+      end
     end
 
-    def Failure(type, value = nil)
-      Failure.new(type: type, value: value, subject: self)
+    def self.module!
+      ::Module.new do
+        def self.included(base); base.const_set(:ResultMixin, self); end
+        def self.extended(base); base.const_set(:ResultMixin, self); end
+      end
     end
   end
+
+  def self.mixin(with: nil)
+    addons = Mixin::Addons.options(with)
+
+    mod = Mixin.module!
+    mod.send(:include, Mixin::Methods)
+    mod.send(:include, *addons) unless addons.empty?
+    mod
+  end
 end

data/lib/bcdd/result/success/methods.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Success::Methods
+  def success?(type = nil)
+    type.nil? || type_checker.allow_success?([type])
+  end
+
+  def failure?(_type = nil)
+    false
+  end
+
+  def value_or
+    value
+  end
+
+  private
+
+  def name
+    :success
+  end
+end