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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c8aec52fd200af8f2c3a7cd19c9a589c5353bca7bd6ed6ca08dbc990b381af
-  data.tar.gz: 0bae864b6bf77b4f5200f2671bbed65ff8fea1f22fbbaa9985e088d4be82d767
+  metadata.gz: 8930af546a87917b02eb7c4af3fdc88670f6b323cbf9e7223553eca07ac6bf8c
+  data.tar.gz: 47a70ea981ae8c9a7405e02c844174996c0d1a3b9788cbf5c37d725d77f00d5c
 SHA512:
-  metadata.gz: 6fa6cabde451cec1eda5600f29131cbe78b7f0e66742bed84257e83d0b45418fc300452b24147a9bb4f319710c87da02ac541c17312e17993e1ea636c09b52c6
-  data.tar.gz: 4ee9dd287f81d027e0538fa94c959ffca9e560274a7d558196f163e7569f9ea7eae996857c55f5b0453a3a876863fa5b384171d368907c1c1c53ec30f72366ea
+  metadata.gz: 83c3a6d065d240bf73ccca409b40e2a0560901617d98b5fe3f9aaefbf3ef87ab444bdd20220b01ce8481ccea55278240433a0641d9549c63a47329d13e3bb5ce
+  data.tar.gz: adfe79828b95caa34379fe0424b4aa2b9a3ee06247eeb29b10c2b7b9fded83dcf327993e13da84f913e5e2c05ad0b53a77562ffe3c1ad25d814265c526b49a78

data/.cursor/commands/pr.md

@@ -0,0 +1,36 @@
+Create a pull request for the current branch.
+
+## Pre-flight checks
+
+1. Run `git status` to check for uncommitted changes.
+    If there are uncommitted changes, stop and ask the user to commit or stash them first
+2. Run `git branch --show-current` to get the branch name
+    Verify not on main/master - if so, stop and ask the user to create a branch first
+3. Run the test suite (`bundle exec rake all_specs` and `bundle exec rubocop`)
+    If any test suite failures, stop and prompt user to resolve first
+
+## Gather context
+
+4. Run `git log origin/main..HEAD --oneline` to see all commits on this branch
+5. Run `git diff origin/main...HEAD --stat` to see changed files
+6. If needed, read the diff for key files to understand the changes
+
+## Generate PR content
+
+7. Generate a PR title: a single line that summarizes the changes (imperative mood, e.g., "Add batch enqueueing support")
+8. Generate a PR body with:
+   - **Summary**: a handful of bullet points describing the key changes
+   - **Details**: If sufficiently complex, include details of each notable change
+   - **Usage Example**: If applicable, a brief code example demonstrating the new or changed feature/API
+
+## Push and create PR
+
+9. Push the branch: `git push -u origin HEAD`
+10. Create the PR as a draft using gh:
+
+gh pr create --draft --title "THE TITLE" --body "$(cat <<'EOF'
+THE BODY HERE
+EOF
+)"
+
+11. Report the PR URL to the user as a link they can click

data/CHANGELOG.md

@@ -1,7 +1,21 @@
 # Changelog
 
 ## Unreleased
-* N/A
+* [FEAT] Action class constants are now created eagerly when child classes inherit from parents with mounted actions, allowing direct constant access (e.g., `TeamsharesAPI::Company::Axns::Get.call`)
+* [FEAT] Add ability to determine if currently running in background
+* [FEAT] Handle done! and fail! while executing user blocks
+* [BREAKING] `emit_metrics` hook now receives keyword arguments (`resource:`, `result:`) instead of positional arguments
+* [FEAT] Default `call` method automatically exposes declared exposures by calling methods with matching names - you can now omit `call` entirely when you only need to expose values from private methods
+* [BREAKING] Rename `auto_log` -> `log_calls`
+* [FEAT] Add `log_errors`
+* [FEAT] Add `raise_piping_errors_in_dev` config option to raise framework errors in dev only
+* [BREAKING] Convert profiling from `profile` method to `use :vernier` strategy - profiling now only captures hooks and user code (excludes framework overhead like tracing, logging, timing)
+* [FEAT] Add `set_logging_context` and `additional_logging_context` hook to inject additional context into exception logging
+* [FEAT] Added ActiveSupport::Notification emission for `axn.call_async` (separate from `axn.call`) - emits notification when async jobs are enqueued with payload including resource, action_class, kwargs, and adapter name
+* [INTERNAL] Refactored async adapters to use template method pattern - adapters now implement `_enqueue_async_job` hook instead of overriding `call_async`, eliminating duplication of notification and logging logic
+* [FEAT] Enhanced `error from:` to support arrays of child classes and `from: true` to match any child action - prefix is now optional when using `from:`
+* Improve handling of _async options to call_async (bugfix + serialization improvements)
+* [BREAKING] Replace `enqueue_all_via` block with new `enqueues_each` DSL (now in `Axn::Async`) - declarative batch enqueueing for background job processing
 
 ## 0.1.0-alpha.3
 * [FEAT] Added Vernier profiling support with `profile if:` conditional interface and `Axn.config.profiling` configuration

data/Rakefile

@@ -6,8 +6,9 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 # RuboCop specs (separate from main specs to avoid loading RuboCop unnecessarily)
-RSpec::Core::RakeTask.new(:spec_rubocop) do |task|
-  task.pattern = "spec_rubocop/**/*_spec.rb"
+task :spec_rubocop do
+  files = Dir.glob("spec_rubocop/**/*_spec.rb")
+  sh "bundle exec rspec #{files.join(' ')}"
 end
 
 # Rails specs (separate from main specs to avoid loading Rails unnecessarily)
@@ -32,3 +33,102 @@ task rails_specs: %i[spec_rails]
 task rubocop_specs: %i[spec_rubocop]
 task all_specs: %i[spec spec_rubocop spec_rails]
 task specs: %i[all_specs]
+
+# Benchmark tasks
+namespace :benchmark do
+  desc "Run benchmarks and save results for current gem version (runs automatically after rake release)"
+  task :release do
+    require_relative "benchmark/support/benchmark_runner"
+    require_relative "benchmark/support/storage"
+    require_relative "lib/axn/version"
+    require_relative "benchmark/support/colors"
+
+    puts Colors.bold(Colors.info("🔬 Running benchmarks for release..."))
+    puts Colors.dim("=" * 80)
+    puts ""
+
+    version = Axn::VERSION
+    puts Colors.info("Version: #{version}")
+    puts ""
+
+    # Check if benchmark already exists for this version
+    filename = Benchmark::Storage.benchmark_filename(version)
+    if File.exist?(filename)
+      puts Colors.error("❌ Benchmark file already exists for version #{version}")
+      puts Colors.info("   File: #{filename}")
+      puts Colors.info("   Delete the file if you want to regenerate benchmarks for this version.")
+      abort
+    end
+
+    # Run benchmarks with verbose output
+    data = Benchmark::BenchmarkRunner.run_all_scenarios(verbose: true)
+
+    # Save benchmark data (filename already determined above)
+    saved_filename = Benchmark::Storage.save_benchmark(data, version)
+    puts ""
+    puts Colors.success("✅ Benchmark data saved to: #{saved_filename}")
+
+    # Update last release version
+    Benchmark::Storage.set_last_release_version(version)
+    puts Colors.success("✅ Last release version updated to: #{version}")
+    puts ""
+    puts Colors.dim("=" * 80)
+  end
+
+  desc "Compare current code performance against last release"
+  task :compare do
+    require_relative "benchmark/support/benchmark_runner"
+    require_relative "benchmark/support/storage"
+    require_relative "benchmark/support/comparison"
+    require_relative "lib/axn/version"
+    require_relative "benchmark/support/colors"
+
+    puts Colors.bold(Colors.info("🔬 Comparing performance against last release..."))
+    puts Colors.dim("=" * 80)
+    puts ""
+
+    # Get last release version
+    last_release_version = Benchmark::Storage.get_last_release_version
+
+    if last_release_version.nil?
+      puts Colors.error("❌ No last release version found.")
+      puts Colors.info("   Run 'rake benchmark:release' after a gem release to create a baseline.")
+      exit 1
+    end
+
+    puts Colors.info("Last release version: #{last_release_version}")
+    puts ""
+
+    # Load baseline benchmark
+    baseline_data = Benchmark::Storage.load_benchmark(last_release_version)
+
+    if baseline_data.nil?
+      puts Colors.error("❌ Benchmark data not found for version: #{last_release_version}")
+      puts Colors.info("   Run 'rake benchmark:release' to create a baseline.")
+      exit 1
+    end
+
+    puts Colors.info("Running benchmarks on current code...")
+    puts ""
+
+    # Run current benchmarks (quiet mode for cleaner output)
+    current_data = Benchmark::BenchmarkRunner.run_all_scenarios(verbose: false)
+
+    puts ""
+    puts Colors.info("Comparing results...")
+    puts ""
+
+    # Compare and display
+    comparison = Benchmark::Comparison.compare(baseline_data, current_data)
+    puts Benchmark::Comparison.format_comparison(comparison)
+  end
+end
+
+# Automatically run benchmark:release after rake release
+Rake::Task["release"].enhance do
+  require_relative "benchmark/support/colors"
+  puts ""
+  puts Colors.bold(Colors.info("🔬 Running benchmarks for released version..."))
+  Rake::Task["benchmark:release"].reenable
+  Rake::Task["benchmark:release"].invoke
+end

data/docs/.vitepress/config.mjs

@@ -39,6 +39,16 @@ export default defineConfig({
           { text: 'Instance Interface', link: '/reference/instance' },
           { text: 'Result Interface', link: '/reference/axn-result' },
           { text: 'Async', link: '/reference/async' },
+          { text: 'FormObject', link: '/reference/form-object' },
+        ]
+      },
+      {
+        text: 'Strategies',
+        items: [
+          { text: 'Overview', link: '/strategies/index' },
+          { text: 'Transaction', link: '/strategies/transaction' },
+          { text: 'Form', link: '/strategies/form' },
+          { text: 'Client', link: '/strategies/client' },
         ]
       },
       {
@@ -48,13 +58,7 @@ export default defineConfig({
           { text: 'Validating User Input', link: '/recipes/validating-user-input' },
           { text: 'Testing Actions', link: '/recipes/testing' },
           { text: 'RuboCop Integration', link: '/recipes/rubocop-integration' },
-        ]
-      },
-      {
-        text: 'Strategies',
-        items: [
-          { text: 'Overview', link: '/strategies/index' },
-          { text: 'Transaction', link: '/strategies/transaction' },
+          { text: 'Formatting Context for Error Tracking', link: '/recipes/formatting-context-for-error-tracking' },
         ]
       },
       {
@@ -63,7 +67,7 @@ export default defineConfig({
           { text: 'Profiling', link: '/advanced/profiling' },
           { text: 'Conventions', link: '/advanced/conventions' },
           { text: 'Mountable', link: '/advanced/mountable' },
-          { text: 'ROUGH NOTES', link: '/advanced/rough' },
+          { text: 'Internal Notes', link: '/advanced/rough' },
         ]
       },
     ],

data/docs/advanced/conventions.md

@@ -12,7 +12,7 @@ These conventions are still in flux as the library is solidified and we gain mor
 
 ## Organizing Actions (Rails)
 
-You _can_ `include Action` into _any_ Ruby class, but to keep track of things we've found it helpful to:
+You _can_ `include Axn` into _any_ Ruby class, but to keep track of things we've found it helpful to:
 
   * Create a new `app/actions` folder for our actions
   * Name them `Actions::[DOMAIN]::[VERB]` where `[DOMAIN]` is a (possibly nested) identifier and `[VERB]` is the action to be taken.

data/docs/advanced/mountable.md

@@ -116,51 +116,6 @@ end
 **Available methods:**
 - `OrderProcessor.call(**kwargs)` - Executes all steps in sequence
 
-### `enqueue_all_via`
-
-The `enqueue_all_via` method is designed for batch processing scenarios where you need to enqueue multiple instances of an action. It creates methods that can process a collection of items and enqueue each as a separate background job.
-
-```ruby
-class SyncForCompany
-  include Axn
-
-  async :sidekiq
-
-  expects :company_id
-
-  def call
-    company = Company.find(company_id)
-    puts "Syncing data for company: #{company.name}"
-    # Sync individual company data
-  end
-
-  enqueue_all_via do
-    puts "About to enqueue sync jobs for all companies"
-
-    Company.find_each.map do |company|
-      enqueue(company_id: company.id)
-    end
-  end
-end
-
-# Usage
-# Enqueue all companies immediately
-SyncForCompany.enqueue_all
-
-# Enqueue the enqueue_all action itself as a background job
-SyncForCompany.enqueue_all_async
-```
-
-**Mounted methods:**
-- `SyncForCompany.enqueue_all` - Executes the block immediately and enqueues individual jobs
-- `SyncForCompany.enqueue_all_async` - Enqueues the enqueue_all action itself as a background job
-
-#### Key Features
-
-- **Inheritance**: Uses `:async_only` mode by default (only inherits async config, nothing else)
-- **enqueue Shortcut**: Use `enqueue` as syntactic sugar for `ClassName.call_async` within the enqueue_all block
-
-
 ## Async Execution
 
 Mountable actions automatically support async execution when an async adapter is configured. Each mounted action gets a `_async` method that executes the action in the background.
@@ -209,7 +164,6 @@ Each mounting strategy has a default inheritance mode that fits its typical use
 
 - **`mount_axn` and `mount_axn_method`**: Use `:lifecycle` mode (inherits hooks, callbacks, messages, and async config, but not fields)
 - **`step`**: Uses `:none` mode (completely independent to avoid conflicts)
-- **`enqueue_all_via`**: Uses `:async_only` mode (only inherits async configuration for enqueueing)
 
 ```ruby
 class UserService
@@ -239,13 +193,6 @@ class UserService
     # Will NOT run log_start or track_success
     expose :valid, true
   end
-
-  # Only inherits async config for enqueueing
-  enqueue_all_via do
-    # Can call enqueue (uses inherited async config)
-    # Does NOT inherit hooks, callbacks, or messages
-    User.find_each { |u| enqueue(user_id: u.id) }
-  end
 end
 ```
 
@@ -276,8 +223,8 @@ end
 Only inherits async configuration. Use this for utility methods that need async capability but nothing else:
 
 ```ruby
-enqueue_all_via inherit: :async_only do
-  # Only inherits async config for enqueueing
+mount_axn :background_task, inherit: :async_only do
+  # Only inherits async config
   # Completely independent otherwise
 end
 ```
@@ -436,7 +383,7 @@ mount_axn(:user@domain)    # Becomes UserDomain constant
 - **Use `mount_axn`** when you need full `Axn::Result` objects and error handling
 - **Use `mount_axn_method`** when you want direct return values for simple operations
 - **Use `step`** when composing complex workflows with multiple sequential operations
-- **Use `enqueue_all_via`** when you need to process multiple items and enqueue each as a separate background job
+- **Use `enqueues_each`** (from `Axn::Async`) when you need to process multiple items and enqueue each as a separate background job
 
 ### 2. Keep Actions Focused
 
@@ -526,37 +473,4 @@ end
 
 ### Batch Processing
 
-```ruby
-class EmailProcessor
-  include Axn
-
-  async :sidekiq
-
-  expects :email_id
-
-  def call
-    email = Email.find(email_id)
-    email.deliver!
-  end
-
-  enqueue_all_via do |email_ids:, priority: :normal|
-    puts "Processing #{email_ids.count} emails with priority: #{priority}"
-
-    email_ids.map do |email_id|
-      enqueue(email_id: email_id)
-    end
-  end
-end
-
-# Process all pending emails immediately
-EmailProcessor.enqueue_all(
-  email_ids: Email.pending.pluck(:id),
-  priority: :high
-)
-
-# Or enqueue the batch processing as a background job
-EmailProcessor.enqueue_all_async(
-  email_ids: Email.pending.pluck(:id),
-  priority: :normal
-)
-```
+See `enqueues_each` in the [Async documentation](../reference/async.md) for batch processing with background jobs.

data/docs/advanced/profiling.md

@@ -32,11 +32,11 @@ bundle install
 
 ### 2. Enable Profiling
 
-No global configuration is needed! Simply call `profile` on the actions you want to profile.
+No global configuration is needed! Simply use the `:vernier` strategy on the actions you want to profile.
 
 ## Basic Usage
 
-Profiling is enabled per-action by calling the `profile` method. You can only call `profile` **once per action** - subsequent calls will override the previous one. This prevents accidental profiling of all actions and ensures you only profile what you intend to analyze.
+Profiling is enabled per-action by using the `:vernier` strategy. This follows the same pattern as other Axn strategies like `:transaction` and `:form`.
 
 ### Simple Profiling
 
@@ -47,7 +47,7 @@ class UserCreation
   include Axn
 
   # Always profile this action
-  profile
+  use :vernier
 
   expects :user_params
 
@@ -72,8 +72,8 @@ Profile only under specific conditions:
 class DataProcessing
   include Axn
 
-  # Profile only when processing large datasets (only one profile call per action)
-  profile if: -> { record_count > 1000 }
+  # Profile only when processing large datasets
+  use :vernier, if: -> { record_count > 1000 }
 
   expects :records, :record_count
 
@@ -89,8 +89,8 @@ end
 class DataProcessing
   include Axn
 
-  # Profile using a method (only one profile call per action)
-  profile if: :should_profile?
+  # Profile using a method
+  use :vernier, if: :should_profile?
 
   expects :records, :record_count, :debug_mode, type: :boolean, default: false
 
@@ -116,7 +116,7 @@ class DevelopmentAction
   include Axn
 
   # High sampling rate for development (more detailed data)
-  profile(sample_rate: 0.5) if Rails.env.development?
+  use :vernier, sample_rate: 0.5 if Rails.env.development?
 
   def call
     # Action logic
@@ -127,7 +127,7 @@ class ProductionAction
   include Axn
 
   # Low sampling rate for production (minimal overhead)
-  profile(sample_rate: 0.01) if Rails.env.production?
+  use :vernier, sample_rate: 0.01 if Rails.env.production?
 
   def call
     # Action logic
@@ -144,7 +144,7 @@ class MyAction
   include Axn
 
   # Custom output directory
-  profile(output_dir: Rails.root.join("tmp", "profiles", Rails.env))
+  use :vernier, output_dir: Rails.root.join("tmp", "profiles", Rails.env)
 
   def call
     # Action logic
@@ -161,7 +161,7 @@ class ComplexAction
   include Axn
 
   # Profile when debug mode is enabled OR when processing admin users
-  profile if: -> { debug_mode || user.admin? }
+  use :vernier, if: -> { debug_mode || user.admin? }
 
   expects :user, :debug_mode, type: :boolean, default: false
 
@@ -219,10 +219,10 @@ Avoid profiling all actions in production:
 
 ```ruby
 # Good: Conditional profiling
-profile if: -> { Rails.env.development? || debug_mode }
+use :vernier, if: -> { Rails.env.development? || debug_mode }
 
 # Avoid: Always profiling in production
-profile  # This can impact performance
+use :vernier  # This can impact performance
 ```
 
 ### 2. Appropriate Sampling Rates
@@ -234,13 +234,13 @@ class MyAction
   include Axn
 
   # High detail for debugging
-  profile(sample_rate: 0.5) if Rails.env.development?
+  use :vernier, sample_rate: 0.5 if Rails.env.development?
 
   # Moderate sampling for staging
-  profile(sample_rate: 0.1) if Rails.env.staging?
+  use :vernier, sample_rate: 0.1 if Rails.env.staging?
 
   # Minimal overhead for production
-  profile(sample_rate: 0.01) if Rails.env.production?
+  use :vernier, sample_rate: 0.01 if Rails.env.production?
 
   def call
     # Action logic
@@ -257,7 +257,7 @@ class OrderProcessing
   include Axn
 
   # Profile only expensive operations
-  profile if: -> { order.total > 1000 }
+  use :vernier, if: -> { order.total > 1000 }
 
   expects :order
 
@@ -305,7 +305,7 @@ Make sure to:
 
 If profile files aren't being generated:
 
-1. Verify your action has `profile` enabled
+1. Verify your action has `use :vernier` enabled
 2. Ensure profiling conditions are met
 3. Check the output directory exists and is writable
 
@@ -321,32 +321,28 @@ Use appropriate sampling rates and conditional profiling to minimize impact.
 
 ## Integration with Other Tools
 
-### Datadog Integration
+### OpenTelemetry and Datadog Integration
 
-Combine profiling with Datadog tracing:
+Axn automatically creates OpenTelemetry spans for all actions when OpenTelemetry is available. These spans appear as children of your Rails request traces in APM tools.
 
-```ruby
-Axn.configure do |c|
-  # Datadog tracing
-  c.wrap_with_trace = proc do |resource, &action|
-    Datadog::Tracing.trace("Action", resource:) do
-      action.call
-    end
-  end
-end
+You can combine profiling with OpenTelemetry tracing:
 
+```ruby
 class MyAction
   include Axn
 
   # Profiling with custom options
-  profile(sample_rate: 0.1)
+  use :vernier, sample_rate: 0.1
 
   def call
     # Action logic
+    # OpenTelemetry spans are automatically created
   end
 end
 ```
 
+For detailed setup instructions on sending traces to Datadog (including the required gems and initialization order), see the [OpenTelemetry Tracing section](/reference/configuration#opentelemetry-tracing) in the Configuration reference.
+
 ## Resources
 
 - [Vernier GitHub Repository](https://github.com/Shopify/vernier)

data/docs/advanced/rough.md

@@ -1,14 +1,33 @@
-::: danger ALPHA
-* TODO: convert rough notes into actual documentation
-:::
+# Internal Notes
 
-## Rough Notes
+This page contains internal implementation notes for contributors and advanced users.
 
-* General note: the inbound/outbound contexts are views into an underlying shared object (passed down through organize calls) -- modifications of one will affect the other (e.g. preprocessing inbound args implicitly transforms them on the underlying context, which is echoed if you also expose it on outbound).
+## Context Sharing
 
-* `context_for_logging` (and decent #inspect support)
+The inbound/outbound contexts are views into an underlying shared object. Modifications to one affect the other:
 
-* Configuring logging (will default to Rails.logger if available, else fall back to basic Logger (but can explicitly set via e.g. `Axn.config.logger = Logger.new($stdout`))
+- Preprocessing inbound args implicitly transforms them on the underlying context
+- If you also expose a preprocessed field on outbound, it will reflect the transformed value
 
-    * Note `context_for_logging` is available (filtered to accessible attrs, filtering out sensitive values). Automatically passed into `on_exception` hook.
+## Logging and Debugging
 
+For information about logging configuration, see the [Configuration reference](/reference/configuration):
+
+- **Logger configuration**: [logger](/reference/configuration#logger)
+- **Log levels**: [log_level](/reference/configuration#log-level)
+- **Automatic logging**: [Automatic Logging](/reference/configuration#automatic-logging)
+
+### `context_for_logging`
+
+The `context_for_logging` method returns a hash of the action's context, with:
+- Filtering to accessible attributes
+- Sensitive values removed (fields marked with `sensitive: true`)
+
+This is automatically passed to the `on_exception` hook. See [Adding Additional Context to Exception Logging](/reference/configuration#adding-additional-context-to-exception-logging) for customizing the context.
+
+### `#inspect` Support
+
+Action instances provide a readable `#inspect` output that shows:
+- The action class name
+- Field values (with sensitive values filtered)
+- Current execution state

data/docs/intro/overview.md

@@ -13,7 +13,7 @@ This library provides a set of conventions for writing business logic in Rails (
 
 ### Minimal example
 
-Your logic goes in a <abbr title="Plain Old Ruby Object">PORO</abbr>. The only requirements are to `include Action` and a `call` method, meaning the basic skeleton looks something like this:
+Your logic goes in a <abbr title="Plain Old Ruby Object">PORO</abbr>. The only requirements are to `include Axn` and define a `call` method, meaning the basic skeleton looks something like this:
 
 ```ruby
 class Foo