toolx 0.1.0

data/lib/tasks/aliases.rake

@@ -0,0 +1,50 @@
+namespace :toolx do
+  namespace :aliases do
+    desc 'Generate toolx_aliases.rb'
+    task :generate do
+      file_name = Rails.root.join('lib', 'toolx_aliases.rb')
+      return if File.exist?(file_name)
+
+      File.open(file_name, 'w') do |file|
+        file.write <<~RUBY
+          require 'toolx'
+  
+          # WithStateMachine = Toolx::Core::Concerns::WithStateMachine
+          # Inquirer = Toolx::Core::Concerns::Inquirer
+          # DateTimeToBoolean = Toolx::Core::Concerns::DateTimeToBoolean
+          # CustomIdentifier = Toolx::Core::Concerns::CustomIdentifier
+          # Transformer = Toolx::Core::Concerns::Transformer
+          
+          NestedError = Toolx::Core::Errors::NestedError
+          NestedStandardError = Toolx::Core::Errors::NestedStandardError
+          AppError = Toolx::Core::Errors::AppError
+          ApiError = Toolx::Core::Errors::ApiError
+          Form = Toolx::Core::Form
+          Presenter = Toolx::Core::Presenter
+          SimpleCrypt = Toolx::Core::SimpleCrypt
+          Operation = Toolx::Core::Operation
+          Operation::Base = ::Toolx::Core::OperationBase
+          Operation::Flow = Toolx::Core::Operation::Flow
+          Env = Toolx::Core::Env
+        RUBY
+      end
+      puts "Aliases generated at #{Pathname.new(file_name).relative_path_from(Rails.root)}"
+      puts "\n"
+      puts "You can add all Toolx accessories to the app/models/application_record.rb like below:"
+      puts <<~RUBY
+        class ApplicationRecord < ActiveRecord::Base
+          primary_abstract_class
+      
+          include Toolx::Core::Concerns::Inquirer
+          include Toolx::Core::Concerns::Transformer
+          include Toolx::Core::Concerns::CustomIdentifier
+          include Toolx::Core::Concerns::DateTimeToBoolean
+          include Toolx::Core::Concerns::WithStateMachine
+        end
+      RUBY
+      puts "\n"
+      puts "Add line below to config/application.rb"
+      puts "require_relative '../lib/toolx_aliases'"
+    end
+  end
+end

data/lib/tasks/annotate_rb.rake

@@ -0,0 +1,23 @@
+namespace :toolx do
+  namespace :annotate do
+    desc 'Generate annotate rake tasks'
+    task :generate do
+      file_name = Rails.root.join('lib', 'tasks', 'annotate_rb.rake')
+      return if File.exist?(file_name)
+
+      File.open(file_name, 'w') do |file|
+        file.write <<~RUBY
+          # This rake task was added by annotate_rb gem.
+          
+          # Can set `ANNOTATERB_SKIP_ON_DB_TASKS` to be anything to skip this
+          if Rails.env.development? && ENV["ANNOTATERB_SKIP_ON_DB_TASKS"].nil?
+            require "annotate_rb"
+          
+            AnnotateRb::Core.load_rake_tasks
+          end
+        RUBY
+      end
+      puts "Annotate rake tasks generated at #{Pathname.new(file_name).relative_path_from(Rails.root)}"
+    end
+  end
+end

data/lib/tasks/stateman.rake

@@ -0,0 +1,50 @@
+require 'rake'
+
+namespace :toolx do
+  namespace :stateman do
+    desc 'Generate StateMachine, Transition class, and migration'
+    task :generate, [:model] => :environment do |_, args|
+      require 'erb'
+      require 'fileutils'
+
+      model = args[:model].to_s.camelize
+      abort 'Model name required' if model.blank?
+
+      class_name = model.camelize
+      file_path = model.underscore
+      path = Rails.root.join('app/models', file_path)
+      FileUtils.mkdir_p(path)
+
+      template_root_path = File.expand_path("../templates/stateman", __dir__)
+
+      templates = {
+        'state_machine.rb.erb' => path.join('state_machine.rb'),
+        'transition.rb.erb' => path.join('transition.rb')
+      }
+
+      templates.each do |template_file, output_path|
+        template_path = File.join(template_root_path, template_file)
+        erb = ERB.new(File.read(template_path), trim_mode: '-')
+        File.write(output_path, erb.result_with_hash(model: model, class_name: class_name))
+        puts "Created #{Pathname.new(output_path).relative_path_from(Rails.root)}"
+      end
+
+      version = ActiveRecord::Migration.current_version.to_s[0..2]
+      timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+      migration_path = Rails.root.join("db/migrate/#{timestamp}_create_#{file_path.gsub('/', '_')}_transitions.rb")
+      migration_template = File.join(template_root_path, 'migration.rb.erb')
+      erb = ERB.new(File.read(migration_template), trim_mode: '-')
+      File.write(migration_path, erb.result_with_hash(model: model, class_name: class_name, version: version))
+      puts "Created #{Pathname.new(migration_path).relative_path_from(Rails.root)}"
+      puts "\n"
+      puts "Do not forget update #{args[:model].to_s.camelize} model #{Pathname.new(path).relative_path_from(Rails.root)} by adding:"
+      puts "\n```\n"
+      puts "include Toolx::Core::Concerns::WithStateMachine"
+      puts "with_state_machine"
+      puts "\n```\n"
+      puts "Do not forget it is works only for ActiveRecord adapter so add to your initializer"
+      puts "echo 'Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }' >> #{Rails.root.join('config/initializers', 'statesman.rb')}"
+      puts "\n\nEnjoy!"
+    end
+  end
+end

data/lib/templates/stateman/migration.rb.erb

@@ -0,0 +1,24 @@
+<% underscored_model = model.underscore.tr("/", "_") %>
+<% demodulized_model = model.demodulize.underscore %>
+class Create<%= class_name.gsub('::', '') %>Transitions < ActiveRecord::Migration[<%= version %>]
+  def change
+    create_table :<%= underscored_model %>_transitions, id: :string do |t|
+      t.references :<%= demodulized_model %>, null: false, type: :string, foreign_key: <%= underscored_model == demodulized_model ? 'true' : "{ to_table: :#{underscored_model.pluralize} }" %>
+      t.string :to_state, null: false
+      t.json :metadata, default: {}
+      t.boolean :most_recent, default: false
+      t.integer :sort_key, null: false
+      t.timestamps null: false
+    end
+
+    add_index(:<%= underscored_model %>_transitions,
+              %i(<%= demodulized_model %>_id sort_key),
+              unique: true,
+              name: 'index_<%= underscored_model %>_transition_parent_sort')
+    add_index(:<%= underscored_model %>_transitions,
+              %i(<%= demodulized_model %>_id most_recent),
+              unique: true,
+              where: 'most_recent',
+              name: 'index_<%= underscored_model %>_transition_parent_most_recent')
+  end
+end

data/lib/templates/stateman/state_machine.rb.erb

@@ -0,0 +1,37 @@
+class <%= class_name %>::StateMachine
+  include Statesman::Machine
+
+  state :pending, initial: true
+  # state :pending, initial: true
+  # state :checking_out
+  # state :purchased
+  # state :shipped
+  # state :cancelled
+  # state :failed
+  # state :refunded
+  #
+  # transition from: :pending,      to: [:checking_out, :cancelled]
+  # transition from: :checking_out, to: [:purchased, :cancelled]
+  # transition from: :purchased,    to: [:shipped, :failed]
+  # transition from: :shipped,      to: :refunded
+  #
+  # after_transition do |model, transition|
+  #   model.update!(status: transition.to_state)
+  # end
+  #
+  # guard_transition(to: :checking_out) do |order|
+  #   order.products_in_stock?
+  # end
+  #
+  # before_transition(from: :checking_out, to: :cancelled) do |order, transition|
+  #   order.reallocate_stock
+  # end
+  #
+  # before_transition(to: :purchased) do |order, transition|
+  #   PaymentService.new(order).submit
+  # end
+  #
+  # after_transition(to: :purchased) do |order, transition|
+  #   MailerService.order_confirmation(order).deliver
+  # end
+end

data/lib/templates/stateman/transition.rb.erb

@@ -0,0 +1,15 @@
+<% underscored_model = model.underscore.tr("/", "_") %>
+<% demodulized_model = model.demodulize.underscore %>
+class <%= class_name %>::Transition < ApplicationRecord
+  # include Statesman::Adapters::ActiveRecordTransition
+  belongs_to :<%= demodulized_model %>, class_name: '<%=class_name %>' # , inverse_of: :<%= underscored_model %>_transitions
+
+  #cid :<%= model.downcase[0..2] %>_tr
+
+  attribute :most_recent, :boolean, default: false
+  attribute :to_state, :string
+  attribute :sort_key, :integer
+  attribute :metadata, :json, default: {}
+
+  validates :to_state, inclusion: { in: <%= class_name %>::StateMachine.states }
+end

data/lib/toolx/core/concerns/custom_identifier.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Concerns
+      module CustomIdentifier
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          # @example Generate a custom ID for the `id` column
+          #   class User < ApplicationRecord
+          #     include CustomIdentifier
+          #     cid 'usr'
+          #   end
+          #
+          #   user.id # => "usr_Nc82xL0w92..."
+          #
+          # @example Use a related model's ID prefix (e.g., workspace)
+          #   class Document < ApplicationRecord
+          #     belongs_to :workspace
+          #     cid 'doc', related: { workspace: 4 }
+          #   end
+          #
+          #   # If workspace_id = "wsp_ABCXYZ...", then document id will be like:
+          #   # "doc_ABCXabcd123..."
+          #
+          # @param [String] prefix Required prefix to prepend to the ID
+          # @param [Integer] size Total length of the generated ID (default: 16)
+          # @param [Hash] related A hash of one related model and how many characters to copy from its ID
+          # @param [Symbol] name The attribute to assign the generated ID to (default: :id)
+          def cid(prefix, size: 16, related: {}, name: :id)
+            before_create do
+              identifier = send(name)
+              next unless identifier.nil?
+
+              shared = if related.present?
+                         object, shared = related.first
+                         ref_key = self.class.reflections[object.to_s].foreign_key
+                         read_attribute(ref_key || '')&.split('_')&.second&.first(shared)
+                       end || ''
+              loop do
+                unique = SecureRandom.base58(size - shared.length)
+
+                send("#{name}=", "#{prefix}_#{shared}#{unique}")
+                break unless self.class.exists?(identifier)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toolx/core/concerns/date_time_to_boolean.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Concerns
+      module DateTimeToBoolean
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # @example
+          #   class User < ApplicationRecord
+          #     include DateTimeToBoolean
+          #     date_time_to_boolean :deleted_at
+          #   end
+          #
+          #   user = User.new
+          #   user.deleted!
+          #   user.deleted = true # or DateTime, Time, String with datetime value
+          #   user.deleted_at # => current time
+          #   user.deleted?   # => true
+          #
+          # @param [Array<Symbol>] columns One or more datetime columns (e.g. `:confirmed_at`, `:deleted_at`)
+          def date_time_to_boolean(*columns)
+            columns.each do |column|
+              m_name = column.to_s.gsub(/_at$/, '').to_sym
+              define_method("#{m_name}?") do
+                public_send(column).present?
+              end
+              define_method("#{m_name}!") do
+                public_send("#{column}=", Time.current)
+              end
+              define_method("#{m_name}=") do |value|
+                if ActiveModel::Type::Boolean.new.cast(value)
+                  time = case value
+                  when DateTime then value.to_time
+                  when Time then value
+                  when String
+                    Time.parse(value) rescue Time.current
+                  else
+                    Time.current
+                  end
+                  public_send("#{column}=", time)
+                else
+                  # if the value is false, set the column to nil
+                  public_send("#{column}=", nil)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toolx/core/concerns/inquirer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Concerns
+      module Inquirer
+        extend ::ActiveSupport::Concern
+
+        class SymbolInquiry < SimpleDelegator
+          def initialize(sym)
+            raise ArgumentError, 'Must be a Symbol' unless sym.is_a?(Symbol)
+            sym.is_a?(::Toolx::Core::Concerns::Inquirer::SymbolInquiry) ? super(sym.__getobj__) : super(sym)
+          end
+
+          def method_missing(method_name, *args, &block)
+            if method_name.to_s.end_with?('?')
+              __getobj__.to_s == method_name.to_s.delete_suffix('?')
+            else
+              super
+            end
+          end
+
+          def respond_to_missing?(method_name, include_private = false)
+            method_name.to_s.end_with?('?') || super
+          end
+
+          def inspect = __getobj__.inspect
+          def to_s = __getobj__.to_s
+          def to_sym = __getobj__
+          def is_a?(klass) = klass == Symbol || super
+
+          def ==(other)
+            __getobj__ == other.to_sym
+          end
+        end
+
+        module NilInquiry
+          def method_missing(method_name, *args, &)
+            return false if method_name.to_s.include?('?')
+
+            super
+          end
+
+          def respond_to_missing?(method_name, include_private = false)
+            return true if method_name.to_s.include?('?')
+
+            super
+          end
+
+          def nil?
+            true
+          end
+        end
+
+        def self.nil_value
+          @nil_value ||= String.new.extend(NilInquiry)
+        end
+
+        class_methods do
+          # @example
+          #   class User < ApplicationRecord
+          #     include Inquirer
+          #     inquirer :status
+          #   end
+          #
+          #   user = User.new(status: "active")
+          #   user.status.active? # => true
+          #   user.status.inactive? # => false
+          #
+          #   user = User.new(status: nil)
+          #   user.status.inactive? # => false (instead of NoMethodError)
+          #
+          # @param [Array<Symbol>] methods List of method names (usually attribute readers) to wrap with inquiry behavior
+          def inquirer(*methods)
+            methods.each do |method_name|
+              define_method :"#{method_name}" do
+                value = super() rescue self[method_name] # avoid super() for dry-struct-generated attributes
+                return ::Toolx::Core::Concerns::Inquirer.nil_value if value.blank?
+                return ::Toolx::Core::Concerns::Inquirer::SymbolInquiry.new(value) if value.is_a?(Symbol)
+
+                value.inquiry
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toolx/core/concerns/transformer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Toolx::Core::Concerns::Transformer
+  extend ActiveSupport::Concern
+
+  # Optional use of normalize_attributes gem
+  class_methods do
+    # @example Strip and downcase the email before saving
+    #   class User < ApplicationRecord
+    #     include Toolx::Core::Concerns::Transformer
+    #
+    #     transform :email, :strip, :downcase
+    #   end
+    #
+    #   user.email = "  Foo@Example.COM  "
+    #   user.email # => "foo@example.com"
+    #
+    # @example Convert blank strings to nil
+    #   transform :first_name, :strip
+    #
+    # @param [Symbol] method_name the attribute to define a transformed setter for
+    # @param [Array<Symbol>] transformations list of transformation methods (e.g., `:strip`, `:downcase`, `:humanize` etc.)
+    def transform(method_name, *transformations)
+      # rubocop:disable all
+      define_method :"#{method_name}=" do |raw_value|
+        return super raw_value unless raw_value.is_a?(String)
+
+        all = (transformations || [])
+        value = begin
+            # permit = %i[upcase downcase strip humanize]
+            # allowed_transformations = (permit & all)
+            all.inject(raw_value) do |current, transformation|
+              current.public_send(transformation) if transformation.is_a?(Symbol) && current.respond_to?(transformation)
+              # TODO: allow to use method class itself like transformation(current) if transformation.is_a?(Method)
+            end
+          end
+        super value
+      end
+    end
+  end
+end

data/lib/toolx/core/concerns/with_state_machine.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'statesman'
+
+module Toolx
+  module Core
+    module Concerns
+      module WithStateMachine
+        extend ActiveSupport::Concern
+
+        included do
+          def in_state?(*state)
+            state.any? { |s| current_state.to_sym == s.to_sym }
+          end
+
+          def not_in_state?(state)
+            !in_state?(state)
+          end
+
+          delegate :can_transition_to?, :transition_to!, :transition_to, :current_state, to: :state_machine
+        end
+
+        class_methods do
+          # It is adding a state machine to the model. Use rake task `bin/rails state_machine:generate[model]` to generate the necessary files.
+          def with_state_machine
+            model_name = name
+            model_namespace = model_name.deconstantize
+            model_base = model_name.demodulize
+
+            transition_class = [model_namespace.presence, model_base, 'Transition'].compact.join('::')
+            state_machine_class = [model_namespace.presence, model_base, 'StateMachine'].compact.join('::')
+
+            has_many :transitions, autosave: false, class_name: transition_class, dependent: :destroy # inverse_of: :project
+
+            include ::Statesman::Adapters::ActiveRecordQueries[
+                      transition_class: transition_class.constantize,
+                      initial_state: state_machine_class.constantize.initial_state
+                    ]
+
+            define_method(:state_machine) do
+              instance_variable_get(:@state_machine) ||
+                instance_variable_set(:@state_machine, state_machine_class.constantize.new(self, transition_class: transition_class.constantize, association_name: :transitions))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toolx/core/env.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Env
+      MissingEnv = Class.new(StandardError)
+
+      def self.[](value) = env_variable!(value)
+      def self.all = ENV
+
+      def self.method_missing(method_name, default = nil, &)
+        name = method_name.to_s
+        return boolean(name[0..-2], default, &) if name[-1] == '?'
+        return integer(name[0..-2], default, &) if name[-1] == '!'
+        return inquirer(name[0..-2], default, &) if name[-1] == '_'
+
+        env_variable!(name, default, &)
+      end
+
+      def self.respond_to?(*_args) = true
+      def respond_to_missing?(*_args) = true
+
+      def self.boolean(value, default, &)
+        result = env_variable!(value, default, &).to_s.downcase
+        ActiveModel::Type::Boolean.new.cast(result)
+      end
+
+      def self.integer(value, default, &) = env_variable!(value, default, &).to_i
+
+      def self.inquirer(value, default, &)
+        result = env_variable!(value, default, &)
+        return ::Toolx::Core::Concerns::Inquirer.nil_value if result.blank?
+        return ::Toolx::Core::Concerns::Inquirer::SymbolInquiry.new(result) if result.is_a?(Symbol)
+
+        result.inquiry
+      end
+
+      def self.env_variable!(value, default = nil, &)
+        default ? ENV.fetch(value.to_s.upcase, default, &) : ENV.fetch(value.to_s.upcase, &)
+      rescue KeyError
+        raise MissingEnv, "Missing: #{value.upcase} env variable"
+      end
+    end
+  end
+end

data/lib/toolx/core/errors/api_error.rb

@@ -0,0 +1,40 @@
+module Toolx
+  module Core
+    module Errors
+      class ApiError < ::Toolx::Core::Errors::AppError
+        attr_reader :details
+
+        def initialize(details = nil)
+          @details = details || {}
+          super(@details[:message] || error_name)
+        end
+
+        def message_namespace
+          @message_namespace ||= self.class.to_s.deconstantize.underscore.tr!('/', '.')
+        end
+
+        def status
+          @status ||= details[:status] || error_name.to_sym
+        end
+
+        private
+
+        def error_name
+          @error_name ||= self.class.to_s.demodulize.underscore
+        end
+      end
+
+      BadRequest = Class.new(ApiError)
+      Unauthorized = Class.new(ApiError)
+      NotFound = Class.new(ApiError)
+      Conflict = Class.new(ApiError)
+      UnprocessableEntity = Class.new(ApiError)
+      FailedDependency = Class.new(ApiError)
+      Forbidden = Class.new(ApiError)
+      InternalServerError = Class.new(ApiError)
+      BadGateway = Class.new(ApiError)
+      ServiceUnavailable = Class.new(ApiError)
+      GatewayTimeout = Class.new(ApiError)
+    end
+  end
+end

data/lib/toolx/core/errors/app_error.rb

@@ -0,0 +1,3 @@
+class Toolx::Core::Errors::AppError < StandardError
+  include ::Toolx::Core::Errors::NestedError
+end

data/lib/toolx/core/errors/nested_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Errors
+      module NestedError
+        attr_reader :nested, :raw_backtrace
+
+        def initialize(msg = nil, nested = $ERROR_INFO)
+          super(msg)
+          @nested = nested
+        end
+
+        def set_backtrace(backtrace) # rubocop:disable Naming/AccessorMethodName
+          @raw_backtrace = backtrace
+          if nested
+            backtrace -= nested_raw_backtrace
+            backtrace += ["#{nested.backtrace.first}: #{nested.message} (#{nested.class.name})"]
+            backtrace += nested.backtrace[1..] || []
+          end
+          super(backtrace)
+        end
+
+        private
+
+        def nested_raw_backtrace
+          nested.respond_to?(:raw_backtrace) ? nested.raw_backtrace : nested.backtrace
+        end
+      end
+    end
+  end
+end

data/lib/toolx/core/errors/nested_standard_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Toolx
+  module Core
+    module Errors
+      class NestedStandardError < StandardError
+        include ::Toolx::Core::Errors::NestedError
+      end
+    end
+  end
+end

data/lib/toolx/core/form.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Toolx::Core::Form
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+  include ActiveModel::Validations::Callbacks
+
+  def as_json(options = nil) = attributes.as_json(options)
+end

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

@@ -0,0 +1,27 @@
+module Toolx::Core::Operation::CallbacksWrapper
+  def perform(...)
+    run_callbacks :perform do
+      super
+    end
+  end
+
+  module ClassMethods
+    def before(...)
+      set_callback(:perform, :before, ...)
+    end
+
+    def after(...)
+      set_callback(:perform, :after, ...)
+    end
+
+    def around(...)
+      set_callback(:perform, :around, ...)
+    end
+  end
+
+  def self.prepended(base)
+    base.include ::ActiveSupport::Callbacks
+    base.extend ClassMethods
+    base.define_callbacks :perform
+  end
+end