toolx 0.1.0

data/lib/toolx/core/operation/flow.rb

@@ -0,0 +1,220 @@
+module Toolx::Core::Operation::Flow
+  def self.included(base)
+    base.send(:extend, ClassMethods)
+  end
+
+  module ClassMethods
+    # @example
+    # executor = MyOperation.flow
+    #                       .bind_with(self)
+    #                       .on(success: :dashboard, fail: :show_error)
+    # executor.perform(name: 'Alice', age: 20).success?
+    # executor.response # => { user: <User object> }
+    # @return [Operation::Flow::Executor] a new instance of Executor for the operation class
+    def flow = Executor.new(self)
+  end
+
+  class Executor
+    ExecutorError = Class.new(StandardError)
+    OperationAlreadyInitialized = Class.new(ExecutorError)
+    OperationNotInitialized = Class.new(ExecutorError)
+
+    def initialize(operation_class)
+      @operation_class = operation_class
+      self
+    end
+
+    attr_reader :operation_class, :operation, :response, :exception, :fail_errors
+
+    # Initializes the operation instance with the given params
+    # Raises OperationAlreadyInitialized if called twice without reset
+    # : (**untyped) -> Executor
+    def new(**params)
+      raise OperationAlreadyInitialized if operation
+
+      @operation = operation_class.new(**params)
+      self
+    end
+
+    # Forces reinitialization of the operation instance
+    # : (**untyped) -> Executor
+    def new!(**params)
+      @operation = nil
+      new(**params)
+    end
+
+    # Runs the operation (initialize if params provided)
+    # : (**untyped) -> Executor
+    def perform(**params)
+      new(**params) if params.present?
+      execute
+    end
+
+    # Forces execution (reset and run)
+    # : (**untyped) -> Executor
+    def perform!(**params)
+      clear_operation!.new(**params) if params.present?
+      clear!
+      execute
+    end
+
+    def fail? = !success?
+    def success? = errors.respond_to?(:empty?) ? errors.empty? : !errors
+    alias failure? fail?
+    alias ok? success?
+
+    # Returns errors from failure or exception
+    # : () -> untyped
+    def errors
+      @errors ||= fail_errors || exception_error
+    end
+
+    # Clears only the operation instance
+    # : () -> Executor
+    def clear_operation!
+      @operation = nil
+      self
+    end
+
+    # Clears execution state (response, error, exception)
+    # : () -> Executor
+    def clear!
+      @response = nil
+      @exception = nil
+      @fail_errors = nil
+      @errors = nil
+      self
+    end
+
+    # Clears everything (operation and state)
+    # : () -> Executor
+    def reset! = clear_operation!.clear!
+
+    # Binds success/fail handlers with method names
+    # : (success: Symbol?, fail: Symbol?) -> Executor
+    # Examples:
+    #   executor.on(success: :dashboard, fail: :show_error)
+    #   executor.on(success: -> () { render :done })
+    #   executor.on(success: -> (response) { render :done, locals: { model: response.subject } })
+    #   executor.on(success: -> (_response, operation) { render :done, locals: { model: operation.response.subject } })
+    def on(actions_with_responses = {})
+      actions_assign(actions_with_responses, :success, :fail)
+    end
+
+    # Binds success handler with method name or block
+    # : (Symbol?) { (Executor) -> void } -> Executor
+    # Examples:
+    #  executor.on_success(:dashboard)
+    #  executor.on_success { render :done }
+    #  executor.on_success { |response| render :done, locals: { model: response.subject } }
+    #  executor.on_success { |_response, operation| render :done, locals: { model: operation.response.subject } }
+    def on_success(binded_method = nil, &block)
+      actions[:success] = binded_method || block
+      self
+    end
+
+    # Binds failure handler with method name or block
+    # : (Symbol?) { (Executor) -> void } -> Executor
+    # Examples:
+    # executor.on_fail(:show_error)
+    # executor.on_fail { render :error }
+    # executor.on_fail { |response| render :error, locals: { error: response.errors } }
+    # executor.on_fail { |_response, operation| render :error, locals: { error: operation.errors } }
+    def on_fail(binded_method = nil, &block)
+      actions[:fail] = binded_method || block
+      self
+    end
+
+    # Assigns object to call symbol handlers on
+    # : (Object) -> Executor
+    def bind_with(bind_object)
+      @bind_object = bind_object
+      self
+    end
+
+    # Removes bound handler object
+    # : () -> Executor
+    def unbind!
+      @bind_object = nil
+      self
+    end
+
+    # Forces failure with custom error payload
+    # : (untyped) -> Executor
+    def fail!(fail_obj = true)
+      @errors = nil
+      @fail_errors = fail_obj
+      self
+    end
+
+    # Accessor for action handlers
+    # : () -> Hash[Symbol, Proc | Symbol]
+    def actions
+      @actions ||= {}
+    end
+
+    private
+
+    def exception_error
+      return unless exception
+
+      {
+        exception: {
+          class: exception.class.name,
+          message: exception.respond_to?(:message) ? exception.message : exception.to_s
+        }
+      }
+    end
+
+    def execute
+      raise OperationNotInitialized unless operation
+
+      @response = operation.perform
+      execute_actions
+      self
+    rescue => exception
+      raise if exception.is_a?(ExecutorError)
+      @exception = exception
+      execute_actions
+      self
+    end
+
+    attr_reader :bind_object
+
+    def actions_assign(hash, *keys)
+      keys.each { |key| actions[key] = hash[key] if hash.key?(key) }
+      self
+    end
+
+    def execute_action_kind(kind)
+      return unless actions.key?(kind)
+
+      action = actions[kind]
+
+      if action.is_a?(Symbol) && bind_object
+        arity = bind_object.method(action).arity
+        case arity
+        when 0 then bind_object.send(action)
+        when 1 then bind_object.send(action, response)
+        else bind_object.send(action, response, self)
+        end
+      elsif action.is_a?(Proc)
+        case action.arity
+        when 0 then action.call
+        when 1 then action.call(response)
+        else action.call(response, self)
+        end
+      end
+
+      # bind_object.send(action, self) if action.is_a?(Symbol) && bind_object
+      # action.call(self) if action.is_a?(Proc)
+    rescue NameError => e
+      raise ExecutorError, "Action '#{action}' not found in #{bind_object.class.name}" if bind_object
+    end
+
+    def execute_actions
+      success? ? execute_action_kind(:success) : execute_action_kind(:fail)
+      self
+    end
+  end
+end

data/lib/toolx/core/operation/params_wrapper.rb

@@ -0,0 +1,33 @@
+module Toolx::Core::Operation::ParamsWrapper
+  def initialize(*args, **kwargs)
+    params = args.first.nil? ? kwargs : args.first
+    if self.class.const_defined?(:Params, false) && !params.is_a?(self.class.const_get(:Params, false))
+      begin
+        params = self.class.const_get(:Params, false).new(params.deep_symbolize_keys)
+      rescue Dry::Struct::Error => e
+        err = ArgumentError.new <<~MSG
+          #{e.message}
+          Provided: #{params.inspect}\n
+        MSG
+        err.set_backtrace(e.backtrace)
+        raise err
+      end
+    end
+    @params = params
+    if args.present? || kwargs.present?
+      super
+    else
+      super()
+    end
+  end
+
+  def self.prepended(base)
+    class << base
+      prepend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def params(&block) = const_set(:Params, Class.new(Dry::Struct, &block))
+  end
+end

data/lib/toolx/core/operation/rescue_wrapper.rb

@@ -0,0 +1,20 @@
+require 'active_support'
+
+module Toolx::Core::Operation::RescueWrapper
+  def perform(*args, **kwargs)
+    if args.present? || kwargs.present?
+      super
+    else
+      super()
+    end
+  rescue => exception
+    handler = handler_for_rescue(exception)
+    return handler.call(exception) if handler
+
+    raise
+  end
+
+  def self.prepended(base)
+    base.include ::ActiveSupport::Rescuable
+  end
+end

data/lib/toolx/core/operation/response_wrapper.rb

@@ -0,0 +1,34 @@
+module Toolx::Core::Operation::ResponseWrapper
+  def perform(*args, **params)
+    response = if args.present? || params.present?
+      super
+    else
+      super()
+    end
+
+    if self.class.constants.include?(:Response) && !response.is_a?(self.class.const_get(:Response))
+      begin
+        response = self.class.const_get(:Response).new(response.to_h.deep_symbolize_keys)
+      rescue Dry::Struct::Error => e
+        err = ArgumentError.new <<~MSG
+          #{e.message}
+          Provided: #{response.inspect}\n
+        MSG
+        err.set_backtrace(e.backtrace)
+        raise err
+      end
+    end
+
+    response.is_a?(Hash) ? ::Hashie::Mash.new(response) : response
+  end
+
+  def self.prepended(base)
+    class << base
+      prepend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def response(&block) = const_set(:Response, Class.new(Dry::Struct, &block))
+  end
+end

data/lib/toolx/core/operation/simplified_result.rb

@@ -0,0 +1,45 @@
+module Toolx::Core::Operation::SimplifiedResult
+  def simplified_result(attr_name)
+    # This module allows defining a simplified accessor for the result of an Operation.
+    # When included and `simplified_result :attribute_name` is called,
+    # it adds a class-level `[]` and `.()` method that initializes the operation,
+    # performs it, and returns the specified attribute from the result.
+    #
+    # Example:
+    #
+    #   class Country::Name < Operation
+    #     simplified_result :value
+    #     # ...
+    #   end
+    #
+    #   Country::Name[source: "PL"] # => returns the value attribute from the result
+    #   or
+    #   Country::Name.call(source: "PL") # => same as above
+    #   Country::Name.(source: "PL") # => same as above
+    #
+    # This is useful for operations that return a single value
+    # and should provide a concise and readable API.
+    define_singleton_method(:[]) do |args = {}|
+      # new(**args).perform.public_send(attr_name)
+      begin
+        new(**args).perform.public_send(attr_name)
+      rescue TypeError, ArgumentError => e
+        required = if const_defined?(:Params, false)
+          const_get(:Params, false).schema.keys.join(', ')
+        else
+          'Operation params are wrongly assigned or not defined'
+        end
+
+        raise ArgumentError, <<~MSG
+          Expected #{self.name} keyword args: #{required}
+          Got: #{args.inspect}
+          #{e.message}
+        MSG
+      end
+    end
+
+    class << self
+      alias_method :call, :[]
+    end
+  end
+end

data/lib/toolx/core/operation/transaction_wrapper.rb

@@ -0,0 +1,32 @@
+module Toolx::Core::Operation::TransactionWrapper
+  def perform(*args, **params)
+    wrapper = proc do
+      if args.present? || params.present?
+        super
+      else
+        super()
+      end
+    end
+
+    connected = ::ActiveRecord::Base.connection_pool.with_connection(&:active?) rescue false # rubocop:disable Style/RescueModifier
+    if connected && self.class.transactional?
+      ActiveRecord::Base.transaction(&wrapper)
+    else
+      wrapper.call
+    end
+  end
+
+  def self.prepended(base)
+    class << base
+      prepend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def transactional? = !@_disable_transactions
+
+    def transactional=(enabled)
+      @_disable_transactions = !enabled
+    end
+  end
+end

data/lib/toolx/core/operation.rb

@@ -0,0 +1,27 @@
+class Toolx::Core::Operation < ::Toolx::Core::OperationBase
+  require_relative 'operation/callbacks_wrapper'
+  require_relative 'operation/transaction_wrapper'
+  require_relative 'operation/params_wrapper'
+  require_relative 'operation/response_wrapper'
+  require_relative 'operation/rescue_wrapper'
+  require_relative 'operation/simplified_result'
+  require_relative 'operation/flow'
+
+  extend ::Toolx::Core::Operation::SimplifiedResult
+
+  class Error < ::Toolx::Core::Errors::NestedStandardError; end
+
+  attr_reader :params
+
+  def self.prepend_builtins(subclass)
+    subclass.prepend ::Toolx::Core::Operation::CallbacksWrapper
+    subclass.prepend ::Toolx::Core::Operation::TransactionWrapper
+    subclass.prepend ::Toolx::Core::Operation::ParamsWrapper
+    subclass.prepend ::Toolx::Core::Operation::ResponseWrapper
+    subclass.prepend ::Toolx::Core::Operation::RescueWrapper
+  end
+
+  def self.inherited(subclass)
+    prepend_builtins(subclass)
+  end
+end

data/lib/toolx/core/operation_base.rb

@@ -0,0 +1,4 @@
+class Toolx::Core::OperationBase
+  def initialize(*, **) end
+  def perform; end
+end

data/lib/toolx/core/presenter.rb

@@ -0,0 +1,50 @@
+class Toolx::Core::Presenter < SimpleDelegator
+  NoPresenterDetected = Class.new(StandardError)
+
+  def initialize(object, **opts)
+    super(object)
+    @__opts = opts || {}
+  end
+
+  attr_reader :__opts
+  def original_object = __getobj__
+
+  # Public: Constructs and returns a new presenter instance.
+  # Accepts flexible arguments to support subclasses with custom initializers.
+  #
+  # Example:
+  #   MyPresenter.present(user, show_deleted: true)
+  def self.present(*args, **kwargs, &block) = new(*args, **kwargs, &block)
+
+  # Public: Returns a Proc that instantiates the presenter.
+  # Allows usage like: `Model.all.map(&MyPresenter)`
+  def self.to_proc = ->(object) { present(object) }
+
+  # Public: Returns a Proc that instantiates the presenter and optionally calls a method on it.
+  # Useful for transforming collections with presentation logic.
+  #
+  # Example:
+  #   Model.all.map(&MyPresenter.as_proc(use: :to_json))
+  def self.as_proc(*args, **kwargs, &block)
+    use = kwargs.delete(:use)
+    ->(object) do
+      presenter = present(object, *args, **kwargs, &block)
+      use ? presenter.public_send(use) : presenter
+    end
+  end
+
+  def self.detect(object)
+    object.class::Presenter
+  rescue NameError
+    raise NoPresenterDetected, "No presenter detected for #{object.class.name}. Please define a Presenter constant in the class."
+  end
+
+  def self.auto_present(object) = detect(object).present(object)
+
+  def t!(key, opts = {}) = I18n.t!([t_default_key, key].join('.'), **opts.merge(locale: __opts[:locale] || :pl))
+  def t(key, opts = {}) = I18n.t([t_default_key, key].join('.'), **opts.merge(locale: __opts[:locale] || :pl))
+
+  def t_default_key
+    @t_default_key ||= self.class.name.sub(/Presenter$/, '').split('::').compact.join('.').underscore
+  end
+end

data/lib/toolx/core/simple_crypt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Toolx::Core::SimpleCrypt
+  MissingSecretError = Class.new(StandardError)
+  EncryptionError = Class.new(StandardError)
+  DecryptionError = Class.new(StandardError)
+
+  def self.default_secret
+    ENV['CRYPT_SECRET'].presence || Rails.application.credentials.secret_key_base.presence || raise(MissingSecretError, 'Encryption secret not configured')
+  end
+
+  def self.crypt(secret = nil)
+    key = secret.presence || default_secret
+    ActiveSupport::MessageEncryptor.new(key[0..31].bytes.pack('c*'))
+  end
+
+  def self.encrypt(value, secret: nil)
+    crypt(secret).encrypt_and_sign(value)
+  rescue => e
+    raise EncryptionError, "Encryption failed: #{e.message}"
+  end
+
+  def self.decrypt(value, secret: nil)
+    crypt(secret).decrypt_and_verify(value)
+  rescue => e
+    raise DecryptionError, "Decryption failed: #{e.message}"
+  end
+end

data/lib/toolx/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Toolx
+  VERSION = '0.1.0'
+end

data/lib/toolx.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'toolx/version'
+
+# Concerns
+Dir[File.join(__dir__, 'toolx/core/concerns/**/*.rb')].sort.each { |f| require f }
+
+require_relative 'toolx/core/env'
+
+require_relative 'toolx/core/errors/nested_error'
+require_relative 'toolx/core/errors/nested_standard_error'
+require_relative 'toolx/core/errors/app_error'
+require_relative 'toolx/core/errors/api_error'
+
+require_relative 'toolx/core/simple_crypt'
+require_relative 'toolx/core/form'
+require_relative 'toolx/core/presenter'
+
+require_relative 'toolx/core/operation_base'
+require_relative 'toolx/core/operation'
+
+module Toolx
+end
+
+if defined?(Rake)
+  spec = Gem::Specification.find_by_name 'toolx'
+  load "#{spec.gem_dir}/lib/tasks/stateman.rake"
+  load "#{spec.gem_dir}/lib/tasks/annotate_rb.rake"
+  load "#{spec.gem_dir}/lib/tasks/aliases.rake"
+end

data/sig/toolx.rbs

@@ -0,0 +1,4 @@
+module Toolx
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end