axn 0.1.0.pre.alpha.2.7 → 0.1.0.pre.alpha.2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b128603df1eec45048f8656f01508a2e9a706e9acd92ce74813cac0bb038f550
-  data.tar.gz: cfc86ffaadab4cc758546eab39992de2d7f3c89547007a2d88643b303d0edd4b
+  metadata.gz: 57d67670bb1cf60960aa2bb8234a5894a611801b69a89957057bfffd07ace8cd
+  data.tar.gz: 9e0025cbe4bc367e1351ea867d630b9fdb3d706547d676b9cd2162e8fda0ef38
 SHA512:
-  metadata.gz: 2767343c37a0612a446482b52320d2ab85009af9e4094fffa0be31577bdf4a67e228f08307e31c0d182dbd3b944881f10af3c7e80d19a7d6c6f6f08a33294417
-  data.tar.gz: fb5d3942ecbeb2e52f4f4376b5d1b90db696470704d39d1b2db55e6880956073f12f0213a13ad8a564ee2048ad76350bebb811ff90db125bf9724d2d31d3167a
+  metadata.gz: 70cc7c2851d95956278d43c746190dd5173ddda62a9a931ae9538374cf75b72523cc7f9b3524a6df6b8b8d57c969fb5510c07fad56b36312130ae86c59e48a15
+  data.tar.gz: f3f961781373a05284ddc54072baaf13998d235528110bf482c221e5f27d6142ab261516d8237bd0689d1161887eef6b567e8ecb4688d400a20ec32d1ae33837

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 0.1.0-alpha.2.7.1
+* [FEAT] Implemented symbol method handler support for callbacks
+
 ## 0.1.0-alpha.2.7
 * [BREAKING] Replaced `messages` declaration with separate `success` and `error` calls
 * [BREAKING] Removed `rescues` method (use `error_from` for custom error messages; all exceptions now report to `on_exception` handlers)
@@ -7,7 +10,7 @@
   * [FEAT] Implemented conditional success message filtering as well
 * [FEAT] Added block support for `error` and `success`
 * [FEAT] `if:` now supports symbol predicates referencing instance methods (arity 0, 1, or keyword `exception:`). If the method accepts `exception:` it is passed as a keyword; else if it accepts one positional arg, it is passed positionally; otherwise it is called with no args. If the method is missing, the symbol falls back to constant lookup (e.g., `:ArgumentError`).
-* [FEAT] `success`/`error` and callbacks now accept symbol method names (e.g., `success :local_method`). Handlers can receive the exception via keyword (`exception:`) or single positional argument; otherwise they are called with no args.
+* [FEAT] `success`/`error` now accept symbol method names (e.g., `success :local_method`). Handlers can receive the exception via keyword (`exception:`) or single positional argument; otherwise they are called with no args.
 * [BREAKING] Updated callback methods (`on_success`, `on_error`, `on_failure`, `on_exception`) to use consistent `if:` interface (matching messages)
 * [FEAT] Added `unless:` support to both `success`/`error` messages and callbacks (`on_success`, `on_error`, `on_failure`, `on_exception`)
 

data/docs/reference/action-result.md

@@ -13,7 +13,7 @@ Every `call` invocation on an Action will return an `Action::Result` instance, w
 | `elapsed_time` | Execution time in milliseconds (Float)
 | any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
 
-NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `messages` declaration](/reference/class#messages).
+NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `success` and `error` declarations](/reference/class#success-and-error).
 
 ### Clarification of exposed values
 

data/docs/reference/class.md

@@ -235,6 +235,16 @@ In addition to the [global exception handler](/reference/configuration#on-except
   * *Callbacks* (defined below) are executed _after_ the `call` -- exceptions or `fail!`s here will _not_ change `result.ok?`
 :::
 
+
+**Note:** Symbol method handlers for all callback types follow the same argument pattern as [message handlers](#conditional-messages):
+- If the method accepts `exception:` as a keyword, the exception is passed as a keyword
+- If the method accepts one positional argument, the exception is passed positionally
+- Otherwise, the method is called with no arguments
+
+::: warning
+You cannot use both `if:` and `unless:` for the same callback - this will raise an `ArgumentError`.
+:::
+
 ### `on_success`
 
 This is triggered after the Axn completes, if it was successful.  Difference from `after`: if the given block raises an error, this WILL be reported to the global exception handler, but will NOT change `ok?` to false.
@@ -280,16 +290,14 @@ def transient_error?
   name == "temporary"
 end
 
-::: warning
-You cannot use both `if:` and `unless:` for the same callback - this will raise an `ArgumentError`.
-:::
-
   on_exception(if: ->(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

@@ -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.
@@ -92,7 +87,6 @@ A couple notes:
   * 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.
@@ -115,6 +109,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 +146,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 })
+    Datadog::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
+  end
+
+  # Global includes
+  c.additional_includes = [MyCustomModule]
+end
+```

data/docs/reference/instance.md

@@ -63,7 +63,7 @@ NOTE: expects a single action call in the block -- if there are multiple calls,
 
 ::: 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.
+  * 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`
 :::
 

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"

data/lib/action/core/flow/callbacks.rb

@@ -23,28 +23,29 @@ module Action
           end
 
           # ONLY raised exceptions (i.e. NOT fail!).
-          def on_exception(**, &block) = _add_callback(:exception, **, block:)
+          def on_exception(handler = nil, **, &block) = _add_callback(:exception, handler:, **, block:)
 
           # ONLY raised on fail! (i.e. NOT unhandled exceptions).
-          def on_failure(**, &block) = _add_callback(:failure, **, block:)
+          def on_failure(handler = nil, **, &block) = _add_callback(:failure, handler:, **, block:)
 
           # Handles both fail! and unhandled exceptions
-          def on_error(**, &block) = _add_callback(:error, **, block:)
+          def on_error(handler = nil, **, &block) = _add_callback(:error, handler:, **, block:)
 
           # Executes when the action completes successfully (after all after hooks complete successfully)
           # Runs in child-first order (child handlers before parent handlers)
-          def on_success(**, &block) = _add_callback(:success, **, block:)
+          def on_success(handler = nil, **, &block) = _add_callback(:success, handler:, **, block:)
 
           private
 
-          def _add_callback(event_type, block:, **kwargs)
+          def _add_callback(event_type, handler: nil, block: nil, **kwargs)
             raise ArgumentError, "on_#{event_type} cannot be called with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
 
             condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
-            raise ArgumentError, "on_#{event_type} must be called with a block" unless block
+            raise ArgumentError, "on_#{event_type} must be called with a block or symbol" unless block || handler
 
+            callback_handler = block || handler
             matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
-            entry = Action::Core::Flow::Handlers::CallbackHandler.new(matcher:, handler: block)
+            entry = Action::Core::Flow::Handlers::CallbackHandler.new(matcher:, handler: callback_handler)
             self._callbacks_registry = _callbacks_registry.register(event_type:, entry:)
           end
         end

data/lib/axn/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.7
+  version: 0.1.0.pre.alpha.2.7.1
 platform: ruby
 authors:
 - Kali Donovan