bcdd-result 0.6.0 → 0.8.0

data/Rakefile

@@ -3,10 +3,16 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
+Rake::TestTask.new(:test_configuration) do |t|
+  t.libs += %w[lib test]
+
+  t.test_files = FileList.new('test/**/configuration_test.rb')
+end
+
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs += %w[lib test]
+
+  t.test_files = FileList.new('test/**/*_test.rb')
 end
 
 require 'rubocop/rake_task'

data/Steepfile

@@ -10,7 +10,7 @@ target :lib do
   # check 'app/models/**/*.rb'        # Glob
   # ignore 'lib/templates/*.rb'
 
-  # library 'pathname'              # Standard libraries
+  library 'singleton'               # Standard libraries
   # library 'strong_json'           # Gems
 
   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)

data/lib/bcdd/result/config/constant_alias.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module ConstantAlias
+      RESULT = 'Result'
+
+      OPTIONS = {
+        RESULT => { default: false, affects: %w[Object] }
+      }.transform_values!(&:freeze).freeze
+
+      MAPPING = {
+        RESULT => { target: ::Object, name: :Result, value: ::BCDD::Result }
+      }.transform_values!(&:freeze).freeze
+
+      Listener = ->(option_name, boolean) do
+        mapping = MAPPING.fetch(option_name)
+
+        target, name, value = mapping.fetch_values(:target, :name, :value)
+
+        defined = target.const_defined?(name, false)
+
+        boolean ? defined || target.const_set(name, value) : defined && target.send(:remove_const, name)
+      end
+
+      def self.switcher
+        Switcher.new(options: OPTIONS, listener: Listener)
+      end
+    end
+
+    private_constant :ConstantAlias
+  end
+end

data/lib/bcdd/result/config/options.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module Options
+      def self.with_defaults(all_flags, config)
+        all_flags ||= {}
+
+        default_flags = Config.instance.to_h.fetch(config)
+
+        config_flags = all_flags.fetch(config, {})
+
+        default_flags.merge(config_flags).slice(*default_flags.keys)
+      end
+
+      def self.filter_map(all_flags, config:, from:)
+        with_defaults(all_flags, config)
+          .filter_map { |name, truthy| from[name] if truthy }
+      end
+
+      def self.addon(map:, from:)
+        filter_map(map, config: :addon, from: from)
+      end
+    end
+  end
+end

data/lib/bcdd/result/config/switcher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    class Switcher
+      attr_reader :_options, :_affects, :listener
+
+      private :_options, :_affects, :listener
+
+      def initialize(options:, listener: nil)
+        @_options = options.transform_values { _1.fetch(:default) }
+        @_affects = options.transform_values { _1.fetch(:affects) }
+        @listener = listener
+      end
+
+      def inspect
+        "#<#{self.class.name} options=#{_options.inspect}>"
+      end
+
+      def freeze
+        _options.freeze
+        super
+      end
+
+      def to_h
+        _options.dup
+      end
+
+      def options
+        _affects.to_h { |name, affects| [name, { enabled: _options[name], affects: affects }] }
+      end
+
+      def enabled?(name)
+        _options[name] || false
+      end
+
+      def enable!(*names)
+        set_many(names, to: true)
+      end
+
+      def disable!(*names)
+        set_many(names, to: false)
+      end
+
+      private
+
+      def set_many(names, to:)
+        require_option!(names)
+
+        names.each do |name|
+          set_one(name, to)
+
+          listener&.call(name, to)
+        end
+
+        options.slice(*names)
+      end
+
+      def set_one(name, boolean)
+        validate_option!(name)
+
+        _options[name] = boolean
+      end
+
+      def require_option!(names)
+        raise ::ArgumentError, "One or more options required. #{available_options_message}" if names.empty?
+      end
+
+      def validate_option!(name)
+        return if _options.key?(name)
+
+        raise ::ArgumentError, "Invalid option: #{name.inspect}. #{available_options_message}"
+      end
+
+      def available_options_message
+        "Available options: #{_options.keys.map(&:inspect).join(', ')}"
+      end
+    end
+
+    private_constant :Switcher
+  end
+end

data/lib/bcdd/result/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+require_relative 'config/options'
+require_relative 'config/switcher'
+require_relative 'config/constant_alias'
+
+class BCDD::Result
+  class Config
+    include Singleton
+
+    ADDON = {
+      continue: {
+        default: false,
+        affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+      }
+    }.transform_values!(&:freeze).freeze
+
+    FEATURE = {
+      expectations: {
+        default: true,
+        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+      }
+    }.transform_values!(&:freeze).freeze
+
+    PATTERN_MATCHING = {
+      nil_as_valid_value_checking: {
+        default: false,
+        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+      }
+    }.transform_values!(&:freeze).freeze
+
+    attr_reader :addon, :feature, :constant_alias, :pattern_matching
+
+    def initialize
+      @addon = Switcher.new(options: ADDON)
+      @feature = Switcher.new(options: FEATURE)
+      @constant_alias = ConstantAlias.switcher
+      @pattern_matching = Switcher.new(options: PATTERN_MATCHING)
+    end
+
+    def freeze
+      addon.freeze
+      feature.freeze
+      constant_alias.freeze
+      pattern_matching.freeze
+
+      super
+    end
+
+    def options
+      {
+        addon: addon,
+        feature: feature,
+        constant_alias: constant_alias,
+        pattern_matching: pattern_matching
+      }
+    end
+
+    def to_h
+      options.transform_values(&:to_h)
+    end
+
+    def inspect
+      "#<#{self.class.name} options=#{options.keys.sort.inspect}>"
+    end
+
+    private_constant :ADDON, :FEATURE, :PATTERN_MATCHING
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  module Expectations::Mixin
+    Factory = BCDD::Result::Expectations::Mixin::Factory
+
+    METHODS = BCDD::Result::Expectations::Mixin::METHODS
+
+    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(config_flags)
+        ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  class Expectations < BCDD::Result::Expectations
+    require_relative 'expectations/mixin'
+
+    def self.mixin_module
+      Mixin
+    end
+
+    def self.result_factory_without_expectations
+      ::BCDD::Result::Context
+    end
+
+    private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
+
+    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
+  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,41 @@
+# frozen_string_literal: true
+
+class BCDD::Result::Context
+  module Mixin
+    Factory = BCDD::Result::Mixin::Factory
+
+    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(config_flags)
+        ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)
+      end
+    end
+  end
+
+  def self.mixin_module
+    Mixin
+  end
+
+  def self.result_factory
+    ::BCDD::Result::Context
+  end
+
+  private_class_method :mixin_module, :result_factory
+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/contract/for_types_and_values.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Contract::ForTypesAndValues
+    include Contract::Interface
+
+    def initialize(types_and_values, config)
+      @nil_as_valid_value_checking =
+        Config::Options
+          .with_defaults(config, :pattern_matching)
+          .fetch(:nil_as_valid_value_checking)
+
+      @types_and_values = types_and_values.transform_keys(&:to_sym)
+
+      @types_contract = Contract::ForTypes.new(@types_and_values.keys)
+    end
+
+    def allowed_types
+      @types_contract.allowed_types
+    end
+
+    def type?(type)
+      @types_contract.type?(type)
+    end
+
+    def type!(type)
+      @types_contract.type!(type)
+    end
+
+    def type_and_value!(data)
+      type, value = data.type, data.value
+
+      value_checking = @types_and_values[type!(type)]
+
+      checking_result = value_checking === value
+
+      return value if checking_result || (checking_result.nil? && @nil_as_valid_value_checking)
+
+      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,33 @@
+# 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, config) do
+    return Disabled if spec.nil?
+
+    spec.is_a?(::Hash) ? ForTypesAndValues.new(spec, config) : ForTypes.new(Array(spec))
+  end
+
+  def self.new(success:, failure:, config:)
+    Evaluator.new(ToEnsure[success, config], ToEnsure[failure, config])
+  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, 1 or 2.")
+  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