axn 0.1.0.pre.alpha.3 → 0.1.0.pre.alpha.4

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

@@ -4,6 +4,10 @@ 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(":")
 
@@ -14,7 +18,7 @@ module Axn
                           "\t* Exception: #{exception.class.name}\n" \
                           "\t* Message: #{exception.message}\n" \
                           "\t* From: #{src}"
-                    "#{"⌵" * 30}\n\n#{msg}\n\n#{"^" * 30}"
+                    "#{'⌵' * 30}\n\n#{msg}\n\n#{'^' * 30}"
                   end
 
         (action || Axn.config.logger).send(:warn, message)

data/lib/axn/mountable/helpers/class_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "axn/mountable/inherit_profiles"
+require "axn/exceptions"
 
 module Axn
   module Mountable
@@ -23,15 +24,25 @@ module Axn
         end
 
         def build_and_configure_action_class(target, name, namespace)
-          mounted_axn = build_action_class(target)
-          configure_class_name_and_constant(mounted_axn, name, namespace)
-          configure_axn_mounted_to(mounted_axn, target)
-          mounted_axn
+          # Mark target as having an action class being created to prevent recursion
+          # This is necessary because create_superclass_for_inherit_mode may create
+          # classes that inherit from target, triggering the inherited callback
+          target.instance_variable_set(:@_axn_creating_action_class_for, target)
+          begin
+            # Pass target through to Factory.build so it can mark the superclass
+            # The superclass flag is checked by the inherited callback in mountable.rb
+            mounted_axn = build_action_class(target, _creating_action_class_for: target)
+            configure_class_name_and_constant(mounted_axn, name, namespace, target)
+            configure_axn_mounted_to(mounted_axn, target)
+            mounted_axn
+          ensure
+            target.instance_variable_set(:@_axn_creating_action_class_for, nil)
+          end
         end
 
         private
 
-        def build_action_class(target)
+        def build_action_class(target, _creating_action_class_for: nil) # rubocop:disable Lint/UnderscorePrefixedVariableName
           existing_axn_klass = @descriptor.instance_variable_get(:@existing_axn_klass)
           return existing_axn_klass if existing_axn_klass
 
@@ -49,12 +60,15 @@ module Axn
             factory_kwargs[:superclass] = create_superclass_for_inherit_mode(target, inherit_config)
           end
 
+          # Pass the target class through to Factory.build so it can mark the superclass
+          factory_kwargs[:_creating_action_class_for] = _creating_action_class_for
+
           Axn::Factory.build(**factory_kwargs, &block)
         end
 
-        def configure_class_name_and_constant(axn_klass, name, axn_namespace)
+        def configure_class_name_and_constant(axn_klass, name, axn_namespace, target)
           configure_class_name(axn_klass, name, axn_namespace) if name.present?
-          register_constant(axn_klass, name, axn_namespace) if should_register_constant?(axn_namespace)
+          register_constant(axn_klass, name, axn_namespace, target) if should_register_constant?(axn_namespace)
         end
 
         def configure_axn_mounted_to(axn_klass, target)
@@ -148,12 +162,29 @@ module Axn
           end
         end
 
-        def register_constant(axn_klass, name, axn_namespace)
+        def register_constant(axn_klass, name, axn_namespace, target)
           constant_name = generate_constant_name(name)
 
-          # Only set the constant if it doesn't exist
-          return if axn_namespace.const_defined?(constant_name, false)
+          # Check if constant already exists - if so, only allow overwriting in inheritance scenarios
+          if axn_namespace.const_defined?(constant_name, false)
+            # Only allow overwriting if this is an inheritance scenario (child overriding parent)
+            # Check if the target's parent has the same method mounted (inheritance override)
+            parent = target.superclass
+            is_inheritance_override = parent.respond_to?(:_mounted_axn_descriptors) &&
+                                      parent._mounted_axn_descriptors.any? { |d| d.name.to_s == name.to_s }
+
+            # If it's not an inheritance override, this is a same-class collision
+            # Raise an error here for clarity, rather than silently skipping and failing later
+            # Use the same error message format as mount_method for consistency
+            unless is_inheritance_override
+              method_name = "#{name}!"
+              strategy_name = @descriptor.mount_strategy.name.split("::").last
+              raise Axn::Mountable::MountingError,
+                    "#{strategy_name} unable to attach -- method '#{method_name}' is already taken"
+            end
+          end
 
+          # Set the constant (either it doesn't exist, or it's an inheritance override)
           axn_namespace.const_set(constant_name, axn_klass)
         end
       end

data/lib/axn/mountable/helpers/namespace_manager.rb

@@ -14,50 +14,22 @@ module Axn
             return axn_class if axn_class.is_a?(Class)
           end
 
-          # Create a namespace class that inherits from parent's Axns if available
-          client_class = target
-          parent_axns = find_parent_axns_namespace(client_class)
-          namespace_class = create_namespace_class(client_class, parent_axns)
-
-          # Only set the constant if it doesn't exist
-          return if target.const_defined?(:Axns, false)
-
-          target.const_set(:Axns, namespace_class)
+          # Create a fresh namespace class for this target
+          create_namespace_class(target).tap do |namespace_class|
+            target.const_set(:Axns, namespace_class) unless target.const_defined?(:Axns, false)
+          end
         end
 
         private
 
-        def find_parent_axns_namespace(client_class)
-          return nil unless client_class.is_a?(Class)
-          return nil unless client_class.superclass.respond_to?(:_mounted_axn_descriptors)
-          return nil unless client_class.superclass.const_defined?(:Axns, false)
-
-          client_class.superclass.const_get(:Axns)
-        end
-
-        def create_namespace_class(client_class, parent_axns)
-          base_class = parent_axns || Class.new
-
-          Class.new(base_class) do
+        def create_namespace_class(client_class)
+          Class.new do
             define_singleton_method(:__axn_mounted_to__) { client_class }
 
             define_singleton_method(:name) do
               client_name = client_class.name.presence || "AnonymousClient_#{client_class.object_id}"
               "#{client_name}::Axns"
             end
-          end.tap do |ns|
-            update_inherited_action_classes(ns, client_class) if parent_axns
-          end
-        end
-
-        def update_inherited_action_classes(namespace, client_class)
-          namespace.constants.each do |const_name|
-            const_value = namespace.const_get(const_name)
-            next unless const_value.is_a?(Class) && const_value.respond_to?(:__axn_mounted_to__)
-
-            # Update __axn_mounted_to__ method on the existing class
-            const_value.define_singleton_method(:__axn_mounted_to__) { client_class }
-            const_value.define_method(:__axn_mounted_to__) { client_class }
           end
         end
       end

data/lib/axn/mountable/inherit_profiles.rb

@@ -45,12 +45,12 @@ module Axn
         case inherit
         when Symbol
           PROFILES.fetch(inherit) do
-            raise ArgumentError, "Unknown inherit profile: #{inherit.inspect}. Valid profiles: #{PROFILES.keys.join(", ")}"
+            raise ArgumentError, "Unknown inherit profile: #{inherit.inspect}. Valid profiles: #{PROFILES.keys.join(', ')}"
           end
         when Hash
           # Validate hash keys
           invalid_keys = inherit.keys - PROFILES[:none].keys
-          raise ArgumentError, "Invalid inherit keys: #{invalid_keys.join(", ")}. Valid keys: #{PROFILES[:none].keys.join(", ")}" if invalid_keys.any?
+          raise ArgumentError, "Invalid inherit keys: #{invalid_keys.join(', ')}. Valid keys: #{PROFILES[:none].keys.join(', ')}" if invalid_keys.any?
 
           # Merge with none profile to ensure all keys are present
           PROFILES[:none].merge(inherit)

data/lib/axn/mountable/mounting_strategies/_base.rb

@@ -31,17 +31,24 @@ module Axn
           # We allow overriding if this is a child class with a parent that has axn methods (inheritance scenario)
           # Otherwise, we raise an error for same-class method collisions
           if _should_raise_method_collision_error?(target, method_name)
-            raise MountingError, "#{name.split("::").last} unable to attach -- method '#{method_name}' is already taken"
+            raise MountingError, "#{name.split('::').last} unable to attach -- method '#{method_name}' is already taken"
           end
 
           target.define_singleton_method(method_name, &)
         end
 
-        private
-
         # Mount methods to the namespace and register the action class
         def mount_to_namespace(descriptor:, target:)
+          define_namespace_methods(descriptor:, target:)
+          # Register the action class as a constant in the namespace
           action_class_builder = Helpers::ClassBuilder.new(descriptor)
+          action_class_builder.mount(target, descriptor.name.to_s)
+        end
+
+        # Define namespace methods on the target's Axns namespace
+        # This is public so it can be called from the inherited callback
+        # without re-registering the constant (which is already created by mounted_axn_for)
+        def define_namespace_methods(descriptor:, target:)
           namespace = Helpers::NamespaceManager.get_or_create_namespace(target)
           name = descriptor.name
           descriptor_ref = descriptor
@@ -61,9 +68,6 @@ module Axn
             axn = descriptor_ref.mounted_axn_for(target:)
             axn.call_async(**kwargs)
           end
-
-          # Register the action class as a constant in the namespace
-          action_class_builder.mount(target, name.to_s)
         end
 
         # Check if we should raise an error for method collision

data/lib/axn/mountable/mounting_strategies/method.rb

@@ -46,7 +46,7 @@ module Axn
 
             if exposed_fields.size > 1
               raise MountingError,
-                    "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(", ")}. " \
+                    "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(', ')}. " \
                     "Use a fresh block with mount_axn_method or ensure the axn class has exactly one exposed field."
             end
           end
@@ -85,7 +85,7 @@ module Axn
             exposed_fields.first # Single field, assume it's expose_return_as
           else
             raise MountingError,
-                  "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(", ")}. " \
+                  "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(', ')}. " \
                   "Use a fresh block with mount_axn_method or ensure the axn class has exactly one exposed field."
           end
         end

data/lib/axn/mountable.rb

@@ -21,7 +21,6 @@ module Axn
   #
   # - `mount_axn` and `mount_axn_method`: `:lifecycle` - Inherits hooks, callbacks, messages, and async config (but not fields)
   # - `step`: `:none` - Completely independent to avoid conflicts
-  # - `enqueue_all_via`: `:async_only` - Only inherits async configuration
   #
   # ### Inheritance Profiles
   #
@@ -53,12 +52,6 @@ module Axn
   #     # Will NOT run log_start or track_success
   #   end
   #
-  #   # enqueue_all_via uses :async_only (only inherits async config)
-  #   MyClass.enqueue_all_via do
-  #     # Can call enqueue (uses inherited async config)
-  #     # Does NOT inherit hooks, callbacks, or messages
-  #   end
-  #
   # @example Custom inheritance control
   #   # Override step default to inherit lifecycle
   #   MyClass.step :my_step, inherit: :lifecycle do
@@ -75,6 +68,47 @@ module Axn
     def self.included(base)
       base.class_eval do
         class_attribute :_mounted_axn_descriptors, default: []
+
+        # Eagerly create action class constants for inherited descriptors
+        # (e.g. allow TeamsharesAPI::Company::Axns::Get.call to work *without* having to
+        # call TeamsharesAPI::Company.get! first)
+        def self.inherited(subclass)
+          super
+
+          # Only process if we have inherited descriptors from parent
+          return unless _mounted_axn_descriptors.any?
+
+          # Skip if subclass doesn't respond to _mounted_axn_descriptors
+          # This prevents recursion when creating action classes that inherit from target
+          return unless subclass.respond_to?(:_mounted_axn_descriptors)
+
+          # Skip if we're currently creating an action class (prevent infinite recursion)
+          # This is necessary because Axn::Factory.build creates classes that inherit from
+          # Axn (which includes Axn::Mountable), triggering inherited callbacks during
+          # action class creation.
+          superclass = subclass.superclass
+          creating_for = superclass&.instance_variable_get(:@_axn_creating_action_class_for)
+          return if creating_for
+
+          # Skip if this is an action class being created (they're in the Axns namespace)
+          # Action classes have names like "ParentClass::Axns::ActionName"
+          subclass_name = subclass.name
+          return if subclass_name&.include?("::Axns::")
+
+          # Eagerly create constants for all inherited descriptors
+          # mounted_axn_for will ensure namespace exists and create the constant
+          # If a child overrides, the new descriptor will replace the constant
+          _mounted_axn_descriptors.each do |descriptor|
+            # This will create the constant if it doesn't exist
+            descriptor.mounted_axn_for(target: subclass)
+            # Also define namespace methods on the child's namespace
+            # This ensures TeamsharesAPI::Company::Axns.get works even though
+            # the descriptor was originally mounted on TeamsharesAPI::Base
+            # We use define_namespace_methods instead of mount_to_namespace to
+            # avoid re-registering the constant (which is already created above)
+            descriptor.mount_strategy.define_namespace_methods(descriptor:, target: subclass)
+          end
+        end
       end
 
       MountingStrategies.all.each do |(_name, klass)|

data/lib/axn/rails/generators/axn_generator.rb

@@ -26,7 +26,25 @@ module Axn
         end
 
         def file_path
-          @file_path ||= name.underscore
+          @file_path ||= begin
+            path = name.underscore
+            # Strip the configured autoload namespace prefix if present
+            # e.g., if namespace is "Actions" and name is "Actions::Slack",
+            # strip "Actions::" to get "slack" instead of "actions/slack"
+            autoload_namespace = configured_autoload_namespace
+            if autoload_namespace && path.start_with?("#{autoload_namespace.underscore}/")
+              path.sub(%r{\A#{Regexp.escape(autoload_namespace.underscore)}/}, "")
+            else
+              path
+            end
+          end
+        end
+
+        def configured_autoload_namespace
+          return nil unless defined?(Axn) && Axn.config.rails.app_actions_autoload_namespace
+
+          namespace = Axn.config.rails.app_actions_autoload_namespace
+          namespace&.to_s
         end
 
         def expectations_with_types

data/lib/axn/rails/generators/templates/action.rb.erb

@@ -12,6 +12,6 @@ class <%= class_name %>
 
 <% end -%>
   def call
-    # TODO: Implement action logic
+    # TODO: Implement logic
   end
 end

data/lib/axn/result.rb

@@ -11,7 +11,7 @@ module Axn
       def ok(msg = nil, **exposures)
         exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
-        Axn::Factory.build(exposes:, success: msg) do
+        Axn::Factory.build(exposes:, success: msg, log_calls: false, log_errors: false) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -21,7 +21,7 @@ module Axn
       def error(msg = nil, **exposures, &block)
         exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
-        Axn::Factory.build(exposes:, error: msg) do
+        Axn::Factory.build(exposes:, error: msg, log_calls: false, log_errors: false) do
           exposures.each do |key, value|
             expose(key, value)
           end

data/lib/axn/strategies/form.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Axn
+  class Strategies
+    module Form
+      # @param expect [Symbol] the attribute name to expect in the context (e.g. :params)
+      # @param expose [Symbol] the attribute name to expose in the context (e.g. :form)
+      # @param type [Class, String] the form class to use, or a string constant path
+      # @param inject [Array<Symbol>] optional additional attributes to include in the form (e.g. [:user, :company])
+      # @yield block to define the form class when type is a string and the constant doesn't exist
+      def self.configure(expect: :params, expose: :form, type: nil, inject: nil, &block)
+        expect ||= :"#{expose.to_s.delete_suffix('_form')}_params"
+
+        # Aliasing to avoid shadowing/any confusion
+        expect_attr = expect
+        expose_attr = expose
+
+        Module.new do
+          extend ActiveSupport::Concern
+
+          included do
+            raise ArgumentError, "form strategy: must pass explicit :type parameter to `use :form` when applying to anonymous classes" if type.nil? && name.nil?
+
+            resolved_type = Axn::Strategies::Form.resolve_type(type, expose_attr, name, &block)
+
+            raise ArgumentError, "form strategy: #{resolved_type} must implement `valid?`" unless resolved_type.method_defined?(:valid?)
+
+            expects expect_attr, type: :params
+            exposes(expose_attr, type: resolved_type)
+
+            define_method expose_attr do
+              attrs_for_form = public_send(expect_attr)&.dup || {}
+
+              Array(inject).each do |ctx|
+                attrs_for_form[ctx] = public_send(ctx)
+              end
+
+              resolved_type.new(attrs_for_form)
+            end
+            memo expose_attr
+
+            before do
+              expose expose_attr => public_send(expose_attr)
+              fail! unless public_send(expose_attr).valid?
+            end
+          end
+        end
+      end
+
+      # Resolve the form type from the given parameters
+      # @param type [Class, String, nil] the form class, constant path, or nil for auto-detection
+      # @param expose_attr [Symbol] the attribute name to expose (used for auto-detection)
+      # @param action_name [String, nil] the name of the action class (used for auto-detection)
+      # @yield block to define the form class when type is a string and the constant doesn't exist
+      # @return [Class] the resolved form class
+      def self.resolve_type(type, expose_attr, action_name, &)
+        type ||= "#{action_name}::#{expose_attr.to_s.classify}"
+
+        if type.is_a?(Class)
+          raise ArgumentError, "form strategy: cannot provide block when type is a Class" if block_given?
+
+          return type
+        end
+
+        type.constantize.tap do
+          raise ArgumentError, "form strategy: cannot provide block when type constant #{type} already exists" if block_given?
+        end
+      rescue NameError
+        # Constant doesn't exist
+        raise ArgumentError, "form strategy: type constant #{type} does not exist and no block provided to define it" unless block_given?
+
+        # Create the class using the block, inheriting from Axn::FormObject
+        Class.new(Axn::FormObject).tap do |klass|
+          klass.class_eval(&)
+          assign_constant(type, klass)
+        end
+      end
+
+      # Helper method to assign a class to a constant path
+      # @param constant_path [String] the full constant path (e.g., "CreateUser::Form")
+      # @param klass [Class] the class to assign
+      def self.assign_constant(constant_path, klass)
+        parts = constant_path.split("::")
+        constant_name = parts.pop
+        parent_path = parts.join("::")
+
+        if parent_path.empty?
+          # Top-level constant
+          Object.const_set(constant_name, klass)
+        else
+          # Nested constant - ensure parent namespace exists
+          parent = parent_path.constantize
+          parent.const_set(constant_name, klass)
+        end
+      end
+    end
+  end
+end

data/lib/axn/strategies/transaction.rb

@@ -9,9 +9,16 @@ module Axn
         raise NotImplementedError, "Transaction strategy requires ActiveRecord" unless defined?(ActiveRecord)
 
         around do |hooked|
+          early_completion = nil
           ActiveRecord::Base.transaction do
             hooked.call
+          rescue Axn::Internal::EarlyCompletion => e
+            # EarlyCompletion is not an error - it's a control flow mechanism
+            # Store it to re-raise after transaction commits
+            early_completion = e
           end
+          # Re-raise EarlyCompletion after transaction commits successfully
+          raise early_completion if early_completion
         end
       end
     end