axn 0.1.0.pre.alpha.3 → 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/version.rb

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

data/lib/axn.rb

@@ -14,6 +14,12 @@ require "axn/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"
 
 # Extensions
 require "axn/mountable"
@@ -36,3 +42,6 @@ module Axn
     end
   end
 end
+
+# Load after Axn is defined since it includes Axn
+require "axn/async/enqueue_all_orchestrator"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.3
+  version: 0.1.0.pre.alpha.4
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-15 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -46,6 +46,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".cursor/commands/pr.md"
 - ".cursor/rules/axn-framework-patterns.mdc"
 - ".cursor/rules/general-coding-standards.mdc"
 - ".cursor/rules/spec/testing-patterns.mdc"
@@ -62,6 +63,7 @@ files:
 - docs/index.md
 - docs/intro/about.md
 - docs/intro/overview.md
+- docs/recipes/formatting-context-for-error-tracking.md
 - docs/recipes/memoization.md
 - docs/recipes/rubocop-integration.md
 - docs/recipes/testing.md
@@ -70,7 +72,10 @@ files:
 - docs/reference/axn-result.md
 - docs/reference/class.md
 - docs/reference/configuration.md
+- docs/reference/form-object.md
 - docs/reference/instance.md
+- docs/strategies/client.md
+- docs/strategies/form.md
 - docs/strategies/index.md
 - docs/strategies/transaction.md
 - docs/usage/setup.md
@@ -83,6 +88,9 @@ files:
 - lib/axn/async/adapters/active_job.rb
 - lib/axn/async/adapters/disabled.rb
 - lib/axn/async/adapters/sidekiq.rb
+- lib/axn/async/batch_enqueue.rb
+- lib/axn/async/batch_enqueue/config.rb
+- lib/axn/async/enqueue_all_orchestrator.rb
 - lib/axn/configuration.rb
 - lib/axn/context.rb
 - lib/axn/core.rb
@@ -94,6 +102,7 @@ files:
 - lib/axn/core/contract_for_subfields.rb
 - lib/axn/core/contract_validation.rb
 - lib/axn/core/contract_validation_for_subfields.rb
+- lib/axn/core/default_call.rb
 - lib/axn/core/field_resolvers.rb
 - lib/axn/core/field_resolvers/extract.rb
 - lib/axn/core/field_resolvers/model.rb
@@ -113,8 +122,8 @@ files:
 - lib/axn/core/flow/messages.rb
 - lib/axn/core/hooks.rb
 - lib/axn/core/logging.rb
+- lib/axn/core/memoization.rb
 - lib/axn/core/nesting_tracking.rb
-- lib/axn/core/profiling.rb
 - lib/axn/core/timing.rb
 - lib/axn/core/tracing.rb
 - lib/axn/core/use_strategy.rb
@@ -124,7 +133,11 @@ files:
 - lib/axn/core/validation/validators/type_validator.rb
 - lib/axn/core/validation/validators/validate_validator.rb
 - lib/axn/exceptions.rb
+- lib/axn/extras.rb
+- lib/axn/extras/strategies/client.rb
+- lib/axn/extras/strategies/vernier.rb
 - lib/axn/factory.rb
+- lib/axn/form_object.rb
 - lib/axn/internal/logging.rb
 - lib/axn/internal/registry.rb
 - lib/axn/mountable.rb
@@ -137,7 +150,6 @@ files:
 - lib/axn/mountable/mounting_strategies.rb
 - lib/axn/mountable/mounting_strategies/_base.rb
 - lib/axn/mountable/mounting_strategies/axn.rb
-- lib/axn/mountable/mounting_strategies/enqueue_all.rb
 - lib/axn/mountable/mounting_strategies/method.rb
 - lib/axn/mountable/mounting_strategies/step.rb
 - lib/axn/rails/engine.rb
@@ -147,8 +159,14 @@ files:
 - lib/axn/result.rb
 - lib/axn/rubocop.rb
 - lib/axn/strategies.rb
+- lib/axn/strategies/form.rb
 - lib/axn/strategies/transaction.rb
 - lib/axn/testing/spec_helpers.rb
+- lib/axn/util/callable.rb
+- lib/axn/util/contract_error_handling.rb
+- lib/axn/util/execution_context.rb
+- lib/axn/util/global_id_serialization.rb
+- lib/axn/util/logging.rb
 - lib/axn/util/memoization.rb
 - lib/axn/version.rb
 - lib/rubocop/cop/axn/README.md

data/lib/axn/core/profiling.rb

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "axn/core/flow/handlers/invoker"
-
-module Axn
-  module Core
-    module Profiling
-      def self.included(base)
-        base.class_eval do
-          class_attribute :_profiling_enabled, default: false
-          class_attribute :_profiling_condition, default: nil
-          class_attribute :_profiling_sample_rate, default: 0.1
-          class_attribute :_profiling_output_dir, default: nil
-
-          extend ClassMethods
-        end
-      end
-
-      module ClassMethods
-        # Enable profiling for this action class
-        #
-        # @param if [Proc, Symbol, #call, nil] Optional condition to determine when to profile
-        # @param sample_rate [Float] Sampling rate (0.0 to 1.0, default: 0.1)
-        # @param output_dir [String, Pathname] Output directory for profile files (default: Rails.root/tmp/profiles or tmp/profiles)
-        # @return [void]
-        def profile(if: nil, sample_rate: 0.1, output_dir: nil)
-          self._profiling_enabled = true
-          self._profiling_condition = binding.local_variable_get(:if)
-          self._profiling_sample_rate = sample_rate
-          self._profiling_output_dir = output_dir || _default_profiling_output_dir
-        end
-
-        private
-
-        def _default_profiling_output_dir
-          if defined?(Rails) && Rails.respond_to?(:root)
-            Rails.root.join("tmp", "profiles")
-          else
-            Pathname.new("tmp/profiles")
-          end
-        end
-      end
-
-      private
-
-      def _with_profiling(&)
-        # Check if this specific action should be profiled
-        return yield unless _should_profile?
-
-        _profile_with_vernier(&)
-      end
-
-      def _profile_with_vernier(&)
-        _ensure_vernier_available!
-
-        class_name = self.class.name.presence || "AnonymousAction"
-        profile_name = "axn_#{class_name}_#{Time.now.to_i}"
-
-        # Ensure output directory exists (only once per instance)
-        _ensure_output_directory_exists
-
-        # Build output file path
-        output_dir = self.class._profiling_output_dir || _default_profiling_output_dir
-        output_file = File.join(output_dir, "#{profile_name}.json")
-
-        # Configure Vernier with our settings
-        collector_options = {
-          out: output_file,
-          allocation_sample_rate: (self.class._profiling_sample_rate * 1000).to_i,
-        }
-
-        Vernier.profile(**collector_options, &)
-      end
-
-      def _ensure_output_directory_exists
-        return if @_profiling_directory_created
-
-        output_dir = self.class._profiling_output_dir || _default_profiling_output_dir
-        FileUtils.mkdir_p(output_dir)
-        @_profiling_directory_created = true
-      end
-
-      def _should_profile?
-        # Fast path: check if action has profiling enabled
-        return false unless self.class._profiling_enabled
-
-        # Fast path: no condition means always profile
-        return true unless self.class._profiling_condition
-
-        # Slow path: evaluate condition (only when needed)
-        Axn::Core::Flow::Handlers::Invoker.call(
-          action: self,
-          handler: self.class._profiling_condition,
-          operation: "determining if profiling should run",
-        )
-      end
-
-      def _ensure_vernier_available!
-        return if defined?(Vernier) && Vernier.is_a?(Module)
-
-        begin
-          require "vernier"
-        rescue LoadError
-          raise LoadError, <<~ERROR
-            Vernier profiler is not available. To use profiling, add 'vernier' to your Gemfile:
-
-              gem 'vernier', '~> 0.1'
-
-            Then run: bundle install
-          ERROR
-        end
-      end
-
-      def _default_profiling_output_dir
-        if defined?(Rails) && Rails.respond_to?(:root)
-          Rails.root.join("tmp", "profiles")
-        else
-          Pathname.new("tmp/profiles")
-        end
-      end
-    end
-  end
-end

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

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Axn
-  module Mountable
-    class MountingStrategies
-      module EnqueueAll
-        include Base
-        extend self # rubocop:disable Style/ModuleFunction -- module_function breaks inheritance
-
-        def default_inherit_mode = :async_only
-
-        module DSL
-          def enqueue_all_via(axn_klass = nil, inherit: MountingStrategies::EnqueueAll.default_inherit_mode, **, &)
-            # enqueue_all_via defaults to :async_only - only needs async config for batch enqueuing
-            Helpers::Mounter.mount_via_strategy(
-              target: self,
-              as: :enqueue_all,
-              name: "enqueue_all",
-              axn_klass:,
-              inherit:,
-              **,
-              &
-            )
-          end
-        end
-
-        def mount_to_target(descriptor:, target:)
-          name = descriptor.name
-
-          mount_method(target:, method_name: name) do |**kwargs|
-            axn = descriptor.mounted_axn_for(target: self)
-            axn.call!(**kwargs)
-            true # Raise or return true
-          end
-
-          mount_method(target:, method_name: "#{name}_async") do |**kwargs|
-            axn = descriptor.mounted_axn_for(target: self)
-            axn.call_async(**kwargs)
-          end
-        end
-
-        def mount_to_namespace(descriptor:, target:)
-          super
-
-          # Add enqueue shortcut to enqueue the *attached-to* axn without
-          # the user having to reference __axn_mounted_to__ in their own code
-          mounted_axn = descriptor.mounted_axn_for(target:)
-          mounted_axn.define_method(:enqueue) do |**kwargs|
-            __axn_mounted_to__.call_async(**kwargs)
-          end
-        end
-      end
-    end
-  end
-end