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

data/docs/reference/class.md

@@ -13,9 +13,10 @@ Both `expects` and `exposes` support the same core options:
 | Option | Example (same for `exposes`) | Meaning |
 | -- | -- | -- |
 | `sensitive` | `expects :password, sensitive: true` | Filters the field's value when logging, reporting errors, or calling `inspect`
-| `default` | `expects :foo, default: 123` | If `foo` isn't explicitly set, it'll default to this value
-| `allow_nil` | `expects :foo, allow_nil: true` | Don't fail if the value is `nil`
-| `allow_blank` | `expects :foo, allow_blank: true` | Don't fail if the value is blank
+| `default` | `expects :foo, default: 123` | If `foo` is missing or explicitly `nil`, it'll default to this value (not applied for blank values)
+| `optional` | `expects :foo, optional: true` | **Recommended**: Don't fail if the value is missing, nil, or blank. Equivalent to `allow_blank: true`
+| `allow_nil` | `expects :foo, allow_nil: true` | Don't fail if the value is `nil` (but will fail for blank strings)
+| `allow_blank` | `expects :foo, allow_blank: true` | Don't fail if the value is blank (nil, empty string, whitespace, etc.)
 | `type` | `expects :foo, type: String` | Custom type validation -- fail unless `name.is_a?(String)`
 | anything else | `expects :foo, inclusion: { in: [:apple, :peach] }` | Any other arguments will be processed [as ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html) (i.e. as if passed to `validates :foo, <...>` on an ActiveRecord model)
 
@@ -26,33 +27,52 @@ Both `expects` and `exposes` support the same core options:
 While we _support_ complex interface validations, in practice you usually just want a `type`, if anything.  Remember this is your validation about how the action is called, _not_ pretty user-facing errors (there's [a different pattern for that](/recipes/validating-user-input)).
 :::
 
-In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support three additional custom validators:
+In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support four additional custom validators:
 * `type: Foo` - fails unless the provided value `.is_a?(Foo)`
   * Edge case: use `type: :boolean` to handle a boolean field (since ruby doesn't have a Boolean class to pass in directly)
   * Edge case: use `type: :uuid` to handle a confirming given string is a UUID (with or without `-` chars)
+  * Edge case: use `type: :params` to accept either a Hash or ActionController::Parameters (Rails-compatible)
 * `validate: [callable]` - Support custom validations (fails if any string is returned OR if it raises an exception)
   * Example:
     ```ruby
     expects :foo, validate: ->(value) { "must be pretty big" unless value > 10 }
     ```
-* `model: true` (or `model: TheModelClass`) - allows auto-hydrating a record when only given its ID
+* `model: true` (or `model: TheModelClass` or `model: { klass: TheModelClass, finder: :find }`) - allows auto-hydrating a record when only given its ID
   * Example:
     ```ruby
-    expects :user_id, model: true
+    expects :user, model: true
+    # or
+    expects :user, model: User
+    # or with custom finder
+    expects :user, model: { klass: User, finder: :find }
     ```
     This line will add expectations that:
-      * `user_id` is provided
-      * `User.find(user_id)` returns a record
+      * `user_id` is provided (automatically derived from field name)
+      * `User.find(user_id)` (or custom finder) returns a record
 
-    And, when used on `expects`, will create two reader methods for you:
-      * `user_id` (normal), _and_
-      * `user` (for the auto-found record)
+    And, when used on `expects`, will create a reader method for you:
+      * `user` (the auto-found record)
 
     ::: info NOTES
-    * The field name must end in `_id`
-    * This was designed for ActiveRecord models, but will work on any class that returns an instance from `find_by(id: <the provided ID>)`
+    * The system automatically looks for `#{field}_id` (e.g., `:user` → `:user_id`)
+    * The `klass` option defaults to the field name classified (e.g., `:user` → `User`)
+    * The `finder` option defaults to `:find` but can be any method that takes an ID directly
+    * This works with any class that has a finder method (e.g., `User.find`, `ApiService.find_by_id`, etc.)
+    * For external APIs, you can pass a `Method` object as the finder
     :::
 
+#### How `optional`, `allow_blank` and `allow_nil` work with validators
+
+When you specify `optional: true`, `allow_blank: true`, or `allow_nil: true` on a field, these options are automatically passed through to **all validators** applied to that field. This means:
+
+- **ActiveModel validations** (like `inclusion`, `length`, etc.) will respect these options
+- **Custom validators** (`type`, `validate`, `model`) will also respect these options
+- **Type validator edge case**: Note passing `allow_blank` is nonsensical for type: :params and type: :boolean
+
+**Recommended approach**: Use `optional: true` instead of `allow_blank: true` for better clarity. The `optional` parameter is equivalent to `allow_blank: true` and makes the intent clearer.
+
+If neither `optional`, `allow_blank` nor `allow_nil` is specified, a default presence validation is automatically added (unless the type is `:boolean` or `:params`, which have their own validation logic as described above).
+
 ### Details specific to `.exposes`
 
 Remember that you'll need [a corresponding `expose` call](/reference/instance#expose) for every variable you declare via `exposes`.
@@ -62,13 +82,14 @@ Remember that you'll need [a corresponding `expose` call](/reference/instance#ex
 
 #### Nested/Subfield expectations
 
-`expects` is for defining the inbound interface. Usually it's enough to declare the top-level fields you receive, but sometimes you want to make expectations about the shape of that data, and/or to define easy accessor methods for deeply nested fields. `expects` supports the `on` option for this (all the normal attributes can be applied as well, _except default, preprocess, and sensitive_):
+`expects` is for defining the inbound interface. Usually it's enough to declare the top-level fields you receive, but sometimes you want to make expectations about the shape of that data, and/or to define easy accessor methods for deeply nested fields. `expects` supports the `on` option for this (all the normal attributes can be applied as well):
 
 ```ruby
 class Foo
   expects :event
   expects :data, type: Hash, on: :event  # [!code focus:2]
   expects :some, :random, :fields, on: :data
+  expects :optional_field, on: :data, default: "default value"  # [!code focus]
 
   def call
     puts "THe event.data.random field's value is: #{random}"
@@ -76,8 +97,12 @@ class Foo
 end
 ```
 
+::: tip Subfield Defaults
+Defaults work the same way for subfields as they do for top-level fields - they are applied when the subfield is missing or explicitly `nil`, but not for blank values.
+:::
+
 #### `preprocess`
-`expects` also supports a `preprocess` option that, if set to a callable, will be executed _before_ applying any validations.  This can be useful for type coercion, e.g.:
+`expects` also supports a `preprocess` option that, if set to a callable, will be executed _before_ applying any defaults or validations.  This can be useful for type coercion, e.g.:
 
 ```ruby
 expects :date, type: Date, preprocess: ->(d) { d.is_a?(Date) ? d : Date.parse(d) }
@@ -124,46 +149,74 @@ def build_error_message(exception:)
 end
 ```
 
-::: warning Message Ordering
-**Important**: Static success/error messages (those without conditions) should be defined **first** in your action class. If you define conditional messages before static ones, the conditional messages will never be reached because the static message will always match first.
+## Message Matching Order {#message-matching-order}
+
+::: danger Important: Understanding Handler Evaluation Order
+Message handlers are stored in **last-defined-first** order and evaluated in that order until a match is found. This has critical implications for how you structure your message declarations.
+:::
+
+### How It Works
+
+1. Handlers are registered in reverse definition order (last defined = first evaluated)
+2. The system evaluates handlers one by one until finding one that matches
+3. Static handlers (no `if:` or `unless:` condition) **always match**
+4. Once a match is found, evaluation stops
+
+### Correct Pattern: Static Fallbacks First
+
+Because static handlers always match, they must be defined **first** (so they're evaluated **last**):
 
-**Correct order:**
 ```ruby
 class MyAction
-  include Action
+  include Axn
 
-  # Define static fallback first
-  success "Default success message"
-  error "Default error message"
+  # 1. Define static fallback FIRST (evaluated last, catches anything unmatched)
+  error "Something went wrong"
 
-  # Then define conditional messages
-  success "Special success", if: :special_condition?
-  error "Special error", if: ArgumentError
+  # 2. Define conditional handlers AFTER (evaluated first, catch specific cases)
+  error "Invalid input provided", if: ArgumentError
+  error "Record not found", if: ActiveRecord::RecordNotFound
 end
 ```
 
-**Incorrect order (conditional messages will be shadowed):**
+### Incorrect Pattern: Conditional Messages Shadowed
+
+If you define static handlers last, they match first and conditional handlers are never reached:
+
 ```ruby
 class MyAction
-  include Action
+  include Axn
 
-  # These conditional messages will never be reached!
-  success "Special success", if: :special_condition?
-  error "Special error", if: ArgumentError
+  # These will NEVER be reached!
+  error "Invalid input provided", if: ArgumentError
+  error "Record not found", if: ActiveRecord::RecordNotFound
 
-  # Static messages defined last will always match first
-  success "Default success message"
-  error "Default error message"
+  # This static handler is evaluated FIRST and always matches
+  error "Something went wrong"
+end
+```
+
+### With Inheritance
+
+Child class handlers are evaluated before parent class handlers:
+
+```ruby
+class ParentAction
+  include Axn
+  error "Parent error"  # Evaluated last
+end
+
+class ChildAction < ParentAction
+  error "Child error"   # Evaluated first
 end
 ```
-:::
 
 ## Conditional messages
 
 While `.error` and `.success` set the default messages, you can register conditional messages using an optional `if:` or `unless:` matcher. The matcher can be:
 
 - an exception class (e.g., `ArgumentError`)
-- a class name string (e.g., `"Action::InboundValidationError"`)
+- a class name string (e.g., `"Axn::InboundValidationError"`)
 - a symbol referencing a local instance method predicate (arity 0 or 1, or keyword `exception:`), e.g. `:bad_input?`
 - a callable (arity 0 or 1, or keyword `exception:`)
 
@@ -226,9 +279,13 @@ The `from:` parameter allows you to customize error messages when an action call
 
 When using `from:`, the error handler receives the exception from the child action, and you can access the child's error message via `e.message` (which contains the `result.error` from the child action).
 
+### Basic usage
+
+You can use `from:` with a single child action class. The prefix and custom handler are optional:
+
 ```ruby
 class InnerAction
-  include Action
+  include Axn
 
   error "Something went wrong in the inner action"
 
@@ -238,9 +295,12 @@ class InnerAction
 end
 
 class OuterAction
-  include Action
+  include Axn
+
+  # Simply inherit child's error message (no prefix or custom handler needed)
+  error from: InnerAction
 
-  # Customize error messages from InnerAction
+  # Or customize the message
   error from: InnerAction do |e|
     "Outer action failed: #{e.message}"
   end
@@ -254,7 +314,58 @@ end
 In this example:
 - When `InnerAction` fails, `OuterAction` will catch the exception
 - The `e.message` contains the error message from `InnerAction`'s result
-- The final error message will be "Outer action failed: Something went wrong in the inner action"
+- With no handler: the error message will be "Something went wrong in the inner action" (inherited directly)
+- With custom handler: the error message will be "Outer action failed: Something went wrong in the inner action"
+
+### Matching multiple child actions
+
+You can pass an array of child action classes to match multiple children:
+
+```ruby
+class OuterAction
+  include Axn
+
+  # Match errors from multiple child actions
+  error from: [FirstChildAction, SecondChildAction]
+
+  # Or with custom handler
+  error from: [FirstChildAction, SecondChildAction] do |e|
+    "Parent caught: #{e.message}"
+  end
+
+  def call
+    # Calls one of the child actions
+  end
+end
+```
+
+You can also mix class references and string class names:
+
+```ruby
+error from: [FirstChildAction, "SecondChildAction"]
+```
+
+### Matching any child action
+
+Use `from: true` to match errors from any child action without listing them explicitly:
+
+```ruby
+class OuterAction
+  include Axn
+
+  # Match errors from any child action
+  error from: true
+
+  # Or with custom handler
+  error from: true do |e|
+    "Any child failed: #{e.message}"
+  end
+
+  def call
+    # Can call any child action
+  end
+end
+```
 
 This pattern is especially useful for:
 - Adding context to error messages from sub-actions
@@ -267,7 +378,7 @@ You can also combine the `from:` parameter with the `prefix:` keyword to create
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
 
   # Add prefix to error messages from InnerAction
   error from: InnerAction, prefix: "API Error: " do |e|
@@ -287,45 +398,95 @@ This results in:
 - With custom message: "API Error: Request failed: Something went wrong in the inner action"
 - With prefix only: "API Error: Something went wrong in the inner action"
 
-### Message ordering and inheritance
+### Message ordering with `from:`
 
-Messages are evaluated in **last-defined-first** order, meaning the most recently defined message that matches its conditions will be used. This applies to both success and error messages:
+When using `from:` with inheritance, the same [message matching order](#message-matching-order) applies. Define your `from:` handlers after your static fallback:
 
 ```ruby
-class ParentAction
-  include Action
+class OuterAction
+  include Axn
 
-  success "Parent success message"
-  error "Parent error message"
-end
+  # Static fallback first
+  error "Something went wrong"
 
-class ChildAction < ParentAction
-  success "Child success message"  # This will be used when action succeeds
-  error "Child error message"      # This will be used when action fails
+  # Then from: handlers for specific child actions
+  error from: InnerAction, prefix: "Inner failed: "
+  error from: AnotherAction, prefix: "Another failed: "
 end
 ```
 
-Within a single class, later definitions override earlier ones:
+## `.async`
+
+Configures the async execution behavior for the action. This determines how the action will be executed when `call_async` is called.
 
 ```ruby
 class MyAction
-  include Action
+  include Axn
+
+  # Configure Sidekiq
+  async :sidekiq do
+    sidekiq_options queue: "high_priority", retry: 5, priority: 10
+  end
 
-  success "First success message"           # Ignored
-  success "Second success message"          # Ignored
-  success "Final success message"           # This will be used
+  # Or use keyword arguments (shorthand)
+  async :sidekiq, queue: "high_priority", retry: 5
+
+  # Configure ActiveJob
+  async :active_job do
+    queue_as "data_processing"
+    self.priority = 10
+    self.wait = 5.minutes
+  end
 
-  error "First error message"               # Ignored
-  error "Second error message"              # Ignored
-  error "Final error message"               # This will be used
+  # Disable async execution
+  async false
+
+  expects :input
+
+  def call
+    # Action logic here
+  end
 end
 ```
 
-::: tip Message Evaluation Order
-The system evaluates handlers in the order they were defined until it finds one that matches and doesn't raise an exception. If a handler raises an exception, it falls back to the next matching handler, then to static messages, and finally to the default message.
+### Available Adapters
 
-**Key point**: Static messages (without conditions) are evaluated **first** in the order they were defined. This means you should define your static fallback messages at the top of your class, before any conditional messages, to ensure proper fallback behavior.
-:::
+**`:sidekiq`** - Integrates with Sidekiq background job processing
+- Supports all Sidekiq configuration options via `sidekiq_options`
+- Supports keyword argument shorthand for common options (`queue`, `retry`, `priority`)
+
+**`:active_job`** - Integrates with Rails' ActiveJob framework
+- Supports all ActiveJob configuration options
+- Works with any ActiveJob backend (Sidekiq, Delayed Job, etc.)
+
+**`false`** - Disables async execution
+- `call_async` will raise a `NotImplementedError`
+
+### Inheritance
+
+Async configuration is inherited from parent classes. Child classes can override the parent's configuration:
+
+```ruby
+class ParentAction
+  include Axn
+
+  async :sidekiq do
+    sidekiq_options queue: "parent_queue"
+  end
+end
+
+class ChildAction < ParentAction
+  # Inherits parent's Sidekiq configuration
+  # Can override with its own configuration
+  async :active_job do
+    queue_as "child_queue"
+  end
+end
+```
+
+### Default Configuration
+
+If no async configuration is specified, the action will use the default configuration set via `Axn.config.set_default_async`. If no default is set, async execution is disabled.
 
 ## Callbacks
 
@@ -371,7 +532,7 @@ Much like the [globally-configured on_exception hook](/reference/configuration#o
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   on_exception do |exception| # [!code focus:3]
     # e.g. trigger a slack error
@@ -383,7 +544,7 @@ Note that by default the `on_exception` block will be applied to _any_ `Standard
 
 ```ruby
 class Foo
-  include Action
+  include Axn
 
   on_exception(if: NoMethodError) do |exception| # [!code focus]
     # e.g. trigger a slack error