axn 0.1.0.pre.alpha.2.8.1 → 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/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/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