axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/axn/factory.rb

@@ -2,13 +2,20 @@
 
 module Axn
   class Factory
+    NOT_PROVIDED = :__not_provided__
+
     class << self
       # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
       def build(
+        callable = nil,
         # Builder-specific options
-        name: nil,
         superclass: nil,
-        expose_return_as: :nil,
+        expose_return_as: nil,
+
+        # Module inclusion options
+        include: [],
+        extend: [],
+        prepend: [],
 
         # Expose standard class-level options
         exposes: [],
@@ -30,19 +37,35 @@ module Axn
         # Strategies
         use: [],
 
+        # Async configuration
+        async: nil,
+
+        # Logging configuration
+        log_calls: NOT_PROVIDED,
+        log_errors: NOT_PROVIDED,
+
+        # Internal flag to prevent recursion during action class creation
+        # Tracks which target class is having an action class created for it
+        _creating_action_class_for: nil,
+
         &block
       )
-        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
+        raise ArgumentError, "[Axn::Factory] Cannot receive both a callable and a block" if callable.present? && block_given?
+
+        executable = callable || block
+        raise ArgumentError, "[Axn::Factory] Must provide either a callable or a block" unless executable
+
+        args = executable.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
 
         if args[:opt].present? || args[:req].present? || args[:rest].present?
           raise ArgumentError,
-                "[Axn::Factory] Cannot convert block to action: block expects positional arguments"
+                "[Axn::Factory] Cannot convert callable to action: callable expects positional arguments"
         end
-        raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
+        raise ArgumentError, "[Axn::Factory] Cannot convert callable to action: callable expects a splat of keyword arguments" if args[:keyrest].present?
 
         if args[:key].present?
           raise ArgumentError,
-                "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
+                "[Axn::Factory] Cannot convert callable to action: callable expects keyword arguments with defaults (ruby does not allow introspecting)"
         end
 
         expects = _hydrate_hash(expects)
@@ -53,25 +76,7 @@ module Axn
         end
 
         # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
-        Class.new(superclass || Object) do
-          include Action unless self < Action
-
-          define_singleton_method(:name) do
-            [
-              superclass&.name.presence || "AnonymousAction",
-              name,
-            ].compact.join("#")
-          end
-
-          define_method(:call) do
-            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |field, hash|
-              hash[field] = public_send(field)
-            end
-
-            retval = instance_exec(**unwrapped_kwargs, &block)
-            expose(expose_return_as => retval) if expose_return_as.present?
-          end
-        end.tap do |axn|
+        _build_axn_class(superclass:, args:, executable:, expose_return_as:, include:, extend:, prepend:, _creating_action_class_for:).tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -80,9 +85,13 @@ module Axn
             axn.exposes(field, **opts)
           end
 
+          # Apply logging configuration (always apply if provided to override defaults)
+          axn.log_calls(log_calls) unless log_calls == NOT_PROVIDED
+          axn.log_errors(log_errors) unless log_errors == NOT_PROVIDED
+
           # Apply success and error handlers
-          _apply_handlers(axn, :success, success, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
-          _apply_handlers(axn, :error, error, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+          _apply_handlers(axn, :success, success, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+          _apply_handlers(axn, :error, error, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
 
           # Hooks
           axn.before(before) if before.present?
@@ -90,10 +99,10 @@ module Axn
           axn.around(around) if around.present?
 
           # Callbacks
-          _apply_handlers(axn, :on_success, on_success, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_failure, on_failure, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_error, on_error, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_exception, on_exception, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_success, on_success, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_failure, on_failure, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_error, on_error, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_exception, on_exception, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
 
           # Strategies
           Array(use).each do |strategy|
@@ -110,8 +119,19 @@ module Axn
             end
           end
 
+          # Async configuration
+          unless async.nil?
+            async_array = Array(async)
+            # Skip async configuration if adapter is nil (but not if array is empty)
+            if !async_array.empty? && async_array[0].nil?
+              # Do nothing - skip async configuration
+            else
+              _apply_async_config(axn, async_array)
+            end
+          end
+
           # Default exposure
-          axn.exposes(expose_return_as, allow_blank: true) if expose_return_as.present?
+          axn.exposes(expose_return_as, optional: true) if expose_return_as.present?
         end
       end
       # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
@@ -138,16 +158,84 @@ module Axn
         return unless value.present?
 
         # Check if the value itself is a hash (this catches the case where someone passes a hash literal)
-        raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if value.is_a?(Hash)
+        raise Axn::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if value.is_a?(Hash)
 
         # Wrap in Array() to handle both single values and arrays
         Array(value).each do |handler|
-          raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if handler.is_a?(Hash)
+          raise Axn::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if handler.is_a?(Hash)
 
           # Both descriptor objects and simple cases (string/proc) can be used directly
           axn.public_send(method_name, handler)
         end
       end
+
+      def _build_axn_class(superclass:, args:, executable:, expose_return_as:, include: nil, extend: nil, prepend: nil, _creating_action_class_for: nil) # rubocop:disable Lint/UnderscorePrefixedVariableName
+        # Mark superclass if we're creating an action class (for recursion prevention)
+        # Track which target class is having an action created for it
+        superclass.instance_variable_set(:@_axn_creating_action_class_for, _creating_action_class_for) if _creating_action_class_for && superclass
+
+        Class.new(superclass || Object) do
+          include Axn unless self < Axn
+
+          Array(include).each { |mod| include mod }
+          Array(extend).each { |mod| extend mod }
+          Array(prepend).each { |mod| prepend mod }
+
+          # Set a default name for anonymous classes to help with debugging
+          define_singleton_method(:name) do
+            "AnonymousAxn_#{object_id}"
+          end
+
+          define_method(:call) do
+            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |field, hash|
+              hash[field] = public_send(field)
+            end
+
+            retval = instance_exec(**unwrapped_kwargs, &executable)
+            expose(expose_return_as => retval) if expose_return_as.present?
+          end
+        end
+      ensure
+        superclass.instance_variable_set(:@_axn_creating_action_class_for, nil) if _creating_action_class_for && superclass
+      end
+
+      def _apply_async_config(axn, async)
+        raise ArgumentError, "[Axn::Factory] Invalid async configuration" unless _validate_async_config(async)
+
+        adapter, *config_args = async
+
+        # Determine hash config and callable config
+        config = config_args.find { |arg| arg.is_a?(Hash) }
+        block = config_args.find { |arg| arg.respond_to?(:call) }
+
+        # Call async once with the determined values
+        axn.async(adapter, **(config || {}), &block)
+      end
+
+      def _validate_async_config(async_array)
+        return false unless async_array.length.between?(1, 3)
+
+        adapter = async_array[0]
+        second_arg = async_array[1]
+        third_arg = async_array[2]
+
+        # First arg must be adapter (symbol/string), false, or nil
+        return false unless adapter.is_a?(Symbol) || adapter.is_a?(String) || adapter == false || adapter.nil?
+
+        case async_array.length
+        when 1
+          # Pattern A: [:sidekiq], [false], or [nil]
+          true
+        when 2
+          # Pattern B: [:sidekiq, hash_or_callable] or [nil, hash_or_callable]
+          second_arg.is_a?(Hash) || second_arg.respond_to?(:call)
+        when 3
+          # Pattern C: [:sidekiq, hash, callable] or [nil, hash, callable]
+          second_arg.is_a?(Hash) && third_arg.respond_to?(:call)
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/axn/form_object.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# This is a base class for all form objects that are used with Axn actions.
+#
+# It provides a number of conveniences for working with form objects, including:
+# - Automatically attr_accessor any attribute for which we add a validation
+# - Add support for nested forms
+# - Add support for money objects (analogous to 'include MoneyRails::ActiveRecord::Monetizable' for ActiveRecord models)
+module Axn
+  class FormObject
+    include ActiveModel::Model
+
+    class << self
+      attr_accessor :field_names
+
+      def inherited(subclass)
+        # Inherit field_names from parent class, or initialize as empty array if parent doesn't have any
+        subclass.field_names = (field_names || []).dup
+
+        super
+      end
+
+      # Override attr_accessor to track field names for automatic #to_h support
+      def attr_accessor(*attributes)
+        # Initialize field_names if not already set
+        self.field_names ||= []
+
+        # Add new attributes to the field_names array
+        self.field_names += attributes.map(&:to_sym)
+
+        super
+      end
+
+      # Automatically attr_accessor any attribute for which we add a validation
+      def validates(*attributes)
+        our_attributes = attributes.dup
+
+        # Pulled from upstream: https://github.com/rails/rails/blob/6f0d1ad14b92b9f5906e44740fce8b4f1c7075dc/activemodel/lib/active_model/validations/validates.rb#L106
+        our_attributes.extract_options!
+        our_attributes.each { |attr| attr_accessor(attr) }
+
+        super
+      end
+
+      # Add support for nested forms
+      def nested_forms(**kwargs)
+        kwargs.each do |name, klass|
+          validates name, presence: true
+
+          define_method("#{name}=") do |params|
+            return instance_variable_set("@#{name}", nil) if params.nil?
+
+            child_params = params.dup
+
+            # Automatically inject the parent into the child form if it has a parent= method
+            child_params[:parent_form] = self if klass.instance_methods.include?(:parent_form=)
+
+            instance_variable_set("@#{name}", klass.new(child_params))
+          end
+
+          validation_method_name = :"validate_#{name}_form"
+          validate validation_method_name
+          define_method(validation_method_name) do
+            return if public_send(name).nil? || public_send(name).valid?
+
+            public_send(name).errors.each do |error|
+              errors.add("#{name}.#{error.attribute}", error.message)
+            end
+          end
+          private validation_method_name
+        end
+      end
+      alias nested_form nested_forms
+    end
+
+    def to_h
+      return {} if self.class.field_names.nil?
+
+      self.class.field_names.each_with_object({}) do |field_name, hash|
+        next unless respond_to?(field_name)
+
+        # Skip parent_form to avoid infinite recursion with circular references
+        next if field_name == :parent_form
+
+        value = public_send(field_name)
+        hash[field_name] = value.is_a?(Axn::FormObject) ? value.to_h : value
+      end
+    end
+  end
+end

data/lib/axn/internal/logging.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Axn
+  module Internal
+    module Logging
+      def self.piping_error(desc, exception:, action: nil)
+        # If raise_piping_errors_in_dev is enabled and we're in development, raise instead of log.
+        # Test and production environments always swallow the error to match production behavior.
+        raise exception if Axn.config.raise_piping_errors_in_dev && Axn.config.env.development?
+
+        # Extract just filename/line number from backtrace
+        src = exception.backtrace.first.split.first.split("/").last.split(":")[0, 2].join(":")
+
+        message = if Axn.config.env.production?
+                    "Ignoring exception raised while #{desc}: #{exception.class.name} - #{exception.message} (from #{src})"
+                  else
+                    msg = "!! IGNORING EXCEPTION RAISED WHILE #{desc.upcase} !!\n\n" \
+                          "\t* Exception: #{exception.class.name}\n" \
+                          "\t* Message: #{exception.message}\n" \
+                          "\t* From: #{src}"
+                    "#{'⌵' * 30}\n\n#{msg}\n\n#{'^' * 30}"
+                  end
+
+        (action || Axn.config.logger).send(:warn, message)
+
+        nil
+      end
+    end
+  end
+end

data/lib/axn/internal/registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Axn
+  module Internal
+    class Registry
+      class NotFound < StandardError; end
+      class DuplicateError < StandardError; end
+
+      class << self
+        def built_in
+          @built_in ||= begin
+            # Get the directory name from the class name (e.g., "Strategies" -> "strategies")
+            dir_name = name.split("::").last.underscore
+
+            # Load all files from the directory
+            files = ::Dir[File.join(registry_directory, dir_name, "*.rb")]
+            files.each { |file| require file }
+
+            # Get all modules defined within this class
+            constants = self.constants.map { |const| const_get(const) }
+            items = select_constants_to_load(constants)
+
+            # Convert module names to keys
+            items.to_h do |item|
+              name = item.name.split("::").last
+              key = name.underscore.to_sym
+              [key, item]
+            end
+          end
+        end
+
+        def register(name, item)
+          items = all # ensure built_in is initialized
+          key = name.to_sym
+          raise duplicate_error_class, "#{item_type} #{name} already registered" if items.key?(key)
+
+          items[key] = item
+          items
+        end
+
+        def all
+          @items ||= built_in.dup
+        end
+
+        def clear!
+          @items = built_in.dup
+        end
+
+        def find(name)
+          raise not_found_error_class, "#{item_type} name cannot be nil" if name.nil?
+          raise not_found_error_class, "#{item_type} name cannot be empty" if name.to_s.strip.empty?
+
+          all[name.to_sym] or raise not_found_error_class, "#{item_type} '#{name}' not found"
+        end
+
+        private
+
+        def item_type
+          # Subclasses can override this for better error messages
+          "Item"
+        end
+
+        def not_found_error_class
+          # Subclasses can override this to return their specific error class
+          NotFound
+        end
+
+        def duplicate_error_class
+          # Subclasses can override this to return their specific error class
+          DuplicateError
+        end
+
+        def registry_directory
+          # Subclasses must override this to return their directory
+          raise NotImplementedError, "Subclasses must implement registry_directory method"
+        end
+
+        def select_constants_to_load(constants)
+          # Subclasses can override this to select which constants to load
+          constants.select { |const| const.is_a?(Module) }
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/descriptor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    # Descriptor holds the information needed to mount an action
+    class Descriptor
+      attr_reader :name, :options, :mounted_axn, :mount_strategy, :existing_axn_klass, :block, :raw_kwargs, :kwargs
+
+      def initialize(name:, as:, axn_klass: nil, block: nil, kwargs: {})
+        @mount_strategy = MountingStrategies.find(as)
+        @existing_axn_klass = axn_klass
+
+        @name = name
+        @block = block
+        @raw_kwargs = kwargs
+
+        @kwargs = mount_strategy.preprocess_kwargs(**kwargs.except(*mount_strategy.strategy_specific_kwargs), axn_klass:)
+        @options = kwargs.slice(*mount_strategy.strategy_specific_kwargs)
+
+        @validator = Helpers::Validator.new(self)
+
+        @validator.validate!
+        freeze
+      end
+
+      def mount(target:)
+        validate_before_mount!(target:)
+        mount_strategy.mount(descriptor: self, target:)
+      end
+
+      def mounted_axn_for(target:)
+        # Check if the target already has this action class cached
+        cache_key = "#{@name}_#{object_id}_#{target.object_id}"
+
+        # Use a class variable to store the cache on the target
+        cache_var = :@_axn_cache
+        target.instance_variable_set(cache_var, {}) unless target.instance_variable_defined?(cache_var)
+        cache = target.instance_variable_get(cache_var)
+
+        return cache[cache_key] if cache.key?(cache_key)
+
+        # Check if constant is already registered
+        action_class_builder = Helpers::ClassBuilder.new(self)
+        namespace = Helpers::NamespaceManager.get_or_create_namespace(target)
+        constant_name = action_class_builder.generate_constant_name(@name.to_s)
+        if namespace.const_defined?(constant_name, false)
+          mounted_axn = namespace.const_get(constant_name)
+          cache[cache_key] = mounted_axn
+          return mounted_axn
+        end
+
+        # Build and configure action class
+        mounted_axn = action_class_builder.build_and_configure_action_class(target, @name.to_s, namespace)
+
+        # Cache on the target
+        cache[cache_key] = mounted_axn
+        mounted_axn
+      end
+
+      def mounted? = @mounted_axn.present?
+
+      private
+
+      def method_name = @name.to_s.underscore
+
+      def validate_before_mount!(target:)
+        # Method name collision validation is now handled in mount_axn
+        # This method is kept for potential future validation needs
+      end
+
+      def mounting_type_name
+        mount_strategy.name.split("::").last.underscore.to_s.humanize
+      end
+    end
+  end
+end