axn 0.1.0.pre.alpha.2.7 → 0.1.0.pre.alpha.2.8

data/docs/reference/configuration.md

@@ -2,7 +2,6 @@
 
 Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call `Action.configure` to adjust a few global settings.
 
-
 ```ruby
 Action.configure do |c|
   c.log_level = :info
@@ -22,7 +21,6 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 For example, if you're using Honeybadger this could look something like:
 
-
 ```ruby
   Action.configure do |c|
     c.on_exception = proc do |e, action:, context:|
@@ -56,13 +54,10 @@ A couple notes:
   * If your handler raises, the failure will _also_ be swallowed and logged
   * This handler is global across _all_ Axns.  You can also specify per-Action handlers via [the class-level declaration](/reference/class#on-exception).
 
-
-## `top_level_around_hook`
+## `wrap_with_trace` and `emit_metrics`
 
 If you're using an APM provider, observability can be greatly enhanced by adding automatic _tracing_ of Action calls and/or emitting count metrics after each call completes.
 
-### Tracing and Metrics
-
 The framework provides two distinct hooks for observability:
 
 - **`wrap_with_trace`**: An around hook that wraps the entire action execution. You MUST call the provided block to execute the action.
@@ -79,7 +74,7 @@ For example, to wire up Datadog:
     end
 
     c.emit_metrics = proc do |resource, result|
-      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome, resource: })
+      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s, resource: })
       TS::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
     end
   end
@@ -88,15 +83,16 @@ For example, to wire up Datadog:
 A couple notes:
 
   * `Datadog::Tracing` is provided by [the datadog gem](https://rubygems.org/gems/datadog)
-  * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`success`, `failure`, `exception`) and elapsed time of the action.
+  * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`result.outcome.success?`, `result.outcome.failure?`, `result.outcome.exception?`) and elapsed time of the action.
   * The `wrap_with_trace` hook is an around hook - you must call the provided block to execute the action
   * The `emit_metrics` hook is called after execution with the result - do not call any blocks
 
-
 ## `logger`
 
 Defaults to `Rails.logger`, if present, otherwise falls back to `Logger.new($stdout)`.  But can be set to a custom logger as necessary.
 
+
+
 ## `additional_includes`
 
 This is much less critical than the preceding options, but on the off chance you want to add additional customization to _all_ your actions you can set additional modules to be included alongside `include Action`.
@@ -115,6 +111,10 @@ For a practical example of this in practice, see [our 'memoization' recipe](/rec
 
 Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
 
+## `env`
+
+Automatically detects the environment from `RACK_ENV` or `RAILS_ENV`, defaulting to `"development"`. This is used internally for conditional behavior (e.g., more verbose logging in non-production environments).
+
 ## Automatic Logging
 
 By default, every `action.call` will emit log lines when it is called and after it completes:
@@ -148,3 +148,37 @@ end
 ```
 
 The `auto_log` method supports inheritance, so subclasses will inherit the setting from their parent class unless explicitly overridden.
+
+## Complete Configuration Example
+
+Here's a complete example showing all available configuration options:
+
+```ruby
+Action.configure do |c|
+  # Logging
+  c.log_level = :info
+  c.logger = Rails.logger
+
+  # Exception handling
+  c.on_exception = proc do |e, action:, context:|
+    message = "[#{action.class.name}] Failing due to #{e.class.name}: #{e.message}"
+    Rails.logger.warn(message)
+    Honeybadger.notify(message, context: { axn_context: context })
+  end
+
+  # Observability
+  c.wrap_with_trace = proc do |resource, &action|
+    Datadog::Tracing.trace("Action", resource:) do
+      action.call
+    end
+  end
+
+  c.emit_metrics = proc do |resource, result|
+    Datadog::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s })
+    Datadog::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
+  end
+
+  # Global includes
+  c.additional_includes = [MyCustomModule]
+end
+```

data/docs/reference/instance.md

@@ -51,56 +51,4 @@ class Foo
 end
 ```
 
-## `#hoist_errors`
 
-Useful when calling one Action from within another.  By default the nested action call will return an Action::Result, but it's up to you to check if the result is `ok?` and to handle potential failure modes... and in practice this is easy to miss.
-
-By wrapping your nested call in `hoist_errors`, it will _automatically_ fail the parent action if the nested call fails.
-
-Accepts a `prefix` keyword argument -- when set, prefixes the `error` message from any failures in the block (useful to return different error messages for each if you're calling multiple sub-actions in a single service).
-
-NOTE: expects a single action call in the block -- if there are multiple calls, only the last one will be checked for `ok?` (although anything _raised_ in the block will still be handled).
-
-::: tip Versus `call!`
-* If you just want to make sure your action fails if the subaction fails: call subaction via `call!` (any failures will raise, which will fail the parent).
-  * Note this passes _child_ exception into _parent_ `messages :error` parsing.
-* If you want _the child's_ `result.error` to become the _parent's_ `result.error` on failure, use `hoist_errors` + `call`
-:::
-
-### Example
-
-```ruby
-class SubAction
-  include Action
-
-  def call
-    fail! "bad news"
-  end
-end
-
-class MainAction
-  include Action
-
-  def call
-    SubAction.call
-  end
-end
-```
-
-_Without_ `hoist_errors`, `MainAction.call` returns an `ok?` result, even though `SubAction.call` always fails, because we haven't explicitly handled the nested call.
-
-By adding `hoist_errors`, though:
-
-```ruby
-class MainAction
-  include Action
-
-  def call
-    hoist_errors(prefix: "From subaction:") do
-      SubAction.call
-    end
-  end
-end
-```
-
-`MainAction.call` now returns a _failed_ result, and `result.error` is "From subaction: bad news".

data/docs/usage/setup.md

@@ -21,4 +21,8 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 If you're using an APM provider, observability can be greatly enhanced by [configuring tracing and metrics hooks](/reference/configuration#tracing-and-metrics).
 
+### Code Quality (Optional)
+
+For teams using RuboCop, Axn provides custom cops to enforce best practices. See the [RuboCop Integration guide](/recipes/rubocop-integration) for setup instructions.
+
 

data/docs/usage/steps.md

@@ -0,0 +1,335 @@
+---
+outline: deep
+---
+
+# Using Steps in Actions
+
+The steps functionality allows you to compose complex actions by breaking them down into sequential, reusable steps. Each step can expect data from the parent context or previous steps, and expose data for subsequent steps.
+
+## Basic Concepts
+
+### What are Steps?
+
+Steps are a way to organize action logic into smaller, focused pieces that:
+- Execute in a defined order
+- Can share data between each other
+- Handle failures gracefully with error prefixing
+- Can be reused across different actions
+
+### How Steps Work
+
+1. **Step Definition**: Define steps using the `step` class method
+2. **Execution Order**: Steps execute sequentially in the order they're defined
+3. **Data Flow**: Each step can expect and expose data
+4. **Error Handling**: Step failures are caught and can trigger error handlers
+
+## Defining Steps
+
+### Using the `step` Method
+
+The `step` method allows you to define steps inline with blocks:
+
+```ruby
+class UserRegistration
+  include Action
+  expects :email, :password, :name
+  exposes :user_id, :welcome_message
+
+  step :validate_input, expects: [:email, :password, :name], exposes: [:validated_data] do
+    # Validation logic
+    fail! "Email is invalid" unless email.match?(/\A[^@\s]+@[^@\s]+\z/)
+    fail! "Password too short" if password.length < 8
+    fail! "Name is required" if name.blank?
+
+    expose :validated_data, { email: email.downcase, password: password, name: name.strip }
+  end
+
+  step :create_user, expects: [:validated_data], exposes: [:user_id] do
+    user = User.create!(validated_data)
+    expose :user_id, user.id
+  end
+
+  step :send_welcome, expects: [:user_id, :validated_data], exposes: [:welcome_message] do
+    WelcomeMailer.send_welcome(user_id, validated_data[:email]).deliver_now
+    expose :welcome_message, "Welcome #{validated_data[:name]}!"
+  end
+
+  def call
+    # Steps handle execution automatically
+  end
+end
+```
+
+### Using the `steps` Method
+
+The `steps` method allows you to compose existing action classes:
+
+```ruby
+class ValidateInput
+  include Action
+  expects :email, :password, :name
+  exposes :validated_data
+
+  def call
+    fail! "Email is invalid" unless email.match?(/\A[^@\s]+@[^@\s]+\z/)
+    fail! "Password too short" if password.length < 8
+    fail! "Name is required" if name.blank?
+
+    expose :validated_data, { email: email.downcase, password: password, name: name.strip }
+  end
+end
+
+class CreateUser
+  include Action
+  expects :validated_data
+  exposes :user_id
+
+  def call
+    user = User.create!(validated_data)
+    expose :user_id, user.id
+  end
+end
+
+class SendWelcome
+  include Action
+  expects :user_id, :validated_data
+  exposes :welcome_message
+
+  def call
+    WelcomeMailer.send_welcome(user_id, validated_data[:email]).deliver_now
+    expose :welcome_message, "Welcome #{validated_data[:name]}!"
+  end
+end
+
+class UserRegistration
+  include Action
+  expects :email, :password, :name
+  exposes :user_id, :welcome_message
+
+  # Use existing action classes as steps
+  steps(ValidateInput, CreateUser, SendWelcome)
+end
+```
+
+### Mixed Approach
+
+You can combine both approaches:
+
+```ruby
+class UserRegistration
+  include Action
+  expects :email, :password, :name
+  exposes :user_id, :welcome_message
+
+  # Use existing action for validation
+  steps(ValidateInput)
+
+  # Define custom step for user creation
+  step :create_user, expects: [:validated_data], exposes: [:user_id] do
+    user = User.create!(validated_data)
+    expose :user_id, user.id
+  end
+
+  # Use existing action for welcome email
+  steps(SendWelcome)
+end
+```
+
+## Data Flow Between Steps
+
+### Expecting Data
+
+Steps can expect data from:
+- **Parent context**: Data passed to the parent action
+- **Previous steps**: Data exposed by earlier steps
+
+```ruby
+step :step1, expects: [:input], exposes: [:processed_data] do
+  expose :processed_data, input.upcase
+end
+
+step :step2, expects: [:processed_data], exposes: [:final_result] do
+  # This step can access both 'input' (from parent) and 'processed_data' (from step1)
+  expose :final_result, "Result: #{processed_data}"
+end
+```
+
+### Exposing Data
+
+Steps expose data using the `expose` method:
+
+```ruby
+step :calculation, expects: [:base_value], exposes: [:doubled_value, :final_result] do
+  doubled = base_value * 2
+  expose :doubled_value, doubled
+  expose :final_result, doubled + 10
+end
+```
+
+### Using `expose_return_as`
+
+For simple calculations, you can use `expose_return_as`:
+
+```ruby
+step :calculation, expects: [:input], expose_return_as: :result do
+  input * 2 + 10  # Return value is automatically exposed as 'result'
+end
+```
+
+## Error Handling
+
+### Automatic Error Prefixing
+
+When a step fails, error messages are automatically prefixed with the step name:
+
+```ruby
+step :validation, expects: [:input] do
+  fail! "Input too short"
+end
+
+# If this step fails, the error message becomes: "validation step: Input too short"
+```
+
+### Step Failure Propagation
+
+When a step fails:
+1. The step's exception is caught
+2. The parent action fails with the prefixed error message
+3. The `on_exception` handlers are triggered appropriately
+
+### Exception Handling
+
+Steps can raise exceptions that will be caught and handled:
+
+```ruby
+step :risky_operation, expects: [:input] do
+  raise StandardError, "Something went wrong with #{input}"
+end
+
+# The exception is caught and the error message becomes: "risky_operation step: Something went wrong with [input]"
+```
+
+
+
+## Best Practices
+
+### 1. Keep Steps Focused
+
+Each step should have a single responsibility:
+
+```ruby
+# ❌ Bad: Step does too many things
+step :process_user, expects: [:user_data], exposes: [:user_id, :welcome_sent] do
+  user = User.create!(user_data)
+  WelcomeMailer.send_welcome(user.id).deliver_now
+  expose :user_id, user.id
+  expose :welcome_sent, true
+end
+
+# ✅ Good: Steps are focused
+step :create_user, expects: [:user_data], exposes: [:user_id] do
+  user = User.create!(user_data)
+  expose :user_id, user.id
+end
+
+step :send_welcome, expects: [:user_id], exposes: [:welcome_sent] do
+  WelcomeMailer.send_welcome(user_id).deliver_now
+  expose :welcome_sent, true
+end
+```
+
+### 2. Use Descriptive Step Names
+
+Step names should clearly indicate what the step does:
+
+```ruby
+# ❌ Bad: Unclear names
+step :step1, expects: [:input] do
+  # ...
+end
+
+# ✅ Good: Descriptive names
+step :validate_email_format, expects: [:input] do
+  # ...
+end
+```
+
+### 3. Handle Failures Gracefully
+
+Use `fail!` for expected failures and raise exceptions for unexpected errors:
+
+```ruby
+step :validation, expects: [:input] do
+  # Expected failure - use fail!
+  fail! "Input too short" if input.length < 3
+
+  # Unexpected error - raise exception
+  raise StandardError, "Database connection failed" if database_unavailable?
+end
+```
+
+### 4. Expose Only Necessary Data
+
+Only expose data that subsequent steps actually need:
+
+```ruby
+# ❌ Bad: Exposing unnecessary data
+step :validation, expects: [:input], exposes: [:input, :validated, :timestamp] do
+  expose :input, input
+  expose :validated, true
+  expose :timestamp, Time.current
+end
+
+# ✅ Good: Only exposing what's needed
+step :validation, expects: [:input], exposes: [:validated_input] do
+  expose :validated_input, input.strip
+end
+```
+
+## Common Use Cases
+
+### API Request Processing
+
+```ruby
+class ProcessAPIRequest
+  include Action
+  expects :request_data
+  exposes :response_data
+
+  step :authenticate, expects: [:request_data], exposes: [:authenticated_user] do
+    # Authentication logic
+    expose :authenticated_user, authenticate_user(request_data[:token])
+  end
+
+  step :authorize, expects: [:authenticated_user, :request_data], exposes: [:authorized] do
+    # Authorization logic
+    fail! "Access denied" unless authorized_user?(authenticated_user, request_data[:action])
+    expose :authorized, true
+  end
+
+  step :process_request, expects: [:request_data, :authenticated_user], exposes: [:response_data] do
+    # Process the actual request
+    expose :response_data, process_user_request(request_data, authenticated_user)
+  end
+end
+```
+
+
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Steps not executing**: Ensure the Steps module is properly included
+2. **Data not flowing**: Check that step names match between `expects` and `exposes`
+3. **Error messages unclear**: Verify step names are descriptive
+
+### Debugging Tips
+
+- Use descriptive step names for better error messages
+- Check that data is properly exposed between steps
+- Verify that step dependencies are correctly specified
+
+## Summary
+
+The steps functionality provides a powerful way to compose complex actions from smaller, focused pieces. By following the patterns and best practices outlined here, you can create maintainable, testable, and reusable action compositions.

data/docs/usage/writing.md

@@ -68,7 +68,7 @@ See [the reference doc](/reference/instance) for a few more handy helper methods
 
 The default `error` and `success` message strings ("Something went wrong" / "Action completed successfully", respectively) _are_ technically safe to show users, but you'll often want to set them to something more useful.
 
-There's a `messages` declaration for that -- you can set strings (most common) or a callable (note for the error case, if you give it a callable that expects a single argument, the exception that was raised will be passed in).
+There are `success` and `error` declarations for that -- you can set strings (most common) or a callable (note for the error case, if you give it a callable that expects a single argument, the exception that was raised will be passed in).
 
 For instance, configuring the action like this:
 
@@ -79,8 +79,8 @@ class Foo
   expects :name, type: String
   exposes :meaning_of_life
 
-  messages success: -> { "Revealed to #{name}: #{result.meaning_of_life}" }, # [!code focus:2]
-           error: ->(e) { "No secret of life for you: #{e.message}" }
+  success { "Revealed to #{name}: #{result.meaning_of_life}" } # [!code focus:2]
+  error { |e| "No secret of life for you: #{e.message}" }
 
   def call
     fail! "Douglas already knows the meaning" if name == "Doug"
@@ -100,6 +100,71 @@ Foo.call(name: "Adams").success # => "Revealed the secret of life to Adams"
 Foo.call(name: "Adams").meaning_of_life # => "Hello Adams, the meaning of life is 42"
 ```
 
+### Advanced Error Message Configuration
+
+You can also use conditional error messages with the `prefix:` keyword and combine them with the `from:` parameter for nested actions:
+
+```ruby
+class ValidationAction
+  include Action
+
+  expects :input
+
+  error if: ArgumentError, prefix: "Validation Error: " do |e|
+    "Invalid input: #{e.message}"
+  end
+
+  error if: StandardError, prefix: "System Error: "
+
+  def call
+    raise ArgumentError, "input too short" if input.length < 3
+    raise StandardError, "unexpected error" if input == "error"
+  end
+end
+
+class ApiAction
+  include Action
+
+  expects :data
+
+  # Combine prefix with from for consistent error formatting
+  error from: ValidationAction, prefix: "API Error: " do |e|
+    "Request validation failed: #{e.message}"
+  end
+
+  # Or use prefix only (falls back to exception message)
+  error from: ValidationAction, prefix: "API Error: "
+
+  def call
+    ValidationAction.call!(input: data)
+  end
+end
+```
+
+This configuration provides:
+- Consistent error message formatting with prefixes
+- Automatic fallback to exception messages when no custom message is provided
+- Proper error message inheritance from nested actions
+
+::: warning Message Ordering
+**Important**: When using conditional messages, always define your static fallback messages **first** in your class, before any conditional messages. This ensures proper fallback behavior.
+
+**Correct order:**
+```ruby
+class Foo
+  include Action
+
+  # Static fallback messages first
+  success "Default success message"
+  error "Default error message"
+
+  # Then conditional messages
+  success "Special success", if: :special_condition?
+  error "Special error", if: ArgumentError
+end
+```
+:::
+
 ## Lifecycle methods
 
 In addition to `#call`, there are a few additional pieces to be aware of:
@@ -156,3 +221,5 @@ A number of custom callback are available for you as well, if you want to take s
 
 ## Strategies
 A number of [Strategies](/strategies/index), which are <abbr title="Don't Repeat Yourself">DRY</abbr>ed bits of commonly-used configuration, are available for your use as well.
+
+```

data/lib/action/attachable/steps.rb

@@ -9,14 +9,16 @@ module Action
         class_attribute :_axn_steps, default: []
       end
 
-      Entry = Data.define(:label, :axn)
-
       class_methods do
         def steps(*steps)
-          self._axn_steps += Array(steps).compact
+          Array(steps).compact.each do |step|
+            raise ArgumentError, "Step #{step} must include Action module" if step.is_a?(Class) && !step.included_modules.include?(Action) && !step < Action
+
+            step("Step #{_axn_steps.length + 1}", step)
+          end
         end
 
-        def step(name, axn_klass = nil, **kwargs, &block)
+        def step(name, axn_klass = nil, error_prefix: nil, **kwargs, &block)
           axn_klass = axn_for_attachment(
             name:,
             axn_klass:,
@@ -27,32 +29,31 @@ module Action
           )
 
           # Add the step to the list of steps
-          steps Entry.new(label: name, axn: axn_klass)
+          _axn_steps << axn_klass
+
+          # Set up error handling for steps without explicit labels
+          error_prefix ||= "#{name}: "
+          error from: axn_klass do |e|
+            "#{error_prefix}#{e.message}"
+          end
         end
       end
 
+      # Execute steps automatically when the action is called
       def call
-        self.class._axn_steps.each_with_index do |step, idx|
-          # Set a default label if we were just given an array of unlabeled steps
-          # TODO: should Axn have a default label passed in already that we could pull out?
-          step = Entry.new(label: "Step #{idx + 1}", axn: step) if step.is_a?(Class)
-
-          hoist_errors(prefix: "#{step.label} step") do
-            step.axn.call(**merged_context_data).tap do |step_result|
-              merge_step_exposures!(step_result)
-            end
-          end
+        _axn_steps.each do |axn|
+          _merge_step_exposures!(axn.call!(**_merged_context_data))
         end
       end
 
       private
 
-      def merged_context_data
+      def _merged_context_data
         @__context.__combined_data
       end
 
       # Each step can expect the data exposed from the previous steps
-      def merge_step_exposures!(step_result)
+      def _merge_step_exposures!(step_result)
         step_result.declared_fields.each do |field|
           @__context.exposed_data[field] = step_result.public_send(field)
         end

data/lib/action/attachable/subactions.rb

@@ -40,7 +40,7 @@ module Action
             axn_klass.call(**kwargs)
           end
 
-          # TODO: do we also need an instance-level version that auto-wraps in hoist_errors(label: name)?
+          # TODO: do we also need an instance-level version that auto-creates the appropriate `error from:` to prefix with the name?
 
           define_singleton_method("#{name}!") do |**kwargs|
             axn_klass.call!(**kwargs)