axn 0.1.0.pre.alpha.2.4.1 → 0.1.0.pre.alpha.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19221983bd11ff17620830a4807b4080f8ea35dfb07050e2af2e6c1dac1e1b7d
-  data.tar.gz: 7ac5fc8f9ae99bd9a5a189ad53f6113c4c544181ff760bbe923ca1867f011877
+  metadata.gz: ad00a162e22de940a1c6e4a4de1f75533fb1aa5440c6cf8808f81a964e2457d4
+  data.tar.gz: dfb840d11657f80f92d3e1aa19bef3cb64b1d28a84f70f0dd1b92c5726f4fd7f
 SHA512:
-  metadata.gz: 4115cc144bfac9420ff85de1ff9198efd092f63594811aed1afbf3ac5a07a5b73a9017b9d9665aac78e128c312d79e996d8dc2f8710fb30a8b9825a51caa30e5
-  data.tar.gz: 7528abe56dd99066409a59a57f07d04f9b9ea98fd399b62aab7318a762920027eb0870b7895b5f8bff525023a7d754c67f0d8c484661929c8a4dab1a360caf6f
+  metadata.gz: 6704196ea530709faf393c51886f0ab4ed34fd5f9654cf4d086d08ba30a455140297bf695d29d0e7a15376b8b3064c9093e882f74f84139e21dc2bdc1e122298
+  data.tar.gz: e319dcdf830b8b49fafa2db5f8461b951bf96db8a57b1b1172075a69db2f1eacd4674807526480d7f56a5fbe03265bf549f755359986a02805a5e982f0c769d1

data/.rubocop.yml

@@ -3,6 +3,10 @@ AllCops:
   SuggestExtensions: false
   NewCops: enable
 
+
+Style/MultilineBlockChain:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -3,6 +3,21 @@
 ## UNRELEASED
 * N/A
 
+## 0.1.0-alpha.2.5
+* Support blank exposures for `Action::Result.ok`
+* Modify Action::Failure's initialize signature (to better match StandardError)
+* Reduce reserved fields to allow some `expects` (e.g. `message`) that would shadow internals if used as `exposes`
+* Default logging changes:
+  * Add `default_log_level` and `default_autolog_level` class methods (so inheritable) via `Action.config`
+  * Remove `global_debug_logging?` from Configuration + unused `SA_DEBUG_TARGETS` approach to configuring logging
+* Improved testing ergonomics: the `type` expectation will now return `true` for _any_ `RSpec::Mocks::` subclass
+* Enqueueable improvements:
+  * Extracted out of Core
+  * Renamed to `Enqueueable::ViaSidekiq` (make it easier to support different background runners in the future)
+  * Added ability to call `.enqueue_all_in_background` to run an Action's class-level `.enqueue_all` method (if defined) on a background worker
+    (important if triggered via a clock process that is NOT intended to execute actual jobs)
+* Restructure internals (call/call! + run/run! + Action::Failure) to simplify upstream implementation since we always wrap any raised exceptions
+
 ## 0.1.0-alpha.2.4.1
 * [FEAT] Adds full suite of per-Axn callbacks: `on_exception`, `on_failure`, `on_error`, `on_success`
 

data/docs/recipes/testing.md

@@ -31,6 +31,56 @@ before do
 end
 ```
 
+### `call!`
+
+The semantics of call-bang are a little different -- if Subaction is called via `call!`, you'll need slightly different code to handle success vs failure:
+
+### Success
+
+```ruby
+let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+
+before do
+  expect(Subaction).to receive(:call!).and_return(subaction_response)
+end
+```
+
+### Failure
+
+Because `call!` will _raise_, we need to use `and_raise` rather than `and_return`:
+
+```ruby
+let(:subaction_exception) { SomeValidErrorClass.new("whatever you expect subclass to raise") }
+
+before do
+  expect(Subaction).to receive(:call!).and_raise(subaction_exception)
+end
+```
+
+NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Action::Failure` exception class.
+
+## Mocking Axn arguments
+
+Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Action.config.env.test?` is `true`_.
+
+This makes it much easier to test Axns, as you can pass in mocks without immediately failing the inbound validation.
+
+```ruby
+subject(:result) { action.call!(sym:) }
+
+let(:action) { build_action { expects :sym, type: Symbol } }
+
+context "with a symbol" do
+  let(:sym) { :hello }
+  it { is_expected.to be_ok }
+end
+
+context "with an RSpec double" do
+  let(:sym) { double(to_s: "hello") }  # [!code focus:2]
+  it { is_expected.to be_ok }
+end
+```
+
 ## RSpec configuration
 
 Configuring rspec to treat files in spec/actions as service specs (very optional):

data/docs/reference/configuration.md

@@ -11,7 +11,8 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 
     c.additional_includes = []
 
-    c.global_debug_logging = false
+    c.default_log_level = :info
+    c.default_autolog_level = :debug
 
     c.logger = ...
   end
@@ -84,21 +85,17 @@ For example:
 
 For a practical example of this in practice, see [our 'memoization' recipe](/recipes/memoization).
 
-## `global_debug_logging`
+## `default_log_level`
 
-By default, every `action.call` will emit _debug_ log lines when it is called and after it completes:
+Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `default_log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
+
+## `default_autolog_level`
+
+By default, every `action.call` will emit log lines when it is called and after it completes:
 
   ```
     [YourCustomAction] About to execute with: {:foo=>"bar"}
     [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
   ```
 
-You can bump the log level from `debug` to `info` for specific actions by including their class name (comma separated, if multiple) in a `SA_DEBUG_TARGETS` ENV variable.
-
-You can also turn this on _globally_ by setting `global_debug_logging = true`.
-
-```ruby
-  Action.configure do |c|
-    c.global_debug_logging = true
-  end
-```
+You can change the default _auto_-log level separately from the log level used for your explicit `log` calls (just like above, via Action.config or a `default_autolog_level` class method).

data/docs/reference/instance.md

@@ -61,6 +61,12 @@ Accepts a `prefix` keyword argument -- when set, prefixes the `error` message fr
 
 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

data/docs/usage/using.md

@@ -55,3 +55,33 @@ Sidekiq integration is NOT YET TESTED/NOT YET USED IN OUR APP, and naming will V
     * enqueue will not retry even if fails
     * enqueue! will go through normal sidekiq retries on any failure (including user-facing `fail!`)
     * Note implicit GlobalID support (if not serializable, will get ArgumentError at callsite)
+
+
+### `.enqueue_all_in_background`
+
+In practice it's fairly common to need to enqueue a bunch of sidekiq jobs from a clock process.
+
+One approach is to define a class-level `.enqueue_all` method on your Action... but that ends up executing the enqueue_all logic directly from the clock process, which is undesirable.
+
+
+::: danger ALPHA
+We are actively testing this pattern -- not yet certain we'll keep it past beta.
+:::
+
+Therefore we've added an `.enqueue_all_in_background` method that will automatically call your `.enqueue_all` _from a background job_ rather than directly on the active process.
+
+```ruby
+class Foo
+  include Action
+
+  def self.enqueue_all
+    SomeModel.some_scope.find_each do |record|
+      enqueue(record:)
+    end
+  end
+
+  ...
+end
+
+Foo.enqueue_all # works, but `SomeModel.some_scope.find_each` is executed in the current context
+Foo.enqueue_all_in_background # same, but runs in the background (via Action::Enqueueable::EnqueueAllWorker)

data/lib/action/core/configuration.rb

@@ -3,10 +3,11 @@
 module Action
   class Configuration
     include Action::Logging
-    attr_accessor :global_debug_logging, :top_level_around_hook
-    attr_writer :logger, :env, :on_exception, :additional_includes
+    attr_accessor :top_level_around_hook
+    attr_writer :logger, :env, :on_exception, :additional_includes, :default_log_level, :default_autolog_level
 
-    def global_debug_logging? = !!global_debug_logging
+    def default_log_level = @default_log_level ||= :info
+    def default_autolog_level = @default_autolog_level ||= :info
 
     def additional_includes = @additional_includes ||= []
 
@@ -15,7 +16,7 @@ module Action
         # TODO: only pass action: or context: if requested (and update documentation)
         @on_exception.call(e, action:, context:)
       else
-        log("[#{action.class.name.presence || "Anonymous Action"}] Exception swallowed: #{e.class.name} - #{e.message}")
+        log("[#{action.class.name.presence || "Anonymous Action"}] Exception raised: #{e.class.name} - #{e.message}")
       end
     end
 

data/lib/action/core/context_facade.rb

@@ -51,7 +51,9 @@ module Action
     def determine_error_message(only_default: false)
       return @context.error_from_user if @context.error_from_user.present?
 
-      exception = @context.exception || (only_default ? Action::Failure.new(@context) : nil)
+      # We need an exception for interceptors, and also in case the messages.error callable expects an argument
+      exception = @context.exception || Action::Failure.new
+
       msg = action._error_msg
 
       unless only_default
@@ -73,7 +75,7 @@ module Action
         action.instance_exec(&msg)
       end
     rescue StandardError => e
-      action.warn("Ignoring #{e.class.name} raised while determining message callable: #{e.message}")
+      action.warn("Ignoring #{e.class.name} while determining message callable: #{e.message}")
       nil
     end
   end
@@ -95,7 +97,9 @@ module Action
     # For ease of mocking return results in tests
     class << self
       def ok(msg = nil, **exposures)
-        Axn::Factory.build(exposes: exposures.keys, messages: { success: msg }) do
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+
+        Axn::Factory.build(exposes:, messages: { success: msg }) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -103,7 +107,10 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        Axn::Factory.build(exposes: exposures.keys, rescues: [-> { true }, msg]) do
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        rescues = [-> { true }, msg]
+
+        Axn::Factory.build(exposes:, rescues:) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -162,7 +169,9 @@ module Action
       return unless facade.is_a?(Action::Result)
 
       return "[OK]" if context.success?
-      return "[failed with '#{context.error_from_user}']" unless context.exception
+      unless context.exception
+        return context.error_from_user.present? ? "[failed with '#{context.error_from_user}']" : "[failed]"
+      end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
     end

data/lib/action/core/contract.rb

@@ -36,6 +36,10 @@ module Action
     module ClassMethods
       def expects(*fields, allow_blank: false, allow_nil: false, default: nil, preprocess: nil, sensitive: false,
                   **validations)
+        fields.each do |field|
+          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPECTATIONS.include?(field.to_s)
+        end
+
         _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess:, sensitive:, **validations).tap do |configs|
           duplicated = internal_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -46,6 +50,10 @@ module Action
       end
 
       def exposes(*fields, allow_blank: false, allow_nil: false, default: nil, sensitive: false, **validations)
+        fields.each do |field|
+          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPOSURES.include?(field.to_s)
+        end
+
         _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess: nil, sensitive:, **validations).tap do |configs|
           duplicated = external_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -57,10 +65,16 @@ module Action
 
       private
 
-      RESERVED_FIELD_NAMES = %w[
-        declared_fields inspect fail!
-        default_error
-        called! rollback! each_pair success? exception ok ok? error success message
+      RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
+        called! fail! rollback! success? ok?
+        inspect default_error
+        each_pair
+      ].freeze
+
+      RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
+        called! fail! rollback! success? ok?
+        inspect each_pair default_error
+        ok error success message
       ].freeze
 
       def _parse_field_configs(*fields, allow_nil: false, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
@@ -68,8 +82,6 @@ module Action
         # Allow local access to explicitly-expected fields -- even externally-expected needs to be available locally
         # (e.g. to allow success message callable to reference exposed fields)
         fields.each do |field|
-          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES.include?(field.to_s)
-
           define_method(field) { internal_context.public_send(field) }
         end
 
@@ -123,9 +135,9 @@ module Action
         raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
 
         klass = direction == :inbound ? Action::InternalContext : Action::Result
-        implicitly_allowed_fields = direction == :inbound ? declared_fields(:outbound) : []
+        implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
 
-        klass.new(action: self, context: @context, declared_fields: declared_fields(direction), implicitly_allowed_fields:)
+        klass.new(action: self, context: @context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
       end
     end
 
@@ -173,7 +185,7 @@ module Action
       end
 
       def context_for_logging(direction = nil)
-        inspection_filter.filter(@context.to_h.slice(*declared_fields(direction)))
+        inspection_filter.filter(@context.to_h.slice(*_declared_fields(direction)))
       end
 
       protected
@@ -186,7 +198,7 @@ module Action
         (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
       end
 
-      def declared_fields(direction)
+      def _declared_fields(direction)
         raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
 
         configs = case direction

data/lib/action/core/contract_validator.rb

@@ -34,7 +34,7 @@ module Action
         msg = begin
           options[:with].call(value)
         rescue StandardError => e
-          warn("Custom validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
+          Action.config.logger.warn("Custom validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
 
           "failed validation: #{e.message}"
         end
@@ -45,7 +45,7 @@ module Action
 
     class TypeValidator < ActiveModel::EachValidator
       def validate_each(record, attribute, value)
-        # TODO: the last one (:value) might be my fault from the make-it-a-hash fallback in #parse_field_configs
+        # NOTE: the last one (:value) might be my fault from the make-it-a-hash fallback in #parse_field_configs
         types = options[:in].presence || Array(options[:with]).presence || Array(options[:value]).presence
 
         return if value.blank? && !types.include?(:boolean) # Handled with a separate default presence validator
@@ -57,6 +57,8 @@ module Action
           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
+            next true if Action.config.env.test? && value.class.name.start_with?("RSpec::Mocks::")
+
             value.is_a?(type)
           end
         end

data/lib/action/core/event_handlers.rb

@@ -27,7 +27,7 @@ module Action
         action.instance_exec(exception, &@handler)
         true
       rescue StandardError => e
-        action.warn("Ignoring #{e.class.name} in when evaluating #{self.class.name} handler: #{e.message}")
+        action.warn("Ignoring #{e.class.name} when evaluating handler: #{e.message}")
         nil
       end
     end
@@ -54,7 +54,7 @@ module Action
           false
         end
       rescue StandardError => e
-        action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
+        action.warn("Ignoring #{e.class.name} while determining matcher: #{e.message}")
         false
       end
 

data/lib/action/core/exceptions.rb

@@ -3,15 +3,16 @@
 module Action
   # Raised internally when fail! is called -- triggers failure + rollback handling
   class Failure < StandardError
-    attr_reader :context
+    DEFAULT_MESSAGE = "Execution was halted"
 
-    def initialize(context = nil, message: nil)
-      super()
-      @message = message if message.present?
-      @context = context
+    def initialize(message = nil, **)
+      @message = message
+      super(**)
     end
 
-    def message = @message.presence || @context.error_from_user.presence || "Execution was halted"
+    def message
+      @message.presence || DEFAULT_MESSAGE
+    end
 
     def inspect = "#<#{self.class.name} '#{message}'>"
   end

data/lib/action/core/hoist_errors.rb

@@ -29,8 +29,10 @@ module Action
           MinimalFailedResult.new(error: nil, exception: e)
         end
 
-        # This ensures the last line of hoist_errors was an Action call (CAUTION: if there are multiple
-        # calls per block, only the last one will be checked!)
+        # This ensures the last line of hoist_errors was an Action call
+        #
+        # CAUTION: if there are multiple calls per block, only the last one will be checked!
+        #
         unless result.respond_to?(:ok?)
           raise ArgumentError,
                 "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"

data/lib/action/core/logging.rb

@@ -14,8 +14,9 @@ module Action
     end
 
     module ClassMethods
-      def log(message, level: :info)
-        level = :info if level == :debug && _targeted_for_debug_logging?
+      def default_log_level = Action.config.default_log_level
+
+      def log(message, level: default_log_level)
         msg = [_log_prefix, message].compact_blank.join(" ")
 
         Action.config.logger.send(level, msg)
@@ -29,13 +30,6 @@ module Action
 
       # TODO: this is ugly, we should be able to override in the config class...
       def _log_prefix = name == "Action::Configuration" ? nil : "[#{name || "Anonymous Class"}]"
-
-      def _targeted_for_debug_logging?
-        return true if Action.config.global_debug_logging?
-
-        target_class_names = (ENV["SA_DEBUG_TARGETS"] || "").split(",").map(&:strip)
-        target_class_names.include?(name)
-      end
     end
   end
 end

data/lib/action/core/swallow_exceptions.rb

@@ -15,8 +15,8 @@ module Action
         include InstanceMethods
         extend ClassMethods
 
-        def run_with_exception_swallowing!
-          original_run!
+        def run
+          run!
         rescue StandardError => e
           # on_error handlers run for both unhandled exceptions and fail!
           self.class._error_handlers.each do |handler|
@@ -25,31 +25,19 @@ module Action
 
           # on_failure handlers run ONLY for fail!
           if e.is_a?(Action::Failure)
+            @context.instance_variable_set("@error_from_user", e.message) if e.message.present?
+
             self.class._failure_handlers.each do |handler|
               handler.execute_if_matches(exception: e, action: self)
             end
+          else
+            # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
+            trigger_on_exception(e)
 
-            # TODO: avoid raising if this was passed along from a child action (esp. if wrapped in hoist_errors)
-            raise e
+            @context.exception = e
           end
 
-          # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
-          trigger_on_exception(e)
-
-          @context.exception = e
-
-          fail!
-        end
-
-        alias_method :original_run!, :run!
-        alias_method :run!, :run_with_exception_swallowing!
-
-        # Tweaked to check @context.object_id rather than context (since forwarding object_id causes Ruby to complain)
-        # TODO: do we actually need the object_id check? Do we need this override at all?
-        def run
-          run!
-        rescue Action::Failure => e
-          raise if @context.object_id != e.context.object_id
+          @context.instance_variable_set("@failure", true)
         end
 
         def trigger_on_exception(exception)
@@ -72,17 +60,12 @@ module Action
         end
 
         class << base
-          def call_bang_with_unswallowed_exceptions(context = {})
+          def call!(context = {})
             result = call(context)
             return result if result.ok?
 
-            raise result.exception if result.exception
-
-            raise Action::Failure.new(result.instance_variable_get("@context"), message: result.error)
+            raise result.exception || Action::Failure.new(result.error)
           end
-
-          alias_method :original_call!, :call!
-          alias_method :call!, :call_bang_with_unswallowed_exceptions
         end
       end
     end
@@ -162,8 +145,7 @@ module Action
         @context.instance_variable_set("@failure", true)
         @context.error_from_user = message if message.present?
 
-        # TODO: should we use context_for_logging here? But doublecheck the one place where we're checking object_id on it...
-        raise Action::Failure.new(@context, message:)
+        raise Action::Failure, message
       end
 
       def try

data/lib/action/core/top_level_around_hook.rb

@@ -6,46 +6,39 @@ module Action
       base.class_eval do
         around :__top_level_around_hook
 
+        extend AutologgingClassMethods
+        include AutologgingInstanceMethods
         include InstanceMethods
       end
     end
 
-    module InstanceMethods
-      def __top_level_around_hook(hooked)
-        timing_start = Time.now
-        _log_before
-
-        _configurable_around_wrapper do
-          (@outcome, @exception) = _call_and_return_outcome(hooked)
-        end
-
-        _log_after(timing_start:, outcome: @outcome)
-
-        raise @exception if @exception
-      end
+    module AutologgingClassMethods
+      def default_autolog_level = Action.config.default_autolog_level
+    end
 
+    module AutologgingInstanceMethods
       private
 
-      def _configurable_around_wrapper(&)
-        return yield unless Action.config.top_level_around_hook
-
-        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
-      end
-
       def _log_before
-        debug [
-          "About to execute",
-          context_for_logging(:inbound).presence&.inspect,
-        ].compact.join(" with: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "About to execute",
+            context_for_logging(:inbound).presence&.inspect,
+          ].compact.join(" with: "),
+        )
       end
 
       def _log_after(outcome:, timing_start:)
         elapsed_mils = ((Time.now - timing_start) * 1000).round(3)
 
-        debug [
-          "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
-          _log_after_data_peak,
-        ].compact.join(". Set: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
+            _log_after_data_peak,
+          ].compact.join(". Set: "),
+        )
       end
 
       def _log_after_data_peak
@@ -58,6 +51,29 @@ module Action
           return str[0, max_length - suffix.length] + suffix if str.length > max_length
         end
       end
+    end
+
+    module InstanceMethods
+      def __top_level_around_hook(hooked)
+        timing_start = Time.now
+        _log_before
+
+        _configurable_around_wrapper do
+          (@outcome, @exception) = _call_and_return_outcome(hooked)
+        end
+
+        _log_after(timing_start:, outcome: @outcome)
+
+        raise @exception if @exception
+      end
+
+      private
+
+      def _configurable_around_wrapper(&)
+        return yield unless Action.config.top_level_around_hook
+
+        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
+      end
 
       def _call_and_return_outcome(hooked)
         hooked.call

data/lib/action/enqueueable/enqueue_all_in_background.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module EnqueueAllInBackground
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def enqueue_all_in_background
+          raise NotImplementedError, "#{name} must implement a .enqueue_all method in order to use .enqueue_all_in_background" unless respond_to?(:enqueue_all)
+
+          ::Action::Enqueueable::EnqueueAllWorker.enqueue(klass_name: name)
+        end
+      end
+    end
+  end
+end

data/lib/action/enqueueable/enqueue_all_worker.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# NOTE: this is a standalone worker for enqueueing all instances of a class.
+# Unlike the other files in the folder, it is NOT included in the Action stack.
+
+# Note it uses Axn-native enqueueing, so will automatically support additional
+# backends as they are added (initially, just Sidekiq)
+
+module Action
+  module Enqueueable
+    class EnqueueAllWorker
+      include Action
+
+      expects :klass_name, type: String
+
+      def call
+        klass_name.constantize.enqueue_all
+      end
+    end
+  end
+end

data/lib/action/enqueueable/via_sidekiq.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module ViaSidekiq
+      def self.included(base)
+        base.class_eval do
+          begin
+            require "sidekiq"
+            include Sidekiq::Job
+          rescue LoadError
+            puts "Sidekiq not available -- skipping Enqueueable"
+            return
+          end
+
+          define_method(:perform) do |*args|
+            context = self.class._params_from_global_id(args.first)
+            bang = args.size > 1 ? args.last : false
+
+            if bang
+              self.class.call!(context)
+            else
+              self.class.call(context)
+            end
+          end
+
+          def self.enqueue(context = {})
+            perform_async(_process_context_to_sidekiq_args(context))
+          end
+
+          def self.enqueue!(context = {})
+            perform_async(_process_context_to_sidekiq_args(context), true)
+          end
+
+          def self.queue_options(opts)
+            opts = opts.transform_keys(&:to_s)
+            self.sidekiq_options_hash = get_sidekiq_options.merge(opts)
+          end
+
+          private
+
+          def self._process_context_to_sidekiq_args(context)
+            client = Sidekiq::Client.new
+
+            _params_to_global_id(context).tap do |args|
+              if client.send(:json_unsafe?, args).present?
+                raise ArgumentError,
+                      "Cannot pass non-JSON-serializable objects to Sidekiq. Make sure all expected arguments are serializable (or respond to to_global_id)."
+              end
+            end
+          end
+
+          def self._params_to_global_id(context)
+            context.stringify_keys.each_with_object({}) do |(key, value), hash|
+              if value.respond_to?(:to_global_id)
+                hash["#{key}_as_global_id"] = value.to_global_id.to_s
+              else
+                hash[key] = value
+              end
+            end
+          end
+
+          def self._params_from_global_id(params)
+            params.each_with_object({}) do |(key, value), hash|
+              if key.end_with?("_as_global_id")
+                hash[key.delete_suffix("_as_global_id")] = GlobalID::Locator.locate(value)
+              else
+                hash[key] = value
+              end
+            end.symbolize_keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/enqueueable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "enqueueable/via_sidekiq"
+require_relative "enqueueable/enqueue_all_in_background"
+
+module Action
+  module Enqueueable
+    extend ActiveSupport::Concern
+
+    included do
+      include ViaSidekiq
+      include EnqueueAllInBackground
+    end
+  end
+end

data/lib/axn/factory.rb

@@ -34,7 +34,6 @@ module Axn
         end
         raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
 
-        # TODO: is there any way to support default arguments? (if so, set allow_blank: true for those)
         if args[:key].present?
           raise ArgumentError,
                 "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
@@ -66,7 +65,7 @@ module Axn
             retval = instance_exec(**unwrapped_kwargs, &block)
             expose(expose_return_as => retval) if expose_return_as.present?
           end
-        end.tap do |axn| # rubocop: disable Style/MultilineBlockChain
+        end.tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end

data/lib/axn/version.rb

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

data/lib/axn.rb

@@ -13,11 +13,11 @@ require_relative "action/core/top_level_around_hook"
 require_relative "action/core/contract"
 require_relative "action/core/swallow_exceptions"
 require_relative "action/core/hoist_errors"
-require_relative "action/core/enqueueable"
 
 require_relative "axn/factory"
 
 require_relative "action/attachable"
+require_relative "action/enqueueable"
 
 def Axn(callable, **) # rubocop:disable Naming/MethodName
   return callable if callable.is_a?(Class) && callable < Action
@@ -42,10 +42,9 @@ module Action
 
       include HoistErrors
 
-      include Enqueueable
-
       # --- Extensions ---
       include Attachable
+      include Enqueueable
 
       # Allow additional automatic includes to be configured
       Array(Action.config.additional_includes).each { |mod| include mod }
@@ -62,3 +61,5 @@ module Action
     end
   end
 end
+
+require "action/enqueueable/enqueue_all_worker"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.4.1
+  version: 0.1.0.pre.alpha.2.5
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-04 00:00:00.000000000 Z
+date: 2025-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -92,13 +92,16 @@ files:
 - lib/action/core/context_facade.rb
 - lib/action/core/contract.rb
 - lib/action/core/contract_validator.rb
-- lib/action/core/enqueueable.rb
 - lib/action/core/event_handlers.rb
 - lib/action/core/exceptions.rb
 - lib/action/core/hoist_errors.rb
 - lib/action/core/logging.rb
 - lib/action/core/swallow_exceptions.rb
 - lib/action/core/top_level_around_hook.rb
+- lib/action/enqueueable.rb
+- lib/action/enqueueable/enqueue_all_in_background.rb
+- lib/action/enqueueable/enqueue_all_worker.rb
+- lib/action/enqueueable/via_sidekiq.rb
 - lib/axn.rb
 - lib/axn/factory.rb
 - lib/axn/version.rb

data/lib/action/core/enqueueable.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Enqueueable
-    def self.included(base)
-      base.class_eval do
-        begin
-          require "sidekiq"
-          include Sidekiq::Job
-        rescue LoadError
-          puts "Sidekiq not available -- skipping Enqueueable"
-          return
-        end
-
-        define_method(:perform) do |*args|
-          context = self.class._params_from_global_id(args.first)
-          bang = args.size > 1 ? args.last : false
-
-          if bang
-            self.class.call!(context)
-          else
-            self.class.call(context)
-          end
-        end
-
-        def self.enqueue(context = {})
-          perform_async(_process_context_to_sidekiq_args(context))
-        end
-
-        def self.enqueue!(context = {})
-          perform_async(_process_context_to_sidekiq_args(context), true)
-        end
-
-        def self.queue_options(opts)
-          opts = opts.transform_keys(&:to_s)
-          self.sidekiq_options_hash = get_sidekiq_options.merge(opts)
-        end
-
-        private
-
-        def self._process_context_to_sidekiq_args(context)
-          client = Sidekiq::Client.new
-
-          _params_to_global_id(context).tap do |args|
-            if client.send(:json_unsafe?, args).present?
-              raise ArgumentError,
-                    "Cannot pass non-JSON-serializable objects to Sidekiq. Make sure all objects in the context are serializable (or respond to to_global_id)."
-            end
-          end
-        end
-
-        def self._params_to_global_id(context)
-          context.stringify_keys.each_with_object({}) do |(key, value), hash|
-            if value.respond_to?(:to_global_id)
-              hash["#{key}_as_global_id"] = value.to_global_id.to_s
-            else
-              hash[key] = value
-            end
-          end
-        end
-
-        def self._params_from_global_id(params)
-          params.each_with_object({}) do |(key, value), hash|
-            if key.end_with?("_as_global_id")
-              hash[key.delete_suffix("_as_global_id")] = GlobalID::Locator.locate(value)
-            else
-              hash[key] = value
-            end
-          end.symbolize_keys
-        end
-      end
-    end
-  end
-end