bcdd-result 0.13.0 → 1.0.0

data/examples/single_listener/app/models/account/owner_creation.rb

@@ -6,7 +6,7 @@ class Account
     include BCDD::Result::RollbackOnFailure
 
     def call(**input)
-      BCDD::Result.transitions(name: self.class.name) do
+      BCDD::Result.event_logs(name: self.class.name) do
         Given(input)
           .and_then(:normalize_input)
           .and_then(:validate_input)

data/examples/single_listener/app/models/user/creation.rb

@@ -6,7 +6,7 @@ class User
     include BCDD::Result::RollbackOnFailure
 
     def call(**input)
-      BCDD::Result.transitions(name: self.class.name) do
+      BCDD::Result.event_logs(name: self.class.name) do
         Given(input)
           .and_then(:normalize_input)
           .and_then(:validate_input)

data/examples/single_listener/app/models/user/token/creation.rb

@@ -5,7 +5,7 @@ class User::Token
     include BCDD::Context.mixin
 
     def call(**input)
-      BCDD::Result.transitions(name: self.class.name) do
+      BCDD::Result.event_logs(name: self.class.name) do
         Given(input)
           .and_then(:normalize_input)
           .and_then(:validate_input)

data/examples/single_listener/config/initializers/bcdd.rb

@@ -3,8 +3,6 @@
 BCDD::Result.config.then do |config|
   config.addon.enable!(:continue)
 
-  config.constant_alias.enable!('BCDD::Context')
-
   config.pattern_matching.disable!(:nil_as_valid_value_checking)
 
   # config.feature.disable!(:expectations) if Rails.env.production?

data/examples/single_listener/config.rb

@@ -10,7 +10,7 @@ require_relative 'config/initializers/bcdd'
 require 'db/setup'
 
 require 'lib/bcdd/result/rollback_on_failure'
-require 'lib/single_transitions_listener'
+require 'lib/single_event_logs_listener'
 require 'lib/runtime_breaker'
 
 require 'app/models/account'

data/examples/single_listener/lib/{single_transitions_listener.rb → single_event_logs_listener.rb}

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-class SingleTransitionsListener
-  include BCDD::Result::Transitions::Listener
+class SingleEventLogsListener
+  include BCDD::Result::EventLogs::Listener
 
-  # A listener will be initialized before the first transition, and it is discarded after the last one.
+  # A listener will be initialized before the first event log, and it is discarded after the last one.
   def initialize
     @buffer = []
   end
 
-  # This method will be called before each transition block.
-  # The parent transition block will be called first in the case of nested transition blocks.
+  # This method will be called before each event log block.
+  # The parent event log block will be called first in the case of nested blocks.
   #
   # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
   def on_start(scope:)
@@ -18,11 +18,11 @@ class SingleTransitionsListener
     @buffer << [id, "##{id} #{name} - #{desc}".chomp('- ')]
   end
 
-  # This method will wrap all the transitions in the same block.
-  # It can be used to perform an instrumentation (measure/report) of the transitions.
+  # This method will wrap all the event_logs in the same block.
+  # It can be used to perform an instrumentation (measure/report) of the event_logs.
   #
   # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
-  def around_transitions(scope:)
+  def around_event_logs(scope:)
     yield
   end
 
@@ -56,43 +56,46 @@ class SingleTransitionsListener
     @buffer << [id, " * #{kind}(#{type}) from method: #{method_name}".chomp('from method: ')]
   end
 
-  MapNestedMessages = ->(transitions, buffer, hide_given_and_continue) do
-    ids_matrix = transitions.dig(:metadata, :ids_matrix)
+  MapNestedMessages = ->(event_logs, buffer, hide_given_and_continue) do
+    ids_level_parent = event_logs.dig(:metadata, :ids, :level_parent)
 
-    messages = buffer.filter_map { |(id, msg)| "#{'   ' * ids_matrix[id].last}#{msg}" if ids_matrix[id] }
+    messages = buffer.filter_map { |(id, msg)| "#{'   ' * ids_level_parent[id].first}#{msg}" if ids_level_parent[id] }
 
     messages.reject! { _1.match?(/\(_(given|continue)_\)/) } if hide_given_and_continue
 
     messages
   end
 
-  # This method will be called at the end of the transitions tracking.
+  # This method will be called at the end of the event_logs tracking.
   #
-  # @param transitions:
+  # @param event_logs:
   # {
   #   :version => 1,
   #   :metadata => {
   #     :duration => 0,
   #     :trace_id => nil,
-  #     :ids_tree => [0, [[1, []], [2, []]]],
-  #     :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
+  #     :ids => {
+  #       :tree => [0, [[1, []], [2, []]]],
+  #       :matrix => { 0 => [0, 0], 1 => [1, 1], 2 => [2, 1]},
+  #       :level_parent => { 0 => [0, 0], 1 => [1, 0], 2 => [1, 0]}
+  #     }
   #   },
   #   :records => [
   #     # ...
   #   ]
   # }
-  def on_finish(transitions:)
-    messages = MapNestedMessages[transitions, @buffer, ENV['HIDE_GIVEN_AND_CONTINUE']]
+  def on_finish(event_logs:)
+    messages = MapNestedMessages[event_logs, @buffer, ENV['HIDE_GIVEN_AND_CONTINUE']]
 
     puts messages.join("\n")
   end
 
-  # This method will be called when an exception is raised during the transitions tracking.
+  # This method will be called when an exception is raised during the event_logs tracking.
   #
   # @param exception: Exception
-  # @param transitions: Hash
-  def before_interruption(exception:, transitions:)
-    messages = MapNestedMessages[transitions, @buffer, ENV['HIDE_GIVEN_AND_CONTINUE']]
+  # @param event_logs: Hash
+  def before_interruption(exception:, event_logs:)
+    messages = MapNestedMessages[event_logs, @buffer, ENV['HIDE_GIVEN_AND_CONTINUE']]
 
     puts messages.join("\n")
 
@@ -101,8 +104,14 @@ class SingleTransitionsListener
     bc.add_silencer { |line| /lib\/bcdd\/result/.match?(line) }
     bc.add_silencer { |line| line.include?(RUBY_VERSION) }
 
-    backtrace = bc.clean(exception.backtrace)
+    dir = "#{FileUtils.pwd[1..]}/"
 
-    puts "\nException: #{exception.message} (#{exception.class}); Backtrace: #{backtrace.join(", ")}"
+    listener_filename = File.basename(__FILE__).chomp('.rb')
+
+    cb = bc.clean(exception.backtrace)
+    cb.each { _1.sub!(dir, '') }
+    cb.reject! { _1.match?(/block \(\d levels?\) in|in `block in|internal:kernel|#{listener_filename}/) }
+
+    puts "\nException:\n  #{exception.message} (#{exception.class})\n\nBacktrace:\n  #{cb.join("\n  ")}"
   end
 end

data/lib/bcdd/{result/context → context}/callable_and_then.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class BCDD::Result
+module BCDD
   module Context::CallableAndThen
-    class Caller < CallableAndThen::Caller
+    class Caller < Result::CallableAndThen::Caller
       module KeyArgs
         def self.parameters?(source)
           parameters = source.parameters.map(&:first)
@@ -11,7 +11,7 @@ class BCDD::Result
         end
 
         def self.invalid_arity(source, method)
-          CallableAndThen::Error::InvalidArity.build(source: source, method: method, arity: 'only keyword args')
+          Result::CallableAndThen::Error::InvalidArity.build(source: source, method: method, arity: 'only keyword args')
         end
       end
 
@@ -30,7 +30,8 @@ class BCDD::Result
       def self.ensure_result_object(source, value, result)
         return result.tap { result.send(:acc).then { _1.merge!(value.merge(_1)) } } if result.is_a?(Context)
 
-        raise Error::UnexpectedOutcome.build(outcome: result, origin: source, expected: Context::EXPECTED_OUTCOME)
+        raise Result::Error::UnexpectedOutcome.build(outcome: result, origin: source,
+                                                     expected: Context::EXPECTED_OUTCOME)
       end
 
       private_class_method :call_proc!, :call_method!

data/lib/bcdd/{result/context → context}/expectations/mixin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Context
+class BCDD::Context
   module Expectations::Mixin
     Factory = BCDD::Result::Expectations::Mixin::Factory
 

data/lib/bcdd/{result/context → context}/expectations.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Context
+class BCDD::Context
   class Expectations < BCDD::Result::Expectations
     require_relative 'expectations/mixin'
 
@@ -9,7 +9,7 @@ class BCDD::Result::Context
     end
 
     def self.result_factory_without_expectations
-      ::BCDD::Result::Context
+      ::BCDD::Context
     end
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations

data/lib/bcdd/context/failure.rb

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

data/lib/bcdd/{result/context → context}/mixin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Context
+class BCDD::Context
   module Mixin
     Factory = BCDD::Result::Mixin::Factory
 
@@ -50,7 +50,7 @@ class BCDD::Result::Context
   end
 
   def self.result_factory
-    ::BCDD::Result::Context
+    ::BCDD::Context
   end
 
   private_class_method :mixin_module, :result_factory

data/lib/bcdd/{result/context → context}/success.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-class BCDD::Result
-  class Context::Error < BCDD::Result::Error
+class BCDD::Context
+  class Error < BCDD::Result::Error
     InvalidExposure = ::Class.new(self)
   end
 
-  class Context::Success < Context
-    include ::BCDD::Result::Success::Methods
+  class Success < self
+    include ::BCDD::Success
 
     FetchValues = ->(acc_values, keys) do
       fetched_values = acc_values.fetch_values(*keys)
@@ -15,7 +15,7 @@ class BCDD::Result
     rescue ::KeyError => e
       message = "#{e.message}. Available to expose: #{acc_values.keys.map(&:inspect).join(', ')}"
 
-      raise Context::Error::InvalidExposure, message
+      raise Error::InvalidExposure, message
     end
 
     def and_expose(type, keys, terminal: true)
@@ -23,7 +23,7 @@ class BCDD::Result
         raise ::ArgumentError, 'keys must be an Array of Symbols'
       end
 
-      Transitions.tracking.reset_and_then!
+      EventLogs.tracking.reset_and_then!
 
       acc_values = acc.merge(value)
 

data/lib/bcdd/context.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class BCDD::Context < BCDD::Result
+  require_relative 'context/failure'
+  require_relative 'context/success'
+  require_relative 'context/mixin'
+  require_relative 'context/expectations'
+  require_relative 'context/callable_and_then'
+
+  EXPECTED_OUTCOME = 'BCDD::Context::Success or BCDD::Context::Failure'
+
+  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:, source: nil, expectations: nil, terminal: nil)
+    value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
+
+    @acc = {}
+
+    super
+  end
+
+  def and_then(method_name = nil, **injected_value, &block)
+    super(method_name, injected_value, &block)
+  end
+
+  def and_then!(source, **injected_value)
+    _call = injected_value.delete(:_call)
+
+    acc.merge!(injected_value)
+
+    super(source, injected_value, _call: _call)
+  end
+
+  protected
+
+  attr_reader :acc
+
+  private
+
+  SourceMethodArity = ->(method) do
+    return 0 if method.arity.zero?
+
+    parameters = method.parameters.map(&:first)
+
+    return 1 if !parameters.empty? && parameters.all?(/\Akey/)
+
+    -1
+  end
+
+  def call_and_then_source_method!(method, injected_value)
+    acc.merge!(value.merge(injected_value))
+
+    case SourceMethodArity[method]
+    when 0 then source.send(method.name)
+    when 1 then source.send(method.name, **acc)
+    else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 1)
+    end
+  end
+
+  def call_and_then_block!(block)
+    acc.merge!(value)
+
+    block.call(acc)
+  end
+
+  def call_and_then_callable!(source, value:, injected_value:, method_name:)
+    acc.merge!(value.merge(injected_value))
+
+    CallableAndThen::Caller.call(source, value: acc, injected_value: injected_value, method_name: method_name)
+  end
+
+  def ensure_result_object(result, origin:)
+    raise_unexpected_outcome_error(result, origin) unless result.is_a?(BCDD::Context)
+
+    return result.tap { _1.acc.merge!(acc) } if result.source.equal?(source)
+
+    raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
+  end
+
+  def raise_unexpected_outcome_error(result, origin)
+    raise Error::UnexpectedOutcome.build(outcome: result, origin: origin, expected: EXPECTED_OUTCOME)
+  end
+
+  private_constant :SourceMethodArity
+end

data/lib/bcdd/failure.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BCDD
+  module Failure
+    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 kind
+      :failure
+    end
+  end
+end

data/lib/bcdd/result/_self.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+class BCDD::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?(::BCDD::Result)
+
+    return result if result.source.equal?(source)
+
+    raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
+  end
+end

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

@@ -5,7 +5,7 @@ class BCDD::Result
     def self.call(source, value:, injected_value:, method_name:)
       method = callable_method(source, method_name)
 
-      Transitions.tracking.record_and_then(method, injected_value) do
+      EventLogs.tracking.record_and_then(method, injected_value) do
         result =
           if source.is_a?(::Proc)
             call_proc!(source, value, injected_value)

data/lib/bcdd/result/config/switchers/addons.rb

@@ -5,9 +5,9 @@ class BCDD::Result
     module Addons
       AFFECTS = %w[
         BCDD::Result.mixin
-        BCDD::Result::Context.mixin
+        BCDD::Context.mixin
         BCDD::Result::Expectations.mixin
-        BCDD::Result::Context::Expectations.mixin
+        BCDD::Context::Expectations.mixin
       ].freeze
 
       OPTIONS = {

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

@@ -4,9 +4,7 @@ class BCDD::Result
   class Config
     module ConstantAliases
       MAPPING = {
-        'Result' => { target: ::Object, name: :Result, value: ::BCDD::Result },
-        'Context' => { target: ::Object, name: :Context, value: ::BCDD::Result::Context },
-        'BCDD::Context' => { target: ::BCDD, name: :Context, value: ::BCDD::Result::Context }
+        'Result' => { target: ::Object, name: :Result, value: ::BCDD::Result }
       }.transform_values!(&:freeze).freeze
 
       OPTIONS = MAPPING.to_h do |option_name, mapping|

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

@@ -6,20 +6,20 @@ class BCDD::Result
       OPTIONS = {
         expectations: {
           default: true,
-          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+          affects: %w[BCDD::Result::Expectations BCDD::Context::Expectations]
         },
-        transitions: {
+        event_logs: {
           default: true,
-          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+          affects: %w[BCDD::Result BCDD::Context BCDD::Result::Expectations BCDD::Context::Expectations]
         },
         and_then!: {
           default: false,
-          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+          affects: %w[BCDD::Result BCDD::Context BCDD::Result::Expectations BCDD::Context::Expectations]
         }
       }.transform_values!(&:freeze).freeze
 
       Listener = ->(option_name, _bool) do
-        Thread.current[Transitions::THREAD_VAR_NAME] = nil if option_name == :transitions
+        Thread.current[EventLogs::THREAD_VAR_NAME] = nil if option_name == :event_logs
       end
 
       def self.switcher

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

@@ -6,7 +6,7 @@ class BCDD::Result
       OPTIONS = {
         nil_as_valid_value_checking: {
           default: false,
-          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+          affects: %w[BCDD::Result::Expectations BCDD::Context::Expectations]
         }
       }.transform_values!(&:freeze).freeze