solid-result 2.0.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Solid::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
+
+      return value if IgnoredTypes.include?(type)
+
+      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/solid/result/contract/interface.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class Solid::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/solid/result/contract/type_checker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Solid::Result::Contract
+  class TypeChecker
+    attr_reader :result_type, :expectations
+
+    def initialize(result_type, expectations:)
+      @result_type = result_type
+
+      @expectations = expectations
+    end
+
+    def allow!(type)
+      expectations.type!(type)
+    end
+
+    def allow?(types)
+      validate(types, expected: expectations, allow_empty: false)
+    end
+
+    def allow_success?(types)
+      validate(types, expected: expectations.success, allow_empty: true)
+    end
+
+    def allow_failure?(types)
+      validate(types, expected: expectations.failure, allow_empty: true)
+    end
+
+    private
+
+    def validate(types, expected:, allow_empty:)
+      (allow_empty && types.empty?) || types.any? { |type| expected.type!(type) == result_type }
+    end
+  end
+
+  private_constant :TypeChecker
+end

data/lib/solid/result/contract.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Solid::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/solid/result/data.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  class Data
+    attr_reader :kind, :type, :value
+
+    def initialize(kind, type, value)
+      @kind = kind
+      @type = type.to_sym
+      @value = value
+    end
+
+    def to_h
+      { kind: kind, type: type, value: value }
+    end
+
+    def to_a
+      [kind, type, value]
+    end
+
+    def inspect
+      format(
+        '#<%<class_name>s kind=%<kind>p type=%<type>p value=%<value>p>',
+        class_name: self.class.name, kind: kind, type: type, value: value
+      )
+    end
+
+    alias to_ary to_a
+    alias to_hash to_h
+  end
+
+  private_constant :Data
+end

data/lib/solid/result/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+class Solid::Result::Error < StandardError
+  def self.build(**_kargs)
+    new
+  end
+
+  class NotImplemented < self
+  end
+
+  class MissingTypeArgument < self
+    def initialize(_message = nil)
+      super('A type (argument) is required to invoke the #on/#on_type method')
+    end
+  end
+
+  class UnexpectedOutcome < self
+    def self.build(outcome:, origin:, expected: nil)
+      expected ||= 'Solid::Result::Success or Solid::Result::Failure'
+
+      new("Unexpected outcome: #{outcome.inspect}. The #{origin} must return this object wrapped by #{expected}")
+    end
+  end
+
+  class InvalidResultSource < self
+    def self.build(given_result:, expected_source:)
+      message =
+        "You cannot call #and_then and return a result that does not belong to the same source!\n" \
+        "Expected source: #{expected_source.inspect}\n" \
+        "Given source: #{given_result.send(:source).inspect}\n" \
+        "Given result: #{given_result.inspect}"
+
+      new(message)
+    end
+  end
+
+  class InvalidSourceMethodArity < self
+    def self.build(source:, method:, max_arity:)
+      new("#{source.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
+    end
+  end
+
+  class UnhandledTypes < self
+    def self.build(types:)
+      source = types.size == 1 ? 'This was' : 'These were'
+
+      new("You must handle all cases. #{source} not handled: #{types.map(&:inspect).join(', ')}")
+    end
+  end
+
+  class CallableAndThenDisabled < self
+    def initialize(_message = nil)
+      super(
+        'You cannot use #and_then! as the feature is disabled. ' \
+        'Please use Solid::Result.config.feature.enable!(:and_then!) to enable it.'
+      )
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Solid::Result::EventLogs
+  class Config
+    attr_reader :listener, :trace_id
+
+    def initialize
+      @trace_id = -> {}
+      @listener = Listener::Null.new
+    end
+
+    def listener=(arg)
+      Listener.kind?(arg) or raise ::ArgumentError, "#{arg.inspect} must be a #{Listener}"
+
+      @listener = arg
+    end
+
+    def trace_id=(arg)
+      raise ::ArgumentError, 'must be a lambda with arity 0' unless arg.is_a?(::Proc) && arg.lambda? && arg.arity.zero?
+
+      @trace_id = arg
+    end
+
+    @instance = new
+
+    singleton_class.send(:attr_reader, :instance)
+  end
+end

data/lib/solid/result/event_logs/listener.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Solid::Result::EventLogs
+  module Listener
+    module ClassMethods
+      def around_event_logs?
+        false
+      end
+
+      def around_and_then?
+        false
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def self.extended(base)
+      base.extend(ClassMethods)
+    end
+
+    def self.kind?(arg)
+      (arg.is_a?(::Class) && arg < self) || (arg.is_a?(::Module) && arg.is_a?(self)) || arg.is_a?(Listeners::Chain)
+    end
+
+    def on_start(scope:); end
+
+    def around_event_logs(scope:)
+      yield
+    end
+
+    def around_and_then(scope:, and_then:)
+      yield
+    end
+
+    def on_record(record:); end
+
+    def on_finish(event_logs:); end
+
+    def before_interruption(exception:, event_logs:); end
+  end
+
+  module Listener::Null
+    extend Listener
+
+    def self.new
+      self
+    end
+  end
+end

data/lib/solid/result/event_logs/listeners.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Solid::Result::EventLogs
+  class Listeners
+    class Chain
+      include Listener
+
+      attr_reader :listeners
+
+      def initialize(list)
+        if list.empty? || list.any? { !Listener.kind?(_1) }
+          raise ArgumentError, "listeners must be a list of #{Listener}"
+        end
+
+        around_and_then = list.select(&:around_and_then?)
+        around_event_logs = list.select(&:around_event_logs?)
+
+        raise ArgumentError, 'only one listener can have around_and_then? == true' if around_and_then.size > 1
+        raise ArgumentError, 'only one listener can have around_event_logs? == true' if around_event_logs.size > 1
+
+        @listeners = { list: list, around_and_then: around_and_then[0], around_event_logs: around_event_logs[0] }
+      end
+
+      def new
+        list, around_and_then, around_event_logs = listeners[:list], nil, nil
+
+        instances = list.map do |item|
+          instance = item.new
+          around_and_then = instance if listener?(:around_and_then, instance)
+          around_event_logs = instance if listener?(:around_event_logs, instance)
+
+          instance
+        end
+
+        list.one? ? list[0].new : Listeners.send(:new, instances, around_and_then, around_event_logs)
+      end
+
+      private
+
+      def listener?(name, obj)
+        listener = listeners[name]
+
+        !listener.nil? && (obj.is_a?(listener) || obj == listener)
+      end
+    end
+
+    private_class_method :new
+
+    def self.[](*listeners)
+      Chain.new(listeners)
+    end
+
+    attr_reader :listeners, :around_and_then_listener, :around_event_logs_listener
+
+    private :listeners, :around_and_then_listener, :around_event_logs_listener
+
+    def initialize(listeners, around_and_then_listener, around_event_logs_listener)
+      @listeners = listeners
+      @around_and_then_listener = around_and_then_listener || Listener::Null
+      @around_event_logs_listener = around_event_logs_listener || Listener::Null
+    end
+
+    def on_start(scope:)
+      listeners.each { _1.on_start(scope: scope) }
+    end
+
+    def around_event_logs(scope:, &block)
+      around_event_logs_listener.around_event_logs(scope: scope, &block)
+    end
+
+    def around_and_then(scope:, and_then:, &block)
+      around_and_then_listener.around_and_then(scope: scope, and_then: and_then, &block)
+    end
+
+    def on_record(record:)
+      listeners.each { _1.on_record(record: record) }
+    end
+
+    def on_finish(event_logs:)
+      listeners.each { _1.on_finish(event_logs: event_logs) }
+    end
+
+    def before_interruption(exception:, event_logs:)
+      listeners.each { _1.before_interruption(exception: exception, event_logs: event_logs) }
+    end
+  end
+end

data/lib/solid/result/event_logs/tracking/disabled.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Solid::Result::EventLogs
+  module Tracking::Disabled
+    def self.exec(_name, _desc)
+      EnsureResult[yield]
+    end
+
+    def self.record(result); end
+
+    def self.record_and_then(_type, _data)
+      yield
+    end
+  end
+end

data/lib/solid/result/event_logs/tracking/enabled.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Solid::Result::EventLogs
+  class Tracking::Enabled
+    attr_accessor :tree, :records, :root_started_at, :listener
+
+    private :tree, :tree=, :records, :records=, :root_started_at, :root_started_at=, :listener, :listener=
+
+    def exec(name, desc)
+      event_log_node, scope = start(name, desc)
+
+      result = nil
+
+      listener.around_event_logs(scope: scope) do
+        result = EnsureResult[yield]
+      end
+
+      tree.move_to_root! if event_log_node.root?
+
+      finish(result)
+
+      result
+    rescue ::Exception => e
+      err!(e, event_log_node)
+    end
+
+    def err!(exception, event_log_node)
+      if event_log_node.root?
+        listener.before_interruption(exception: exception, event_logs: map_event_logs)
+
+        reset!
+      end
+
+      raise exception
+    end
+
+    def reset!
+      self.tree = Tracking::EMPTY_TREE
+    end
+
+    def record(result)
+      return if tree.frozen?
+
+      track(result, time: ::Time.now.getutc)
+    end
+
+    def record_and_then(type_arg, arg)
+      return yield if tree.frozen?
+
+      type = type_arg.instance_of?(::Method) ? :method : type_arg
+
+      current_and_then = { type: type, arg: arg }
+      current_and_then[:method_name] = type_arg.name if type == :method
+
+      tree.current.value[1] = current_and_then
+
+      scope, and_then = tree.current_value
+
+      result = nil
+
+      listener.around_and_then(scope: scope, and_then: and_then) { result = yield }
+
+      result
+    end
+
+    def reset_and_then!
+      return if tree.frozen?
+
+      tree.current.value[1] = Tracking::EMPTY_HASH
+    end
+
+    private
+
+    def start(name, desc)
+      name_and_desc = [name, desc]
+
+      tree.frozen? ? root_start(name_and_desc) : tree.insert!(name_and_desc)
+
+      scope = tree.current.value[0]
+
+      listener.on_start(scope: scope)
+
+      [tree.current, scope]
+    end
+
+    def finish(result)
+      node = tree.current
+
+      tree.move_up!
+
+      return unless node.root?
+
+      event_logs = map_event_logs
+
+      result.send(:event_logs=, event_logs)
+
+      listener.on_finish(event_logs: event_logs)
+
+      reset!
+    end
+
+    TreeNodeValueNormalizer = ->(id, (nam, des)) { [{ id: id, name: nam, desc: des }, Tracking::EMPTY_HASH] }
+
+    def root_start(name_and_desc)
+      self.root_started_at = now_in_milliseconds
+
+      self.listener = build_listener
+
+      self.records = []
+
+      self.tree = Tree.new(name_and_desc, normalizer: TreeNodeValueNormalizer)
+    end
+
+    def track(result, time:)
+      record = track_record(result, time)
+
+      records << record
+
+      listener.on_record(record: record)
+
+      record
+    end
+
+    def track_record(result, time)
+      result_data = result.data.to_h
+      result_data[:source] = result.send(:source)
+
+      root, = tree.root_value
+      parent, = tree.parent_value
+      current, and_then = tree.current_value
+
+      { root: root, parent: parent, current: current, result: result_data, and_then: and_then, time: time }
+    end
+
+    def now_in_milliseconds
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    def map_event_logs
+      duration = (now_in_milliseconds - root_started_at)
+
+      trace_id = Config.instance.trace_id.call
+
+      ids = { tree: tree.ids, matrix: tree.ids_matrix, level_parent: tree.ids_level_parent }
+
+      metadata = { duration: duration, trace_id: trace_id, ids: ids }
+
+      { version: Tracking::VERSION, records: records, metadata: metadata }
+    end
+
+    def build_listener
+      Config.instance.listener.new
+    rescue ::StandardError => e
+      err = "#{e.message} (#{e.class}); Backtrace: #{e.backtrace&.join(', ')}"
+
+      warn("Fallback to #{Listener::Null} because registered listener raised an exception: #{err}")
+
+      Listener::Null.new
+    end
+  end
+end

data/lib/solid/result/event_logs/tracking.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Solid::Result
+  module EventLogs
+    module Tracking
+      require_relative 'tracking/enabled'
+      require_relative 'tracking/disabled'
+
+      VERSION = 1
+
+      EMPTY_ARRAY = [].freeze
+      EMPTY_HASH = {}.freeze
+      EMPTY_TREE = Tree.new(nil).freeze
+      EMPTY_IDS = { tree: EMPTY_ARRAY, matrix: EMPTY_HASH, level_parent: EMPTY_HASH }.freeze
+      EMPTY = {
+        version: VERSION,
+        records: EMPTY_ARRAY,
+        metadata: { duration: 0, ids: EMPTY_IDS, trace_id: nil }.freeze
+      }.freeze
+
+      def self.instance
+        ::Solid::Result::Config.instance.feature.enabled?(:event_logs) ? Tracking::Enabled.new : Tracking::Disabled
+      end
+    end
+  end
+end