axn 0.1.0.pre.alpha.2.8 → 0.1.0.pre.alpha.3

data/docs/reference/instance.md

@@ -2,7 +2,7 @@
 
 ## `#expose`
 
-Used to set a value on the Action::Result. Remember you can only `expose` keys that you have declared in [the class-level interface](/reference/class).
+Used to set a value on the Axn::Result. Remember you can only `expose` keys that you have declared in [the class-level interface](/reference/class).
 
 * Accepts two positional arguments (the key and value to set, respectively): `expose :some_key, 123`
 * Accepts a hash with one or more key/value pairs: `expose some_key: 123, another: 456`
@@ -12,43 +12,28 @@ Primarily used for its side effects, but it does return a Hash with the key/valu
 
 ## `#fail!`
 
-Called with a string, it immediately halts execution and sets `result.error` to the provided string.
+Called with a string, it immediately halts execution and sets `result.error` to the provided string. Can also accept keyword arguments that will be exposed before halting execution.
 
-## `#log`
-
-Helper method to log (via the [configurable](/reference/configuration#logger) `Action.config.logger`) the string you provide (prefixed with the Action's class name).
-
-* First argument (required) is a string message to log
-* Also accepts a `level:` keyword argument to change the log level (defaults to `info`)
+* First argument (optional) is a string error message
+* Additional keyword arguments are exposed as data before halting
 
-Primarily used for its side effects; returns whatever the underlying `Action.config.logger` instance returns but it does return a Hash with the key/value pair(s) you exposed.
+## `#done!`
 
-## `#try`
+Called with an optional string, it immediately halts execution and sets `result.success` to the provided string (or default success message if none provided). Can also accept keyword arguments that will be exposed before halting execution. Skips `after` hooks and remaining `call` method execution, but allows `around` hooks to complete normally.
 
-Accepts a block.  Any exceptions raised within that block will be swallowed, but _they will NOT fail the action_!
+* First argument (optional) is a string success message
+* Additional keyword arguments are exposed as data before halting
 
-A few details:
-* An explicit `fail!` call _will_ still fail the action
-* Any exceptions swallowed _will_ still be reported via the `on_exception` handler
+**Important:** This method 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 for transaction-safe early completion.
 
-This is primarily useful in an after block, e.g. trigger notifications after an action has been taken.  If the notification fails to send you DO want to log the failure somewhere to investigate, but since the core action has already been taken often you do _not_ want to fail.
-
-Example:
-
-```ruby
-class Foo
-  include Action
+## `#log`
 
-  after do
-    try { send_slack_notifications } # [!code focus]
-  end
+Helper method to log (via the [configurable](/reference/configuration#logger) `Axn.config.logger`) the string you provide (prefixed with the Action's class name).
 
-  def call = ...
+* First argument (required) is a string message to log
+* Also accepts a `level:` keyword argument to change the log level (defaults to `info`)
 
-  private
+Primarily used for its side effects; returns whatever the underlying `Axn.config.logger` instance returns but it does return a Hash with the key/value pair(s) you exposed.
 
-  def send_slack_notifications = ...
-end
-```
 
 

data/docs/strategies/index.md

@@ -19,7 +19,7 @@ To use a strategy in your action, call the `use` method with the strategy name:
 
 ```ruby
 class CreateUser
-  include Action
+  include Axn
 
   use :transaction
 
@@ -35,11 +35,11 @@ end
 
 ### Using Strategies with Configuration
 
-Some strategies support configuration options. These strategies have a `setup` method that accepts configuration and returns a configured module.  As an _imaginary_ example:
+Some strategies support configuration options. These strategies have a `configure` method that accepts configuration and returns a configured module.  As an _imaginary_ example:
 
 ```ruby
 class ProcessPayment
-  include Action
+  include Axn
 
   use :retry, max_attempts: 3, backoff: :exponential
 
@@ -55,7 +55,7 @@ end
 
 ## Built-in Strategies
 
-The list of built in strategies is available via `Action::Strategies.built_in`.
+The list of built in strategies is available via `Axn::Strategies.built_in`.
 
 ## Registering Custom Strategies
 
@@ -79,14 +79,14 @@ end
 Then register it with the strategies system:
 
 ```ruby
-Action::Strategies.register(:my_custom, MyCustomStrategy)
+Axn::Strategies.register(:my_custom, MyCustomStrategy)
 ```
 
 Now you can use it in your actions:
 
 ```ruby
 class MyAction
-  include Action
+  include Axn
 
   use :my_custom
 
@@ -98,13 +98,13 @@ end
 
 ### Configurable Strategies
 
-For strategies that need configuration, implement a `setup` method that returns a configured module:
+For strategies that need configuration, implement a `configure` method that returns a configured module:
 
 ```ruby
 module RetryStrategy
   extend ActiveSupport::Concern
 
-  def self.setup(max_attempts: 3, backoff: :linear, &block)
+  def self.configure(max_attempts: 3, backoff: :linear, &block)
     Module.new do
       extend ActiveSupport::Concern
 
@@ -142,15 +142,15 @@ module RetryStrategy
 end
 
 # Register the strategy
-Action::Strategies.register(:retry, RetryStrategy)
+Axn::Strategies.register(:retry, RetryStrategy)
 ```
 
 ### Strategy Registration Best Practices
 
 1. **Register early**: Register custom strategies during application initialization
 2. **Use descriptive names**: Choose strategy names that clearly indicate their purpose
-3. **Handle configuration validation**: Validate configuration options in your `setup` method
-4. **Return proper modules**: Always return a module from the `setup` method
+3. **Handle configuration validation**: Validate configuration options in your `configure` method
+4. **Return proper modules**: Always return a module from the `configure` method
 5. **Document your strategies**: Include clear documentation for how to use your custom strategies
 
 ### Example: Complete Custom Strategy
@@ -161,7 +161,7 @@ Here's a complete example of a custom strategy that adds performance monitoring
 module PerformanceMonitoringStrategy
   extend ActiveSupport::Concern
 
-  def self.setup(threshold_ms: 1000, notify_slow: false, &block)
+  def self.configure(threshold_ms: 1000, notify_slow: false, &block)
     Module.new do
       extend ActiveSupport::Concern
 
@@ -194,11 +194,11 @@ module PerformanceMonitoringStrategy
 end
 
 # Register the strategy
-Action::Strategies.register(:performance_monitoring, PerformanceMonitoringStrategy)
+Axn::Strategies.register(:performance_monitoring, PerformanceMonitoringStrategy)
 
 # Use it in an action
 class ExpensiveCalculation
-  include Action
+  include Axn
 
   use :performance_monitoring, threshold_ms: 500, notify_slow: true
 
@@ -227,7 +227,7 @@ end
 You can inspect all registered strategies:
 
 ```ruby
-Action::Strategies.all
+Axn::Strategies.all
 # Returns a hash of strategy names to their modules
 ```
 
@@ -236,11 +236,11 @@ Action::Strategies.all
 To find a specific strategy by name:
 
 ```ruby
-Action::Strategies.find(:transaction)
+Axn::Strategies.find(:transaction)
 # Returns the strategy module for the transaction strategy
 
-Action::Strategies.find(:nonexistent)
-# Raises Action::StrategyNotFound: Strategy 'nonexistent' not found
+Axn::Strategies.find(:nonexistent)
+# Raises Axn::StrategyNotFound: Strategy 'nonexistent' not found
 ```
 
 The `find` method is useful when you need to programmatically access a strategy module or verify that a strategy exists before using it.
@@ -250,15 +250,15 @@ The `find` method is useful when you need to programmatically access a strategy
 To reset strategies to only built-in ones (useful in tests):
 
 ```ruby
-Action::Strategies.clear!
+Axn::Strategies.clear!
 ```
 
 ### Strategy Errors
 
 The following errors may be raised when using strategies:
 
-- `Action::StrategyNotFound`: When trying to use a strategy that hasn't been registered
-- `Action::DuplicateStrategyError`: When trying to register a strategy with a name that's already taken
+- `Axn::StrategyNotFound`: When trying to use a strategy that hasn't been registered
+- `Axn::DuplicateStrategyError`: When trying to register a strategy with a name that's already taken
 - `ArgumentError`: When providing configuration to a strategy that doesn't support it
 
 ## Best Practices

data/docs/strategies/transaction.md

@@ -4,7 +4,7 @@ The `transaction` strategy wraps your action execution in a database transaction
 
 ```ruby
 class TransferFunds
-  include Action
+  include Axn
 
   use :transaction
 

data/docs/usage/setup.md

@@ -21,6 +21,20 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 If you're using an APM provider, observability can be greatly enhanced by [configuring tracing and metrics hooks](/reference/configuration#tracing-and-metrics).
 
+### Rails Integration (Optional)
+
+When using Axn in a Rails application, you can configure how actions are autoloaded from the `app/actions` directory. By default, actions are loaded without any namespace, but you can configure a namespace to help differentiate them from existing service objects:
+
+```ruby
+# config/initializers/axn.rb
+Axn.configure do |c|
+  # Use :Actions namespace to differentiate from existing service objects
+  c.rails.app_actions_autoload_namespace = :Actions
+end
+```
+
+This is particularly useful when migrating from existing service object patterns, as it makes it easy to distinguish between new Axn actions and legacy service objects when you see `action.call` in your codebase.
+
 ### Code Quality (Optional)
 
 For teams using RuboCop, Axn provides custom cops to enforce best practices. See the [RuboCop Integration guide](/recipes/rubocop-integration) for setup instructions.

data/docs/usage/steps.md

@@ -31,7 +31,7 @@ The `step` method allows you to define steps inline with blocks:
 
 ```ruby
 class UserRegistration
-  include Action
+  include Axn
   expects :email, :password, :name
   exposes :user_id, :welcome_message
 
@@ -66,7 +66,7 @@ The `steps` method allows you to compose existing action classes:
 
 ```ruby
 class ValidateInput
-  include Action
+  include Axn
   expects :email, :password, :name
   exposes :validated_data
 
@@ -80,7 +80,7 @@ class ValidateInput
 end
 
 class CreateUser
-  include Action
+  include Axn
   expects :validated_data
   exposes :user_id
 
@@ -91,7 +91,7 @@ class CreateUser
 end
 
 class SendWelcome
-  include Action
+  include Axn
   expects :user_id, :validated_data
   exposes :welcome_message
 
@@ -102,7 +102,7 @@ class SendWelcome
 end
 
 class UserRegistration
-  include Action
+  include Axn
   expects :email, :password, :name
   exposes :user_id, :welcome_message
 
@@ -117,7 +117,7 @@ You can combine both approaches:
 
 ```ruby
 class UserRegistration
-  include Action
+  include Axn
   expects :email, :password, :name
   exposes :user_id, :welcome_message
 
@@ -292,7 +292,7 @@ end
 
 ```ruby
 class ProcessAPIRequest
-  include Action
+  include Axn
   expects :request_data
   exposes :response_data
 

data/docs/usage/using.md

@@ -7,9 +7,9 @@ outline: deep
 
 ## Common Case
 
-An action executed via `#call` _always_ returns an instance of the `Action::Result` class.
+An action executed via `#call` _always_ returns an instance of the `Axn::Result` class.
 
-This means the result _always_ implements a consistent interface, including `ok?` and `error` (see [full details](/reference/action-result)) as well as any variables that the action `exposes`.
+This means the result _always_ implements a consistent interface, including `ok?` and `error` (see [full details](/reference/axn-result)) as well as any variables that the action `exposes`.
 
 As a consumer, you usually want a conditional that surfaces `error` unless the result is `ok?` (remember that any exceptions have been swallowed), and otherwise takes whatever success action is relevant.
 
@@ -38,20 +38,31 @@ end
 
 ### `#call!`
 
-An action executed via `#call!` (note the `!`) does _not_ swallow exceptions -- a _successful_ action will return an `Action::Result` just like `call`, but any exceptions will bubble up uncaught (note: technically they _will_ be caught, your on_exception handler triggered, and then re-raised) and any explicit `fail!` calls will raise an `Action::Failure` exception with your custom message.
+An action executed via `#call!` (note the `!`) does _not_ swallow exceptions -- a _successful_ action will return an `Axn::Result` just like `call`, but any exceptions will bubble up uncaught (note: technically they _will_ be caught, your on_exception handler triggered, and then re-raised) and any explicit `fail!` calls will raise an `Axn::Failure` exception with your custom message.
 
 This is a much less common pattern, as you're giving up the benefits of error swallowing and the consistent return interface guarantee, but it can be useful in limited contexts (usually for smaller, one-off scripts where it's easier to just let a failure bubble up rather than worry about adding conditionals for error handling).
 
 
-### `#enqueue`
+### `#call_async`
 
-Before adopting this library, our code was littered with one-line workers whose only job was to fire off a service on a background job.  We were able to remove that entire glue layer by directly supporting enqueueing sidekiq jobs from the Action itself.
+Before adopting this library, our code was littered with one-line workers whose only job was to fire off a service on a background job. We were able to remove that entire glue layer by directly supporting async execution via background jobs from the Axn itself.
 
-::: danger ALPHA
-Sidekiq integration is NOT YET TESTED/NOT YET USED IN OUR APP, and naming will VERY LIKELY change to make it clearer which actions will be retried!
-:::
+```ruby
+class ProcessDataAction
+  include Axn
+
+  expects :data
+
+  def call
+    # Process data logic here
+  end
+end
+
+# Execute synchronously
+result = ProcessDataAction.call(data: large_dataset)
+
+# Execute asynchronously
+ProcessDataAction.call_async(data: large_dataset)
+```
 
-* enqueue vs enqueue!
-    * enqueue will not retry even if fails
-    * enqueue! will go through normal sidekiq retries on any failure (including user-facing `fail!`)
-    * Note implicit GlobalID support (if not serializable, will get ArgumentError at callsite)
+For detailed information about configuring async adapters (Sidekiq, ActiveJob, etc.), see the [Async Execution documentation](/reference/async).

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,7 +204,7 @@ class ValidationAction
 end
 
 class ApiAction
-  include Action
+  include Axn
 
   expects :data
 
@@ -152,7 +233,7 @@ This configuration provides:
 **Correct order:**
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   # Static fallback messages first
   success "Default success message"
@@ -175,13 +256,13 @@ 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.
 
 For instance, given this configuration:
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   before { log("before hook") } # [!code focus:2]
   after :log_after

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    class Adapters
+      module ActiveJob
+        extend ActiveSupport::Concern
+
+        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
+          def call_async(**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])
+              end
+            end
+
+            job.perform_later(**kwargs)
+          end
+
+          private
+
+          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,26 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    class Adapters
+      module Disabled
+        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
+
+            def self.call_async(**kwargs)
+              # Remove _async parameter to avoid confusion in error message
+              kwargs.delete(:_async)
+
+              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