axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.3

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      module Method
+        include Base
+        extend self
+
+        def default_inherit_mode = :lifecycle
+
+        module DSL
+          def mount_axn_method(name, axn_klass = nil, inherit: MountingStrategies::Method.default_inherit_mode, **, &)
+            # mount_axn_method defaults to :lifecycle - participates in parent's execution lifecycle
+            Helpers::Mounter.mount_via_strategy(
+              target: self,
+              as: :method,
+              name:,
+              axn_klass:,
+              inherit:,
+              **,
+              &
+            )
+          end
+        end
+
+        def strategy_specific_kwargs = super + [:expose_return_as]
+
+        def preprocess_kwargs(**kwargs)
+          # Call parent preprocessing first
+          processed_kwargs = super
+
+          # Methods require a return value
+          processed_kwargs[:expose_return_as] = processed_kwargs[:expose_return_as].presence || :value
+
+          # Methods aren't capable of returning multiple values
+          if processed_kwargs[:exposes].present?
+            raise MountingError,
+                  "Methods aren't capable of exposing multiple values (will automatically expose return value instead)"
+          end
+
+          # Check for existing axn class with multiple exposed fields
+          if processed_kwargs[:axn_klass].present?
+            axn_klass = processed_kwargs[:axn_klass]
+            exposed_fields = axn_klass.external_field_configs.map(&:field)
+
+            if exposed_fields.size > 1
+              raise MountingError,
+                    "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
+
+          processed_kwargs
+        end
+
+        def mount_to_target(descriptor:, target:)
+          name = descriptor.name
+
+          mount_method(target:, method_name: "#{name}!") do |**kwargs|
+            # Lazy load the action class for the current target
+            axn_klass = descriptor.mounted_axn_for(target: self)
+
+            # Determine expose_return_as by introspecting the axn class
+            exposed_fields = axn_klass.external_field_configs.map(&:field)
+            expose_return_as = exposed_fields.size == 1 ? exposed_fields.first : nil
+
+            result = axn_klass.call!(**kwargs)
+            return result if expose_return_as.nil?
+
+            result.public_send(expose_return_as)
+          end
+        end
+
+        private
+
+        def _determine_exposure_to_return(axn_klass)
+          # Introspect the axn class to determine expose_return_as
+          exposed_fields = axn_klass.external_field_configs.map(&:field)
+
+          case exposed_fields.size
+          when 0
+            nil # No exposed fields, return nil to avoid public_send
+          when 1
+            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(", ")}. " \
+                  "Use a fresh block with mount_axn_method or ensure the axn class has exactly one exposed field."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      module Step
+        include Base
+        extend self # rubocop:disable Style/ModuleFunction -- module_function breaks inheritance
+
+        def default_inherit_mode = :none
+
+        module DSL
+          def steps(*steps)
+            Array(steps).compact.each do |step_class|
+              next unless step_class.is_a?(Class)
+              raise ArgumentError, "Step #{step_class} must include Axn module" if !step_class.included_modules.include?(::Axn) && !step_class < ::Axn
+
+              num_steps = _mounted_axn_descriptors.count { |descriptor| descriptor.mount_strategy.key == :step }
+              step("Step #{num_steps + 1}", step_class)
+            end
+          end
+
+          def step(name, axn_klass = nil, error_prefix: nil, inherit: MountingStrategies::Step.default_inherit_mode, **, &)
+            # Steps default to :none - they are isolated units of work
+            Helpers::Mounter.mount_via_strategy(
+              target: self,
+              as: :step,
+              name:,
+              axn_klass:,
+              error_prefix:,
+              inherit:,
+              **,
+              &
+            )
+          end
+        end
+
+        def strategy_specific_kwargs = super + [:error_prefix]
+
+        def mount_to_target(descriptor:, target:)
+          error_prefix = descriptor.options[:error_prefix] || "#{descriptor.name}: "
+          axn_klass = descriptor.mounted_axn_for(target:)
+
+          target.error from: axn_klass do |e|
+            "#{error_prefix}#{e.message}"
+          end
+
+          # Only define #call method once
+          return if target.instance_variable_defined?(:@_axn_call_method_defined_for_steps)
+
+          target.define_method(:call) do
+            step_descriptors = self.class._mounted_axn_descriptors.select { |d| d.mount_strategy.key == :step }
+
+            step_descriptors.each do |step_descriptor|
+              axn = step_descriptor.mounted_axn_for(target:)
+              step_result = axn.call!(**@__context.__combined_data)
+
+              # Extract exposed fields from step result and update exposed_data
+              step_result.declared_fields.each do |field|
+                @__context.exposed_data[field] = step_result.public_send(field)
+              end
+            end
+          end
+          target.instance_variable_set(:@_axn_call_method_defined_for_steps, true)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/mounting_strategies.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+
+module Axn
+  module Mountable
+    class MountingTypeNotFound < Axn::Internal::Registry::NotFound; end
+    class DuplicateMountingTypeError < Axn::Internal::Registry::DuplicateError; end
+
+    class MountingStrategies < Axn::Internal::Registry
+      class << self
+        def registry_directory = __dir__
+
+        private
+
+        def item_type = "Mounting Type"
+        def not_found_error_class = MountingTypeNotFound
+        def duplicate_error_class = DuplicateMountingTypeError
+
+        def select_constants_to_load(constants)
+          # Select modules that are not the Base module
+          constants.select do |const|
+            const.is_a?(Module) && const != Base
+          end
+        end
+      end
+    end
+
+    # Trigger registry loading to ensure mounting strategies are available
+    MountingStrategies.all
+  end
+end

data/lib/axn/mountable.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "axn/mountable/inherit_profiles"
+require "axn/mountable/mounting_strategies"
+require "axn/mountable/descriptor"
+require "axn/mountable/helpers/validator"
+require "axn/mountable/helpers/class_builder"
+require "axn/mountable/helpers/namespace_manager"
+require "axn/mountable/helpers/mounter"
+
+module Axn
+  # Mountable provides functionality for mounting actions to classes
+  #
+  # ## Inheritance Behavior
+  #
+  # Mounted actions inherit features from their target class in different ways depending on the
+  # mounting strategy. Each strategy has sensible defaults, but you can customize inheritance
+  # behavior using the `inherit` parameter.
+  #
+  # ### Default Inheritance Modes
+  #
+  # - `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
+  #
+  # - `:lifecycle` - Inherits everything except fields (hooks, callbacks, messages, async config)
+  # - `:async_only` - Only inherits async configuration
+  # - `:none` - Completely standalone with no inheritance
+  #
+  # You can also use a hash for granular control:
+  #   `inherit: { fields: false, hooks: true, callbacks: false, messages: true, async: true }`
+  #
+  # Available hash keys: `:fields`, `:hooks`, `:callbacks`, `:messages`, `:async`
+  #
+  # @example Default inheritance behavior
+  #   class MyClass
+  #     include Axn
+  #
+  #     before :log_start
+  #     on_success :track_success
+  #     async :sidekiq
+  #   end
+  #
+  #   # mount_axn uses :lifecycle (inherits hooks, callbacks, messages, async)
+  #   MyClass.mount_axn :my_action do
+  #     # Will run log_start before and track_success after
+  #   end
+  #
+  #   # step uses :none (completely independent)
+  #   MyClass.step :my_step do
+  #     # 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
+  #     # Will now run hooks and callbacks
+  #   end
+  #
+  #   # Use granular control
+  #   MyClass.mount_axn :my_action, inherit: { hooks: true, callbacks: false } do
+  #     # Will run hooks but not callbacks
+  #   end
+  module Mountable
+    extend ActiveSupport::Concern
+
+    def self.included(base)
+      base.class_eval do
+        class_attribute :_mounted_axn_descriptors, default: []
+      end
+
+      MountingStrategies.all.each do |(_name, klass)|
+        base.extend klass::DSL if klass.const_defined?(:DSL)
+      end
+    end
+  end
+end

data/lib/axn/rails/engine.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Only define the Engine if Rails is available
+if defined?(Rails) && Rails.const_defined?(:Engine)
+  module Axn
+    module RailsIntegration
+      class Engine < Rails::Engine
+        # Set a custom engine name that's more concise than the module path
+        engine_name "axn_rails"
+
+        # This engine is automatically loaded when AXN is used in a Rails context
+        # It ensures proper initialization and integration with Rails
+
+        # The engine is intentionally minimal - AXN is designed to work
+        # as a standalone library that can be used in any Ruby context
+
+        # However, when used alongside Rails, we ensure that the app/actions
+        # directory is automatically added to the autoloader so that Rails can
+        # automatically load the actions.
+        initializer "axn.add_app_actions_to_autoload", after: :load_config_initializers do |app|
+          actions_path = app.root.join("app/actions")
+
+          # Only add if the directory exists
+          next unless File.directory?(actions_path)
+
+          # Use modern Rails autoloader API (Rails 7.2+)
+          # Namespace is configurable via Axn.config.rails.app_actions_autoload_namespace
+          autoload_namespace = Axn.config.rails.app_actions_autoload_namespace
+
+          if autoload_namespace
+            # Create the namespace module if it doesn't exist
+            namespace = Object.const_get(autoload_namespace) if Object.const_defined?(autoload_namespace)
+            unless namespace
+              namespace = Module.new
+              Object.const_set(autoload_namespace, namespace)
+            end
+            Rails.autoloaders.main.push_dir(actions_path, namespace:)
+          else
+            # No namespace - load directly
+            Rails.autoloaders.main.push_dir(actions_path)
+          end
+        end
+
+        # Register the generator
+        generators do
+          require_relative "generators/axn_generator"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Axn
+  module RailsIntegration
+    module Generators
+      class AxnGenerator < Rails::Generators::NamedBase
+        namespace "axn"
+        source_root File.expand_path("templates", __dir__)
+
+        argument :expectations, type: :array, default: [], banner: "expectation1 expectation2 ..."
+
+        def create_action_file
+          template "action.rb.erb", "app/actions/#{file_path}.rb"
+        end
+
+        def create_spec_file
+          return unless spec_generation_enabled?
+
+          template "action_spec.rb.erb", "spec/actions/#{file_path}_spec.rb"
+        end
+
+        private
+
+        def class_name
+          @class_name ||= name.camelize
+        end
+
+        def file_path
+          @file_path ||= name.underscore
+        end
+
+        def expectations_with_types
+          expectations.map { |exp| { name: exp, type: "String" } }
+        end
+
+        def spec_generation_enabled?
+          return false unless rspec_available?
+          return false if spec_generation_skipped?
+
+          true
+        end
+
+        def rspec_available?
+          defined?(RSpec)
+        end
+
+        def spec_generation_skipped?
+          return false unless defined?(Rails) && Rails.application&.config&.generators
+
+          generators_config = Rails.application.config.generators
+
+          # Check individual boolean flags (modern style)
+          return true if generators_config.respond_to?(:test_framework) &&
+                         generators_config.test_framework == false
+
+          # Check for specific spec-related flags
+          spec_flags = %w[specs axn_specs]
+          spec_flags.each do |flag|
+            return true if generators_config.respond_to?(flag) &&
+                           generators_config.public_send(flag) == false
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class <%= class_name %>
+  include Axn
+<% if expectations.any? -%>
+
+<% expectations.each do |expectation| -%>
+  expects :<%= expectation %>
+<% end -%>
+
+<% else -%>
+
+<% end -%>
+  def call
+    # TODO: Implement action logic
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe <%= class_name %> do
+<% if expectations.any? -%>
+<% expectations.each do |expectation| -%>
+  let(:<%= expectation %>) { "<%= expectation %>" }
+<% end -%>
+
+<% end -%>
+  describe ".call" do
+    subject(:result) { described_class.call(<%= expectations.any? ? expectations.map { |exp| "#{exp}:" }.join(", ") : "" %>) }
+
+    it "executes successfully" do
+      expect(result).to be_ok
+    end
+<% if expectations.any? -%>
+
+    it "TODO: replace with a meaningful failure case" do
+      result = described_class.call
+      expect(result).not_to be_ok
+      expect(result.error).to eq("Something went wrong")
+    end
+<% end -%>
+  end
+end

data/lib/{action → axn}/result.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require "action/core/context/facade"
-require "action/core/context/facade_inspector"
+require "axn/core/context/facade"
+require "axn/core/context/facade_inspector"
 
-module Action
+module Axn
   # Outbound / External ContextFacade
   class Result < ContextFacade
     # For ease of mocking return results in tests
     class << self
       def ok(msg = nil, **exposures)
-        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
         Axn::Factory.build(exposes:, success: msg) do
           exposures.each do |key, value|
@@ -19,7 +19,7 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
         Axn::Factory.build(exposes:, error: msg) do
           exposures.each do |key, value|
@@ -40,7 +40,7 @@ module Action
     end
 
     # External interface
-    delegate :ok?, :exception, :elapsed_time, to: :context
+    delegate :ok?, :exception, :elapsed_time, :finalized?, to: :context
 
     def error
       return if ok?
@@ -64,7 +64,7 @@ module Action
     ].freeze
 
     def outcome
-      label = if exception.is_a?(Action::Failure)
+      label = if exception.is_a?(Axn::Failure)
                 OUTCOME_FAILURE
               elsif exception
                 OUTCOME_EXCEPTION
@@ -79,15 +79,34 @@ module Action
     # TODO: exposed for errors :from support, but should be private if possible
     def __action__ = @action
 
+    # Enable pattern matching support for Ruby 3+
+    def deconstruct_keys(keys)
+      attrs = {
+        ok: ok?,
+        success:,
+        error:,
+        message:,
+        outcome: outcome.to_sym,
+        finalized: finalized?,
+      }
+
+      # Add all exposed data
+      attrs.merge!(@context.exposed_data)
+
+      # Return filtered attributes if keys specified
+      keys ? attrs.slice(*keys) : attrs
+    end
+
     private
 
     def _context_data_source = @context.exposed_data
 
-    # TODO: hook for adding early-return success at some point
-    def _user_provided_success_message = nil
+    def _user_provided_success_message
+      @context.__early_completion_message.presence
+    end
 
     def _user_provided_error_message
-      return unless exception.is_a?(Action::Failure)
+      return unless exception.is_a?(Axn::Failure)
       return if exception.default_message?
       return if exception.cause # We raised this ourselves from nesting
 
@@ -103,7 +122,7 @@ module Action
             exposes :#{method_name}
         MSG
 
-        raise Action::ContractViolation::MethodNotAllowed, msg
+        raise Axn::ContractViolation::MethodNotAllowed, msg
       end
 
       super

data/lib/{action → axn}/strategies/transaction.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   class Strategies
     module Transaction
       extend ActiveSupport::Concern

data/lib/axn/strategies.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+
+module Axn
+  class StrategyNotFound < Axn::Internal::Registry::NotFound; end
+  class DuplicateStrategyError < Axn::Internal::Registry::DuplicateError; end
+
+  class Strategies < Axn::Internal::Registry
+    class << self
+      def registry_directory = __dir__
+
+      private
+
+      def item_type = "Strategy"
+      def not_found_error_class = StrategyNotFound
+      def duplicate_error_class = DuplicateStrategyError
+    end
+  end
+end

data/lib/axn/testing/spec_helpers.rb

@@ -3,19 +3,17 @@
 module Axn
   module Testing
     module SpecHelpers
-      def build_action(&block)
-        action = Class.new.send(:include, Action)
+      def build_axn(&block)
+        action = Class.new.send(:include, Axn)
         action.class_eval(&block) if block
         action
       end
-
-      def build_axn(**, &)
-        Axn::Factory.build(**, &)
-      end
     end
   end
 end
 
-RSpec.configure do |config|
-  config.include Axn::Testing::SpecHelpers
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Axn::Testing::SpecHelpers
+  end
 end

data/lib/axn/util/memoization.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    module Memoization
+      UNSET = Object.new.freeze
+
+      def self.define_memoized_reader_method(target, field, &block)
+        target.define_method(field) do
+          ivar = :"@_memoized_reader_#{field}"
+          cached_val = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : UNSET
+          return cached_val unless cached_val == UNSET
+
+          value = instance_exec(&block)
+          instance_variable_set(ivar, value)
+        end
+      end
+    end
+  end
+end

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.8.1"
+  VERSION = "0.1.0-alpha.3"
 end

data/lib/axn.rb

@@ -1,37 +1,38 @@
 # frozen_string_literal: true
 
 require "active_support"
+require "active_support/concern"
 
-module Axn; end
+# Standalone
 require "axn/version"
-require "axn/util"
 require "axn/factory"
+require "axn/configuration"
+require "axn/exceptions"
 
-require "action/configuration"
-require "action/exceptions"
+# The core implementation
+require "axn/core"
 
-require "action/core"
+# Utilities
+require "axn/util/memoization"
 
-require "action/attachable"
-require "action/enqueueable"
+# Extensions
+require "axn/mountable"
+require "axn/async"
 
-def Axn(callable, **) # rubocop:disable Naming/MethodName
-  return callable if callable.is_a?(Class) && callable < Action
+# Rails integration (if in Rails context)
+require "axn/rails/engine" if defined?(Rails) && Rails.const_defined?(:Engine)
 
-  Axn::Factory.build(**, &callable)
-end
-
-module Action
+module Axn
   def self.included(base)
     base.class_eval do
       include Core
 
       # --- Extensions ---
-      include Attachable
-      include Enqueueable
+      include Mountable
+      include Async
 
       # Allow additional automatic includes to be configured
-      Array(Action.config.additional_includes).each { |mod| include mod }
+      Array(Axn.config.additional_includes).each { |mod| include mod }
     end
   end
 end