interactor-extended 0.1.0

data/lib/interactor/extended.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'interactor'
+require 'logger'
+require_relative 'extended/version'
+require_relative 'extended/helpers'
+require_relative 'extended/configuration'
+require_relative 'contextable'
+require_relative 'light_context'
+require_relative 'light_context_definition'
+require_relative 'context_definition'
+require_relative 'organize'
+require_relative 'populate'
+require_relative 'loggable'
+require_relative 'threadable'
+require_relative 'duration/base_formatter'
+require_relative 'duration/json_formatter'
+require_relative 'duration/string_formatter'
+require_relative 'duration/color_string_formatter'
+require_relative 'duration'
+require_relative 'jobify'
+require_relative 'colorize'
+require_relative 'flow'
+require_relative 'operation'
+
+module Interactor
+  module Extended
+    @cache = {}
+    class << self
+      # Returns the current configuration.
+      # @return [Configuration]
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Sets the configuration.
+      # @param config [Configuration] The new configuration.
+      # @return [Configuration]
+      attr_writer :configuration
+
+      # Yields the configuration for customization.
+      # @yield [Configuration] The configuration object.
+      # @return [untyped]
+      def configure
+        yield configuration
+      end
+
+      # Returns the modules to include for a given kind and type.
+      # @param kind [Symbol] The kind of module (:flow or :operation).
+      # @param type [Symbol, Array<Symbol>] The type or types of modules.
+      # @return [Array<Module>]
+      def modules(kind, type)
+        [
+          kind == :flow ? ::Interactor::Organizer : ::Interactor,
+          *(type.is_a?(Array) ? type : configuration.types[type].to_a)
+        ]
+      end
+
+      # Builds a module containing the specified kinds and types.
+      # @param kind [Symbol] The kind of module.
+      # @param type [Symbol, Array<Symbol>] The type or types of modules.
+      # @return [Module]
+      def build_module(kind, type)
+        modules = modules(kind, type)
+        @cache[[kind, type]] ||= Module.new do
+          define_singleton_method(:included) do |base|
+            modules.each { base.include(_1) }
+          end
+        end
+      end
+
+      # Spawns a new thread that inherits the current duration tracking context.
+      # @yield The block to execute in the new thread.
+      # @return [Thread]
+      def thread(&block)
+        current = Thread.current.thread_variable_get('interactor.duration')&.data
+        Thread.new do
+          Thread.current.thread_variable_set('interactor.duration_current', current)
+          block.call
+        end
+      end
+    end
+  end
+end

data/lib/interactor/flow.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides flow management for interactors.
+  module Flow
+    class << self
+      # Includes the flow modules into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        Extended.modules(:flow, ::Interactor::Extended.configuration.type).each { base.include(_1) }
+      end
+
+      # Builds a flow module for the given type.
+      # @param type [Symbol] The type of flow.
+      # @return [Module]
+      def [](type)
+        Extended.build_module(:flow, type)
+      end
+    end
+  end
+end

data/lib/interactor/jobify.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides jobify functionality to interactor classes, allowing them to be executed as background jobs.
+  module Jobify
+    include Interactor::Extended::Helpers
+
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      attr_reader :job_active, :job_class, :job_default, :job_params
+
+      # Configures the interactor to be jobified.
+      # @param klass [Class, nil] The job class to use. Defaults to `#{self.class.name}Job`.
+      # @param params [untyped, nil] Parameters to pass to the job. Can be a Proc.
+      # @param default [bool] Whether jobify is enabled by default.
+      # @yield [interactor] Yields the interactor instance to generate params.
+      def jobify(klass: nil, params: nil, default: false, &block)
+        @job_active = true
+        @job_class = klass
+        @job_default = default
+        @job_params = params || block
+      end
+    end
+
+    # Returns whether the job is active.
+    # @return [bool, nil]
+    def job_active
+      self.class.job_active
+    end
+
+    # Returns whether the job is enabled by default.
+    # @return [bool]
+    def job_default
+      self.class.job_default
+    end
+
+    # Runs the interactor, potentially as a job.
+    # @return [untyped]
+    def run!
+      return super if !jobify? || !job_active
+
+      with_hooks { perform_job(job_params) }
+    end
+
+    protected
+
+    # Determines if jobify should be used based on context or default.
+    # @return [bool]
+    def jobify?
+      context[:jobify].nil? ? job_default : context[:jobify]
+    end
+
+    # Returns the job class.
+    # @return [Class]
+    def job_class
+      self.class.job_class || Object.const_get("#{self.class.name}Job")
+    end
+
+    # Returns the job parameters.
+    # @return [untyped]
+    def job_params
+      self.class.job_params&.call(self)
+    end
+
+    # Checks if the job should be performed with a delay.
+    # @return [bool]
+    def perform_in?
+      context[:jobify].to_s.to_i.positive?
+    end
+
+    # Performs the job with the given parameters.
+    # @param params [untyped] The parameters for the job.
+    # @return [void]
+    def perform_job(params = nil)
+      args = (params || context.to_h.reject { |key| key.match(/^_/) }).then do |parameters|
+        parameters.respond_to?(:as_json) ? parameters.as_json : deep_transform_keys(parameters, &:to_s)
+      end
+      perform_in? ? perform_in(context[:jobify].to_i, args) : perform_later(args)
+    end
+
+    # Performs the job later (asynchronously).
+    # @param args [untyped] The arguments for the job.
+    # @return [void]
+    def perform_later(args)
+      return job_class.perform_later(args) if job_class.respond_to?(:perform_later)
+
+      job_class.perform_async(args) if sidekiq?
+    end
+
+    # Performs the job in with a delay.
+    # @param wait [untyped] The delay duration.
+    # @param args [untyped] The arguments for the job.
+    # @return [void]
+    def perform_in(wait, args)
+      return job_class.perform_in(wait, args) if job_class.respond_to?(:perform_in)
+
+      job_class.set(wait:).perform_later(args) if application_job?
+    end
+
+    # Checks if jos class is Sidekiq.
+    # @return [bool]
+    def sidekiq?
+      SidekiqJob.included_modules.include?(Sidekiq::Job)
+    rescue StandardError
+      false
+    end
+
+    # Checks if job class is ApplicationJob.
+    # @return [bool]
+    def application_job?
+      ApplicationJob.superclass == ActiveJob::Base
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/interactor/light_context.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Interactor
+  # A lightweight context object for interactors.
+  class LightContext < BasicObject
+    %i[
+      block_given?
+      class
+      hash
+      instance_of?
+      instance_variables
+      is_a?
+      kind_of?
+      method
+      methods
+      nil?
+      object_id
+      private_methods
+      public_send
+      send
+      tap
+      then
+      raise
+      itself
+    ].each do |method_name|
+      define_method(method_name, ::Kernel.instance_method(method_name))
+    end
+
+    # Checks if the context is successful.
+    # @return [bool]
+    def success?
+      !failure?
+    end
+
+    # Checks if the context has failed.
+    # @return [bool]
+    def failure?
+      @failure || false
+    end
+
+    # Fails the context with the given data.
+    # @param context [Hash] The failure data.
+    # @raise [Failure] Always raises a Failure.
+    def fail!(context = {})
+      context.each { |key, value| self[key.to_sym] = value }
+      @failure = true
+      raise Failure, self
+    end
+
+    # Marks an interactor as called.
+    # @param interactor [untyped] The interactor instance.
+    def called!(interactor)
+      _called << interactor
+    end
+
+    # Triggers rollback for all called interactors.
+    # @return [bool]
+    def rollback!
+      return false if @rolled_back
+
+      _called.reverse_each(&:rollback)
+      @rolled_back = true
+    end
+
+    # Returns the list of interactors called so far (used for rollback).
+    # @return [Array<untyped>]
+    def _called
+      @called ||= []
+    end
+
+    # Initializes the context with data.
+    # @param data [Hash] The initial data.
+    def initialize(data = {})
+      @data = data.to_h.transform_keys(&:to_sym)
+    end
+
+    # Converts the context to a hash.
+    # @return [Hash]
+    def to_h
+      data.to_h.clone
+    end
+
+    # Returns a string representation of the context.
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{to_h}>"
+    end
+
+    # Returns a string representation of the context.
+    # @return [String]
+    def to_s
+      inspect
+    end
+
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
+    # Checks if the context contains a key.
+    # @param name [untyped] The key to check.
+    # @return [bool]
+    def key?(name)
+      data.key?(name.to_sym)
+    end
+
+    # Retrieves a value by key.
+    # @param name [untyped] The key.
+    # @return [untyped]
+    def [](name)
+      data[name.to_sym]
+    end
+
+    # Sets a value by key.
+    # @param key [untyped] The key.
+    # @param value [untyped] The value.
+    # @return [untyped]
+    def []=(key, value)
+      data[key.to_sym] = value
+    end
+
+    # Checks if the context responds to a method.
+    # @param name [untyped] The method name.
+    # @param include_private [bool] Whether to include private methods.
+    # @return [bool]
+    def respond_to?(name, include_private = false) # rubocop:disable Style/OptionalBooleanParameter
+      self.class.method_defined?(name) || respond_to_missing?(name, include_private)
+    end
+
+    # Deconstructs the context for pattern matching.
+    # @param keys [Array<Symbol>, nil] The keys to include.
+    # @return [Hash[Symbol, untyped]]
+    def deconstruct_keys(keys = nil)
+      deconstructed_keys = to_h.merge(success: success?, failure: failure?)
+      keys ? deconstructed_keys.slice(*keys) : deconstructed_keys
+    end
+
+    private
+
+    attr_reader :data
+
+    def respond_to_missing?(name, _include_private = false)
+      return true if name.end_with?('=')
+      return true if name.end_with?('?') && data.key?(name.to_s.chomp('?').to_sym)
+      return true if data.key?(name.to_sym)
+
+      false
+    end
+
+    def method_missing(name, *args)
+      if name.end_with?('?') && data.key?(key = name.to_s.chomp('?').to_sym)
+        value = data[key]
+        value.respond_to?(:empty?) ? !value.empty? : !!value # rubocop:disable Style/DoubleNegation
+      elsif name.end_with?('=')
+        data[name.to_s.chomp('=').to_sym] = args.first
+      else
+        data[name]
+      end
+    end
+
+    class << self
+      # Builds a LightContext from a hash or returns the context itself.
+      # @param context [Hash, LightContext] The context data.
+      # @return [LightContext]
+      def build(context = {})
+        context.is_a?(self) ? context : new(context.to_h)
+      end
+    end
+  end
+end

data/lib/interactor/light_context_definition.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Defines inputs and outputs for a light context interactor.
+  module LightContextDefinition
+    include Interactor::Extended::Helpers
+
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # 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.
+      # @param required [bool] Whether the attribute is required.
+      # @param direction [Symbol] The direction (:input or :output).
+      def attribute(*methods, array: false, default: nil, required: false, direction: :output) # rubocop:disable Lint/UnusedMethodArgument
+        methods.pop if !(methods.last.is_a?(String) || methods.last.is_a?(Symbol)) || methods.last == :boolean
+        methods.each do |method|
+          define_method(method) { context[method] }
+        end
+        return if direction != :output
+
+        methods.each do |method|
+          define_method(:"#{method}=") { context[method] = _1 }
+        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
+    end
+  end
+end

data/lib/interactor/loggable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides logging functionality for interactors.
+  module Loggable
+    class << self
+      # Includes the logging functionality into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # Returns the logger from the configuration.
+      # @return [untyped]
+      def logger
+        ::Interactor::Extended.configuration.logger
+      end
+    end
+
+    # Returns the logger.
+    # @return [untyped]
+    def logger
+      self.class.logger
+    end
+  end
+end

data/lib/interactor/operation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides operation management for interactors.
+  module Operation
+    class << self
+      # Includes the operation modules into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        Extended.modules(:operation, ::Interactor::Extended.configuration.type).each { base.include(_1) }
+      end
+
+      # Builds an operation module for the given type.
+      # @param type [Symbol] The type of operation.
+      # @return [Module]
+      def [](type)
+        Extended.build_module(:operation, type)
+      end
+    end
+  end
+end

data/lib/interactor/organize.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides orchestration functionality for interactors.
+  module Organize
+    # A thread runner that executes a klass in a new thread.
+    class ThreadRunner < Proc
+      alias call! call
+    end
+
+    class << self
+      # Includes the organize functionality into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # Creates a ThreadRunner for the given class.
+      # @param klass [Class] The class to run in a thread.
+      # @return [ThreadRunner]
+      def thread(klass)
+        ThreadRunner.new { |context| ::Interactor::Extended.thread { klass.call!(context) } }
+      end
+    end
+
+    # Executes the organized interactors.
+    # @return [untyped]
+    def call
+      organize(organized) if self.class.respond_to?(:organized)
+    end
+
+    protected
+
+    # Organizes the execution of interactors.
+    # @param organized [untyped] The interactors to organize.
+    # @return [untyped]
+    def organize(*organized)
+      organized.flatten.map { _1.call!(context) }.map { _1.join if _1.is_a?(Thread) }
+    end
+
+    # Returns the organized interactors.
+    # @return [untyped]
+    def organized
+      context[:organized] || self.class.organized
+    end
+  end
+end

data/lib/interactor/populate.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides context population functionality.
+  module Populate
+    class << self
+      # Includes the populate functionality into a base class.
+      # @param base [Class] The class to include the module into.
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # Calls the interactor with the given arguments.
+      # @param args [untyped] The arguments.
+      # @return [untyped]
+      def call(*args)
+        populate(*args) { super(_1) }
+      end
+
+      # Calls the interactor with the given arguments, raising on failure.
+      # @param args [untyped] The arguments.
+      # @return [untyped]
+      def call!(*args)
+        populate(*args) { super(_1) }
+      end
+
+      private
+
+      # Populates the context with data from the parent context.
+      # @param context [Hash] The context to populate.
+      # @param parent_context [untyped] The parent context.
+      # @param keys [untyped] The keys to populate.
+      # @yield [context] The context to yield.
+      # @return [untyped]
+      def populate(context = {}, parent_context = nil, *keys) # rubocop:disable Metrics
+        parent_context = context[:context] if context[:context]
+        keys = context[:context_keys] if context[:context_keys]
+        return unless block_given?
+        return yield(context) if parent_context.nil?
+
+        original_keys = keys
+        keys = parent_context.to_h.keys.grep(/^_/) if original_keys.empty?
+        keys&.each { context[_1] = parent_context[_1] }
+        yield(context).tap do |result|
+          keys = result.to_h.keys.grep(/^_/) if original_keys.empty?
+          keys.each { parent_context[_1] = result[_1] }
+        end
+      end
+    end
+
+    protected
+
+    # Assigns data to the context.
+    # @param data [Hash] The data to assign.
+    # @return [LightContext]
+    def context_assign(data = {})
+      data.each { |key, value| context[key] = value }
+      context
+    end
+  end
+end

data/lib/interactor/threadable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Interactor
+  # Provides a thread helper that propagates duration tracking context into new threads.
+  module Threadable
+    # Spawns a new thread that inherits the current duration tracking context.
+    # @yield The block to execute in the new thread.
+    # @return [Thread]
+    def thread(&)
+      Interactor::Extended.thread(&)
+    end
+  end
+end

data/sig/interactor/colorize.rbs

@@ -0,0 +1,9 @@
+module Interactor
+  module Colorize
+    class << self
+      def colorize: (String msg, ?Symbol | nil color_value, ?color: Symbol | nil, ?mode: Symbol | nil, ?bg: Symbol | nil) -> String
+    end
+
+    def colorize: (*untyped) -> String
+  end
+end

data/sig/interactor/context_definition.rbs

@@ -0,0 +1,20 @@
+module Interactor
+  module ContextDefinition
+    class << self
+      def included: (untyped base) -> void
+    end
+
+    module ClassMethods
+      attr_accessor attributes: Hash[Symbol, Hash[Symbol, untyped]] | nil
+
+      def attribute: (*Symbol | String, ?array: bool, ?default: untyped, ?required: bool, ?direction: Symbol) -> void
+      def input: (*Symbol | String, ?array: bool, ?default: untyped, ?required: bool, ?writer: bool) -> void
+      def output: (*Symbol | String, ?array: bool, ?default: untyped, ?required: bool) -> void
+      def all_attributes: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def remove_all_attributes!: () -> void
+    end
+
+    def initialize: (*untyped) -> void
+    def run!: () -> untyped
+  end
+end

data/sig/interactor/contextable.rbs

@@ -0,0 +1,6 @@
+module Interactor
+  module Contextable
+    def initialize: (?Hash[untyped, untyped] context) -> void
+    def ctx: () -> LightContext
+  end
+end

data/sig/interactor/duration/base_formatter.rbs

@@ -0,0 +1,12 @@
+module Interactor
+  module Duration
+    class BaseFormatter
+      def initialize: (untyped duration, ?Hash[untyped, untyped] options) -> void
+      def value: () -> untyped
+
+      class << self
+        def value: (untyped data) -> untyped
+      end
+    end
+  end
+end

data/sig/interactor/duration/color_string_formatter.rbs

@@ -0,0 +1,9 @@
+module Interactor
+  module Duration
+    class ColorStringFormatter < StringFormatter
+      protected
+
+      def message: (Hash[Symbol, untyped] node, Integer max) -> String
+    end
+  end
+end