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

data/docs/reference/form-object.md

@@ -0,0 +1,252 @@
+---
+outline: deep
+---
+
+# Axn::FormObject
+
+`Axn::FormObject` is a base class for creating form objects that validate user input. It extends `ActiveModel::Model` with conveniences specifically designed for use with Axn actions.
+
+## Overview
+
+Form objects provide a layer between raw user input and your domain logic. They:
+- Validate user-facing input with friendly error messages
+- Provide a clean interface for accessing validated data
+- Support nested form objects for complex forms
+- Automatically track field names for serialization
+
+## Basic Usage
+
+```ruby
+class RegistrationForm < Axn::FormObject
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :password, presence: true, length: { minimum: 8 }
+  validates :password_confirmation, presence: true
+
+  validate :passwords_match
+
+  private
+
+  def passwords_match
+    return if password == password_confirmation
+
+    errors.add(:password_confirmation, "doesn't match password")
+  end
+end
+```
+
+## Auto-Generated Accessors
+
+Unlike plain `ActiveModel::Model`, `Axn::FormObject` automatically creates `attr_accessor` methods for any field you validate:
+
+```ruby
+class MyForm < Axn::FormObject
+  validates :name, presence: true    # Automatically creates attr_accessor :name
+  validates :email, presence: true   # Automatically creates attr_accessor :email
+end
+
+form = MyForm.new(name: "Alice", email: "alice@example.com")
+form.name   # => "Alice"
+form.email  # => "alice@example.com"
+```
+
+You can also explicitly declare accessors:
+
+```ruby
+class MyForm < Axn::FormObject
+  attr_accessor :optional_field  # Tracked in field_names
+
+  validates :required_field, presence: true
+end
+```
+
+## Field Name Tracking
+
+`Axn::FormObject` tracks all declared fields in `field_names`, which is used for serialization:
+
+```ruby
+class MyForm < Axn::FormObject
+  validates :name, presence: true
+  validates :email, presence: true
+  attr_accessor :notes
+end
+
+MyForm.field_names  # => [:name, :email, :notes]
+```
+
+## Serialization with `#to_h`
+
+The `#to_h` method converts the form object to a hash containing all tracked fields:
+
+```ruby
+class ProfileForm < Axn::FormObject
+  validates :name, presence: true
+  validates :bio, length: { maximum: 500 }
+end
+
+form = ProfileForm.new(name: "Alice", bio: "Developer")
+form.to_h  # => { name: "Alice", bio: "Developer" }
+```
+
+This is particularly useful when creating or updating records:
+
+```ruby
+class UpdateProfile
+  include Axn
+
+  use :form, type: ProfileForm
+
+  expects :user, model: User
+
+  def call
+    user.update!(form.to_h)
+  end
+end
+```
+
+## Nested Forms
+
+Use `nested_forms` (or `nested_form`) to declare child form objects:
+
+```ruby
+class OrderForm < Axn::FormObject
+  validates :customer_email, presence: true
+
+  nested_form shipping_address: AddressForm
+  nested_form billing_address: AddressForm
+end
+
+class AddressForm < Axn::FormObject
+  validates :street, presence: true
+  validates :city, presence: true
+  validates :zip, presence: true
+end
+```
+
+### Nested Form Behavior
+
+- Nested forms are validated when the parent is validated
+- Child errors are bubbled up with prefixed attribute names
+- The child form receives a `parent_form` accessor if it defines one
+
+```ruby
+form = OrderForm.new(
+  customer_email: "alice@example.com",
+  shipping_address: { street: "123 Main St", city: "Boston", zip: "02101" },
+  billing_address: { street: "", city: "", zip: "" }  # Invalid
+)
+
+form.valid?  # => false
+form.errors.full_messages
+# => ["Billing address.street can't be blank", "Billing address.city can't be blank", ...]
+```
+
+### Accessing Parent Form
+
+Child forms can access their parent:
+
+```ruby
+class LineItemForm < Axn::FormObject
+  attr_accessor :parent_form  # Will be set automatically
+
+  validates :quantity, presence: true, numericality: { greater_than: 0 }
+
+  validate :quantity_available
+
+  private
+
+  def quantity_available
+    return unless parent_form&.product
+
+    max = parent_form.product.stock_quantity
+    errors.add(:quantity, "exceeds available stock (#{max})") if quantity > max
+  end
+end
+```
+
+## Inheritance
+
+Form objects support inheritance, and field names are inherited:
+
+```ruby
+class BaseForm < Axn::FormObject
+  validates :created_by, presence: true
+end
+
+class UserForm < BaseForm
+  validates :email, presence: true
+  validates :name, presence: true
+end
+
+UserForm.field_names  # => [:created_by, :email, :name]
+```
+
+## Integration with Actions
+
+Form objects are designed to work seamlessly with the [Form Strategy](/strategies/form):
+
+```ruby
+class CreateUser
+  include Axn
+
+  use :form, type: UserForm
+
+  exposes :user
+
+  error { form.errors.full_messages.to_sentence }
+  success { "Welcome, #{user.name}!" }
+
+  def call
+    user = User.create!(form.to_h)
+    expose user: user
+  end
+end
+
+class UserForm < Axn::FormObject
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true
+  validates :password, presence: true, length: { minimum: 8 }
+end
+```
+
+## Complete Example
+
+```ruby
+class CompanyRegistrationForm < Axn::FormObject
+  validates :company_name, presence: true
+  validates :industry, presence: true, inclusion: { in: %w[tech finance healthcare retail] }
+
+  nested_form admin: AdminForm
+  nested_form billing: BillingForm
+
+  def industry_options
+    [
+      ["Technology", "tech"],
+      ["Finance", "finance"],
+      ["Healthcare", "healthcare"],
+      ["Retail", "retail"]
+    ]
+  end
+end
+
+class AdminForm < Axn::FormObject
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true
+  validates :password, presence: true, length: { minimum: 8 }
+end
+
+class BillingForm < Axn::FormObject
+  attr_accessor :parent_form
+
+  validates :billing_email, presence: true
+  validates :payment_method, presence: true, inclusion: { in: %w[card ach invoice] }
+
+  def billing_email
+    @billing_email.presence || parent_form&.admin&.email
+  end
+end
+```
+
+## See Also
+
+- [Form Strategy](/strategies/form) - Using form objects with actions
+- [Validating User Input](/recipes/validating-user-input) - When to use form objects

data/docs/strategies/client.md

@@ -0,0 +1,212 @@
+# Client Strategy
+
+The `client` strategy provides a declarative way to configure HTTP clients for API integrations. It creates a memoized Faraday connection with sensible defaults and optional error handling.
+
+::: warning Peer Dependency
+This strategy requires the `faraday` gem to be available. It is only registered when Faraday is loaded.
+:::
+
+## Basic Usage
+
+```ruby
+class FetchUserData
+  include Axn
+
+  use :client, url: "https://api.example.com"
+
+  expects :user_id
+  exposes :user_data
+
+  def call
+    response = client.get("/users/#{user_id}")
+    expose user_data: response.body
+  end
+end
+```
+
+## Configuration Options
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `name` | `:client` | The method name for accessing the client |
+| `url` | (required) | Base URL for the API |
+| `headers` | `{}` | Default headers to include in all requests |
+| `user_agent` | Auto-generated | Custom User-Agent header |
+| `debug` | `false` | Enable Faraday response logging |
+| `prepend_config` | `nil` | Proc to prepend middleware configuration |
+| `error_handler` | `nil` | Error handling configuration (see below) |
+
+Any additional options are passed directly to `Faraday.new`.
+
+## Default Middleware
+
+The client strategy automatically configures these middleware:
+
+1. `Content-Type: application/json` header
+2. `User-Agent` header (configurable)
+3. `response :raise_error` - Raises on 4xx/5xx responses
+4. `request :url_encoded` - Encodes request parameters
+5. `request :json` - JSON request encoding
+6. `response :json` - JSON response parsing
+
+## Custom Client Name
+
+```ruby
+class ExternalApiAction
+  include Axn
+
+  use :client, name: :api_client, url: "https://api.example.com"
+  use :client, name: :auth_client, url: "https://auth.example.com"
+
+  def call
+    token = auth_client.post("/token").body["access_token"]
+    data = api_client.get("/data", nil, { "Authorization" => "Bearer #{token}" })
+    # ...
+  end
+end
+```
+
+## Dynamic Configuration
+
+Options can be callables (procs/lambdas) for dynamic values:
+
+```ruby
+class SecureApiAction
+  include Axn
+
+  use :client,
+    url: "https://api.example.com",
+    headers: -> { { "Authorization" => "Bearer #{current_token}" } }
+
+  private
+
+  def current_token
+    # Fetch or refresh token as needed
+    TokenStore.get_valid_token
+  end
+end
+```
+
+## Custom Headers
+
+```ruby
+class ApiAction
+  include Axn
+
+  use :client,
+    url: "https://api.example.com",
+    headers: {
+      "X-API-Key" => ENV["API_KEY"],
+      "Accept" => "application/json"
+    }
+end
+```
+
+## Error Handling
+
+The `error_handler` option configures custom error handling middleware:
+
+```ruby
+class ApiAction
+  include Axn
+
+  use :client,
+    url: "https://api.example.com",
+    error_handler: {
+      if: -> { status != 200 },           # Condition to trigger error handling
+      error_key: "error.message",          # JSON path to error message
+      detail_key: "error.details",         # JSON path to error details (optional)
+      backtrace_key: "error.backtrace",    # JSON path to backtrace (optional)
+      exception_class: CustomApiError,     # Exception class to raise (default: Faraday::BadRequestError)
+      formatter: ->(error, details, env) { # Custom message formatter (optional)
+        "API Error: #{error} - #{details}"
+      },
+      extract_detail: ->(key, value) {     # Extract detail from hash/array (optional)
+        "#{key}: #{value}"
+      }
+    }
+end
+```
+
+### Error Handler Options
+
+| Option | Description |
+| ------ | ----------- |
+| `if` | Condition proc to trigger error handling (receives `status`, `body`, `response_env`) |
+| `error_key` | Dot-notation path to error message in response JSON |
+| `detail_key` | Dot-notation path to error details |
+| `backtrace_key` | Dot-notation path to backtrace |
+| `exception_class` | Exception class to raise (default: `Faraday::BadRequestError`) |
+| `formatter` | Custom proc to format the error message |
+| `extract_detail` | Proc to extract details from nested structures |
+
+## Prepending Middleware
+
+Use `prepend_config` when you need to add middleware before the default stack:
+
+```ruby
+class ApiAction
+  include Axn
+
+  use :client,
+    url: "https://api.example.com",
+    prepend_config: ->(conn) {
+      conn.request :retry, max: 3, interval: 0.5
+      conn.request :authorization, "Bearer", -> { fetch_token }
+    }
+end
+```
+
+## Complete Example
+
+```ruby
+class SyncExternalData
+  include Axn
+
+  use :client,
+    name: :external_api,
+    url: ENV["EXTERNAL_API_URL"],
+    headers: -> { { "Authorization" => "Bearer #{api_token}" } },
+    user_agent: "MyApp/1.0",
+    error_handler: {
+      error_key: "error.message",
+      detail_key: "error.details",
+      extract_detail: ->(node) { node["field"] ? "#{node['field']}: #{node['message']}" : node["message"] }
+    }
+
+  expects :company, model: Company
+  exposes :synced_records
+
+  error "Failed to sync external data"
+  error from: Faraday::BadRequestError do |e|
+    "External API error: #{e.message}"
+  end
+
+  def call
+    response = external_api.get("/companies/#{company.external_id}/data")
+    records = response.body["records"].map do |record|
+      company.external_records.find_or_create_by!(external_id: record["id"]) do |r|
+        r.data = record
+      end
+    end
+    expose synced_records: records
+  end
+
+  private
+
+  def api_token
+    Rails.cache.fetch("external_api_token", expires_in: 1.hour) do
+      # Token refresh logic
+    end
+  end
+end
+```
+
+## Memoization
+
+The client is automatically memoized using `memo`, so repeated calls to the client method return the same Faraday connection instance. This ensures efficient connection reuse within a single action execution.
+
+## See Also
+
+- [Strategies Overview](/strategies/index) - How to use and create strategies
+- [Memoization](/recipes/memoization) - How memoization works in Axn

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/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,7 @@ 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)