bcdd-result 0.11.0 → 0.13.0

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Account
+  class OwnerCreation
+    include BCDD::Context.mixin
+    include BCDD::Result::RollbackOnFailure
+
+    def call(**input)
+      BCDD::Result.transitions(name: self.class.name) do
+        Given(input)
+          .and_then(:normalize_input)
+          .and_then(:validate_input)
+          .then { |result|
+            rollback_on_failure {
+              result
+                .and_then(:create_owner)
+                .and_then(:create_account)
+                .and_then(:link_owner_to_account)
+            }
+          }.and_expose(:account_owner_created, %i[user account])
+      end
+    end
+
+    private
+
+    def normalize_input(**options)
+      uuid = String(options.fetch(:uuid) { ::SecureRandom.uuid }).strip.downcase
+
+      Continue(uuid:)
+    end
+
+    def validate_input(uuid:, owner:)
+      err = ::Hash.new { |hash, key| hash[key] = [] }
+
+      err[:uuid] << 'must be an UUID' unless uuid.match?(/\A[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}\z/i)
+      err[:owner] << 'must be a Hash' unless owner.is_a?(::Hash)
+
+      err.empty? ? Continue() : Failure(:invalid_input, **err)
+    end
+
+    def create_owner(owner:, **)
+      ::User::Creation.new.call(**owner).handle do |on|
+        on.success { |output| Continue(user: { record: output[:user], token: output[:token] }) }
+        on.failure { |output| Failure(:invalid_owner, **output) }
+      end
+    end
+
+    def create_account(uuid:, **)
+      ::RuntimeBreaker.try_to_interrupt(env: 'BREAK_ACCOUNT_CREATION')
+
+      account = ::Account.create(uuid:)
+
+      account.persisted? ? Continue(account:) : Failure(:invalid_record, **account.errors.messages)
+    end
+
+    def link_owner_to_account(account:, user:, **)
+      Member.create!(account:, user: user.fetch(:record), role: :owner)
+
+      Continue()
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Account < ActiveRecord::Base
+  has_many :memberships, inverse_of: :account, dependent: :destroy, class_name: '::Account::Member'
+  has_many :users, through: :memberships, inverse_of: :accounts
+
+  where_ownership = -> { where(account_members: {role: :owner}) }
+
+  has_one :ownership, where_ownership, dependent: nil, inverse_of: :account, class_name: '::Account::Member'
+  has_one :owner, through: :ownership, source: :user
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class User
+  class Creation
+    include BCDD::Context.mixin
+    include BCDD::Result::RollbackOnFailure
+
+    def call(**input)
+      BCDD::Result.transitions(name: self.class.name) do
+        Given(input)
+          .and_then(:normalize_input)
+          .and_then(:validate_input)
+          .and_then(:validate_email_uniqueness)
+          .then { |result|
+            rollback_on_failure {
+              result
+                .and_then(:create_user)
+                .and_then(:create_user_token)
+            }
+          }
+          .and_expose(:user_created, %i[user token])
+      end
+    end
+
+    private
+
+    def normalize_input(name:, email:, **options)
+      name = String(name).strip.gsub(/\s+/, ' ')
+      email = String(email).strip.downcase
+
+      uuid = String(options.fetch(:uuid) { ::SecureRandom.uuid }).strip.downcase
+
+      Continue(uuid:, name:, email:)
+    end
+
+    def validate_input(uuid:, name:, email:, password:, password_confirmation:)
+      err = ::Hash.new { |hash, key| hash[key] = [] }
+
+      err[:uuid] << 'must be an UUID' unless uuid.match?(/\A[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}\z/i)
+      err[:name] << 'must be present' if name.blank?
+      err[:email] << 'must be email' unless email.match?(::URI::MailTo::EMAIL_REGEXP)
+      err[:password] << 'must be present' if password.blank?
+      err[:password_confirmation] << 'must be present' if password_confirmation.blank?
+
+      err.empty? ? Continue() : Failure(:invalid_input, **err)
+    end
+
+    def validate_email_uniqueness(email:, **)
+      ::User.exists?(email:) ? Failure(:email_already_taken) : Continue()
+    end
+
+    def create_user(uuid:, name:, email:, password:, password_confirmation:)
+      ::RuntimeBreaker.try_to_interrupt(env: 'BREAK_USER_CREATION')
+
+      user = ::User.create(uuid:, name:, email:, password:, password_confirmation:)
+
+      user.persisted? ? Continue(user:) : Failure(:invalid_record, **user.errors.messages)
+    end
+
+    def create_user_token(user:, **)
+      Token::Creation.new.call(user: user).handle do |on|
+        on.success { |output| Continue(token: output[:token]) }
+        on.failure { raise 'Token creation failed' }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class User::Token
+  class Creation
+    include BCDD::Context.mixin
+
+    def call(**input)
+      BCDD::Result.transitions(name: self.class.name) do
+        Given(input)
+          .and_then(:normalize_input)
+          .and_then(:validate_input)
+          .and_then(:validate_token_existence)
+          .and_then(:create_token)
+          .and_expose(:token_created, %i[token])
+      end
+    end
+
+    private
+
+    def normalize_input(**options)
+      Continue(executed_at: options.fetch(:executed_at) { ::Time.current })
+    end
+
+    def validate_input(user:, executed_at:)
+      err = ::Hash.new { |hash, key| hash[key] = [] }
+
+      err[:user] << 'must be a User' unless user.is_a?(::User)
+      err[:user] << 'must be persisted' unless user.try(:persisted?)
+      err[:executed_at] << 'must be a time' unless executed_at.is_a?(::Time)
+
+      err.empty? ? Continue() : Failure(:invalid_user, **err)
+    end
+
+    def validate_token_existence(user:, **)
+      user.token.nil? ? Continue() : Failure(:token_already_exists)
+    end
+
+    def create_token(user:, executed_at:, **)
+      ::RuntimeBreaker.try_to_interrupt(env: 'BREAK_USER_TOKEN_CREATION')
+
+      token = user.create_token(
+        access_token: ::SecureRandom.hex(24),
+        refresh_token: ::SecureRandom.hex(24),
+        access_token_expires_at: executed_at + 15.days,
+        refresh_token_expires_at: executed_at + 30.days
+      )
+
+      token.persisted? ? Continue(token:) : Failure(:token_creation_failed, **token.errors.messages)
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class User::Token < ActiveRecord::Base
+  self.table_name = 'user_tokens'
+
+  belongs_to :user, inverse_of: :token
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class User < ActiveRecord::Base
+  has_secure_password
+
+  has_many :memberships, inverse_of: :user, dependent: :destroy, class_name: '::Account::Member'
+  has_many :accounts, through: :memberships, inverse_of: :users
+
+  where_ownership = -> { where(account_members: { role: :owner }) }
+
+  has_one :ownership, where_ownership, inverse_of: :user, class_name: '::Account::Member'
+  has_one :account, through: :ownership, inverse_of: :owner
+
+  has_one :token, inverse_of: :user, dependent: :destroy, class_name: '::User::Token'
+end

data/examples/single_listener/config/boot.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'sqlite3', '~> 1.7'
+  gem 'bcrypt', '~> 3.1.20'
+  gem 'activerecord', '~> 7.1', '>= 7.1.3', require: 'active_record'
+  gem 'bcdd-result', path: '../../'
+end
+
+require 'active_support/all'

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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?
+end

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_transitions_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_transitions_listener.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class SingleTransitionsListener
+  include BCDD::Result::Transitions::Listener
+
+  # A listener will be initialized before the first transition, 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.
+  #
+  # @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 transitions in the same block.
+  # It can be used to perform an instrumentation (measure/report) of the transitions.
+  #
+  # @param scope: {:id=>1, :name=>"SomeOperation", :desc=>"Optional description"}
+  def around_transitions(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 = ->(transitions, buffer, hide_given_and_continue) do
+    ids_matrix = transitions.dig(:metadata, :ids_matrix)
+
+    messages = buffer.filter_map { |(id, msg)| "#{'   ' * ids_matrix[id].last}#{msg}" if ids_matrix[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.
+  #
+  # @param transitions:
+  # {
+  #   :version => 1,
+  #   :metadata => {
+  #     :duration => 0,
+  #     :trace_id => nil,
+  #     :ids_tree => [0, [[1, []], [2, []]]],
+  #     :ids_matrix => {0 => [0, 0], 1 => [1, 1], 2 => [2, 1]}
+  #   },
+  #   :records => [
+  #     # ...
+  #   ]
+  # }
+  def on_finish(transitions:)
+    messages = MapNestedMessages[transitions, @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.
+  #
+  # @param exception: Exception
+  # @param transitions: Hash
+  def before_interruption(exception:, transitions:)
+    messages = MapNestedMessages[transitions, @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) }
+
+    backtrace = bc.clean(exception.backtrace)
+
+    puts "\nException: #{exception.message} (#{exception.class}); Backtrace: #{backtrace.join(", ")}"
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class CallableAndThen::Caller
+    def self.call(source, value:, injected_value:, method_name:)
+      method = callable_method(source, method_name)
+
+      Transitions.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?(::BCDD::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/bcdd/result/callable_and_then/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class BCDD::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/bcdd/result/callable_and_then/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class BCDD::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/bcdd/result/callable_and_then.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class BCDD::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/bcdd/result/config/switchers/features.rb

@@ -10,7 +10,11 @@ class BCDD::Result
         },
         transitions: {
           default: true,
-          affects: %w[BCDD::Result BCDD::Result::Context]
+          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        },
+        and_then!: {
+          default: false,
+          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
         }
       }.transform_values!(&:freeze).freeze
 

data/lib/bcdd/result/config.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'singleton'
-
 require_relative 'config/options'
 require_relative 'config/switcher'
 require_relative 'config/switchers/addons'
@@ -11,7 +9,7 @@ require_relative 'config/switchers/pattern_matching'
 
 class BCDD::Result
   class Config
-    include Singleton
+    include ::Singleton
 
     attr_reader :addon, :feature, :constant_alias, :pattern_matching
 
@@ -20,6 +18,15 @@ class BCDD::Result
       @feature = Features.switcher
       @constant_alias = ConstantAliases.switcher
       @pattern_matching = PatternMatching.switcher
+      @and_then_ = CallableAndThen::Config.new
+    end
+
+    def transitions
+      Transitions::Config.instance
+    end
+
+    def and_then!
+      @and_then_
     end
 
     def freeze
@@ -27,6 +34,8 @@ class BCDD::Result
       feature.freeze
       constant_alias.freeze
       pattern_matching.freeze
+      and_then!.freeze
+      transitions.freeze
 
       super
     end
@@ -45,7 +54,9 @@ class BCDD::Result
     end
 
     def inspect
-      "#<#{self.class.name} options=#{options.keys.sort.inspect}>"
+      "#<#{self.class.name} " \
+        "options=#{options.keys.sort.inspect} " \
+        "and_then!=#{and_then!.options.inspect}>"
     end
   end
 end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Context::CallableAndThen
+    class Caller < 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)
+          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(:acc).then { _1.merge!(value.merge(_1)) } } if result.is_a?(Context)
+
+        raise Error::UnexpectedOutcome.build(outcome: result, origin: source, expected: Context::EXPECTED_OUTCOME)
+      end
+
+      private_class_method :call_proc!, :call_method!
+    end
+  end
+end

data/lib/bcdd/result/context/expectations/mixin.rb

@@ -9,7 +9,7 @@ class BCDD::Result::Context
     module Addons
       module Continue
         private def Continue(**value)
-          Success.new(type: :continued, value: value, subject: 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, subject: self)
+          Success(::BCDD::Result::IgnoredTypes::GIVEN, **value)
         end
       end