interactor-extended 0.1.0

data/lib/interactor/colorize.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides colorization utilities for strings.
+  module Colorize
+    class << self
+      COLORS = {
+        black: 30,
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        white: 37,
+        default: 39,
+        light_black: 90,
+        light_red: 91,
+        light_green: 92,
+        light_yellow: 93,
+        light_blue: 94,
+        light_magenta: 95,
+        light_cyan: 96,
+        light_white: 97
+      }.freeze
+      MODES = {
+        default: 0, # Turn off all attributes
+        bold: 1,
+        dim: 2,
+        italic: 3,
+        underline: 4,
+        blink: 5,
+        blink_slow: 5,
+        blink_fast: 6,
+        invert: 7,
+        hide: 8,
+        strike: 9,
+        double_underline: 20,
+        reveal: 28,
+        overlined: 53
+      }.freeze
+      # Colorizes a string with the given options.
+      # @param msg [String] The message to colorize.
+      # @param color_value [Symbol, nil] The color value.
+      # @param color [Symbol, nil] The color.
+      # @param mode [Symbol, nil] The mode.
+      # @param bg [Symbol, nil] The background color.
+      # @return [String] The colorized string.
+      def colorize(msg, color_value = nil, color: nil, mode: nil, bg: nil) # rubocop:disable Naming/MethodParameterName
+        "\033[#{MODES[mode] || MODES[:bold]};#{COLORS[color_value || color] || COLORS[:default]};#{(COLORS[bg] || COLORS[:default]) + 10}m#{msg}\033[0m" # rubocop:disable Layout/LineLength
+      end
+    end
+
+    # Colorizes the receiver using the Colorize module.
+    # @param args [untyped] Arguments to pass to Colorize.colorize.
+    # @return [String]
+    def colorize(*)
+      ::Interactor::Colorize.colorize(*)
+    end
+  end
+end

data/lib/interactor/context_definition.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Defines inputs and outputs for an interactor's context.
+  module ContextDefinition
+    include Interactor::Extended::Helpers
+
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+        base.remove_all_attributes!
+      end
+    end
+
+    module ClassMethods
+      attr_accessor :attributes
+
+      # Defines an attribute for the context.
+      # @param methods [Symbol, String] The attribute names.
+      # @param array [bool] Whether the attribute is an array.
+      # @param default [untyped, nil] Default value for the attribute.
+      # @param required [bool] Whether the attribute is required.
+      # @param direction [Symbol] The direction of the attribute (:input or :output).
+      def attribute(*methods, array: false, default: nil, required: false, direction: :output) # rubocop:disable Metrics
+        self.attributes ||= {}
+        if !(methods.last.is_a?(String) || methods.last.is_a?(Symbol)) || methods.last == :boolean
+          type = methods.pop
+          type = [TrueClass, FalseClass] if type == :boolean
+          type = type.is_a?(Array) ? type.map(&:name) : type.name
+          methods.each do |method|
+            attributes[method] = {
+              type:,
+              direction:,
+              array:,
+              default:,
+              required:
+            }
+          end
+        end
+        methods.each do |method|
+          define_method(method) { context[method] }
+        end
+        return if direction != :output
+
+        methods.each do |method|
+          define_method(:"#{method}=") { |value| set_attribute(method, value) }
+        end
+      end
+
+      # Defines an input attribute.
+      # @param methods [Symbol, String] The input names.
+      # @param array [bool] Whether the input is an array.
+      # @param default [untyped, nil] Default value.
+      # @param required [bool] Whether the input is required.
+      # @param writer [bool] Whether to define a writer method.
+      def input(*methods, array: false, default: nil, required: false, writer: false)
+        attribute(*methods, array:, default:, required:, direction: writer ? :output : :input)
+      end
+
+      # Defines an output attribute.
+      # @param methods [Symbol, String] The output names.
+      # @param array [bool] Whether the output is an array.
+      # @param default [untyped, nil] Default value.
+      # @param required [bool] Whether the output is required.
+      def output(*methods, array: false, default: nil, required: false)
+        attribute(*methods, array:, default:, required:)
+      end
+
+      # Returns all attributes defined in the class hierarchy.
+      # @return [Hash[Symbol, Hash[Symbol, untyped]]]
+      def all_attributes
+        return @all_attributes if defined?(@all_attributes)
+
+        klass = self
+        attributes_arr = []
+        loop do
+          attributes_arr << klass.attributes
+          klass = klass.superclass
+          break if klass == Object
+        end
+        @all_attributes ||= attributes_arr.reverse.compact.each_with_object({}) { |attrs, result| result.merge!(attrs) }
+      end
+
+      # Removes all cached attributes.
+      # @return [void]
+      def remove_all_attributes!
+        remove_instance_variable(:@all_attributes) if defined?(@all_attributes)
+      end
+    end
+
+    def initialize(*)
+      super
+      initialize_default_values
+      errors = check_attributes
+      context.fail!(errors:, interactor: self.class.name) unless errors.empty?
+    rescue Failure # rubocop:disable Lint/SuppressedException
+    end
+
+    # Runs the interactor, raising a Failure if the context has failed.
+    # @return [untyped]
+    def run!
+      raise Failure, context if context.failure?
+
+      super
+    end
+
+    private
+
+    def initialize_default_values
+      self.class.all_attributes
+          .select { |key, options| !options[:default].nil? && !context.respond_to?(key) }
+          .each do |key, options|
+        value =
+          if options[:default].is_a?(Proc)
+            instance_exec(*[self, context][0, options[:default].arity], &options[:default])
+          else
+            deep_dup(options[:default])
+          end
+        set_attribute(key, value)
+      end
+    end
+
+    def set_attribute(key, value)
+      error = check_attribute(key, value)
+      context.fail!(errors: { key => [error] }) if error
+      context[key] = value
+    end
+
+    def check_attributes
+      self.class.all_attributes.filter_map do |key, _options|
+        error = check_attribute(key)
+        [key, [error]] if error
+      end.to_h
+    end
+
+    def check_attribute(key, value = nil) # rubocop:disable Metrics
+      options = self.class.all_attributes[key]
+      return unless options
+
+      value ||= context[key]
+      types = [options[:type]].flatten.map { safe_constantize(_1) }
+      if value.nil?
+        return options[:required] ? "#{options[:direction].capitalize} param \"#{key}\" is required" : nil
+      end
+
+      if options[:array]
+        return if value.is_a?(Array) && value.all? { |item| types.any? { |type| item.is_a?(type) } }
+
+        return "#{options[:direction].capitalize} param \"#{key}\" is not kind of Array of #{types.join(', ')}"
+      end
+      return if types.any? { |type| value.is_a?(type) }
+
+      "#{options[:direction].capitalize} param \"#{key}\" is not kind of #{types.join(', ')}"
+    end
+  end
+end

data/lib/interactor/contextable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides context management for interactors.
+  module Contextable
+    # Initializes the contextable with a context hash.
+    # @param context [Hash] The context data.
+    def initialize(context = {})
+      @context = LightContext.build(context)
+    end
+
+    # Returns the context object.
+    # @return [LightContext]
+    def ctx
+      @context
+    end
+  end
+end

data/lib/interactor/duration/base_formatter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Duration
+    # Base class for duration formatters.
+    class BaseFormatter
+      # Initializes the formatter with duration data.
+      # @param duration Array[String, Array[Float, Float]] The duration data.
+      def initialize(duration, options = {})
+        @duration = duration
+        @options = options
+      end
+
+      # Returns the duration data.
+      # @return Array[String, Array[Float, Float]]
+      def value
+        @duration
+      end
+
+      class << self
+        def value(data)
+          format = ::Interactor::Extended.configuration.duration_format&.to_sym
+          case format
+          when :json, :flat_json then JsonFormatter
+          when :string, :flat_string then StringFormatter
+          else ColorStringFormatter
+          end.new(data, flat: format.to_s.match(/^flat_/)).value
+        end
+      end
+    end
+  end
+end

data/lib/interactor/duration/color_string_formatter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Duration
+    # Formats duration data into a colorized string.
+    class ColorStringFormatter < StringFormatter
+      protected
+
+      def message(node, max)
+        [
+          ::Interactor::Colorize.colorize(node[:name].ljust(max - (node[:level] * 2)), :yellow),
+          [
+            "count: #{node[:count]}".ljust(10),
+            "time: #{::Interactor::Colorize.colorize(node[:time].to_s.ljust(25), :green)}",
+            "own: #{::Interactor::Colorize.colorize(node[:own].to_s.ljust(25), :green)}",
+            "max: #{::Interactor::Colorize.colorize(node[:max].to_s.ljust(25), :green)}"
+          ].join("\t")
+        ].join("\t")
+      end
+    end
+  end
+end

data/lib/interactor/duration/json_formatter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Duration
+    # Formats duration data into a JSON-compatible array of hashes.
+    class JsonFormatter < BaseFormatter
+      def value
+        tree.then { @options[:flat] ? to_flat(_1) : _1 }
+      end
+
+      protected
+
+      def tree
+        @tree ||= process_duration(@duration.then { @options[:flat] ? process_flat_duration(_1) : _1 })
+      end
+
+      def process_duration(data, level = 0)
+        data.group_by(&:first).map do |name, values|
+          {
+            name:,
+            level:,
+            count: values.count,
+            time: values.sum { _1[3] - _1[2] }.fdiv(values.count),
+            own: values.sum { _1[4] }.fdiv(values.count),
+            max: values.max_by { _1[4] }.last,
+            children: process_duration(values.flat_map { _1[1] }, level + 1)
+          }
+        end
+      end
+
+      def process_flat_duration(data)
+        data.flat_map { [_1.dup.tap { |value| value[1] = [] }] + process_flat_duration(_1[1]) }
+      end
+
+      def to_flat(data)
+        data.each_with_object([]) do |item, result|
+          result << item.except(:children)
+          result.concat(to_flat(item[:children]))
+        end
+      end
+    end
+  end
+end

data/lib/interactor/duration/string_formatter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Duration
+    # Formats duration data into a string.
+    class StringFormatter < JsonFormatter
+      # Returns the string representation of the duration data.
+      # @return String
+      def value
+        super
+        flat_data = to_flat(tree)
+
+        if @options[:flat]
+          max = flat_data.map { _1[:name].length }.max
+          return flat_data.map { message(_1, max) }.join("\n")
+        end
+
+        max = flat_data.map { (_1[:level] * 2) + _1[:name].length }.max
+        tree_value(tree, max).strip
+      end
+
+      protected
+
+      def tree_value(node, max, prefix = '', is_last: true, connector: nil, new_prefix: nil) # rubocop:disable Metrics
+        if node.is_a?(Array)
+          return node.map.with_index do |child, i|
+            tree_value(child, max, '', is_last: i == node.size - 1, connector: '', new_prefix: '')
+          end.join
+        end
+
+        children = node[:children].to_a
+        new_prefix ||= prefix + (is_last ? '  ' : '│ ')
+        [
+          prefix,
+          connector || (is_last ? '└ ' : '├ '),
+          message(node, max),
+          "\n",
+          children.map.with_index do |child, i|
+            tree_value(child, max, new_prefix, is_last: i == children.size - 1)
+          end.join
+        ].join
+      end
+
+      def message(node, max)
+        [
+          node[:name].ljust(max - (@options[:flat] ? 0 : node[:level] * 2)),
+          [
+            "count: #{node[:count]}".ljust(10),
+            "time: #{node[:time].to_s.ljust(25)}",
+            "own: #{node[:own].to_s.ljust(25)}",
+            "max: #{node[:max].to_s.ljust(25)}"
+          ].join("\t")
+        ].join("\t")
+      end
+    end
+  end
+end

data/lib/interactor/duration.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides duration tracking for interactors.
+  module Duration
+    Storage = Struct.new(:data, :total)
+    class << self
+      # Includes the duration tracking functionality into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        base.extend(ClassMethods)
+        base.class_eval do # rubocop:disable Metrics/BlockLength
+          around :_process_duration
+
+          def self.inherited(subclass)
+            super
+            subclass.around :_process_duration
+          end
+
+          private
+
+          def _duration
+            Thread.current.thread_variable_get('interactor.duration')
+          end
+
+          def _duration=(value)
+            Thread.current.thread_variable_set('interactor.duration', value)
+          end
+
+          def _duration_current
+            Thread.current.thread_variable_get('interactor.duration_current')
+          end
+
+          def _duration_current=(value)
+            Thread.current.thread_variable_set('interactor.duration_current', value)
+          end
+
+          def _duration_clock
+            Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+          end
+
+          def _process_duration(interactor, key = self.class.name)
+            self._duration ||= nil
+            initial_operation = _duration.nil?
+            self._duration = Storage.new(data: [], total: 0) if _duration.nil?
+            parent = _duration.data << (current = [key, []])
+            _duration.data = current[1]
+            duration_total = _duration.total.clone
+            current[2] = _duration_clock
+            interactor.call
+          ensure
+            current[3] = _duration_clock
+            current[4] = current[3] - current[2] - (_duration.total - duration_total)
+            _duration.data = parent
+            _duration.total += current[4]
+            _duration_print if initial_operation
+          end
+
+          def _duration_print
+            data = _duration.data
+            self._duration = nil
+            return data.each { _duration_current.push(_1) } if _duration_current
+
+            ::Interactor::Extended.configuration.on_duration&.call(BaseFormatter.value(data))
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      # Enables duration tracking for the next defined method (or all methods if `all` is true).
+      # @param all [bool] When true, tracks every subsequently defined method.
+      # @return [void]
+      def duration(all = false) # rubocop:disable Style/OptionalBooleanParameter
+        @__duration_all_methods = true if all
+        @__duration_next_method = true
+      end
+
+      # Wraps any method defined after a `duration` call with duration tracking.
+      # @param name [Symbol] The name of the method that was just added.
+      # @return [void]
+      def method_added(name)
+        super
+        return unless @__duration_next_method
+
+        @__duration_next_method = false
+        original = instance_method(name)
+        define_method(name) do |*args, **kwargs, &block|
+          key = "#{self.class.name}##{name}"
+          interactor = -> { original.bind_call(self, *args, **kwargs, &block) }
+          _process_duration(interactor, key)
+        end
+        @__duration_next_method = true if @__duration_all_methods
+      end
+    end
+  end
+end

data/lib/interactor/extended/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Extended
+    # Manages configuration for the Interactor Extended gem.
+    class Configuration
+      attr_accessor :logger,
+                    :type, # ctx|light|legacy|all|all_debug
+                    :duration_format, # json|string|color_string
+                    :on_duration
+      attr_reader :types
+
+      # Initializes the configuration with default values.
+      def initialize
+        @logger = defined?(Rails) ? Rails.logger : ::Logger.new($stdout)
+        @type = :all
+        @duration_format = :color_string
+        @on_duration = -> { @logger.debug("\n#{_1}") }
+        @types = {}
+        add_type!(:base)
+        add_type!(:ctx, [::Interactor::Contextable])
+        add_type!(:light, [
+                    ::Interactor::LightContextDefinition,
+                    ::Interactor::Populate,
+                    ::Interactor::Organize,
+                    ::Interactor::Threadable
+                  ], :ctx)
+        add_type!(:legacy, [
+                    ::Interactor::ContextDefinition,
+                    ::Interactor::Populate,
+                    ::Interactor::Organize,
+                    ::Interactor::Threadable,
+                    ::Interactor::Jobify
+                  ], :ctx)
+        add_type!(:all, [::Interactor::Colorize, ::Interactor::Loggable], :legacy)
+        add_type!(:all_debug, [::Interactor::Duration], :all)
+      end
+
+      # Adds a new type to the configuration.
+      # @param type [Symbol] The name of the type.
+      # @param modules [Array<Module>] The modules to include.
+      # @param inherit [Symbol, nil] The type to inherit from.
+      # @raise [RuntimeError] If the type already exists.
+      def add_type!(type, modules = [], inherit = nil)
+        raise 'Can\'t replace' if @types.key?(type.to_sym)
+
+        @types[type.to_sym] = (inherit ? @types[inherit.to_sym].to_a : []) + modules
+      end
+    end
+  end
+end

data/lib/interactor/extended/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Extended
+    # Base error class for the Extended gem.
+    class Error < StandardError; end
+  end
+end

data/lib/interactor/extended/helpers.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Extended
+    # Provides helper methods for the Extended gem.
+    module Helpers
+      # Deeply duplicates an object.
+      # @param obj [untyped] The object to duplicate.
+      # @return [untyped]
+      def deep_dup(obj)
+        case obj
+        when Hash
+          obj.to_h { |k, v| [deep_dup(k), deep_dup(v)] }
+        when Array
+          obj.map { deep_dup(_1) }
+        when NilClass, FalseClass, TrueClass, Symbol, Numeric
+          obj
+        else
+          obj.dup
+        end
+      end
+
+      # Deeply transforms keys of an object.
+      # @param object [untyped] The object to transform.
+      # @yield [Symbol] The key to transform.
+      # @return [untyped]
+      def deep_transform_keys(object, &block)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            result[yield(key)] = deep_transform_keys(value, &block)
+          end
+        when Array
+          object.map { deep_transform_keys(_1, &block) }
+        else
+          object
+        end
+      end
+
+      # Safely constantizes a string.
+      # @param camel_cased_word [String] The string to constantize.
+      # @return [untyped]
+      def safe_constantize(camel_cased_word)
+        Object.const_get(camel_cased_word)
+      rescue NameError => e
+        raise if e.name && !(camel_cased_word.to_s.split('::').include?(e.name.to_s) ||
+          e.name.to_s == camel_cased_word.to_s)
+      rescue LoadError => e
+        message = e.respond_to?(:original_message) ? e.original_message : e.message
+        raise unless /Unable to autoload constant #{const_regexp(camel_cased_word)}/.match?(message)
+      end
+    end
+  end
+end

data/lib/interactor/extended/version.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Interactor
+  module Extended
+    # The version string for the gem.
+    VERSION =
+      if File.exist?(File.expand_path(File.join(__dir__, '../../../VERSION')))
+        File.read(File.expand_path(File.join(__dir__, '../../../VERSION')))
+      else
+        ''
+      end.strip.freeze
+
+    class << self
+      # Returns the full version string including revision.
+      # @return [String]
+      def version
+        [VERSION, revision].compact.join('-')
+      end
+
+      # Returns the git revision if available.
+      # @return [String, nil]
+      def revision
+        source = Gem::Specification.find_by_name('interactor-extended')&.source
+        source.revision if source.is_a?(Bundler::Source::Git)
+      rescue Gem::MissingSpecError
+        nil
+      end
+    end
+  end
+end