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

data/docs/usage/writing.md

@@ -208,7 +208,10 @@ class ApiAction
 
   expects :data
 
-  # Combine prefix with from for consistent error formatting
+  # Simply inherit child's error (prefix and handler are optional)
+  error from: ValidationAction
+
+  # Or combine prefix with from for consistent error formatting
   error from: ValidationAction, prefix: "API Error: " do |e|
     "Request validation failed: #{e.message}"
   end
@@ -216,6 +219,12 @@ class ApiAction
   # Or use prefix only (falls back to exception message)
   error from: ValidationAction, prefix: "API Error: "
 
+  # Match multiple child actions
+  error from: [ValidationAction, AnotherAction]
+
+  # Match any child action
+  error from: true
+
   def call
     ValidationAction.call!(input: data)
   end
@@ -223,9 +232,11 @@ end
 ```
 
 This configuration provides:
+- Simple error message inheritance without requiring prefix or handler
 - Consistent error message formatting with prefixes
 - Automatic fallback to exception messages when no custom message is provided
 - Proper error message inheritance from nested actions
+- Support for matching multiple child actions or any child action
 
 ::: warning Message Ordering
 **Important**: When using conditional messages, always define your static fallback messages **first** in your class, before any conditional messages. This ensures proper fallback behavior.
@@ -258,6 +269,37 @@ In addition to `#call`, there are a few additional pieces to be aware of:
 
 Note execution is halted whenever `fail!` is called, `done!` is called, or an exception is raised (so a `before` block failure won't execute `call` or `after`, while an `after` block failure will make `result.ok?` be false even though `call` completed successfully). The `done!` method specifically skips `after` hooks and any remaining `call` method execution, but allows `around` hooks to complete normally.
 
+#### Around hooks
+
+Around hooks wrap the entire action execution, including before and after hooks. They receive a block that represents the next step in the chain:
+
+```ruby
+class Foo
+  include Axn
+
+  around :with_timing
+  around do |chain|
+    log("outer around start")
+    chain.call
+    log("outer around end")
+  end
+
+  def call
+    log("in call")
+  end
+
+  private
+
+  def with_timing(chain)
+    start = Time.current
+    chain.call
+    log("Took #{Time.current - start}s")
+  end
+end
+```
+
+#### Before/After example
+
 For instance, given this configuration:
 
 ```ruby
@@ -301,6 +343,62 @@ This follows the natural pattern of setup (general → specific) and teardown (s
 A number of custom callback are available for you as well, if you want to take specific actions when a given Axn succeeds or fails. See the [Class Interface docs](/reference/class#callbacks) for details.
 
 ## Strategies
+
 A number of [Strategies](/strategies/index), which are <abbr title="Don't Repeat Yourself">DRY</abbr>ed bits of commonly-used configuration, are available for your use as well.
 
+::: info Optional Peer Libraries
+Axn provides enhanced functionality when certain peer libraries are available:
+
+- **Rails**: Automatic engine loading, autoloading for `app/actions`, and generators
+- **Faraday**: Enables the [Client Strategy](/strategies/client) for HTTP API integrations
+- **memo_wise**: Extends built-in `memo` helper to support methods with arguments (see [Memoization recipe](/recipes/memoization))
+
+These are all optional—Axn works great without them, but they unlock additional features when present.
+:::
+
+## Advanced: Default call behavior
+
+::: tip For Experienced Users
+This section covers an advanced shortcut. If you're new to Axn, start by explicitly defining your `call` method.
+:::
+
+If you don't define a `call` method, Axn provides a default implementation that automatically exposes all declared exposures by calling methods with matching names. This allows you to simplify actions that only need to compute and expose values:
+
+```ruby
+class CertificatesByDestination
+  include Axn
+  exposes :certs_by_destination, type: Hash
+
+  private
+
+  def certs_by_destination
+    # Your logic here - automatically exposed
+    { "dest1" => "cert1", "dest2" => "cert2" }
+  end
+end
+```
+
+This is equivalent to:
+
+```ruby
+class CertificatesByDestination
+  include Axn
+  exposes :certs_by_destination, type: Hash
+
+  def call
+    expose certs_by_destination: certs_by_destination
+  end
+
+  private
+
+  def certs_by_destination
+    { "dest1" => "cert1", "dest2" => "cert2" }
+  end
+end
 ```
+
+**Important notes:**
+- The default `call` requires a method matching each declared exposure (unless a `default` is provided)
+- If a method is missing and no default is provided, the action will fail with a helpful error message
+- You can still override `call` to implement custom logic when needed
+- If a method returns `nil` for an exposed-only field with no default, it's treated as missing (user-defined methods that legitimately return `nil` should use `expose` explicitly or provide a default)

data/lib/axn/async/adapters/active_job.rb

@@ -6,6 +6,10 @@ module Axn
       module ActiveJob
         extend ActiveSupport::Concern
 
+        def self._running_in_background?
+          defined?(ActiveJob) && ActiveJob::Base.current_job.present?
+        end
+
         included do
           raise LoadError, "ActiveJob is not available. Please add 'activejob' to your Gemfile." unless defined?(::ActiveJob::Base)
 
@@ -16,23 +20,28 @@ module Axn
         end
 
         class_methods do
-          def call_async(**kwargs)
+          private
+
+          # Implements adapter-specific enqueueing logic for ActiveJob.
+          # Note: Adapters must implement _enqueue_async_job and must NOT override call_async.
+          def _enqueue_async_job(kwargs)
             job = active_job_proxy_class
 
-            if kwargs[:_async].is_a?(Hash)
-              options = kwargs.delete(:_async)
-              if options[:wait_until]
-                job = job.set(wait_until: options[:wait_until])
-              elsif options[:wait]
-                job = job.set(wait: options[:wait])
+            # Extract and normalize _async options (removes _async from kwargs)
+            normalized_options = _extract_and_normalize_async_options(kwargs)
+
+            # Process normalized async options if present
+            if normalized_options
+              if normalized_options["wait_until"]
+                job = job.set(wait_until: normalized_options["wait_until"])
+              elsif normalized_options["wait"]
+                job = job.set(wait: normalized_options["wait"])
               end
             end
 
-            job.perform_later(**kwargs)
+            job.perform_later(kwargs)
           end
 
-          private
-
           def active_job_proxy_class
             @active_job_proxy_class ||= create_active_job_proxy_class
           end

data/lib/axn/async/adapters/disabled.rb

@@ -4,16 +4,31 @@ module Axn
   module Async
     class Adapters
       module Disabled
+        def self._running_in_background?
+          false
+        end
+
         def self.included(base)
           base.class_eval do
             # Validate that kwargs are not provided for Disabled adapter
             raise ArgumentError, "Disabled adapter does not accept configuration options." if _async_config&.any?
             raise ArgumentError, "Disabled adapter does not accept configuration block." if _async_config_block
 
+            # Exception to the adapter pattern: Disabled adapter overrides call_async directly
+            # to raise immediately without emitting notifications or logging.
+            # Other adapters must NOT override call_async and should only implement _enqueue_async_job.
             def self.call_async(**kwargs)
               # Remove _async parameter to avoid confusion in error message
               kwargs.delete(:_async)
 
+              # Don't emit notification or log - just raise immediately
+              raise NotImplementedError,
+                    "Async execution is explicitly disabled for #{name}. " \
+                    "Use `async :sidekiq` or `async :active_job` to enable background processing."
+            end
+
+            def self._enqueue_async_job(kwargs)
+              # This should never be called since call_async raises, but define it for completeness
               raise NotImplementedError,
                     "Async execution is explicitly disabled for #{name}. " \
                     "Use `async :sidekiq` or `async :active_job` to enable background processing."

data/lib/axn/async/adapters/sidekiq.rb

@@ -6,6 +6,10 @@ module Axn
       module Sidekiq
         extend ActiveSupport::Concern
 
+        def self._running_in_background?
+          defined?(::Sidekiq) && ::Sidekiq.server?
+        end
+
         included do
           raise LoadError, "Sidekiq is not available. Please add 'sidekiq' to your Gemfile." unless defined?(::Sidekiq)
 
@@ -14,6 +18,11 @@ module Axn
 
           include ::Sidekiq::Job
 
+          # Sidekiq's processor calls .new on the worker class from outside the class hierarchy
+          # (see Sidekiq::Processor#dispatch which does `klass.new`).
+          # Since Axn::Core makes :new private, we need to restore it for Sidekiq workers.
+          public_class_method :new
+
           # Apply configuration block if present
           class_eval(&_async_config_block) if _async_config_block
 
@@ -22,48 +31,32 @@ module Axn
         end
 
         class_methods do
-          def call_async(**kwargs)
-            job_kwargs = _params_to_global_id(kwargs)
-
-            if kwargs[:_async].is_a?(Hash)
-              options = kwargs.delete(:_async)
-              if options[:wait_until]
-                return perform_at(options[:wait_until], job_kwargs)
-              elsif options[:wait]
-                return perform_in(options[:wait], job_kwargs)
-              end
-            end
+          private
 
-            perform_async(job_kwargs)
-          end
+          # Implements adapter-specific enqueueing logic for Sidekiq.
+          # Note: Adapters must implement _enqueue_async_job and must NOT override call_async.
+          def _enqueue_async_job(kwargs)
+            # Extract and normalize _async options (removes _async from kwargs)
+            normalized_options = _extract_and_normalize_async_options(kwargs)
 
-          def _params_to_global_id(context = {})
-            return {} if context.nil?
+            # Convert kwargs to string keys and handle GlobalID conversion
+            job_kwargs = Axn::Util::GlobalIdSerialization.serialize(kwargs)
 
-            context.stringify_keys.each_with_object({}) do |(key, value), hash|
-              if value.respond_to?(:to_global_id)
-                hash["#{key}_as_global_id"] = value.to_global_id.to_s
-              else
-                hash[key] = value
+            # Process normalized async options if present
+            if normalized_options
+              if normalized_options["wait_until"]
+                return perform_at(normalized_options["wait_until"], job_kwargs)
+              elsif normalized_options["wait"]
+                return perform_in(normalized_options["wait"], job_kwargs)
               end
             end
-          end
 
-          def _params_from_global_id(params)
-            return {} if params.nil?
-
-            params.each_with_object({}) do |(key, value), hash|
-              if key.end_with?("_as_global_id")
-                hash[key.delete_suffix("_as_global_id")] = GlobalID::Locator.locate(value)
-              else
-                hash[key] = value
-              end
-            end.symbolize_keys
+            perform_async(job_kwargs)
           end
         end
 
         def perform(*args)
-          context = self.class._params_from_global_id(args.first)
+          context = Axn::Util::GlobalIdSerialization.deserialize(args.first)
 
           # Always use bang version so sidekiq can retry if we failed
           self.class.call!(**context)

data/lib/axn/async/batch_enqueue/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    module BatchEnqueue
+      # Stores the configuration for a single enqueues_each declaration
+      class Config
+        attr_reader :field, :from, :via, :filter_block
+
+        def initialize(field:, from:, via:, filter_block:)
+          @field = field
+          @from = from
+          @via = via
+          @filter_block = filter_block
+        end
+
+        # Resolves the source collection for iteration
+        # Can be a lambda, a symbol (method name on target), or inferred from model: true
+        def resolve_source(target:)
+          return from.call if from.is_a?(Proc)
+          return target.send(from) if from.is_a?(Symbol)
+
+          # Infer from field's model config if 'from' is nil
+          field_config = target.internal_field_configs.find { |c| c.field == field }
+          model_opts = field_config&.validations&.dig(:model)
+          model_class = model_opts[:klass] if model_opts.is_a?(Hash)
+
+          unless model_class
+            raise ArgumentError,
+                  "enqueues_each :#{field} requires `from:` option or a `model:` declaration " \
+                  "on `expects :#{field}` to infer the source collection."
+          end
+          model_class.all
+        end
+      end
+    end
+  end
+end

data/lib/axn/async/batch_enqueue.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "axn/async/batch_enqueue/config"
+
+module Axn
+  module Async
+    # BatchEnqueue provides declarative batch enqueueing for Axn actions.
+    #
+    # Fields with `model:` declarations are automatically inferred for iteration.
+    # Use `enqueues_each` to override defaults, add filtering, or iterate non-model fields.
+    # All Axn classes have `enqueue_all` defined, which validates configuration and
+    # executes iteration asynchronously via EnqueueAllOrchestrator.
+    #
+    # @example Auto-inference from model: (no enqueues_each needed)
+    #   class SyncCompany
+    #     include Axn
+    #     async :sidekiq
+    #
+    #     expects :company, model: Company  # Auto-inferred: Company.all
+    #
+    #     def call
+    #       # sync logic
+    #     end
+    #   end
+    #
+    #   SyncCompany.enqueue_all  # Automatically iterates Company.all
+    #
+    # @example With explicit source override
+    #   enqueues_each :company, from: -> { Company.active }
+    #
+    # @example With extraction (passes company_id instead of company object)
+    #   enqueues_each :company_id, from: -> { Company.active }, via: :id
+    #
+    # @example With filter block
+    #   enqueues_each :company do |company|
+    #     company.active? && !company.in_exit?
+    #   end
+    #
+    # @example Override on enqueue_all call
+    #   # Override with enumerable (replaces source)
+    #   SyncCompany.enqueue_all(company: Company.active.limit(10))
+    #
+    #   # Override with scalar (makes it static, no iteration)
+    #   SyncCompany.enqueue_all(company: Company.find(123))
+    #
+    # @example Multi-field cross-product
+    #   enqueues_each :user, from: -> { User.active }
+    #   enqueues_each :company, from: -> { Company.active }
+    #   # Produces user_count × company_count jobs
+    module BatchEnqueue
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_batch_enqueue_configs, default: []
+      end
+
+      # DSL methods for batch enqueueing
+      module DSL
+        # Batch enqueue jobs for this action.
+        #
+        # Validates async is configured, validates static args, then executes
+        # iteration asynchronously via EnqueueAllOrchestrator.
+        #
+        # Fields with `model:` declarations are automatically inferred for iteration.
+        # You can override iteration by passing enumerables (to replace source) or
+        # scalars (to make fields static) as kwargs.
+        #
+        # @param static_args [Hash] Arguments to pass to every enqueued job.
+        #   - Scalar values: Treated as static args (passed to all jobs)
+        #   - Enumerable values: Treated as iteration sources (overrides configured sources)
+        #   - Exception: Arrays/Sets are static when field expects enumerable type
+        # @return [String] Job ID from the async adapter
+        # @raise [NotImplementedError] If async is not configured
+        # @raise [MissingEnqueuesEachError] If expects exist but no iteration config found
+        # @raise [ArgumentError] If required static fields are missing
+        def enqueue_all(**static_args)
+          EnqueueAllOrchestrator.enqueue_for(self, **static_args)
+        end
+
+        # Declare a field to iterate over for batch enqueueing.
+        #
+        # Note: Fields with `model:` declarations are automatically inferred, so
+        # `enqueues_each` is only needed to override defaults, add filtering, or
+        # iterate non-model fields.
+        #
+        # @param field [Symbol] The field name from expects to iterate over
+        # @param from [Proc, Symbol, nil] The source collection.
+        #   - Proc/lambda: Called to get the collection
+        #   - Symbol: Method name on the action class
+        #   - nil: Inferred from field's `model:` declaration (Model.all)
+        # @param via [Symbol, nil] Optional attribute to extract from each item (e.g., :id)
+        # @param block [Proc, nil] Optional filter block - return truthy to enqueue, falsy to skip
+        def enqueues_each(field, from: nil, via: nil, &filter_block)
+          self._batch_enqueue_configs += [Config.new(field:, from:, via:, filter_block:)]
+        end
+      end
+    end
+  end
+end