solid-result 2.0.0

data/lib/solid/result/_self.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  attr_accessor :unknown, :event_logs
+
+  attr_reader :source, :data, :type_checker, :terminal
+
+  protected :source
+
+  private :unknown, :unknown=, :type_checker, :event_logs=
+
+  def self.config
+    Config.instance
+  end
+
+  def self.configuration(freeze: true)
+    yield(config)
+
+    freeze and config.freeze
+  end
+
+  def initialize(type:, value:, source: nil, expectations: nil, terminal: nil)
+    data = Data.new(kind, type, value)
+
+    @type_checker = Contract.evaluate(data, expectations)
+    @source = source
+    @terminal = kind == :failure || (terminal && !IgnoredTypes.include?(type))
+    @data = data
+
+    self.unknown = true
+    self.event_logs = EventLogs::Tracking::EMPTY
+
+    EventLogs.tracking.record(self)
+  end
+
+  def terminal?
+    terminal
+  end
+
+  def type
+    data.type
+  end
+
+  def value
+    data.value
+  end
+
+  def type?(arg)
+    type_checker.allow!(arg.to_sym) == type
+  end
+
+  def success?(_type = nil)
+    raise Error::NotImplemented
+  end
+
+  def failure?(_type = nil)
+    raise Error::NotImplemented
+  end
+
+  def value_or(&_block)
+    raise Error::NotImplemented
+  end
+
+  def on(*types, &block)
+    raise Error::MissingTypeArgument if types.empty?
+
+    tap { known(block) if type_checker.allow?(types) }
+  end
+
+  def on_success(*types, &block)
+    tap { known(block) if type_checker.allow_success?(types) && success? }
+  end
+
+  def on_failure(*types, &block)
+    tap { known(block) if type_checker.allow_failure?(types) && failure? }
+  end
+
+  def on_unknown
+    tap { yield(value, type) if unknown }
+  end
+
+  def and_then(method_name = nil, injected_value = nil, &block)
+    return self if terminal?
+
+    method_name && block and raise ::ArgumentError, 'method_name and block are mutually exclusive'
+
+    method_name ? call_and_then_source_method(method_name, injected_value) : call_and_then_block(block)
+  end
+
+  def and_then!(source, injected_value = nil, _call: nil)
+    raise Error::CallableAndThenDisabled unless Config.instance.feature.enabled?(:and_then!)
+
+    return self if terminal?
+
+    call_and_then_callable!(source, value: value, injected_value: injected_value, method_name: _call)
+  end
+
+  def handle
+    handler = Handler.new(self, type_checker: type_checker)
+
+    yield handler
+
+    handler.send(:outcome)
+  end
+
+  def ==(other)
+    self.class == other.class && type == other.type && value == other.value
+  end
+
+  def hash
+    [self.class, type, value].hash
+  end
+
+  def inspect
+    format('#<%<class_name>s type=%<type>p value=%<value>p>', class_name: self.class.name, type: type, value: value)
+  end
+
+  def deconstruct
+    [type, value]
+  end
+
+  TYPE_AND_VALUE = %i[type value].freeze
+
+  def deconstruct_keys(keys)
+    output = TYPE_AND_VALUE.each_with_object({}) do |key, hash|
+      hash[key] = send(key) if keys.include?(key)
+    end
+
+    output.empty? ? value : output
+  end
+
+  def method_missing(name, *args, &block)
+    name.end_with?('?') ? is?(name.to_s.chomp('?')) : super
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    name.end_with?('?') || super
+  end
+
+  alias is? type?
+  alias eql? ==
+  alias on_type on
+
+  private
+
+  def kind
+    :unknown
+  end
+
+  def known(block)
+    self.unknown = false
+
+    block.call(value, type)
+  end
+
+  def call_and_then_source_method(method_name, injected_value)
+    method = source.method(method_name)
+
+    EventLogs.tracking.record_and_then(method, injected_value) do
+      result = call_and_then_source_method!(method, injected_value)
+
+      ensure_result_object(result, origin: :method)
+    end
+  end
+
+  def call_and_then_source_method!(method, injected_value)
+    case method.arity
+    when 0 then source.send(method.name)
+    when 1 then source.send(method.name, value)
+    when 2 then source.send(method.name, value, injected_value)
+    else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 2)
+    end
+  end
+
+  def call_and_then_block(block)
+    EventLogs.tracking.record_and_then(:block, nil) do
+      result = call_and_then_block!(block)
+
+      ensure_result_object(result, origin: :block)
+    end
+  end
+
+  def call_and_then_block!(block)
+    block.call(value)
+  end
+
+  def call_and_then_callable!(source, value:, injected_value:, method_name:)
+    CallableAndThen::Caller.call(source, value: value, injected_value: injected_value, method_name: method_name)
+  end
+
+  def ensure_result_object(result, origin:)
+    raise Error::UnexpectedOutcome.build(outcome: result, origin: origin) unless result.is_a?(::Solid::Result)
+
+    return result if result.source.equal?(source)
+
+    raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
+  end
+end

data/lib/solid/result/callable_and_then/caller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class CallableAndThen::Caller
+    def self.call(source, value:, injected_value:, method_name:)
+      method = callable_method(source, method_name)
+
+      EventLogs.tracking.record_and_then(method, injected_value) do
+        result =
+          if source.is_a?(::Proc)
+            call_proc!(source, value, injected_value)
+          else
+            call_method!(source, method, value, injected_value)
+          end
+
+        ensure_result_object(source, value, result)
+      end
+    end
+
+    def self.call_proc!(source, value, injected_value)
+      case source.arity
+      when 1 then source.call(value)
+      when 2 then source.call(value, injected_value)
+      else raise CallableAndThen::Error::InvalidArity.build(source: source, method: :call, arity: '1..2')
+      end
+    end
+
+    def self.call_method!(source, method, value, injected_value)
+      case method.arity
+      when 1 then source.send(method.name, value)
+      when 2 then source.send(method.name, value, injected_value)
+      else raise CallableAndThen::Error::InvalidArity.build(source: source, method: method.name, arity: '1..2')
+      end
+    end
+
+    def self.callable_method(source, method_name)
+      source.method(method_name || Config.instance.and_then!.default_method_name_to_call)
+    end
+
+    def self.ensure_result_object(source, _value, result)
+      return result if result.is_a?(::Solid::Result)
+
+      raise Error::UnexpectedOutcome.build(outcome: result, origin: source)
+    end
+
+    private_class_method :new, :allocate
+    private_class_method :call_proc!, :call_method!, :callable_method, :ensure_result_object
+  end
+end

data/lib/solid/result/callable_and_then/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class CallableAndThen::Config
+    attr_accessor :default_method_name_to_call
+
+    def initialize
+      self.default_method_name_to_call = :call
+    end
+
+    def options
+      { default_method_name_to_call: default_method_name_to_call }
+    end
+  end
+end

data/lib/solid/result/callable_and_then/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class CallableAndThen::Error < Error
+    class InvalidArity < self
+      def self.build(source:, method:, arity:)
+        new("Invalid arity for #{source.class}##{method} method. Expected arity: #{arity}")
+      end
+    end
+  end
+end

data/lib/solid/result/callable_and_then.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  module CallableAndThen
+    require_relative 'callable_and_then/error'
+    require_relative 'callable_and_then/config'
+    require_relative 'callable_and_then/caller'
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Solid::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.select(all_flags, config:, from:)
+        with_defaults(all_flags, config)
+          .filter_map { |name, truthy| [name, from[name]] if truthy }
+          .to_h
+      end
+
+      def self.addon(map:, from:)
+        select(map, config: :addon, from: from)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class Solid::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/solid/result/config/switchers/addons.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Config
+    module Addons
+      AFFECTS = %w[
+        Solid::Result.mixin
+        Solid::Output.mixin
+        Solid::Result::Expectations.mixin
+        Solid::Output::Expectations.mixin
+      ].freeze
+
+      OPTIONS = {
+        continue: { default: false, affects: AFFECTS },
+        given: { default: true, affects: AFFECTS }
+      }.transform_values!(&:freeze).freeze
+
+      def self.switcher
+        Switcher.new(options: OPTIONS)
+      end
+    end
+
+    private_constant :Addons
+  end
+end

data/lib/solid/result/config/switchers/constant_aliases.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Config
+    module ConstantAliases
+      MAPPING = {
+        'Result' => { target: ::Object, name: :Result, value: ::Solid::Result }
+      }.transform_values!(&:freeze).freeze
+
+      OPTIONS = MAPPING.to_h do |option_name, mapping|
+        affects = mapping.fetch(:target).name.freeze
+
+        [option_name, { default: false, affects: [affects].freeze }]
+      end.freeze
+
+      Listener = ->(option_name, bool) do
+        mapping = MAPPING.fetch(option_name)
+
+        target, name, value = mapping.fetch_values(:target, :name, :value)
+
+        defined = target.const_defined?(name, false)
+
+        bool ? 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 :ConstantAliases
+  end
+end

data/lib/solid/result/config/switchers/features.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Config
+    module Features
+      OPTIONS = {
+        expectations: {
+          default: true,
+          affects: %w[Solid::Result::Expectations Solid::Output::Expectations]
+        },
+        event_logs: {
+          default: true,
+          affects: %w[Solid::Result Solid::Output Solid::Result::Expectations Solid::Output::Expectations]
+        },
+        and_then!: {
+          default: false,
+          affects: %w[Solid::Result Solid::Output Solid::Result::Expectations Solid::Output::Expectations]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      Listener = ->(option_name, _bool) do
+        Thread.current[EventLogs::THREAD_VAR_NAME] = nil if option_name == :event_logs
+      end
+
+      def self.switcher
+        Switcher.new(options: OPTIONS, listener: Listener)
+      end
+    end
+
+    private_constant :Features
+  end
+end

data/lib/solid/result/config/switchers/pattern_matching.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Config
+    module PatternMatching
+      OPTIONS = {
+        nil_as_valid_value_checking: {
+          default: false,
+          affects: %w[Solid::Result::Expectations Solid::Output::Expectations]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      def self.switcher
+        Switcher.new(options: OPTIONS)
+      end
+    end
+
+    private_constant :PatternMatching
+  end
+end

data/lib/solid/result/config.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'config/options'
+require_relative 'config/switcher'
+require_relative 'config/switchers/addons'
+require_relative 'config/switchers/constant_aliases'
+require_relative 'config/switchers/features'
+require_relative 'config/switchers/pattern_matching'
+
+class Solid::Result
+  class Config
+    attr_reader :addon, :feature, :constant_alias, :pattern_matching
+
+    def initialize
+      @addon = Addons.switcher
+      @feature = Features.switcher
+      @constant_alias = ConstantAliases.switcher
+      @pattern_matching = PatternMatching.switcher
+      @and_then_ = CallableAndThen::Config.new
+    end
+
+    def event_logs
+      EventLogs::Config.instance
+    end
+
+    def and_then!
+      @and_then_
+    end
+
+    def freeze
+      addon.freeze
+      feature.freeze
+      constant_alias.freeze
+      pattern_matching.freeze
+      and_then!.freeze
+      event_logs.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} " \
+        "and_then!=#{and_then!.options.inspect}>"
+    end
+
+    @instance = new
+
+    singleton_class.send(:attr_reader, :instance)
+  end
+end

data/lib/solid/result/contract/disabled.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  module Contract::Disabled
+    extend Contract::Interface
+
+    EMPTY_SET = ::Set.new.freeze
+
+    def self.allowed_types
+      EMPTY_SET
+    end
+
+    def self.type?(_type)
+      true
+    end
+
+    def self.type!(type)
+      type
+    end
+
+    def self.type_and_value!(_data); end
+
+    private_constant :EMPTY_SET
+  end
+end

data/lib/solid/result/contract/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Solid::Result::Contract::Error < Solid::Result::Error
+  class UnexpectedType < self
+    def self.build(type:, allowed_types:)
+      new("type :#{type} is not allowed. Allowed types: #{allowed_types.map(&:inspect).join(', ')}")
+    end
+  end
+
+  class UnexpectedValue < self
+    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/solid/result/contract/evaluator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Contract::Evaluator
+    include Contract::Interface
+
+    attr_reader :allowed_types, :success, :failure
+
+    def initialize(success, failure)
+      @success = success
+      @failure = failure
+
+      @allowed_types = (success.allowed_types | failure.allowed_types).freeze
+    end
+
+    def type?(type)
+      success_disabled = success == Contract::Disabled
+      failure_disabled = failure == Contract::Disabled
+
+      return Contract::Disabled.type?(type) if success_disabled && failure_disabled
+
+      (!success_disabled && success.type?(type)) || (!failure_disabled && failure.type?(type))
+    end
+
+    def type!(type)
+      return type if type?(type)
+
+      raise Contract::Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
+    end
+
+    def type_and_value!(data)
+      self.for(data).type_and_value!(data)
+    end
+
+    private
+
+    def for(data)
+      case data.kind
+      when :unknown then Contract::Disabled
+      when :success then success
+      else failure
+      end
+    end
+  end
+end

data/lib/solid/result/contract/for_types.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Contract::ForTypes
+    include Contract::Interface
+
+    attr_reader :allowed_types
+
+    def initialize(types)
+      @allowed_types = Array(types).map(&:to_sym).to_set.freeze
+    end
+
+    def type?(type)
+      IgnoredTypes.include?(type) || allowed_types.member?(type)
+    end
+
+    def type!(type)
+      return type if type?(type)
+
+      raise Contract::Error::UnexpectedType.build(type: type, allowed_types: allowed_types)
+    end
+
+    def type_and_value!(data)
+      type!(data.type)
+
+      nil
+    end
+  end
+end