axn 0.1.0.pre.alpha.2.2 → 0.1.0.pre.alpha.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcfb310e364c4fb2c7159a6bdc1ff6766c0025b3b0741a62316d3e18cb5f3bf7
-  data.tar.gz: 7af1c3d88a69c0d109983c85fb6dc1b5ddf162568ee1e1aa516f15bf1d12a1d2
+  metadata.gz: e3313bd117a57aae98551088df5895b6db302830101dda0e2fb95f057f97000f
+  data.tar.gz: 9517e1d297998af62a2fc2107d3a002a71d5b767dda250b6ebec4d29958902a6
 SHA512:
-  metadata.gz: 13868e68f4a7b9a45bebbcf793bba1855ec2fa524ccd6f24fdaf1364bb143fcd4cfd862f0906d6455d10e61492b723ffbdc2c836a887052b030d509bf18171b0
-  data.tar.gz: 53014437d7a3972ec584195b2c20955ff9f2c1138dba3eeb35df2e82db8d62ec3b3561ec6b1d870472fc7fcea79dd1c2abe759cf341c46e024ae143d266bfa64
+  metadata.gz: e3b80de43c96e2362562dc35d88fd28d7c7b97a0dba2e73168031063fa8bed3d64ae3c46dd4f751af6ea051c17fc4592e6c246f505f9e319e5dd6e87caabfc67
+  data.tar.gz: c451f8b99639f94bb38d982ab4913b5e126ee099ed97f31cf2ad70903efbc5acb69bc715e634d39e56aad0720d8bd4007a24794255ea9519307f268b4f312061

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
 ## UNRELEASED
+* N/A
+
+## 0.1.0-alpha.2.4
+* [FEAT] Adds per-Axn `on_exception` handlers
+
+## 0.1.0-alpha.2.3
+* `expects` / `exposes`: Add `type: :uuid` special case validation
+* [BUGFIX] Allow `hoist_errors` to pass the result through on success (allow access to subactions' exposures)
+* [`Axn::Factory`] Support error_from + rescues
+* `Action::Result.error` spec helper -- creation should NOT trigger global exception handler
+* [CHANGE] `expects` / `exposes`: The `default` key, if a callable, should be evaluated in the _instance_'s context
 
 ## 0.1.0-alpha.2.2
 * Expands `Action::Result.ok` and `Action::Result.error` to better support mocking in specs

data/docs/reference/class.md

@@ -25,6 +25,7 @@ While we _support_ complex interface validations, in practice you usually just w
 In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support two additional custom validators:
 * `type: Foo` - fails unless the provided value `.is_a?(Foo)`
   * Edge case: use `type: :boolean` to handle a boolean field (since ruby doesn't have a Boolean class to pass in directly)
+  * Edge case: use `type: :uuid` to handle a confirming given string is a UUID (with or without `-` chars)
 * `validate: [callable]` - Support custom validations (fails if any string is returned OR if it raises an exception)
   * Example:
     ```ruby
@@ -62,7 +63,7 @@ messages success: "All good!", error: ->(e) { "Bad news: #{e.message}" }
 
 While `.messages` sets the _default_ error/success messages and is more commonly used, there are times when you want specific error messages for specific failure cases.
 
-`error_for` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured global error handler.
+`error_for` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured exception handlers (global or specific to this class).
 
 ```ruby
 messages error: "bad"
@@ -74,3 +75,37 @@ rescues ActiveRecord::InvalidRecord => "Invalid params provided"
 error_for ArgumentError, ->(e) { "Argument error: #{e.message}"
 error_for -> { name == "bad" }, -> { "was given bad name: #{name}" }
 ```
+
+## `on_exception`
+
+Much like the [globally-configured on_exception hook](/reference/configuration#on-exception), you can also specify exception handlers for a _specific_ Axn class:
+
+```ruby
+class Foo
+  include Action
+
+  on_exception do |exception| # [!code focus:3]
+    # e.g. trigger a slack error
+  end
+end
+```
+
+Note that by default the `on_exception` block will be applied to _any_ `StandardError` that is raised, but you can specify a matcher using the same logic as for [`error_for` and `rescues`](#error-for-and-rescues):
+
+```ruby
+class Foo
+  include Action
+
+  on_exception NoMethodError do |exception| # [!code focus]
+    # e.g. trigger a slack error
+  end
+
+  on_exception ->(e) { e.is_a?(ZeroDivisionError) } do # [!code focus]
+    # e.g. trigger a slack error
+  end
+end
+```
+
+If multiple `on_exception` handlers are provided, ALL that match the raised exception will be triggered in the order provided.
+
+The _global_ handler will be triggered _after_ all class-specific handlers.

data/docs/reference/configuration.md

@@ -39,6 +39,7 @@ A couple notes:
 
   * `context` will contain the arguments passed to the `action`, _but_ any marked as sensitive (e.g. `expects :foo, sensitive: true`) will be filtered out in the logs.
   * 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`

data/lib/action/core/context_facade.rb

@@ -103,7 +103,7 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        Axn::Factory.build(exposes: exposures.keys, messages: { error: msg }) do
+        Axn::Factory.build(exposes: exposures.keys, rescues: [-> { true }, msg]) do
           exposures.each do |key, value|
             expose(key, value)
           end

data/lib/action/core/contract.rb

@@ -163,11 +163,12 @@ module Action
           hash[config.field] = config.default
         end.compact
 
-        defaults_mapping.each do |field, default_value|
-          unless @context.public_send(field)
-            @context.public_send("#{field}=",
-                                 default_value.respond_to?(:call) ? default_value.call : default_value)
-          end
+        defaults_mapping.each do |field, default_value_getter|
+          next if @context.public_send(field).present?
+
+          default_value = default_value_getter.respond_to?(:call) ? instance_exec(&default_value_getter) : default_value_getter
+
+          @context.public_send("#{field}=", default_value)
         end
       end
 

data/lib/action/core/contract_validator.rb

@@ -54,6 +54,8 @@ module Action
         record.errors.add attribute, (options[:message] || msg) unless types.any? do |type|
           if type == :boolean
             [true, false].include?(value)
+          elsif type == :uuid
+            value.is_a?(String) && value.match?(/\A[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\z/i)
           else
             value.is_a?(type)
           end

data/lib/action/core/hoist_errors.rb

@@ -36,7 +36,9 @@ module Action
                 "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"
         end
 
-        _handle_hoisted_errors(result, prefix:) unless result.ok?
+        return result if result.ok?
+
+        _handle_hoisted_errors(result, prefix:)
       end
 
       # Separate method to allow overriding in subclasses

data/lib/action/core/swallow_exceptions.rb

@@ -3,8 +3,10 @@
 module Action
   module SwallowExceptions
     CustomErrorInterceptor = Data.define(:matcher, :message, :should_report_error)
+    CustomErrorHandler = Data.define(:matcher, :block)
+
     class CustomErrorInterceptor
-      def matches?(exception:, action:)
+      def self.matches?(matcher:, exception:, action:)
         if matcher.respond_to?(:call)
           if matcher.arity == 1
             !!action.instance_exec(exception, &matcher)
@@ -24,12 +26,17 @@ module Action
         action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
         false
       end
+
+      def matches?(exception:, action:)
+        self.class.matches?(matcher:, exception:, action:)
+      end
     end
 
     def self.included(base)
       base.class_eval do
         class_attribute :_success_msg, :_error_msg
         class_attribute :_custom_error_interceptors, default: []
+        class_attribute :_exception_handlers, default: []
 
         include InstanceMethods
         extend ClassMethods
@@ -62,6 +69,10 @@ module Action
           interceptor = self.class._error_interceptor_for(exception: e, action: self)
           return if interceptor&.should_report_error == false
 
+          # Call any handlers registered on *this specific action* class
+          _on_exception(e)
+
+          # Call any global handlers
           Action.config.on_exception(e,
                                      action: self,
                                      context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
@@ -103,6 +114,12 @@ module Action
         _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
       end
 
+      def on_exception(matcher = StandardError, &block)
+        raise ArgumentError, "on_exception must be called with a block" unless block_given?
+
+        self._exception_handlers += [CustomErrorHandler.new(matcher:, block:)]
+      end
+
       def default_error = new.internal_context.default_error
 
       # Private helpers
@@ -144,6 +161,18 @@ module Action
       end
 
       delegate :default_error, to: :internal_context
+
+      def _on_exception(exception)
+        handlers = self.class._exception_handlers.select do |this|
+          CustomErrorInterceptor.matches?(matcher: this.matcher, exception:, action: self)
+        end
+
+        handlers.each do |handler|
+          instance_exec(exception, &handler.block)
+        rescue StandardError => e
+          warn("Ignoring #{e.class.name} in on_exception hook: #{e.message}")
+        end
+      end
     end
   end
 end

data/lib/axn/factory.rb

@@ -14,6 +14,10 @@ module Axn
         exposes: [],
         expects: [],
         messages: {},
+        error_from: {},
+        rescues: {},
+
+        # Hooks
         before: nil,
         after: nil,
         around: nil,
@@ -73,6 +77,9 @@ module Axn
 
           axn.messages(**messages) if messages.present? && messages.values.any?(&:present?)
 
+          axn.error_from(**_array_to_hash(error_from)) if error_from.present?
+          axn.rescues(**_array_to_hash(rescues)) if rescues.present?
+
           # Hooks
           axn.before(before) if before.present?
           axn.after(after) if after.present?
@@ -98,6 +105,12 @@ module Axn
 
       def _hash_with_default_array = Hash.new { |h, k| h[k] = [] }
 
+      def _array_to_hash(given)
+        return given if given.is_a?(Hash)
+
+        [given].to_h
+      end
+
       def _hydrate_hash(given)
         return given if given.is_a?(Hash)
 

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.2"
+  VERSION = "0.1.0-alpha.2.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.2
+  version: 0.1.0.pre.alpha.2.4
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-21 00:00:00.000000000 Z
+date: 2025-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel