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

data/docs/recipes/formatting-context-for-error-tracking.md

@@ -0,0 +1,186 @@
+# Formatting Context for Error Tracking Systems
+
+The `context` hash passed to the global `on_exception` handler may contain complex objects (like ActiveRecord models, `ActionController::Parameters`, or `Axn::FormObject` instances) that aren't easily serialized by error tracking systems. You can format these values to make them more readable.
+
+## Basic Example
+
+```ruby
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    formatted_context = format_hash_values(context)
+
+    Honeybadger.notify(e, context: { axn_context: formatted_context })
+  end
+end
+
+def format_hash_values(hash)
+  hash.transform_values do |v|
+    if v.respond_to?(:to_global_id)
+      v.to_global_id.to_s
+    elsif v.is_a?(ActionController::Parameters)
+      v.to_unsafe_h
+    elsif v.is_a?(Axn::FormObject)
+      v.to_h
+    else
+      v
+    end
+  end
+end
+```
+
+## What This Converts
+
+- **ActiveRecord objects** → Their global ID string (via `to_global_id`)
+- **`ActionController::Parameters`** → A plain hash
+- **`Axn::FormObject` instances** → Their hash representation
+- **Other values** → Remain unchanged
+
+This ensures that your error tracking system receives serializable, readable context data instead of complex objects that may not serialize properly.
+
+## Recursive Formatting
+
+If your context contains nested hashes with complex objects, you may want to recursively format the entire structure:
+
+```ruby
+def format_hash_values(hash)
+  hash.transform_values do |v|
+    case v
+    when Hash
+      format_hash_values(v)
+    when Array
+      v.map { |item| item.is_a?(Hash) ? format_hash_values(item) : format_value(item) }
+    else
+      format_value(v)
+    end
+  end
+end
+
+def format_value(v)
+  if v.respond_to?(:to_global_id)
+    v.to_global_id.to_s
+  elsif v.is_a?(ActionController::Parameters)
+    v.to_unsafe_h
+  elsif v.is_a?(Axn::FormObject)
+    v.to_h
+  else
+    v
+  end
+end
+```
+
+## Advanced Example: Production Implementation
+
+Here's a comprehensive example that includes additional context, a retry command generator, and proper handling of ActiveRecord models:
+
+```ruby
+Axn.configure do |c|
+  def format_hash_values(hash)
+    hash.transform_values do |v|
+      if v.respond_to?(:to_global_id)
+        v.to_global_id.to_s
+      elsif v.is_a?(ActionController::Parameters)
+        v.to_unsafe_h
+      elsif v.is_a?(Axn::FormObject)
+        v.to_h
+      else
+        v
+      end
+    end
+  end
+
+  # Format values for retry commands - produces copy-pasteable Ruby code
+  def format_value_for_retry_command(value)
+    # Handle ActiveRecord model instances
+    if value.respond_to?(:to_global_id) && value.respond_to?(:id) && !value.is_a?(Class)
+      begin
+        model_class = value.class.name
+        id = value.id
+        return "#{model_class}.find(#{id.inspect})"
+      rescue StandardError
+        # If accessing id fails, fall through to default behavior
+      end
+    end
+
+    # Handle GlobalID strings (useful for serialized values)
+    if value.is_a?(String) && value.start_with?("gid://")
+      begin
+        gid = GlobalID.parse(value)
+        if gid
+          model_class = gid.model_class.name
+          id = gid.model_id
+          return "#{model_class}.find(#{id.inspect})"
+        end
+      rescue StandardError
+        # If parsing fails, fall through to default behavior
+      end
+    end
+
+    # Default: use inspect for other types
+    value.inspect
+  end
+
+  def retry_command(action:, context:)
+    action_name = action.class.name
+    return nil if action_name.nil?
+
+    expected_fields = action.internal_field_configs.map(&:field)
+
+    return "#{action_name}.call()" if expected_fields.empty?
+
+    args = expected_fields.map do |field|
+      value = context[field]
+      "#{field}: #{format_value_for_retry_command(value)}"
+    end.join(", ")
+
+    "#{action_name}.call(#{args})"
+  end
+
+  c.on_exception = proc do |e, action:, context:|
+    axn_name = action.class.name || "AnonymousClass"
+    message = "[#{axn_name}] Raised #{e.class.name}: #{e.message}"
+
+    hb_context = {
+      axn: axn_name,
+      axn_context: format_hash_values(context),
+      current_attributes: format_hash_values(Current.attributes),
+      retry_command: retry_command(action:, context:),
+      exception: e,
+    }
+
+    fingerprint = [axn_name, e.class.name, e.message].join(" - ")
+    Honeybadger.notify(message, context: hb_context, backtrace: e.backtrace, fingerprint:)
+  rescue StandardError => rep
+    Rails.logger.warn "!! Axn failed to report action failure to honeybadger!\nOriginal exception: #{e}\nReporting exception: #{rep}"
+  end
+end
+```
+
+This example includes:
+
+- **Formatted context**: Uses `format_hash_values` to serialize complex objects for readable error tracking
+- **Smart retry commands**: Generates copy-pasteable Ruby code, converting ActiveRecord models to `Model.find(id)` calls instead of raw inspect output
+- **GlobalID support**: Handles both live model instances and serialized GlobalID strings
+- **Additional context**: Includes `Current.attributes` (if using a Current pattern) for request-level context
+- **Error fingerprinting**: Creates a fingerprint from action name, exception class, and message to group similar errors
+- **Error handling**: Wraps the Honeybadger notification in a rescue block to prevent reporting failures from masking the original exception
+
+### Example Output
+
+For an action like:
+
+```ruby
+class UpdateUser
+  include Axn
+  expects :user, model: User
+  expects :name, type: String
+end
+```
+
+The retry command would generate:
+
+```ruby
+UpdateUser.call(user: User.find(123), name: "Alice")
+```
+
+This can be copied directly from your error tracking system and pasted into a Rails console to reproduce the error.
+

data/docs/recipes/memoization.md

@@ -1,46 +1,131 @@
-### Adding memoization
+# Memoization
 
-For a practical example of [the `additional_includes` configuration](/reference/configuration#additional-includes) in practice, consider adding new functionality to all Actions.
+Axn has built-in memoization support via the `memo` helper. This caches the result of method calls, ensuring they're only computed once per action execution.
 
-For instance, at Teamshares we automatically add memoization support (via [memo_wise](https://github.com/panorama-ed/memo_wise)) to all Actions.  But we didn't want to add another dependency to the core library, so we've implemented this by:
+## Basic Usage
 
+The `memo` helper works out of the box for methods without arguments:
 
 ```ruby
-  Axn.configure do |c|
-    c.additional_includes = [TS::Memoization]
+class GenerateReport
+  include Axn
+
+  expects :company, model: Company
+  exposes :report
+
+  def call
+    expose report: {
+      total_revenue: total_revenue,
+      top_products: top_products.map(&:name),
+      # top_products is only queried once, even though it's called twice
+      product_count: top_products.count
+    }
+  end
+
+  private
+
+  memo def top_products
+    company.products.order(sales_count: :desc).limit(10)
+  end
+
+  memo def total_revenue
+    company.orders.sum(:total)
   end
+end
 ```
 
+## How It Works
+
+- `memo` wraps the method and caches its return value on first call
+- Subsequent calls return the cached value without re-executing the method
+- Memoization is scoped to the action instance, so each `call` starts fresh
+
+## Methods With Arguments
+
+For methods that accept arguments, Axn supports the `memo_wise` gem:
+
+```ruby
+# Gemfile
+gem "memo_wise"
+```
+
+With `memo_wise` available, you can automatically memoize methods with arguments:
+
 ```ruby
-module TS::Memoization
-  extend ActiveSupport::Concern
+class CalculatePricing
+  include Axn
+
+  expects :product
+  exposes :pricing
 
-  included do
-    prepend MemoWise
+  def call
+    expose pricing: {
+      retail: price_for(:retail),
+      wholesale: price_for(:wholesale),
+      # Each unique argument is cached separately
+      bulk: price_for(:bulk)
+    }
   end
 
-  class_methods do
-    def memo(...) = memo_wise(...)
+  private
+
+  memo def price_for(tier)
+    # Complex pricing calculation...
+    PricingEngine.calculate(product, tier:)
   end
 end
 ```
 
-And with those pieces in place `memo` is available in all Actions:
+If you try to use `memo` on a method with arguments without `memo_wise` installed, you'll get a helpful error:
+
+```
+ArgumentError: Memoization of methods with arguments requires the 'memo_wise' gem.
+Please add 'memo_wise' to your Gemfile or use a method without arguments.
+```
+
+## When to Use Memoization
+
+Memoization is particularly useful for:
+
+- **Database queries** called multiple times within an action
+- **API calls** or external service lookups
+- **Complex computations** that are expensive to repeat
 
 ```ruby
-class ContrivedExample
+class SyncUserData
   include Axn
 
-  exposes :nums
+  expects :user, model: User
 
   def call
-    expose nums: Array.new(10) { random_number }
+    update_profile if needs_profile_update?
+    update_preferences if needs_preferences_update?
+    notify_if_changed
   end
 
   private
 
-  memo def random_number = rand(1..100) # [!code focus]
+  # Called multiple times - only fetches once
+  memo def external_data
+    ExternalApi.fetch_user_data(user.external_id)
+  end
+
+  def needs_profile_update?
+    external_data[:profile_version] > user.profile_version
+  end
+
+  def needs_preferences_update?
+    external_data[:preferences_hash] != user.preferences_hash
+  end
+
+  def notify_if_changed
+    # ...
+  end
 end
 ```
 
-Because of the `memo` usage, `ContrivedExample.call.nums` will be a ten-element array of _the same number_, rather than re-calling `rand` for each element.
+## Notes
+
+- Memoization persists only for the duration of a single action execution
+- When `memo_wise` is available, Axn automatically uses it (no configuration needed)
+- See the [memo_wise documentation](https://github.com/panorama-ed/memo_wise) for advanced features like cache resetting

data/docs/reference/async.md

@@ -158,3 +158,272 @@ end
 # The job will be retried up to 3 times before giving up
 FailingAction.call_async(data: "test")
 ```
+
+## Batch Enqueueing with `enqueues_each`
+
+The `enqueues_each` method provides a declarative way to set up batch enqueueing. It automatically iterates over collections and enqueues each item as a separate background job.
+
+### Basic Usage
+
+```ruby
+class SyncForCompany
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company
+
+  def call
+    puts "Syncing data for company: #{company.name}"
+    # Sync individual company data
+  end
+
+  # No enqueues_each needed! Source is auto-inferred from model: Company
+end
+
+# Usage
+SyncForCompany.enqueue_all  # Automatically iterates Company.all and enqueues each company
+```
+
+**How it works:**
+1. `enqueue_all` validates configuration upfront (async configured, static args present)
+2. If all arguments are serializable, enqueues an `EnqueueAllOrchestrator` job in the background
+3. If any argument is unserializable (e.g., an AR relation override), executes in the foreground instead
+4. During execution, iterates over the source collection and enqueues individual jobs
+5. Model-based iterations (using `find_each`) are processed first for memory efficiency
+
+### Auto-Inference from `model:` Declarations
+
+If a field has a `model:` declaration and the model class responds to `find_each`, you **don't need to explicitly declare `enqueues_each`**. The source collection is automatically inferred:
+
+```ruby
+class SyncForCompany
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company  # Auto-inferred: Company.all
+
+  def call
+    # ... sync logic
+  end
+
+  # No enqueues_each needed - automatically iterates Company.all
+end
+
+SyncForCompany.enqueue_all  # Works without explicit enqueues_each!
+```
+
+### Explicit Configuration with `enqueues_each`
+
+Use `enqueues_each` when you need to:
+- Override the default source (e.g., `Company.active` instead of `Company.all`)
+- Add filtering logic
+- Extract specific attributes
+- Iterate over fields without `model:` declarations
+
+```ruby
+class SyncForCompany
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company
+
+  def call
+    # ... sync logic
+  end
+
+  # Override default source
+  enqueues_each :company, from: -> { Company.active }
+
+  # With extraction (passes company_id instead of company object)
+  enqueues_each :company_id, from: -> { Company.active }, via: :id
+
+  # With filter block
+  enqueues_each :company do |company|
+    company.active? && !company.in_exit?
+  end
+
+  # Method name as source
+  enqueues_each :company, from: :active_companies
+end
+```
+
+### Overriding on `enqueue_all` Call
+
+You can override iteration sources or make fields static when calling `enqueue_all`:
+
+```ruby
+class SyncForCompany
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company
+  expects :user, model: User
+
+  def call
+    # ... sync logic
+  end
+
+  # Default: iterates Company.all
+  enqueues_each :company
+end
+
+# Override with a subset (enumerable kwarg replaces source)
+SyncForCompany.enqueue_all(company: Company.active.limit(10))
+
+# Override with a single value (scalar kwarg makes it static, no iteration)
+SyncForCompany.enqueue_all(company: Company.find(123))
+
+# Mix static and iterated fields
+SyncForCompany.enqueue_all(
+  company: Company.active,  # Iterates over active companies
+  user: User.find(1)        # Static: same user for all jobs
+)
+```
+
+### Dynamic Iteration via Kwargs
+
+You can iterate over fields without any `enqueues_each` declaration by passing enumerables directly:
+
+```ruby
+class ProcessFormats
+  include Axn
+  async :sidekiq
+
+  expects :format
+  expects :mode
+
+  def call
+    # ... process logic
+  end
+end
+
+# Pass enumerables to create cross-product iteration
+ProcessFormats.enqueue_all(
+  format: [:csv, :json, :xml],  # Iterates: 3 jobs
+  mode: :full                    # Static: same mode for all
+)
+
+# Multiple enumerables create cross-product
+ProcessFormats.enqueue_all(
+  format: [:csv, :json],         # 2 formats
+  mode: [:full, :incremental]    # 2 modes
+)
+# Result: 2 × 2 = 4 jobs total
+```
+
+**Note:** Arrays and Sets are treated as static values (not iterated) when the field expects an enumerable type:
+
+```ruby
+expects :tags, type: Array
+
+# This passes the entire array as a static value
+ProcessTags.enqueue_all(tags: ["ruby", "rails", "testing"])
+```
+
+### Multi-Field Cross-Product Iteration
+
+Multiple `enqueues_each` declarations create a cross-product of all combinations:
+
+```ruby
+class SyncForUserAndCompany
+  include Axn
+  async :sidekiq
+
+  expects :user, model: User
+  expects :company, model: Company
+
+  def call
+    # ... sync logic for user + company combination
+  end
+
+  enqueues_each :user, from: -> { User.active }
+  enqueues_each :company, from: -> { Company.active }
+end
+
+# Creates user_count × company_count jobs
+# Each combination of (user, company) gets its own job
+SyncForUserAndCompany.enqueue_all
+```
+
+### Static Fields
+
+Fields declared with `expects` but not covered by `enqueues_each` (or auto-inference) become static fields that must be passed to `enqueue_all`:
+
+```ruby
+class SyncWithMode
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company  # Auto-inferred, will iterate
+  expects :sync_mode                 # Static, must be provided
+
+  def call
+    # Uses both company (iterated) and sync_mode (static)
+  end
+end
+
+# sync_mode must be provided - it's passed to every enqueued job
+SyncWithMode.enqueue_all(sync_mode: :full)
+```
+
+### Memory Efficiency
+
+For optimal memory usage, model-based configs (using `find_each`) are automatically processed first in nested iterations. This ensures ActiveRecord-style batch processing happens before loading potentially large enumerables into memory.
+
+```ruby
+# Model-based iteration uses find_each (memory efficient)
+expects :company, model: Company  # Processed first
+
+# Array-based iteration uses each (loads all into memory)
+enqueues_each :format, from: -> { [:csv, :json, :xml] }  # Processed second
+```
+
+### Iteration Method Selection
+
+- **`find_each`**: Used when the source responds to `find_each` (ActiveRecord collections) - processes in batches for memory efficiency
+- **`each`**: Used for plain arrays and other enumerables - loads all items into memory
+
+### Background vs Foreground Execution
+
+By default, `enqueue_all` enqueues an `EnqueueAllOrchestrator` job to perform the iteration and individual job enqueueing in the background. This makes it safe to call directly from clock processes (e.g., Heroku scheduler) without risking memory bloat from loading large collections.
+
+However, if you pass an **enumerable override** (like an ActiveRecord relation or array), `enqueue_all` automatically falls back to foreground execution—iterating and enqueueing immediately in the current process. This is because the iteration source (a lambda wrapping the enumerable) cannot be serialized for background execution.
+
+```ruby
+class SyncForCompany
+  include Axn
+  async :sidekiq
+
+  expects :company, model: Company
+
+  def call
+    # ... sync logic
+  end
+
+  enqueues_each :company, from: -> { Company.active }
+end
+
+# Default: enqueues orchestrator job in background (safe for clock processes)
+SyncForCompany.enqueue_all
+
+# Override with a relation: executes in foreground (relation can't be serialized)
+SyncForCompany.enqueue_all(company: Company.where(plan: "enterprise"))
+
+# Override with a single value: runs in background (GlobalID-serializable scalar)
+SyncForCompany.enqueue_all(company: Company.find(123))
+```
+
+**Why this matters:**
+- Configure your default iteration source via `enqueues_each` for scheduled/recurring jobs
+- By default, `enqueue_all` runs safely in the background without loading your entire dataset into memory
+- For one-off manual calls with a filtered subset, pass an enumerable override—foreground execution handles it automatically
+- Scalar overrides (single objects) are serialized via GlobalID and still run in the background
+
+This design lets you use the same action class for both scheduled batch processing and ad-hoc targeted runs.
+
+### Edge Cases and Limitations
+
+1. **Fields expecting enumerable types**: If a field expects `Array` or `Set`, arrays/sets passed to `enqueue_all` are treated as static values (not iterated)
+2. **Strings and Hashes**: Always treated as static values, even though they respond to `:each`
+3. **No model or source**: If a field has no `model:` declaration and no `enqueues_each` with `from:`, you must pass it as a kwarg to `enqueue_all` or it will raise an error
+4. **Required static fields**: Fields without defaults that aren't covered by iteration must be provided to `enqueue_all`