solid-process 0.3.0 → 0.5.0

data/docs/030_INTERMEDIATE_USAGE.md

@@ -0,0 +1,74 @@
+<small>
+
+`Previous` [Basic Usage](./020_BASIC_USAGE.md) | `Next` [Advanced Usage](./040_ADVANCED_USAGE.md)
+
+</small>
+
+# Intermediate Usage
+
+**Status:** 🟡 `in-progress`
+
+In this section, we will learn how to use steps to express the process in a more structured way.
+
+```ruby
+class User::Registration < Solid::Process
+  input do
+    attribute :email, :string
+    attribute :password, :string
+    attribute :password_confirmation, :string
+  end
+
+  def call(attributes)
+    rollback_on_failure {
+      Given(attributes)
+        .and_then(:create_user)
+        .and_then(:create_user_account)
+        .and_then(:create_user_inbox)
+        .and_then(:create_user_token)
+    }
+      .and_then(:send_email_confirmation)
+      .and_expose(:user_registered, [:user])
+  end
+
+  private
+
+  def create_user(email:, password:, password_confirmation:, **)
+    user = User.create(email:, password:, password_confirmation:)
+
+    return Continue(user:) if user.persisted?
+
+    input.errors.merge!(user.errors)
+
+    Failure(:invalid_input, input:)
+  end
+
+  def create_user_account(user:, **)
+    account = Account.create!(uuid: SecureRandom.uuid)
+
+    account.memberships.create!(user:, role: :owner)
+
+    Continue(account:)
+  end
+
+  def create_user_inbox(account:, **)
+    account.task_lists.inbox.create!
+
+    Continue()
+  end
+
+  def create_user_token(user:, **)
+    user.create_token!
+
+    Continue()
+  end
+
+  def send_email_confirmation(user:, **)
+    UserMailer.with(
+      user:,
+      token: user.generate_token_for(:email_confirmation)
+    ).email_confirmation.deliver_later
+
+    Continue()
+  end
+end
+```

data/docs/040_ADVANCED_USAGE.md

@@ -0,0 +1,96 @@
+<small>
+
+`Previous` [Intermediate Usage](./030_INTERMEDIATE_USAGE.md) | `Next` [Error Handling](./050_ERROR_HANDLING.md)
+
+</small>
+
+# Advanced Usage
+
+**Status:** 🟡 `in-progress`
+
+In this section, we will learn how to use input normalization and validation, dependencies, and nested processes.
+
+```ruby
+class User::Registration < Solid::Process
+  deps do
+    attribute :mailer, default: UserMailer
+    attribute :token_creation, default: User::Token::Creation
+    attribute :task_list_creation, default: Account::Task::List::Creation
+  end
+
+  input do
+    attribute :email, :string
+    attribute :password, :string
+    attribute :password_confirmation, :string
+
+    before_validation do
+      self.email = email.downcase.strip
+    end
+
+    with_options presence: true do
+      validates :email, format: User::Email::REGEXP
+      validates :password, confirmation: true, length: {minimum: User::Password::MINIMUM_LENGTH}
+    end
+  end
+
+  def call(attributes)
+    rollback_on_failure {
+      Given(attributes)
+        .and_then(:check_if_email_is_taken)
+        .and_then(:create_user)
+        .and_then(:create_user_account)
+        .and_then(:create_user_inbox)
+        .and_then(:create_user_token)
+    }
+      .and_then(:send_email_confirmation)
+      .and_expose(:user_registered, [:user])
+  end
+
+  private
+
+  def check_if_email_is_taken(email:, **)
+    input.errors.add(:email, "has already been taken") if User.exists?(email:)
+
+    input.errors.any? ? Failure(:invalid_input, input:) : Continue()
+  end
+
+  def create_user(email:, password:, password_confirmation:, **)
+    user = User.create(email:, password:, password_confirmation:)
+
+    return Continue(user:) if user.persisted?
+
+    input.errors.merge!(user.errors)
+
+    Failure(:invalid_input, input:)
+  end
+
+  def create_user_account(user:, **)
+    account = Account.create!(uuid: SecureRandom.uuid)
+
+    account.memberships.create!(user:, role: :owner)
+
+    Continue(account:)
+  end
+
+  def create_user_inbox(account:, **)
+    case deps.task_list_creation.call(account:, inbox: true)
+    in Solid::Success(task_list:) then Continue()
+    end
+  end
+
+  def create_user_token(user:, **)
+    case deps.token_creation.call(user:)
+    in Solid::Success(token:) then Continue()
+    end
+  end
+
+  def send_email_confirmation(user:, **)
+    deps.mailer.with(
+      user:,
+      token: user.generate_token_for(:email_confirmation)
+    ).email_confirmation.deliver_later
+
+    Continue()
+  end
+end
+```

data/docs/050_ERROR_HANDLING.md

@@ -0,0 +1,3 @@
+# Error handling
+
+**Status:** 🔴 `to-do`

data/docs/060_TESTING.md

@@ -0,0 +1,3 @@
+# Testing
+
+**Status:** 🔴 `to-do`

data/docs/070_INSTRUMENTATION.md

@@ -0,0 +1,3 @@
+# Instrumentation
+
+**Status:** 🔴 `to-do`

data/docs/080_RAILS_INTEGRATION.md

@@ -0,0 +1,3 @@
+# Instrumentation
+
+**Status:** 🔴 `to-do`

data/docs/090_INTERNAL_LIBRARIES.md

@@ -0,0 +1,3 @@
+# Internal Libraries
+
+**Status:** 🔴 `to-do`

data/docs/100_PORTS_AND_ADAPTERS.md

@@ -0,0 +1,3 @@
+# Ports and Adapters (Hexagonal Architecture)
+
+**Status:** 🔴 `to-do`

data/lib/solid/input.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "model"
-
 class Solid::Input
   include ::Solid::Model
 end

data/lib/solid/model.rb

@@ -5,6 +5,16 @@ require_relative "model/access"
 module Solid::Model
   extend ::ActiveSupport::Concern
 
+  module ClassMethods
+    def [](...)
+      new(...)
+    end
+
+    def inherited(subclass)
+      subclass.include(::Solid::Model)
+    end
+  end
+
   included do
     include ::ActiveModel.const_defined?(:Api, false) ? ::ActiveModel::Api : ::ActiveModel::Model
     include ::ActiveModel.const_defined?(:Access, false) ? ::ActiveModel::Access : ::Solid::Model::Access
@@ -12,19 +22,21 @@ module Solid::Model
     include ::ActiveModel::Attributes
     include ::ActiveModel::Dirty
     include ::ActiveModel::Validations::Callbacks
+
+    extend ActiveModel::Callbacks
+
+    define_model_callbacks :initialize, only: :after
   end
 
-  module ClassMethods
-    def [](...)
-      new(...)
-    end
+  def initialize(...)
+    super
 
-    def inherited(subclass)
-      subclass.include(::Solid::Model)
-    end
+    run_callbacks(:initialize)
   end
 
   def inspect
     "#<#{self.class.name} #{attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}>"
   end
+
+  alias_method :[], :public_send
 end

data/lib/solid/output.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "solid/result"
+
+module Solid
+  def self.Success(...)
+    ::Solid::Output::Success(...)
+  end
+
+  def self.Failure(...)
+    ::Solid::Output::Failure(...)
+  end
+end

data/lib/solid/process/backtrace_cleaner.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Solid::Process::BacktraceCleaner < ActiveSupport::BacktraceCleaner
+  def initialize
+    super
+
+    add_blocks_silencer
+  end
+
+  private
+
+  BLOCKS_PATTERN = /in [`']block in|in [`'](?:Kernel#)?then'|internal:kernel|block \(\d+ levels?\) in/.freeze
+
+  def add_blocks_silencer
+    add_silencer { |line| line.match?(BLOCKS_PATTERN) }
+  end
+end

data/lib/solid/process/caller.rb

@@ -16,7 +16,7 @@ class Solid::Process
             elsif input.invalid?
               Failure(:invalid_input, input: input)
             else
-              super(input.attributes.deep_symbolize_keys)
+              super(input.attributes.symbolize_keys)
             end
         rescue ::Exception => exception
           rescue_with_handler(exception) || raise

data/lib/solid/process/event_logs/basic_logger_listener.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class Solid::Process::EventLogs::BasicLoggerListener
+  include Solid::Result::EventLogs::Listener
+
+  class_attribute :logger, :backtrace_cleaner
+
+  self.logger = ActiveSupport::Logger.new($stdout)
+  self.backtrace_cleaner = Solid::Process::BacktraceCleaner.new
+
+  module MessagesNesting
+    MAP_STEP_METHOD = lambda do |record_result|
+      kind, type, value = record_result.values_at(:kind, :type, :value)
+
+      value_keys = "#{value.keys.join(":, ")}:"
+      value_keys = "" if value_keys == ":"
+
+      case type
+      when :_given_ then "Given(#{value_keys})"
+      when :_continue_ then "Continue(#{value_keys})"
+      else "#{kind.capitalize}(:#{type}, #{value_keys})"
+      end
+    end
+
+    MAP_STEP_MESSAGE = lambda do |record|
+      step = MAP_STEP_METHOD[record[:result]]
+
+      method_name = record.dig(:and_then, :method_name)
+
+      " * #{step} from method: #{method_name}".chomp("from method: ").chomp(" ")
+    end
+
+    MAP_IDS_WITH_MESSAGES = lambda do |records|
+      process_ids = []
+
+      records.each_with_object([]) do |record, messages|
+        current = record[:current]
+
+        current_id = current[:id]
+
+        unless process_ids.include?(current_id)
+          process_ids << current_id
+
+          id, name, desc = current.values_at(:id, :name, :desc)
+
+          messages << [current_id, "##{id} #{name} - #{desc}".chomp("- ").chomp(" ")]
+        end
+
+        messages << [current_id, MAP_STEP_MESSAGE[record]]
+      end
+    end
+
+    def self.map(event_logs)
+      ids_level_parent = event_logs.dig(:metadata, :ids, :level_parent)
+
+      messages = MAP_IDS_WITH_MESSAGES[event_logs[:records]]
+
+      messages.map { |(id, msg)| "#{"   " * ids_level_parent[id].first}#{msg}" }
+    end
+  end
+
+  def on_finish(event_logs:)
+    messages = MessagesNesting.map(event_logs)
+
+    logger.info messages.join("\n")
+  end
+
+  def before_interruption(exception:, event_logs:)
+    messages = MessagesNesting.map(event_logs)
+
+    logger.info messages.join("\n")
+
+    cleaned_backtrace = backtrace_cleaner.clean(exception.backtrace).join("\n  ")
+
+    logger.error "\nException:\n  #{exception.message} (#{exception.class})\n\nBacktrace:\n  #{cleaned_backtrace}"
+  end
+end

data/lib/solid/process/event_logs.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Solid::Process
+  module EventLogs
+    require_relative "event_logs/basic_logger_listener"
+  end
+end

data/lib/solid/process/version.rb

@@ -2,6 +2,6 @@
 
 module Solid
   class Process
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/solid/process.rb

@@ -2,18 +2,12 @@
 
 require "active_support/all"
 require "active_model"
-require "solid/result"
 
 module Solid
-  require "solid/input"
-
-  def self.Success(...)
-    ::Solid::Output::Success(...)
-  end
-
-  def self.Failure(...)
-    ::Solid::Output::Failure(...)
-  end
+  require_relative "model"
+  require_relative "value"
+  require_relative "input"
+  require_relative "output"
 
   class Process
     require "solid/process/version"
@@ -23,6 +17,8 @@ module Solid
     require "solid/process/callbacks"
     require "solid/process/class_methods"
     require "solid/process/active_record"
+    require "solid/process/backtrace_cleaner"
+    require "solid/process/event_logs"
 
     extend ClassMethods
 
@@ -40,15 +36,17 @@ module Solid
       new.call(arg)
     end
 
-    def self.configuration(&block)
+    def self.config
+      Config.instance
+    end
+
+    def self.configuration(freeze: true, &block)
       yield config
 
-      config.freeze
+      config.tap { _1.freeze if freeze }
     end
 
-    def self.config
-      Config.instance
-    end
+    singleton_class.alias_method :configure, :configuration
 
     attr_reader :output, :input, :dependencies
 

data/lib/solid/validators/email_validator.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 class EmailValidator < ActiveModel::EachValidator
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
+    return model.errors.add(attribute, :blank, **options) if value.blank?
+
     return if value.is_a?(String) && URI::MailTo::EMAIL_REGEXP.match?(value)
 
-    obj.errors.add attribute, (options[:message] || "is not an email")
+    model.errors.add(attribute, :invalid, **options)
   end
 end

data/lib/solid/validators/id_validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "solid/validators"
+
+class IdValidator < ActiveModel::EachValidator
+  OPTIONS = {only_integer: true, greater_than: 0}.freeze
+
+  def validate_each(model, attribute, value)
+    opts = OPTIONS.merge(options.except(*OPTIONS.keys))
+
+    opts[:attributes] = attribute
+
+    ::ActiveModel::Validations::NumericalityValidator.new(opts).validate_each(model, attribute, value)
+  end
+
+  private_constant :OPTIONS
+end

data/lib/solid/validators/instance_of_validator.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require "solid/validators"
+
 class InstanceOfValidator < ActiveModel::EachValidator
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
     with_option = Array.wrap(options[:with] || options[:in])
 
     return if with_option.any? { |type| value.instance_of?(type) }
 
-    expectation = with_option.map(&:name).join(" | ")
+    message = "is not an instance of #{with_option.map(&:name).join(" | ")}"
 
-    obj.errors.add(attribute, (options[:message] || "is not an instance of #{expectation}"))
+    Solid::Validators.add_error(model, attribute, message, options)
   end
 end

data/lib/solid/validators/is_validator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "solid/validators"
+
+class IsValidator < ActiveModel::EachValidator
+  def validate_each(model, attribute, value)
+    with_option = Array.wrap(options[:with] || options[:in])
+
+    return if with_option.all? do |predicate|
+      raise ArgumentError, "expected a predicate method, got #{predicate.inspect}" unless predicate.end_with?("?")
+
+      value.try(predicate)
+    end
+
+    message = "does not satisfy the predicate#{"s" if with_option.size > 1}: #{with_option.join(" & ")}"
+
+    Solid::Validators.add_error(model, attribute, message, options)
+  end
+end

data/lib/solid/validators/kind_of_validator.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require "solid/validators"
+
 class KindOfValidator < ActiveModel::EachValidator
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
     with_option = Array.wrap(options[:with] || options[:in])
 
     return if with_option.any? { |type| value.is_a?(type) }
 
-    expectation = with_option.map(&:name).join(" | ")
+    message = "is not a #{with_option.map(&:name).join(" | ")}"
 
-    obj.errors.add(attribute, (options[:message] || "is not a #{expectation}"))
+    Solid::Validators.add_error(model, attribute, message, options)
   end
 end

data/lib/solid/validators/respond_to_validator.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require "solid/validators"
+
 class RespondToValidator < ActiveModel::EachValidator
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
     with_option = Array.wrap(options[:with] || options[:in])
 
     return if with_option.all? { value.respond_to?(_1) }
 
-    expectation = with_option.map(&:inspect).join(" & ")
+    message = "does not respond to #{with_option.map(&:inspect).join(" & ")}"
 
-    obj.errors.add(attribute, (options[:message] || "does not respond to #{expectation}"))
+    Solid::Validators.add_error(model, attribute, message, options)
   end
 end

data/lib/solid/validators/singleton_validator.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
+require "solid/validators"
+
 class SingletonValidator < ActiveModel::EachValidator
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
     with_option = Array.wrap(options[:with] || options[:in])
 
-    unless value.is_a?(Module)
-      return obj.errors.add(attribute, options[:message] || "is not a class or module")
-    end
+    return model.errors.add(attribute, options[:message] || "is not a class or module") unless value.is_a?(Module)
 
-    is_valid = with_option.any? do |type|
-      type.is_a?(Module) or raise ArgumentError, "#{type.inspect} is not a class or module"
+    return if with_option.any? do |type|
+      raise ArgumentError, "#{type.inspect} is not a class or module" unless type.is_a?(Module)
 
       value == type || (value < type || value.is_a?(type))
     end
 
-    expectation = with_option.map(&:name).join(" | ")
+    message = "is not #{with_option.map(&:name).join(" | ")}"
 
-    is_valid or obj.errors.add(attribute, (options[:message] || "is not #{expectation}"))
+    Solid::Validators.add_error(model, attribute, message, options)
   end
 end

data/lib/solid/validators/uuid_validator.rb

@@ -5,16 +5,16 @@ class UuidValidator < ActiveModel::EachValidator
   CASE_SENSITIVE = /\A#{PATTERN}\z/.freeze
   CASE_INSENSITIVE = /\A#{PATTERN}\z/i.freeze
 
-  def validate_each(obj, attribute, value)
+  def validate_each(model, attribute, value)
     case_sensitive = options.fetch(:case_sensitive, true)
 
+    return model.errors.add(attribute, :blank, **options) if value.blank?
+
     regexp = case_sensitive ? CASE_SENSITIVE : CASE_INSENSITIVE
 
     return if value.is_a?(String) && value.match?(regexp)
 
-    message = options[:message] || "is not a valid UUID (case #{case_sensitive ? "sensitive" : "insensitive"})"
-
-    obj.errors.add(attribute, message)
+    model.errors.add(attribute, :invalid, **options)
   end
 
   private_constant :PATTERN

data/lib/solid/validators.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Solid
+  module Validators
+    def self.add_error(model, attribute, message, options)
+      if ActiveModel.const_defined?(:Error)
+        model.errors.add(attribute, **options.merge(message: message))
+      else
+        model.errors.add(attribute, options.fetch(:message, message))
+      end
+    end
+  end
+end

data/lib/solid/value.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Solid::Value
+  module ClassMethods
+    UNDEFINED = ::Object.new
+
+    def new(value = UNDEFINED)
+      return value if value.is_a?(self)
+
+      UNDEFINED.equal?(value) ? super() : super(value: value)
+    end
+
+    def attribute(...)
+      super(:value, ...)
+    end
+
+    def validates(...)
+      super(:value, ...)
+    end
+  end
+
+  def self.included(subclass)
+    subclass.include Solid::Model
+    subclass.extend ClassMethods
+    subclass.attribute
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && other.value == value
+  end
+
+  def hash
+    value.hash
+  end
+
+  def to_s
+    value.to_s
+  end
+
+  alias_method :eql?, :==
+end