axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.3

data/docs/recipes/rubocop-integration.md

@@ -1,12 +1,16 @@
 # RuboCop Integration
 
-Axn provides custom RuboCop cops to help enforce best practices and maintain code quality in your Action-based codebase.
+Axn provides a custom RuboCop cop to help enforce proper result handling when calling Actions.
 
-## Overview
+## What It Does
 
-The `Axn/UncheckedResult` cop enforces proper result handling when calling Actions. It can detect when Action results are ignored and help ensure consistent error handling patterns.
+The `Axn/UncheckedResult` cop detects when you call another Action from within an Action but don't properly handle the result. This helps prevent silent failures and ensures consistent error handling patterns.
 
-## Installation
+> **⚠️ Warning**: This cop uses static analysis and cannot distinguish between actual Axn classes and other classes that happen to have a `call` method. If you're using legacy services or other service patterns alongside Axn, you may encounter false positives. Use RuboCop disable comments for intentional violations.
+>
+> **💡 Tip**: If you're using the Actions namespace (see [Rails Integration](/usage/setup#rails-integration-optional)), you can configure the cop to only check `Actions::*` classes, eliminating false positives from other service objects.
+
+## Setup
 
 ### 1. Add to Your .rubocop.yml
 
@@ -14,137 +18,37 @@ The `Axn/UncheckedResult` cop enforces proper result handling when calling Actio
 require:
   - axn/rubocop
 
-# Enable Axn's custom cop
 Axn/UncheckedResult:
   Enabled: true
-  CheckNested: true      # Check nested Action calls
-  CheckNonNested: true   # Check non-nested Action calls
-  Severity: warning      # or error
+  Severity: warning
 ```
 
 ### 2. Verify Installation
 
-Run RuboCop to ensure the cop is loaded:
-
 ```bash
 bundle exec rubocop --show-cops | grep Axn
 ```
 
-You should see:
-```
-Axn/UncheckedResult
-```
-
-## Configuration Options
-
-### CheckNested
-
-Controls whether the cop checks Action calls that are inside other Action classes.
-
-```yaml
-Axn/UncheckedResult:
-  CheckNested: true   # Check nested calls (default)
-  CheckNested: false  # Skip nested calls
-```
-
-**When to use `CheckNested: false`:**
-- You're gradually adopting the rule and want to focus on top-level calls first
-- Your team has different standards for nested vs. non-nested calls
-- You're using a different pattern for nested Action handling
-
-### CheckNonNested
-
-Controls whether the cop checks Action calls that are outside Action classes.
-
-```yaml
-Axn/UncheckedResult:
-  CheckNonNested: true   # Check non-nested calls (default)
-  CheckNonNested: false  # Skip non-nested calls
-```
-
-**When to use `CheckNonNested: false`:**
-- You're only concerned about nested Action calls
-- Top-level Action calls are handled by other tools or processes
-- You want to focus on the most critical use case first
-
-### Severity
-
-Controls how violations are reported.
-
-```yaml
-Axn/UncheckedResult:
-  Severity: warning  # Show as warnings (default)
-  Severity: error    # Show as errors (fails CI)
-```
-
-## Common Configuration Patterns
+You should see `Axn/UncheckedResult` in the output.
 
-### Full Enforcement (Recommended for New Projects)
+## Basic Usage
 
-```yaml
-Axn/UncheckedResult:
-  Enabled: true
-  CheckNested: true
-  CheckNonNested: true
-  Severity: error
-```
-
-### Gradual Adoption (Recommended for Existing Projects)
-
-```yaml
-Axn/UncheckedResult:
-  Enabled: true
-  CheckNested: true      # Start with nested calls
-  CheckNonNested: false  # Add this later
-  Severity: warning      # Start with warnings
-```
-
-### Nested-Only Focus
-
-```yaml
-Axn/UncheckedResult:
-  Enabled: true
-  CheckNested: true
-  CheckNonNested: false
-  Severity: warning
-```
-
-## What the Cop Checks
-
-The cop analyzes your code to determine if you're:
-
-1. **Inside an Action class** - Classes that `include Action`
-2. **Inside the `call` method** - Only the main execution method
-3. **Calling another Action** - Using `.call` on Action classes
-4. **Properly handling the result** - One of the acceptable patterns
-
-## What the Cop Ignores
-
-The cop will NOT report offenses for:
-
-- Action calls outside of Action classes (if `CheckNonNested: false`)
-- Action calls in methods other than `call`
-- Action calls that use `call!` (bang method)
-- Action calls where the result is properly handled
-
-## Proper Result Handling Patterns
-
-### ✅ Using call!
+### ✅ Good - Using call!
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     InnerAction.call!(param: "value")  # Exceptions bubble up
   end
 end
 ```
 
-### ✅ Checking result.ok?
+### ✅ Good - Checking the result
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     return result unless result.ok?
@@ -153,200 +57,50 @@ class OuterAction
 end
 ```
 
-### ✅ Checking result.failed?
-
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")
-    if result.failed?
-      return result
-    end
-    # Process successful result...
-  end
-end
-```
-
-### ✅ Accessing result.error
-
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")
-    if result.error
-      return result
-    end
-    # Process successful result...
-  end
-end
-```
-
-### ✅ Returning the result
-
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")
-    result  # Result is returned, so it's properly handled
-  end
-end
-```
-
-### ✅ Using result in expose
-
-```ruby
-class OuterAction
-  include Action
-  exposes :nested_result
-  def call
-    result = InnerAction.call(param: "value")
-    expose nested_result: result  # Result is used, so it's properly handled
-  end
-end
-```
-
-### ✅ Passing result to another method
-
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")
-    process_result(result)  # Result is used, so it's properly handled
-  end
-end
-```
-
-## Common Anti-Patterns
-
-### ❌ Ignoring the result
+### ❌ Bad - Ignoring the result
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
-    InnerAction.call(param: "value")  # Result ignored - will trigger offense
+    InnerAction.call(param: "value")  # Will trigger offense
     # This continues even if InnerAction fails
   end
 end
 ```
 
-### ❌ Assigning but not using
+## Configuration
 
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")  # Assigned but never used
-    # Will trigger offense unless result is properly handled
-  end
-end
-```
+The cop supports flexible configuration:
 
-### ❌ Using unrelated attributes
-
-```ruby
-class OuterAction
-  include Action
-  def call
-    result = InnerAction.call(param: "value")
-    some_other_method(result.some_other_attribute)  # Not checking success/failure
-    # Will trigger offense - need to check result.ok? first
-  end
-end
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Check nested Axn calls (default: true)
+  CheckNonNested: true   # Check non-nested Axn calls (default: true)
+  ActionsNamespace: "Actions"  # Only check Actions::* classes (optional)
+  Severity: warning      # or error
 ```
 
-## Migration Strategies
-
-### For New Projects
-
-1. Enable the cop with full enforcement from the start
-2. Use `Severity: error` to catch violations early
-3. Train your team on the proper patterns
-
-### For Existing Projects
+### ActionsNamespace Configuration
 
-1. **Phase 1**: Enable with `CheckNested: true, CheckNonNested: false, Severity: warning`
-2. **Phase 2**: Fix all nested Action violations
-3. **Phase 3**: Enable `CheckNonNested: true`
-4. **Phase 4**: Fix all non-nested Action violations
-5. **Phase 5**: Set `Severity: error`
+When using the Actions namespace, you can configure the cop to only check calls on `Actions::*` classes:
 
-### Using RuboCop Disable Comments
+```yaml
+Axn/UncheckedResult:
+  ActionsNamespace: "Actions"
+```
 
-For intentional violations, you can disable the cop:
+This eliminates false positives from other service objects while still catching unchecked Axn action calls:
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
-    # rubocop:disable Axn/UncheckedResult
-    InnerAction.call(param: "value")  # Intentionally ignored
-    # rubocop:enable Axn/UncheckedResult
+    SomeService.call(param: "value")        # Won't trigger cop
+    Actions::InnerAction.call(param: "value")  # Will trigger cop
   end
 end
 ```
 
-## Troubleshooting
-
-### Cop Not Loading
-
-If you see "uninitialized constant" errors:
-
-1. Ensure the gem is properly installed: `bundle list | grep axn`
-2. Check your `.rubocop.yml` syntax
-3. Verify the require path: `require: - axn/rubocop`
-
-### False Positives
-
-If the cop reports violations for properly handled results:
-
-1. Check that you're using the exact patterns shown above
-2. Ensure the result variable name matches exactly
-3. Verify the result is being used in an acceptable way
-
-### Performance Issues
-
-The cop analyzes AST nodes, so it's generally fast. If you experience slowdowns:
-
-1. Ensure you're not running RuboCop on very large files
-2. Consider using RuboCop's `--parallel` option
-3. Use `.rubocop_todo.yml` for gradual adoption
-
-## Best Practices
-
-1. **Start Small**: Begin with warnings and nested calls only
-2. **Be Consistent**: Choose one pattern and stick with it
-3. **Train Your Team**: Make sure everyone understands the rules
-4. **Review Regularly**: Use the cop in your CI/CD pipeline
-5. **Document Exceptions**: Use disable comments sparingly and document why
-
-## Integration with CI/CD
-
-Add RuboCop to your CI pipeline to catch violations early:
-
-```yaml
-# .github/workflows/rubocop.yml
-name: RuboCop
-on: [push, pull_request]
-jobs:
-  rubocop:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.2
-      - run: bundle install
-      - run: bundle exec rubocop
-```
-
-## Related Resources
-
-- [Action Result Reference](/reference/action-result)
-- [Configuration Guide](/reference/configuration)
-- [Testing Recipes](/recipes/testing)
-- [Best Practices Guide](/advanced/conventions)
+For detailed configuration options, usage patterns, and troubleshooting, see the [technical documentation](https://github.com/teamshares/axn/blob/main/lib/rubocop/cop/axn/README.md).

data/docs/recipes/testing.md

@@ -8,23 +8,23 @@
 
 Say you're writing unit specs for PrimaryAction that calls Subaction, and you want to mock out the Subaction call.
 
-To generate a successful Action::Result:
+To generate a successful Axn::Result:
 
-* Base case: `Action::Result.ok`
-* [Optional] Custom message: `Action::Result.ok("It went awesome")`
-* [Optional] Custom exposures: `Action::Result.ok("It went awesome", some_var: 123)`
+* Base case: `Axn::Result.ok`
+* [Optional] Custom message: `Axn::Result.ok("It went awesome")`
+* [Optional] Custom exposures: `Axn::Result.ok("It went awesome", some_var: 123)`
 
-To generate a failed Action::Result:
+To generate a failed Axn::Result:
 
-* Base case: `Action::Result.error`
-* [Optional] Custom message: `Action::Result.error("It went poorly")`
-* [Optional] Custom exposures: `Action::Result.error("It went poorly", some_var: 123)`
-* [Optional] Custom exception: `Action::Result.error(some_var: 123) { raise FooBarException.new("bad thing") }`
+* Base case: `Axn::Result.error`
+* [Optional] Custom message: `Axn::Result.error("It went poorly")`
+* [Optional] Custom exposures: `Axn::Result.error("It went poorly", some_var: 123)`
+* [Optional] Custom exception: `Axn::Result.error(some_var: 123) { raise FooBarException.new("bad thing") }`
 
 Either way, using those to mock an actual call would look something like this in your rspec:
 
 ```ruby
-let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+let(:subaction_response) { Axn::Result.ok("custom message", foo: 1) }
 
 before do
   expect(Subaction).to receive(:call).and_return(subaction_response)
@@ -38,7 +38,7 @@ The semantics of call-bang are a little different -- if Subaction is called via
 ### Success
 
 ```ruby
-let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+let(:subaction_response) { Axn::Result.ok("custom message", foo: 1) }
 
 before do
   expect(Subaction).to receive(:call!).and_return(subaction_response)
@@ -57,18 +57,18 @@ before do
 end
 ```
 
-NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Action::Failure` exception class.
+NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Axn::Failure` exception class.
 
 ## Mocking Axn arguments
 
-Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Action.config.env.test?` is `true`_.
+Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Axn.config.env.test?` is `true`_.
 
 This makes it much easier to test Axns, as you can pass in mocks without immediately failing the inbound validation.
 
 ```ruby
 subject(:result) { action.call!(sym:) }
 
-let(:action) { build_action { expects :sym, type: Symbol } }
+let(:action) { build_axn { expects :sym, type: Symbol } }
 
 context "with a symbol" do
   let(:sym) { :hello }

data/docs/recipes/validating-user-input.md

@@ -1,7 +1,7 @@
 # Validating _user_ input
 
 ::: danger ALPHA
-This has not yet been fully fleshed out.  For now, the general idea is that user-facing validation is a _separate layer_ from the declarative expectations about what inputs your Action takes (e.g. `expects :params` and pass to a form object, rather than accepting field-level params directly).
+This has not yet been fully fleshed out.  For now, the general idea is that user-facing validation is a _separate layer_ from the declarative expectations about what inputs your Axn takes (e.g. `expects :params` and pass to a form object, rather than accepting field-level params directly).
 :::
 
 

data/docs/reference/async.md

@@ -0,0 +1,160 @@
+# Async Execution
+
+Axn provides built-in support for asynchronous execution through background job processing libraries. This allows you to execute actions in the background without blocking the main thread.
+
+## Overview
+
+Async execution in Axn is designed to be simple and consistent across different background job libraries. You can configure async behavior globally or per-action, and all async adapters support the same interface.
+
+## Basic Usage
+
+### Configuring Async Adapters
+
+```ruby
+class EmailAction
+  include Axn
+
+  # Configure async adapter
+  async :sidekiq
+
+  expects :user, :message
+
+  def call
+    # Send email logic
+  end
+end
+
+# Execute immediately (synchronous)
+result = EmailAction.call(user: user, message: "Welcome!")
+
+# Execute asynchronously (background)
+EmailAction.call_async(user: user, message: "Welcome!")
+```
+
+### Available Async Adapters
+
+#### Sidekiq
+
+The Sidekiq adapter provides integration with the Sidekiq background job processing library.
+
+```ruby
+# In your action class
+async :sidekiq do
+  sidekiq_options queue: "high_priority", retry: 5, priority: 10
+end
+
+# Or with keyword arguments (shorthand)
+async :sidekiq, queue: "high_priority", retry: 5
+```
+
+**Configuration options:**
+- `queue`: The Sidekiq queue name (default: "default")
+- `retry`: Number of retry attempts (default: 25)
+- `priority`: Job priority (default: 0)
+- Any other Sidekiq options supported by `sidekiq_options`
+
+#### ActiveJob
+
+The ActiveJob adapter provides integration with Rails' ActiveJob framework.
+
+```ruby
+# In your action class
+async :active_job do
+  queue_as "high_priority"
+  self.priority = 10
+  self.wait = 5.minutes
+end
+```
+
+**Configuration options:**
+- `queue_as`: The ActiveJob queue name
+- `priority`: Job priority
+- `wait`: Delay before execution
+- Any other ActiveJob options
+
+#### Disabled
+
+Disables async execution entirely. The action will raise a `NotImplementedError` when `call_async` is called.
+
+```ruby
+# In your action class
+async false
+```
+
+## Delayed Execution
+
+All async adapters support delayed execution using the `_async` parameter in `call_async`. This allows you to schedule actions to run at specific future times without changing the interface.
+
+```ruby
+class EmailAction
+  include Axn
+  async :sidekiq
+
+  expects :user, :message
+
+  def call
+    # Send email logic
+  end
+end
+
+# Immediate execution
+EmailAction.call_async(user: user, message: "Welcome!")
+
+# Delayed execution - wait 1 hour
+EmailAction.call_async(user: user, message: "Follow up", _async: { wait: 1.hour })
+
+# Scheduled execution - run at specific time
+EmailAction.call_async(user: user, message: "Reminder", _async: { wait_until: 1.week.from_now })
+```
+
+### Supported Scheduling Options
+
+- `wait`: Execute after a specific time interval (e.g., `1.hour`, `30.minutes`)
+- `wait_until`: Execute at a specific future time (e.g., `1.hour.from_now`, `Time.parse("2024-01-01 12:00:00")`)
+
+### Adapter-Specific Behavior
+
+- **Sidekiq**: Uses `perform_in` for `wait` and `perform_at` for `wait_until`
+- **ActiveJob**: Uses `set(wait:)` for `wait` and `set(wait_until:)` for `wait_until`
+- **Disabled**: Ignores scheduling options and raises `NotImplementedError`
+
+### Parameter Name Safety
+
+The `_async` parameter is reserved for scheduling options.
+
+## Global Configuration
+
+You can set default async configuration that will be applied to all actions that don't explicitly configure their own async behavior:
+
+```ruby
+Axn.configure do |c|
+  # Set a default async configuration
+  c.set_default_async(:sidekiq, queue: "default") do
+    sidekiq_options retry: 3
+  end
+end
+
+# Now all actions will use Sidekiq by default
+class MyAction
+  include Axn
+  # No async configuration needed - uses default
+end
+```
+
+## Error Handling
+
+Async actions trigger via `call!` internally, so they raise on failure, which means the background job system can seamlessly handle retries.
+
+```ruby
+class FailingAction
+  include Axn
+  async :sidekiq, retry: 3
+
+  def call
+    fail! "Something went wrong"
+  end
+end
+
+# The job will be retried up to 3 times before giving up
+FailingAction.call_async(data: "test")
+```