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

data/docs/strategies/form.md

@@ -0,0 +1,235 @@
+# Form Strategy
+
+The `form` strategy provides a declarative way to validate user input using form objects. It bridges the gap between raw user input (like `params`) and validated, structured data.
+
+::: tip When to Use
+Use the form strategy when you need to validate **user-facing input** with user-friendly error messages. This is different from `expects` validations, which validate the **developer contract** (how the action is called).
+:::
+
+## Basic Usage
+
+```ruby
+class CreateUser
+  include Axn
+
+  use :form, type: CreateUser::Form
+
+  def call
+    # form is automatically validated and exposed
+    # If validation fails, the action fails with form.errors
+    User.create!(form.to_h)
+  end
+end
+
+class CreateUser::Form < Axn::FormObject
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true, length: { minimum: 2 }
+end
+```
+
+## Configuration Options
+
+The form strategy accepts several configuration options:
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `type` | Auto-detected | The form class to use (see [Type Resolution](#type-resolution)) |
+| `expect` | `:params` | The input field name to read from |
+| `expose` | `:form` | The field name to expose the form object as |
+| `inject` | `nil` | Additional context fields to inject into the form |
+
+### Type Resolution
+
+The `type` option determines which form class to use:
+
+1. **Explicit class**: `use :form, type: MyFormClass`
+2. **String constant path**: `use :form, type: "CreateUser::Form"`
+3. **Auto-detected**: If not specified, inferred from action name + expose name (e.g., `CreateUser` + `:form` → `CreateUser::Form`)
+
+```ruby
+# Explicit type
+use :form, type: RegistrationForm
+
+# String constant (useful for avoiding load order issues)
+use :form, type: "Users::RegistrationForm"
+
+# Auto-detected from action name
+class CreateUser
+  include Axn
+  use :form  # Uses CreateUser::Form
+end
+```
+
+### Inline Form Definition
+
+You can define the form class inline using a block:
+
+```ruby
+class CreateUser
+  include Axn
+
+  use :form do
+    validates :email, presence: true
+    validates :name, presence: true
+  end
+
+  def call
+    User.create!(form.to_h)
+  end
+end
+```
+
+This creates an anonymous form class that inherits from `Axn::FormObject`.
+
+### Custom Field Names
+
+```ruby
+class ProcessOrder
+  include Axn
+
+  # Read from :order_params, expose as :order_form
+  use :form, expect: :order_params, expose: :order_form, type: OrderForm
+
+  def call
+    # Access via order_form instead of form
+    Order.create!(order_form.to_h)
+  end
+end
+```
+
+### Injecting Context
+
+Use `inject` to pass additional context fields to the form:
+
+```ruby
+class UpdateProfile
+  include Axn
+
+  expects :user, model: User
+  use :form, type: ProfileForm, inject: [:user]
+
+  def call
+    user.update!(form.to_h)
+  end
+end
+
+class ProfileForm < Axn::FormObject
+  attr_accessor :user  # Injected from action context
+
+  validates :email, presence: true
+  validate :email_unique_for_other_users
+
+  private
+
+  def email_unique_for_other_users
+    return if user.nil?
+    return unless User.where.not(id: user.id).exists?(email: email)
+
+    errors.add(:email, "is already taken")
+  end
+end
+```
+
+## How It Works
+
+When you use the form strategy, the following happens automatically:
+
+1. **Expects params**: Adds `expects :params, type: :params` (or your custom `expect` field)
+2. **Exposes form**: Adds `exposes :form` (or your custom `expose` field)
+3. **Creates form**: Defines a memoized method that creates the form from params
+4. **Validates in before hook**: Runs `form.valid?` in a before hook; if invalid, the action fails
+
+```ruby
+# This:
+use :form, type: MyForm
+
+# Is roughly equivalent to:
+expects :params, type: :params
+exposes :form, type: MyForm
+
+def form
+  @form ||= MyForm.new(params)
+end
+
+before do
+  expose form: form
+  fail! unless form.valid?
+end
+```
+
+## Error Handling
+
+When form validation fails:
+- The action fails (returns `ok? == false`)
+- `result.error` contains a generic message
+- `result.form.errors` contains the detailed validation errors
+
+```ruby
+result = CreateUser.call(params: { email: "", name: "" })
+
+result.ok?                    # => false
+result.form.errors.full_messages
+# => ["Email can't be blank", "Name can't be blank"]
+```
+
+### User-Facing Errors
+
+To expose user-friendly error messages, configure a custom error handler:
+
+```ruby
+class CreateUser
+  include Axn
+
+  use :form, type: CreateUser::Form
+
+  error { form.errors.full_messages.to_sentence }
+
+  def call
+    User.create!(form.to_h)
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+class CreateCompanyMember
+  include Axn
+
+  expects :company, model: Company
+  use :form, type: MemberForm, inject: [:company]
+
+  exposes :member
+
+  error { form.errors.full_messages.to_sentence }
+  success { "#{member.name} has been added to #{company.name}" }
+
+  def call
+    member = company.members.create!(form.to_h)
+    expose member: member
+  end
+end
+
+class MemberForm < Axn::FormObject
+  attr_accessor :company  # Injected
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true
+  validates :role, presence: true, inclusion: { in: %w[admin member guest] }
+
+  validate :email_not_already_member
+
+  private
+
+  def email_not_already_member
+    return unless company&.members&.exists?(email: email)
+
+    errors.add(:email, "is already a member of this company")
+  end
+end
+```
+
+## See Also
+
+- [Axn::FormObject](/reference/form-object) - The base class for form objects
+- [Validating User Input](/recipes/validating-user-input) - When to use form validation vs expects validation

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

@@ -5,7 +5,7 @@ outline: deep
 
 ## Installation
 
-Adding `axn` to your Gemfile is enough to start using `include Action`.
+Adding `axn` to your Gemfile is enough to start using `include Axn`.
 
 ## Global Configuration
 
@@ -19,7 +19,21 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 ### Metrics / Tracing
 
-If you're using an APM provider, observability can be greatly enhanced by [configuring tracing and metrics hooks](/reference/configuration#tracing-and-metrics).
+If you're using an APM provider, observability can be greatly enhanced by [configuring OpenTelemetry tracing and metrics hooks](/reference/configuration#opentelemetry-tracing). Axn automatically creates OpenTelemetry spans when OpenTelemetry is available.
+
+### 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)
 

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).