solid-result 2.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/solid_result'
+
+require 'db/setup'
+
+require 'lib/solid/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/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 Solid::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\/solid\/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/examples/single_listener/lib/solid/result/rollback_on_failure.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Solid::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/lib/solid/failure.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Solid
+  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/solid/output/callable_and_then.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Solid
+  module Output::CallableAndThen
+    class Caller < Result::CallableAndThen::Caller
+      module KeyArgs
+        def self.parameters?(source)
+          parameters = source.parameters.map(&:first)
+
+          !parameters.empty? && parameters.all?(/\Akey/)
+        end
+
+        def self.invalid_arity(source, method)
+          Result::CallableAndThen::Error::InvalidArity.build(source: source, method: method, arity: 'only keyword args')
+        end
+      end
+
+      def self.call_proc!(source, value, _injected_value)
+        return source.call(**value) if KeyArgs.parameters?(source)
+
+        raise KeyArgs.invalid_arity(source, :call)
+      end
+
+      def self.call_method!(source, method, value, _injected_value)
+        return source.send(method.name, **value) if KeyArgs.parameters?(method)
+
+        raise KeyArgs.invalid_arity(source, method.name)
+      end
+
+      def self.ensure_result_object(source, value, result)
+        return result.tap { result.send(:memo).then { _1.merge!(value.merge(_1)) } } if result.is_a?(Output)
+
+        raise Result::Error::UnexpectedOutcome.build(outcome: result, origin: source,
+                                                     expected: Output::EXPECTED_OUTCOME)
+      end
+
+      private_class_method :call_proc!, :call_method!
+    end
+  end
+end

data/lib/solid/output/expectations/mixin.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Solid::Output
+  module Expectations::Mixin
+    Factory = Solid::Result::Expectations::Mixin::Factory
+
+    Methods = Solid::Result::Expectations::Mixin::Methods
+
+    module Addons
+      module Continue
+        private def Continue(**value)
+          Success(::Solid::Result::IgnoredTypes::CONTINUE, **value)
+        end
+      end
+
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          Success(::Solid::Result::IgnoredTypes::GIVEN, **value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
+
+      def self.options(config_flags)
+        ::Solid::Result::Config::Options.addon(map: config_flags, from: OPTIONS)
+      end
+    end
+  end
+end

data/lib/solid/output/expectations.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Solid::Output
+  class Expectations < Solid::Result::Expectations
+    require_relative 'expectations/mixin'
+
+    def self.mixin_module
+      Mixin
+    end
+
+    def self.result_factory_without_expectations
+      ::Solid::Output
+    end
+
+    private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
+
+    def Success(type, **value)
+      _ResultAs(Success, type, value)
+    end
+
+    def Failure(type, **value)
+      _ResultAs(Failure, type, value)
+    end
+  end
+end

data/lib/solid/output/failure.rb

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

data/lib/solid/output/mixin.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class Solid::Output
+  module Mixin
+    Factory = Solid::Result::Mixin::Factory
+
+    module Methods
+      def Success(type, **value)
+        _ResultAs(Success, type, value)
+      end
+
+      def Failure(type, **value)
+        _ResultAs(Failure, type, value)
+      end
+
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, source: self, terminal: terminal)
+      end
+    end
+
+    module Addons
+      module Continue
+        def Success(type, **value)
+          _ResultAs(Success, type, value, terminal: true)
+        end
+
+        private def Continue(**value)
+          _ResultAs(Success, ::Solid::Result::IgnoredTypes::CONTINUE, value)
+        end
+      end
+
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          _ResultAs(Success, ::Solid::Result::IgnoredTypes::GIVEN, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
+
+      def self.options(config_flags)
+        ::Solid::Result::Config::Options.addon(map: config_flags, from: OPTIONS)
+      end
+    end
+  end
+
+  def self.mixin_module
+    Mixin
+  end
+
+  def self.result_factory
+    ::Solid::Output
+  end
+
+  private_class_method :mixin_module, :result_factory
+end

data/lib/solid/output/success.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Solid::Output
+  class Error < Solid::Result::Error
+    InvalidExposure = ::Class.new(self)
+  end
+
+  class Success < self
+    include ::Solid::Success
+
+    FetchValues = ->(memo_values, keys) do
+      fetched_values = memo_values.fetch_values(*keys)
+
+      keys.zip(fetched_values).to_h
+    rescue ::KeyError => e
+      message = "#{e.message}. Available to expose: #{memo_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!
+
+      memo_values = memo.merge(value)
+
+      value_to_expose = FetchValues.call(memo_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/solid/output.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+class Solid::Output < Solid::Result
+  require_relative 'output/failure'
+  require_relative 'output/success'
+  require_relative 'output/mixin'
+  require_relative 'output/expectations'
+  require_relative 'output/callable_and_then'
+
+  EXPECTED_OUTCOME = 'Solid::Output::Success or Solid::Output::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'
+
+    @memo = {}
+
+    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)
+
+    memo.merge!(injected_value)
+
+    super(source, injected_value, _call: _call)
+  end
+
+  def [](key)
+    value[key]
+  end
+
+  def dig(...)
+    value.dig(...)
+  end
+
+  def fetch(...)
+    value.fetch(...)
+  end
+
+  def slice(...)
+    value.slice(...)
+  end
+
+  def values_at(...)
+    value.values_at(...)
+  end
+
+  def fetch_values(...)
+    value.fetch_values(...)
+  end
+
+  protected
+
+  attr_reader :memo
+
+  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)
+    memo.merge!(value.merge(injected_value))
+
+    case SourceMethodArity[method]
+    when 0 then source.send(method.name)
+    when 1 then source.send(method.name, **memo)
+    else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 1)
+    end
+  end
+
+  def call_and_then_block!(block)
+    memo.merge!(value)
+
+    block.call(memo)
+  end
+
+  def call_and_then_callable!(source, value:, injected_value:, method_name:)
+    memo.merge!(value.merge(injected_value))
+
+    CallableAndThen::Caller.call(source, value: memo, 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?(Solid::Output)
+
+    return result.tap { _1.memo.merge!(memo) } 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