axn 0.1.0.pre.alpha.2.7.1 → 0.1.0.pre.alpha.2.8

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_ `error` message 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

@@ -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)

data/lib/action/context.rb

@@ -11,28 +11,24 @@ module Action
       # Framework-managed fields
       @failure = false
       @exception = nil
-      @error_from_user = nil
-      @error_prefix = nil
       @elapsed_time = nil
     end
 
-    def fail!(message = nil)
-      @error_from_user = message if message.present?
-      raise Action::Failure, message
-    end
-
-    # INTERNAL: base for further filtering (for logging) or providing user with usage hints
-    def __combined_data = @provided_data.merge(@exposed_data)
-
     # Framework state methods
     def ok? = !@failure
     def failed? = @failure || false
 
     # Framework field accessors
-    attr_accessor :exception, :error_from_user, :error_prefix, :elapsed_time
+    attr_accessor :elapsed_time
+    attr_reader :exception
+    private :elapsed_time=
 
-    # Internal failure state setter (for framework use)
-    attr_writer :failure
-    private :failure=
+    # INTERNAL: base for further filtering (for logging) or providing user with usage hints
+    def __combined_data = @provided_data.merge(@exposed_data)
+
+    def __record_exception(e)
+      @exception = e
+      @failure = true
+    end
   end
 end

data/lib/action/core/context/facade.rb

@@ -15,7 +15,7 @@ module Action
 
       (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
         singleton_class.define_method(field) do
-          context_data_source[field]
+          _context_data_source[field]
         end
       end
     end
@@ -34,6 +34,15 @@ module Action
 
     def action_name = @action.class.name.presence || "The action"
 
-    def context_data_source = raise NotImplementedError
+    def _context_data_source = raise NotImplementedError
+
+    def _msg_resolver(event_type, exception:)
+      Action::Core::Flow::Handlers::Resolvers::MessageResolver.new(
+        action._messages_registry,
+        event_type,
+        action:,
+        exception:,
+      )
+    end
   end
 end

data/lib/action/core/context/facade_inspector.rb

@@ -22,8 +22,9 @@ module Action
       return unless facade.is_a?(Action::Result)
 
       return "[OK]" if context.ok?
-      unless context.exception
-        return context.error_from_user.present? ? "[failed with '#{context.error_from_user}']" : "[failed]"
+
+      if context.exception.is_a?(Action::Failure)
+        return context.exception.message.present? ? "[failed with '#{context.exception.message}']" : "[failed]"
       end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])

data/lib/action/core/context/internal.rb

@@ -5,20 +5,12 @@ require "action/core/context/facade"
 module Action
   # Inbound / Internal ContextFacade
   class InternalContext < ContextFacade
-    # Available for use from within message callables
-    def default_error
-      msg = action.class._static_message_for(:error, action:, exception: @context.exception || Action::Failure.new)
-      [@context.error_prefix, msg.presence || "Something went wrong"].compact.join(" ").squeeze(" ")
-    end
-
-    def default_success
-      msg = action.class._static_message_for(:success, action:, exception: nil)
-      msg.presence || "Action completed successfully"
-    end
+    def default_error = _msg_resolver(:error, exception: Action::Failure.new).resolve_default_message
+    def default_success = _msg_resolver(:success, exception: nil).resolve_default_message
 
     private
 
-    def context_data_source = @context.provided_data
+    def _context_data_source = @context.provided_data
 
     def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
       if @context.__combined_data.key?(method_name.to_sym)

data/lib/action/core/contract_validation.rb

@@ -13,7 +13,7 @@ module Action
           new_value = config.preprocess.call(initial_value)
           @__context.provided_data[config.field] = new_value
         rescue StandardError => e
-          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}"
+          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}", cause: e
         end
       end