bcdd-result 0.12.0 → 1.0.0

data/examples/single_listener/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+require_relative 'config/boot'
+require_relative 'config/initializers/bcdd'
+
+require 'db/setup'
+
+require 'lib/bcdd/result/rollback_on_failure'
+require 'lib/single_event_logs_listener'
+require 'lib/runtime_breaker'
+
+require 'app/models/account'
+require 'app/models/account/member'
+require 'app/models/user'
+require 'app/models/user/token'
+
+require 'app/models/account/owner_creation'
+require 'app/models/user/token/creation'
+require 'app/models/user/creation'

data/examples/single_listener/db/setup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+
+ActiveRecord::Base.establish_connection(
+  host: 'localhost',
+  adapter: 'sqlite3',
+  database: ':memory:'
+)
+
+ActiveRecord::Schema.define do
+  suppress_messages do
+    create_table :accounts do |t|
+      t.string :uuid, null: false, index: {unique: true}
+
+      t.timestamps
+    end
+
+    create_table :users do |t|
+      t.string :uuid, null: false, index: {unique: true}
+      t.string :name, null: false
+      t.string :email, null: false, index: {unique: true}
+      t.string :password_digest, null: false
+
+      t.timestamps
+    end
+
+    create_table :user_tokens do |t|
+      t.belongs_to :user, null: false, foreign_key: true, index: true
+      t.string :access_token, null: false
+      t.string :refresh_token, null: false
+      t.datetime :access_token_expires_at, null: false
+      t.datetime :refresh_token_expires_at, null: false
+
+      t.timestamps
+    end
+
+    create_table :account_members do |t|
+      t.integer :role, null: false, default: 0
+      t.belongs_to :user, null: false, foreign_key: true, index: true
+      t.belongs_to :account, null: false, foreign_key: true, index: true
+
+      t.timestamps
+
+      t.index %i[account_id role], unique: true, where: "(role = 0)"
+      t.index %i[account_id user_id], unique: true
+    end
+  end
+end

data/examples/single_listener/lib/bcdd/result/rollback_on_failure.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BCDD::Result::RollbackOnFailure
+  def rollback_on_failure(model: ::ActiveRecord::Base)
+    result = nil
+
+    model.transaction do
+      result = yield
+
+      raise ::ActiveRecord::Rollback if result.failure?
+    end
+
+    result
+  end
+end

data/examples/single_listener/lib/runtime_breaker.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RuntimeBreaker
+  Interruption = Class.new(StandardError)
+
+  def self.try_to_interrupt(env:)
+    return unless String(ENV[env]).strip.start_with?(/1|t/)
+
+    raise Interruption, "Runtime breaker activated (#{env})"
+  end
+end

data/examples/single_listener/lib/single_event_logs_listener.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+class SingleEventLogsListener
+  include BCDD::Result::EventLogs::Listener
+
+  # 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 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:)
+    scope => { id:, name:, desc: }
+
+    @buffer << [id, "##{id} #{name} - #{desc}".chomp('- ')]
+  end
+
+  # 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_event_logs(scope:)
+    yield
+  end
+
+  # This method will wrap each and_then call.
+  # It can be used to perform an instrumentation (measure/report) of the and_then calls.
+  #
+  # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
+  # @param and_then:
+  #  {:type=>:block, :arg=>:some_injected_value}
+  #  {:type=>:method, :arg=>:some_injected_value, :method_name=>:some_method_name}
+  def around_and_then(scope:, and_then:)
+    yield
+  end
+
+  # This method will be called after each result recording/tracking.
+  #
+  # @param record:
+  # {
+  #   :root => {:id=>0, :name=>"RootOperation", :desc=>nil},
+  #   :parent => {:id=>0, :name=>"RootOperation", :desc=>nil},
+  #   :current => {:id=>1, :name=>"SomeOperation", :desc=>nil},
+  #   :result => {:kind=>:success, :type=>:_continue_, :value=>{some: :thing}, :source=><MyProcess:0x0000000102fd6378>},
+  #   :and_then => {:type=>:method, :arg=>nil, :method_name=>:some_method},
+  #   :time => 2024-01-26 02:53:11.310431 UTC
+  # }
+  def on_record(record:)
+    record => { current: { id: }, result: { kind:, type: } }
+
+    method_name = record.dig(:and_then, :method_name)
+
+    @buffer << [id, " * #{kind}(#{type}) from method: #{method_name}".chomp('from method: ')]
+  end
+
+  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_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 event_logs tracking.
+  #
+  # @param event_logs:
+  # {
+  #   :version => 1,
+  #   :metadata => {
+  #     :duration => 0,
+  #     :trace_id => nil,
+  #     :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(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 event_logs tracking.
+  #
+  # @param exception: Exception
+  # @param event_logs: Hash
+  def before_interruption(exception:, event_logs:)
+    messages = MapNestedMessages[event_logs, @buffer, ENV['HIDE_GIVEN_AND_CONTINUE']]
+
+    puts messages.join("\n")
+
+    bc = ::ActiveSupport::BacktraceCleaner.new
+    bc.add_filter { |line| line.gsub(__dir__.sub('/lib', ''), '').sub(/\A\//, '')}
+    bc.add_silencer { |line| /lib\/bcdd\/result/.match?(line) }
+    bc.add_silencer { |line| line.include?(RUBY_VERSION) }
+
+    dir = "#{FileUtils.pwd[1..]}/"
+
+    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
 
@@ -9,7 +9,7 @@ class BCDD::Result::Context
     module Addons
       module Continue
         private def Continue(**value)
-          Success.new(type: :continued, value: value, source: self)
+          Success(::BCDD::Result::IgnoredTypes::CONTINUE, **value)
         end
       end
 
@@ -17,7 +17,7 @@ class BCDD::Result::Context
         private def Given(*values)
           value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
 
-          Success.new(type: :given, value: value, source: self)
+          Success(::BCDD::Result::IgnoredTypes::GIVEN, **value)
         end
       end
 

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
 
@@ -25,7 +25,7 @@ class BCDD::Result::Context
         end
 
         private def Continue(**value)
-          _ResultAs(Success, :continued, value)
+          _ResultAs(Success, ::BCDD::Result::IgnoredTypes::CONTINUE, value)
         end
       end
 
@@ -33,7 +33,7 @@ class BCDD::Result::Context
         private def Given(*values)
           value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
 
-          _ResultAs(Success, :given, value)
+          _ResultAs(Success, ::BCDD::Result::IgnoredTypes::GIVEN, value)
         end
       end
 
@@ -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/context/success.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class BCDD::Context
+  class Error < BCDD::Result::Error
+    InvalidExposure = ::Class.new(self)
+  end
+
+  class Success < self
+    include ::BCDD::Success
+
+    FetchValues = ->(acc_values, keys) do
+      fetched_values = acc_values.fetch_values(*keys)
+
+      keys.zip(fetched_values).to_h
+    rescue ::KeyError => e
+      message = "#{e.message}. Available to expose: #{acc_values.keys.map(&:inspect).join(', ')}"
+
+      raise Error::InvalidExposure, message
+    end
+
+    def and_expose(type, keys, terminal: true)
+      unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
+        raise ::ArgumentError, 'keys must be an Array of Symbols'
+      end
+
+      EventLogs.tracking.reset_and_then!
+
+      acc_values = acc.merge(value)
+
+      value_to_expose = FetchValues.call(acc_values, keys)
+
+      expectations = type_checker.expectations
+
+      self.class.new(type: type, value: value_to_expose, source: source, terminal: terminal, expectations: expectations)
+    end
+  end
+end

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, source) do
+      EventLogs.tracking.record_and_then(method, injected_value) do
         result =
           if source.is_a?(::Proc)
             call_proc!(source, value, injected_value)