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

data/lib/axn/util/callable.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    module Callable
+      extend self
+
+      # Calls a callable with only the positional and keyword arguments it expects.
+      # If the callable accepts **kwargs (keyrest), passes all provided kwargs.
+      # If the callable accepts *args (rest), passes all provided positional args.
+      #
+      # @param callable [Proc, Method, #call] A callable object
+      # @param args [Array] An array of positional arguments to potentially pass
+      # @param kwargs [Hash] A hash of keyword arguments to potentially pass
+      # @return The return value of calling the callable
+      #
+      # @example
+      #   proc = ->(resource:, result:) { }
+      #   Callable.call_with_desired_shape(proc, kwargs: { resource: "Action", result: result, extra: "ignored" })
+      #   # Calls proc with only resource: and result:
+      #
+      # @example
+      #   proc = ->(a, b, c:) { }
+      #   Callable.call_with_desired_shape(proc, args: [1, 2, 3, 4], kwargs: { c: 5, d: 6 })
+      #   # Calls proc with args [1, 2, 3] and kwargs { c: 5 }
+      #
+      # @example
+      #   proc = ->(**kwargs) { }
+      #   Callable.call_with_desired_shape(proc, kwargs: { resource: "Action", result: result })
+      #   # Calls proc with all kwargs
+      # Calls a callable with only the positional and keyword arguments it expects.
+      def call_with_desired_shape(callable, args: [], kwargs: {})
+        filtered_args, filtered_kwargs = only_requested_params(callable, args:, kwargs:)
+        callable.call(*filtered_args, **filtered_kwargs)
+      end
+
+      # Returns filtered args and kwargs for a callable without calling it.
+      # Useful when you need to execute the callable in a specific context (e.g., via instance_exec).
+      #
+      # @param callable [Proc, Method, #parameters] A callable object
+      # @param args [Array] An array of positional arguments to potentially pass
+      # @param kwargs [Hash] A hash of keyword arguments to potentially pass
+      # @return [Array<Array, Hash>] A tuple of [filtered_args, filtered_kwargs]
+      #
+      # @example
+      #   proc = ->(resource:, result:) { }
+      #   args, kwargs = Callable.only_requested_params(proc, kwargs: { resource: "Action", result: result, extra: "ignored" })
+      #   # => [[], { resource: "Action", result: result }]
+      #   action.instance_exec(*args, **kwargs, &proc)
+      def only_requested_params(callable, args: [], kwargs: {})
+        return [args, kwargs] unless callable.respond_to?(:parameters)
+
+        params = callable.parameters
+
+        # Determine which positional arguments to pass
+        filtered_args = filter_positional_args(params, args)
+
+        # Determine which keyword arguments to pass
+        filtered_kwargs = filter_kwargs(params, kwargs)
+
+        [filtered_args, filtered_kwargs]
+      end
+
+      # Returns filtered args and kwargs for a callable when passing an exception.
+      # The exception will be passed as either a positional argument or keyword argument,
+      # depending on what the callable expects.
+      #
+      # @param callable [Proc, Method, #parameters] A callable object
+      # @param exception [Exception, nil] The exception to potentially pass
+      # @return [Array<Array, Hash>] A tuple of [filtered_args, filtered_kwargs]
+      #
+      # @example
+      #   proc = ->(exception:) { }
+      #   args, kwargs = Callable.only_requested_params_for_exception(proc, exception)
+      #   # => [[], { exception: exception }]
+      #   action.instance_exec(*args, **kwargs, &proc)
+      #
+      # @example
+      #   proc = ->(exception) { }
+      #   args, kwargs = Callable.only_requested_params_for_exception(proc, exception)
+      #   # => [[exception], {}]
+      #   action.instance_exec(*args, **kwargs, &proc)
+      def only_requested_params_for_exception(callable, exception)
+        return [[], {}] unless exception
+
+        args = [exception]
+        kwargs = { exception: }
+        only_requested_params(callable, args:, kwargs:)
+      end
+
+      private
+
+      def filter_positional_args(params, args)
+        return args if args.empty?
+
+        required_count = params.count { |type, _name| type == :req }
+        optional_count = params.count { |type, _name| type == :opt }
+        has_rest = params.any? { |type, _name| type == :rest }
+
+        # If it accepts *args (rest), pass all provided args
+        return args if has_rest
+
+        # Otherwise, pass up to (required + optional) args
+        max_args = required_count + optional_count
+        args.first(max_args)
+      end
+
+      def filter_kwargs(params, kwargs)
+        return kwargs if kwargs.empty?
+
+        accepts_keyrest = params.any? { |type, _name| type == :keyrest }
+        return kwargs if accepts_keyrest
+
+        # Only pass explicitly expected keyword arguments
+        expected_keywords = params.select { |type, _name| %i[key keyreq].include?(type) }.map { |_type, name| name }
+        kwargs.select { |key, _value| expected_keywords.include?(key) }
+      end
+    end
+  end
+end

data/lib/axn/util/contract_error_handling.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    module ContractErrorHandling
+      module_function
+
+      # Executes a block, allowing fail! and done! to propagate normally,
+      # but wrapping other StandardErrors in the specified exception class.
+      #
+      # @param exception_class [Class] The exception class to wrap errors in
+      # @param message [String, Proc] Error message or proc that takes (field_identifier, error)
+      # @param field_identifier [String] Identifier for the field (for error messages)
+      # @yield The block to execute
+      # @raise [Axn::Failure] Re-raised if raised in block
+      # @raise [Axn::Internal::EarlyCompletion] Re-raised if raised in block
+      # @raise [exception_class] Wrapped exception for other StandardErrors
+      def with_contract_error_handling(exception_class:, message:, field_identifier:)
+        yield
+      rescue Axn::Failure, Axn::Internal::EarlyCompletion => e
+        raise e # Re-raise control flow exceptions without wrapping
+      rescue StandardError => e
+        error_message = if message.is_a?(Proc)
+                          message.call(field_identifier, e)
+                        else
+                          format(message, field_identifier, e.message)
+                        end
+        raise exception_class, error_message, cause: e
+      end
+    end
+  end
+end

data/lib/axn/util/execution_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    module ExecutionContext
+      module_function
+
+      # Determines if code is currently running within a background job context.
+      # Checks all registered async adapters to see if any report running in background.
+      #
+      # @return [Boolean] true if running in a background job, false otherwise
+      #
+      # @example
+      #   if Axn::Util::ExecutionContext.background?
+      #     # Code is running in Sidekiq or ActiveJob
+      #   end
+      def background?
+        Axn::Async::Adapters.all.values.any? do |adapter|
+          adapter.respond_to?(:_running_in_background?) && adapter._running_in_background?
+        end
+      rescue StandardError
+        false
+      end
+
+      # Determines if code is currently running in an interactive console (IRB, Pry, Rails console).
+      # Used to skip visual separators in console output since the prompt already provides separation.
+      #
+      # @return [Boolean] true if running in a console, false otherwise
+      def console?
+        defined?(Rails::Console) || defined?(IRB) || defined?(Pry)
+      end
+    end
+  end
+end

data/lib/axn/util/global_id_serialization.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    # Utilities for serializing/deserializing objects with GlobalID support.
+    # Used by async adapters to convert ActiveRecord objects to GlobalID strings
+    # for job serialization, and back to objects when the job runs.
+    module GlobalIdSerialization
+      GLOBAL_ID_SUFFIX = "_as_global_id"
+
+      class << self
+        # Serialize a hash for background job processing:
+        # - Convert GlobalID-able objects (e.g., ActiveRecord models) to GlobalID strings
+        # - Stringify keys for JSON compatibility
+        #
+        # @param params [Hash] The parameters to serialize
+        # @return [Hash] Serialized hash with string keys and GlobalID strings
+        def serialize(params)
+          return {} if params.nil? || params.empty?
+
+          params.each_with_object({}) do |(key, value), hash|
+            string_key = key.to_s
+            if value.respond_to?(:to_global_id)
+              hash["#{string_key}#{GLOBAL_ID_SUFFIX}"] = value.to_global_id.to_s
+            else
+              hash[string_key] = value
+            end
+          end
+        end
+
+        # Deserialize a hash from background job processing:
+        # - Convert GlobalID strings back to objects
+        # - Symbolize keys for use with kwargs
+        #
+        # @param params [Hash] The serialized parameters
+        # @return [Hash] Deserialized hash with symbol keys and resolved objects
+        def deserialize(params)
+          return {} if params.nil? || params.empty?
+
+          params.each_with_object({}) do |(key, value), hash|
+            if key.end_with?(GLOBAL_ID_SUFFIX)
+              original_key = key.delete_suffix(GLOBAL_ID_SUFFIX).to_sym
+              hash[original_key] = GlobalID::Locator.locate(value)
+            else
+              hash[key.to_sym] = value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axn/util/logging.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Axn
+  module Util
+    module Logging
+      extend self
+
+      MAX_CONTEXT_LENGTH = 150
+      TRUNCATION_SUFFIX = "…<truncated>…"
+
+      # Logs a message at the specified level with error handling
+      # @param action_class [Class] The action class to log from
+      # @param level [Symbol] The log level (e.g., :info, :warn)
+      # @param message_parts [Array<String>] Parts of the message to join
+      # @param error_context [String] Context for error reporting if logging fails
+      # @param join_string [String] String to join message parts with
+      # @param before [String, nil] Text to prepend to the message
+      # @param after [String, nil] Text to append to the message
+      # @param prefix [String, nil] Override the default log prefix (useful for class-level logging)
+      # @param context_direction [Symbol, nil] Direction for context logging (:inbound or :outbound)
+      # @param context_instance [Object, nil] Action instance for instance-level context_for_logging
+      # @param context_data [Hash, nil] Raw data for class-level context_for_logging
+      def log_at_level(
+        action_class,
+        level:,
+        message_parts:,
+        error_context:,
+        join_string: " ",
+        before: nil,
+        after: nil,
+        prefix: nil,
+        context_direction: nil,
+        context_instance: nil,
+        context_data: nil
+      )
+        return unless level
+
+        # Prepare and format context if needed
+        context_str = if context_instance && context_direction
+                        # Instance-level context_for_logging
+                        data = context_instance.context_for_logging(context_direction)
+                        format_context(data)
+                      elsif context_data && context_direction
+                        # Class-level context_for_logging
+                        data = action_class.context_for_logging(data: context_data, direction: context_direction)
+                        format_context(data)
+                      end
+
+        # Add context to message parts if present
+        full_message_parts = context_str ? message_parts + [context_str] : message_parts
+        message = full_message_parts.compact.join(join_string)
+
+        action_class.public_send(level, message, before:, after:, prefix:)
+      rescue StandardError => e
+        Axn::Internal::Logging.piping_error(error_context, action: action_class, exception: e)
+      end
+
+      private
+
+      # Formats context data for logging, with truncation if needed
+      def format_context(data)
+        return unless data.present?
+
+        formatted = format_object(data)
+        return formatted if formatted.length <= MAX_CONTEXT_LENGTH
+
+        formatted[0, MAX_CONTEXT_LENGTH - TRUNCATION_SUFFIX.length] + TRUNCATION_SUFFIX
+      end
+
+      # Formats an object for logging, handling special cases for ActiveRecord and ActionController::Parameters
+      def format_object(data)
+        case data
+        when Hash
+          # NOTE: slightly more manual in order to avoid quotes around ActiveRecord objects' <Class#id> formatting
+          "{#{data.map { |k, v| "#{k}: #{format_object(v)}" }.join(', ')}}"
+        when Array
+          data.map { |v| format_object(v) }
+        else
+          return data.to_unsafe_h if defined?(ActionController::Parameters) && data.is_a?(ActionController::Parameters)
+          return "<#{data.class.name}##{data.to_param.presence || 'unpersisted'}>" if defined?(ActiveRecord::Base) && data.is_a?(ActiveRecord::Base)
+
+          data.inspect
+        end
+      end
+    end
+  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.4"
 end

data/lib/axn.rb

@@ -1,37 +1,47 @@
 # 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 "axn/util/callable"
+require "axn/util/logging"
+require "axn/util/execution_context"
+require "axn/util/contract_error_handling"
+require "axn/util/global_id_serialization"
+require "axn/form_object"
 
-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
+
+# Load after Axn is defined since it includes Axn
+require "axn/async/enqueue_all_orchestrator"

data/lib/rubocop/cop/axn/README.md

@@ -4,11 +4,11 @@ This directory contains custom RuboCop cops specifically designed for the Axn li
 
 ## Axn/UncheckedResult
 
-This cop enforces proper result handling when calling Actions. It can be configured to check nested calls, non-nested calls, or both.
+This cop enforces proper result handling when calling Axns. It can be configured to check nested calls, non-nested calls, or both.
 
 ### Why This Rule Exists
 
-When Actions are nested, proper error handling becomes crucial. Without proper result checking, failures in nested Actions can be silently ignored, leading to:
+When Axns are nested, proper error handling becomes crucial. Without proper result checking, failures in nested Axns can be silently ignored, leading to:
 
 - Silent failures that are hard to debug
 - Inconsistent error handling patterns
@@ -21,8 +21,8 @@ The cop supports flexible configuration to match your team's needs:
 ```yaml
 Axn/UncheckedResult:
   Enabled: true
-  CheckNested: true      # Check nested Action calls (default: true)
-  CheckNonNested: true   # Check non-nested Action calls (default: true)
+  CheckNested: true      # Check nested Axn calls (default: true)
+  CheckNonNested: true   # Check non-nested Axn calls (default: true)
   Severity: warning      # or error, if you want to enforce it strictly
 ```
 
@@ -33,21 +33,21 @@ Axn/UncheckedResult:
    CheckNested: true
    CheckNonNested: true
    ```
-   Checks all Action calls regardless of nesting.
+   Checks all Axn calls regardless of nesting.
 
 2. **Nested Only**:
    ```yaml
    CheckNested: true
    CheckNonNested: false
    ```
-   Only checks Action calls from within other Actions.
+   Only checks Axn calls from within other Axns.
 
 3. **Non-Nested Only**:
    ```yaml
    CheckNested: false
    CheckNonNested: true
    ```
-   Only checks top-level Action calls.
+   Only checks top-level Axn calls.
 
 4. **Disabled**:
    ```yaml
@@ -62,7 +62,7 @@ Axn/UncheckedResult:
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     InnerAction.call(param: "value")  # Missing result check
     # This will always continue even if InnerAction fails
@@ -74,7 +74,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     InnerAction.call!(param: "value")  # Using call! ensures exceptions bubble up
   end
@@ -85,7 +85,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     return result unless result.ok?
@@ -98,7 +98,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     if result.failed?
@@ -113,7 +113,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     if result.error
@@ -128,7 +128,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     result  # Result is returned, so it's properly handled
@@ -140,7 +140,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   exposes :nested_result
   def call
     result = InnerAction.call(param: "value")
@@ -153,7 +153,7 @@ end
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     process_result(result)  # Result is used, so it's properly handled
@@ -165,19 +165,19 @@ end
 
 The cop analyzes your code to determine if you're:
 
-1. **Inside an Action class** - Classes that `include Action`
+1. **Inside an Axn class** - Classes that `include Axn`
 2. **Inside the `call` method** - Only the main execution method
-3. **Calling another Action** - Using `.call` on Action classes
+3. **Calling another Axn** - Using `.call` on Axn classes
 4. **Properly handling the result** - One of the acceptable patterns above
 
 ### What the Cop Ignores
 
 The cop will NOT report offenses for:
 
-- Action calls outside of Action classes
-- Action calls in methods other than `call`
-- Action calls that use `call!` (bang method)
-- Action calls where the result is properly handled
+- Axn calls outside of Axn classes
+- Axn calls in methods other than `call`
+- Axn calls that use `call!` (bang method)
+- Axn calls where the result is properly handled
 
 ### Configuration
 
@@ -189,8 +189,8 @@ require:
 
 Axn/UncheckedResult:
   Enabled: true
-  CheckNested: true      # Check nested Action calls
-  CheckNonNested: true   # Check non-nested Action calls
+  CheckNested: true      # Check nested Axn calls
+  CheckNonNested: true   # Check non-nested Axn calls
   Severity: warning      # or error, if you want to enforce it strictly
 ```