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

data/docs/usage/writing.md

@@ -8,7 +8,7 @@ The core boilerplate is pretty minimal:
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   def call
     # ... do some stuff here?
@@ -22,14 +22,15 @@ The first step is to determine what arguments you expect to be passed into `call
 
 If you want to expose any results to the caller, declare that via the `exposes` keyword.
 
-Both of these optionally accept `type:`, `allow_nil:`, `allow_blank:`, and any other ActiveModel validation (see: [reference](/reference/class)).
+Both of these optionally accept `type:`, `optional:`, `allow_nil:`, `allow_blank:`, and any other ActiveModel validation (see: [reference](/reference/class)).
 
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   expects :name, type: String # [!code focus:2]
+  expects :email, type: String, optional: true # [!code focus:2]
   exposes :meaning_of_life
 
   def call
@@ -42,13 +43,15 @@ end
 
 Once the interface is defined, you're primarily focused on defining the `call` method.
 
-To abort execution with a specific error message, call `fail!`.
+To abort execution with a specific error message, call `fail!`. You can also provide exposures as keyword arguments.
+
+To complete execution early with a success result, call `done!` with an optional success message and exposures as keyword arguments.
 
 If you declare that your action `exposes` anything, you need to actually `expose` it.
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   expects :name, type: String
   exposes :meaning_of_life
@@ -64,6 +67,84 @@ end
 
 See [the reference doc](/reference/instance) for a few more handy helper methods (e.g. `#log`).
 
+### Convenient failure with context
+
+Both `fail!` and `done!` can accept keyword arguments to expose data before halting execution:
+
+```ruby
+class UserValidator
+  include Axn
+
+  expects :email
+  exposes :error_code, :field
+
+  def call
+    if email.blank?
+      fail!("Email is required", error_code: 422, field: "email")
+    end
+
+    # ... validation logic
+  end
+end
+```
+
+## Early completion with `done!`
+
+The `done!` method allows you to complete an action early with a success result, bypassing the rest of the execution:
+
+```ruby
+class UserLookup
+  include Axn
+
+  expects :user_id
+  exposes :user, :cached
+
+  def call
+    # Check cache first
+    cached_user = Rails.cache.read("user:#{user_id}")
+    if cached_user
+      done!("User found in cache", user: cached_user, cached: true) # Early completion with exposures
+    end
+
+    # This won't execute if done! was called above
+    user = User.find(user_id)
+    expose user: user, cached: false
+  end
+end
+```
+
+### Important behavior notes
+
+**Hook execution:**
+- `done!` **skips** any `after` hooks (or `call` method if called from a `before` hook)
+- `around` hooks **will complete** normally, allowing transactions and tracing to finish properly
+- If you want code that executes on both normal AND early success, use an `on_success` callback instead of an `after` hook
+
+**Transaction handling:**
+- `done!` is implemented internally via an exception, so it **will roll back** manually applied `ActiveRecord::Base.transaction` blocks
+- Use the [`use :transaction` strategy](/strategies/transaction) instead - transactions applied via this strategy will **NOT** be rolled back by `done!`
+- This ensures database consistency while allowing early completion
+
+**Validation:**
+- Outbound validation (required `exposes`) still runs even with early completion
+- If required fields are not provided, the action will fail despite the early completion
+
+```ruby
+class BadExample
+  include Axn
+
+  expects :user_id
+  exposes :user  # Required field
+
+  def call
+    done!("Early completion") # This will FAIL - user not exposed
+  end
+end
+
+BadExample.call(user_id: 123).ok? # => false
+BadExample.call(user_id: 123).exception # => Axn::OutboundValidationError
+```
+
 ## Customizing messages
 
 The default `error` and `success` message strings ("Something went wrong" / "Action completed successfully", respectively) _are_ technically safe to show users, but you'll often want to set them to something more useful.
@@ -74,7 +155,7 @@ For instance, configuring the action like this:
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   expects :name, type: String
   exposes :meaning_of_life
@@ -106,7 +187,7 @@ You can also use conditional error messages with the `prefix:` keyword and combi
 
 ```ruby
 class ValidationAction
-  include Action
+  include Axn
 
   expects :input
 
@@ -123,11 +204,14 @@ class ValidationAction
 end
 
 class ApiAction
-  include Action
+  include Axn
 
   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
@@ -135,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
@@ -142,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.
@@ -152,7 +244,7 @@ This configuration provides:
 **Correct order:**
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   # Static fallback messages first
   success "Default success message"
@@ -175,13 +267,44 @@ In addition to `#call`, there are a few additional pieces to be aware of:
 
 `before`, `after`, and `around` hooks are supported. They can receive a block directly, or the symbol name of a local method.
 
-Note execution is halted whenever `fail!` 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).
+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
 class Foo
-  include Action
+  include Axn
 
   before { log("before hook") } # [!code focus:2]
   after :log_after
@@ -220,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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    class Adapters
+      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)
+
+          # Validate that kwargs are not provided for ActiveJob
+          if _async_config&.any?
+            raise ArgumentError, "ActiveJob adapter requires a configuration block. Use `async :active_job do ... end` instead of passing keyword arguments."
+          end
+        end
+
+        class_methods do
+          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
+
+            # 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)
+          end
+
+          def active_job_proxy_class
+            @active_job_proxy_class ||= create_active_job_proxy_class
+          end
+
+          def create_active_job_proxy_class
+            # Store reference to the original action class
+            action_class = self
+
+            # Create the ActiveJob proxy class
+            Class.new(::ActiveJob::Base).tap do |proxy|
+              # Give the job class a meaningful name for logging and debugging
+              job_name = "#{name}::ActiveJobProxy"
+              const_set("ActiveJobProxy", proxy)
+              proxy.define_singleton_method(:name) { job_name }
+
+              # Apply the async configuration block if it exists
+              proxy.class_eval(&_async_config_block) if _async_config_block
+
+              # Define the perform method
+              proxy.define_method(:perform) do |job_context = {}|
+                # Call the original action class with the job context
+                action_class.call!(**job_context)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+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."
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    class Adapters
+      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)
+
+          # Use Sidekiq::Job if available (Sidekiq 7+), otherwise error
+          raise LoadError, "Sidekiq::Job is not available. Please check your Sidekiq version." unless defined?(::Sidekiq::Job)
+
+          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
+
+          # Apply kwargs configuration if present
+          sidekiq_options(**_async_config) if _async_config&.any?
+        end
+
+        class_methods do
+          private
+
+          # 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)
+
+            # Convert kwargs to string keys and handle GlobalID conversion
+            job_kwargs = Axn::Util::GlobalIdSerialization.serialize(kwargs)
+
+            # 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
+
+            perform_async(job_kwargs)
+          end
+        end
+
+        def perform(*args)
+          context = Axn::Util::GlobalIdSerialization.deserialize(args.first)
+
+          # Always use bang version so sidekiq can retry if we failed
+          self.class.call!(**context)
+        end
+      end
+    end
+  end
+end

data/lib/axn/async/adapters.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+require "active_support/core_ext/string/inflections"
+
+module Axn
+  module Async
+    class AdapterNotFound < Axn::Internal::Registry::NotFound; end
+    class DuplicateAdapterError < Axn::Internal::Registry::DuplicateError; end
+
+    class Adapters < Axn::Internal::Registry
+      class << self
+        def registry_directory = __dir__
+
+        private
+
+        def item_type = "Adapter"
+        def not_found_error_class = AdapterNotFound
+        def duplicate_error_class = DuplicateAdapterError
+      end
+    end
+
+    # Trigger registry loading to ensure adapters are available
+    Adapters.all
+  end
+end

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