axn 0.1.0.pre.alpha.2.5.1.1 → 0.1.0.pre.alpha.2.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb044bed464d8840289e69cb631ff47ebc44999ac7e6327fc3b69dd62a37a6af
-  data.tar.gz: 0f0db9209a545ac84b88df56aaeaea431e6094385c433775f8d3f6501d84e870
+  metadata.gz: 6902996eda6bf8911d2f90f73217d56a0905ddf0772ebfee3a9c2bbf8072279e
+  data.tar.gz: 3615981ef31731e017b2b9399b485290041b1a79cc0ccc231c189399ddb4e5f4
 SHA512:
-  metadata.gz: df227aa350f02e53d8141fec5bd6855ed31c1da64ec9b6567ce3906b86fce2bc6b1b4bc24a38042b565da8c7bee6df0ed95fd0bd1ab5afa8b722397ce10b5f09
-  data.tar.gz: 35b54feff70f62f1b18e9dbe9b0ac066ee6c1b13118f871e9b4bf36a8949661410886b4ac97e019f5c3a89c5f3082c9cebe0008a12c5fc810cbea418ef1c99bc
+  metadata.gz: 1f9ae2c8d65defac13be5abded734bdcf1057e8d880878d8cf4c57c58ef537d257a7a96208fe83616ce8ddc89344c60042b9eadbe8575b52d14fa9fa9981489e
+  data.tar.gz: bcbf95ea1e179a44076cb5b451f0ab1f94001bccb30bd78fd3fbbd025472fb08bed4cda805cf934ab6f3328f4aced08a96ff4983142aeed67c7121ecddd11e2b

data/.rubocop.yml

@@ -27,12 +27,18 @@ Style/TrailingCommaInArrayLiteral:
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma
 
+Style/ClassAndModuleChildren:
+  Enabled: false
+
 Style/DoubleNegation:
   Enabled: false
 
 Metrics/BlockLength:
   Enabled: false
 
+Metrics/ModuleLength:
+  Enabled: false
+
 Metrics/MethodLength:
   Max: 60
 

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+* N/A
+
+## 0.1.0-alpha.2.5.2
+* [BREAKING] Removing `EnqueueAllInBackground` + `EnqueueAllWorker` - better + simply solved at application level
+* [TEST] Expose spec helpers to consumers (add `require "axn/testing/spec_helpers"` to your `spec_helper.rb`)
+# [FEAT] Added ability to use custom Strategies (via e.g. `use :transaction`)
+
+## 0.1.0-alpha.2.5.1.2
+* [BUGFIX] Subfield expectations: now support hashes with string keys (using with_indifferent_access)
+* [BUGFIX] Subfield expectations: Model reader fields now cache initial value (otherwise get fresh instance each call, cannot make in-memory changes)
+
 ## 0.1.0-alpha.2.5.1.1
 * [BUGFIX] TypeValidator must handle anonymous classes when determining if given argument is an RSpec mock
 

data/docs/.vitepress/config.mjs

@@ -47,6 +47,13 @@ export default defineConfig({
           { text: 'Testing Actions', link: '/recipes/testing' },
         ]
       },
+      {
+        text: 'Strategies',
+        items: [
+          { text: 'Overview', link: '/strategies/index' },
+          { text: 'Transaction', link: '/strategies/transaction' },
+        ]
+      },
       {
         text: 'Additional Notes',
         items: [

data/docs/strategies/index.md

@@ -0,0 +1,272 @@
+# Strategies
+
+Strategies in Axn are reusable modules that provide common functionality and configuration patterns for your actions. They allow you to DRY up your code by encapsulating frequently used behaviors into named, configurable modules.
+
+## What are Strategies?
+
+Strategies are Ruby modules that can be included into your actions to add specific functionality. They're designed to be:
+
+- **Reusable**: Once defined, they can be used across multiple actions
+- **Configurable**: Many strategies support configuration options
+- **Composable**: You can use multiple strategies in a single action
+- **Discoverable**: Built-in strategies are automatically loaded, and custom ones can be registered
+
+## How to Use Strategies
+
+### Basic Usage
+
+To use a strategy in your action, call the `use` method with the strategy name:
+
+```ruby
+class CreateUser
+  include Action
+
+  use :transaction
+
+  expects :email, :name
+
+  def call
+    # This action will now run within a database transaction (including before/after hooks)
+    user = User.create!(email: email, name: name)
+    expose :user, user
+  end
+end
+```
+
+### Using Strategies with Configuration
+
+Some strategies support configuration options. These strategies have a `setup` method that accepts configuration and returns a configured module.  As an _imaginary_ example:
+
+```ruby
+class ProcessPayment
+  include Action
+
+  use :retry, max_attempts: 3, backoff: :exponential
+
+  expects :amount, :card_token
+
+  def call
+    # This action will retry up to 3 times with exponential backoff
+    result = PaymentProcessor.charge(amount, card_token)
+    expose :transaction_id, result.id
+  end
+end
+```
+
+## Built-in Strategies
+
+The list of built in strategies is available via `Action::Strategies.built_in`.
+
+## Registering Custom Strategies
+
+### Simple Strategies
+
+To create a custom strategy, define a module that extends `ActiveSupport::Concern`:
+
+```ruby
+module MyCustomStrategy
+  extend ActiveSupport::Concern
+
+  included do
+    # Add your strategy behavior here
+    # For example, add hooks, validations, or other functionality
+    before { log("Custom strategy before hook") }
+    after { log("Custom strategy after hook") }
+  end
+end
+```
+
+Then register it with the strategies system:
+
+```ruby
+Action::Strategies.register(:my_custom, MyCustomStrategy)
+```
+
+Now you can use it in your actions:
+
+```ruby
+class MyAction
+  include Action
+
+  use :my_custom
+
+  def call
+    # Your action implementation
+  end
+end
+```
+
+### Configurable Strategies
+
+For strategies that need configuration, implement a `setup` method that returns a configured module:
+
+```ruby
+module RetryStrategy
+  extend ActiveSupport::Concern
+
+  def self.setup(max_attempts: 3, backoff: :linear, &block)
+    Module.new do
+      extend ActiveSupport::Concern
+
+      included do
+        around do |hooked|
+          attempts = 0
+          begin
+            attempts += 1
+            hooked.call
+          rescue StandardError => e
+            if attempts < max_attempts
+              sleep(backoff_delay(attempts, backoff))
+              retry
+            else
+              raise e
+            end
+          end
+        end
+      end
+
+      private
+
+      def backoff_delay(attempt, type)
+        case type
+        when :linear
+          attempt * 0.1
+        when :exponential
+          0.1 * (2 ** (attempt - 1))
+        else
+          0.1
+        end
+      end
+    end
+  end
+end
+
+# Register the strategy
+Action::Strategies.register(:retry, RetryStrategy)
+```
+
+### Strategy Registration Best Practices
+
+1. **Register early**: Register custom strategies during application initialization
+2. **Use descriptive names**: Choose strategy names that clearly indicate their purpose
+3. **Handle configuration validation**: Validate configuration options in your `setup` method
+4. **Return proper modules**: Always return a module from the `setup` method
+5. **Document your strategies**: Include clear documentation for how to use your custom strategies
+
+### Example: Complete Custom Strategy
+
+Here's a complete example of a custom strategy that adds performance monitoring:
+
+```ruby
+module PerformanceMonitoringStrategy
+  extend ActiveSupport::Concern
+
+  def self.setup(threshold_ms: 1000, notify_slow: false, &block)
+    Module.new do
+      extend ActiveSupport::Concern
+
+      included do
+        around do |hooked|
+          start_time = Time.current
+          result = hooked.call
+          duration = ((Time.current - start_time) * 1000).round(2)
+
+          if duration > threshold_ms
+            log("Action took #{duration}ms (threshold: #{threshold_ms}ms)", level: :warn)
+            notify_slow_action(duration) if notify_slow
+          else
+            log("Action completed in #{duration}ms", level: :info)
+          end
+
+          result
+        end
+      end
+
+      private
+
+      def notify_slow_action(duration)
+        # In a real implementation, this might send to a monitoring service
+        # like New Relic, DataDog, or a custom alerting system
+        Rails.logger.warn("SLOW ACTION ALERT: #{self.class.name} took #{duration}ms")
+      end
+    end
+  end
+end
+
+# Register the strategy
+Action::Strategies.register(:performance_monitoring, PerformanceMonitoringStrategy)
+
+# Use it in an action
+class ExpensiveCalculation
+  include Action
+
+  use :performance_monitoring, threshold_ms: 500, notify_slow: true
+
+  expects :data
+
+  def call
+    # This action will be monitored for performance
+    result = perform_expensive_calculation(data)
+    expose :result, result
+  end
+
+  private
+
+  def perform_expensive_calculation(data)
+    # Simulate expensive operation
+    sleep(0.1)
+    data.map { |item| item * 2 }
+  end
+end
+```
+
+## Strategy Management
+
+### Viewing Available Strategies
+
+You can inspect all registered strategies:
+
+```ruby
+Action::Strategies.all
+# Returns a hash of strategy names to their modules
+```
+
+### Finding Specific Strategies
+
+To find a specific strategy by name:
+
+```ruby
+Action::Strategies.find(:transaction)
+# Returns the strategy module for the transaction strategy
+
+Action::Strategies.find(:nonexistent)
+# Raises Action::StrategyNotFound: Strategy 'nonexistent' not found
+```
+
+The `find` method is useful when you need to programmatically access a strategy module or verify that a strategy exists before using it.
+
+### Clearing Strategies
+
+To reset strategies to only built-in ones (useful in tests):
+
+```ruby
+Action::Strategies.clear!
+```
+
+### Strategy Errors
+
+The following errors may be raised when using strategies:
+
+- `Action::StrategyNotFound`: When trying to use a strategy that hasn't been registered
+- `Action::DuplicateStrategyError`: When trying to register a strategy with a name that's already taken
+- `ArgumentError`: When providing configuration to a strategy that doesn't support it
+
+## Best Practices
+
+1. **Keep strategies focused**: Each strategy should have a single, well-defined responsibility
+2. **Use meaningful names**: Strategy names should clearly indicate their purpose
+3. **Document configuration**: If your strategy accepts configuration, document all available options
+4. **Test your strategies**: Write tests for your custom strategies to ensure they work correctly
+5. **Consider composition**: Design strategies to work well together when used in combination
+
+

data/docs/strategies/transaction.md

@@ -0,0 +1,29 @@
+# Transaction Strategy
+
+The `transaction` strategy wraps your action execution in a database transaction:
+
+```ruby
+class TransferFunds
+  include Action
+
+  use :transaction
+
+  expects :from_account, :to_account, :amount
+
+  def call
+    from_account.withdraw!(amount)
+    to_account.deposit!(amount)
+    expose :transfer_id, SecureRandom.uuid
+  end
+end
+```
+
+**Important**: The transaction wraps the entire action execution, including:
+- `before` hooks
+- The main `call` method
+- `after` hooks
+- Success/failure callbacks (`on_success`, `on_failure`, etc.)
+
+This means that if any part of the action (including hooks or callbacks) raises an exception or calls `fail!`, the entire transaction will be rolled back.
+
+**Requirements**: Requires ActiveRecord to be available in your application.

data/docs/usage/using.md

@@ -55,33 +55,3 @@ 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/docs/usage/writing.md

@@ -154,5 +154,5 @@ after hook
 
 A number of custom callback are available for you as well, if you want to take specific actions when a given Axn succeeds or fails. See the [Class Interface docs](/reference/class#callbacks) for details.
 
-## Debugging
-Remember you can [enable debug logging](/reference/configuration.html#global-debug-logging) to print log lines before and after each action is executed.
+## Strategies
+A number of [Strategies](/strategies), 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/core/contract.rb

@@ -109,6 +109,17 @@ module Action
         end
       end
 
+      def define_memoized_reader_method(field, &block)
+        define_method(field) do
+          ivar = :"@_memoized_reader_#{field}"
+          cached_val = instance_variable_get(ivar)
+          return cached_val if cached_val.present?
+
+          value = instance_exec(&block)
+          instance_variable_set(ivar, value)
+        end
+      end
+
       def _define_field_reader(field)
         # 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)
@@ -120,7 +131,7 @@ module Action
         raise ArgumentError, "Model validation expects to be given a field ending in _id (given: #{field})" unless field.to_s.end_with?("_id")
         raise ArgumentError, "Failed to define model reader - #{name} is already defined" if method_defined?(name)
 
-        define_method(name) do
+        define_memoized_reader_method(name) do
           Validators::ModelValidator.instance_for(field:, klass:, id: public_send(field))
         end
       end

data/lib/action/core/contract_for_subfields.rb

@@ -82,22 +82,11 @@ module Action
         raise ArgumentError, "expects does not support duplicate sub-keys (i.e. `#{field}` is already defined)" if method_defined?(field)
 
         define_memoized_reader_method(field) do
-          public_send(on).fetch(field)
+          Action::Validation::Subfields.extract(field, public_send(on))
         end
 
         _define_model_reader(field, validations[:model]) if validations.key?(:model)
       end
-
-      def define_memoized_reader_method(field, &block)
-        define_method(field) do
-          ivar = :"@_memoized_reader_#{field}"
-          cached_val = instance_variable_get(ivar)
-          return cached_val if cached_val.present?
-
-          value = instance_exec(&block)
-          instance_variable_set(ivar, value)
-        end
-      end
     end
 
     module InstanceMethods

data/lib/action/core/use_strategy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Action
+  module UseStrategy
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def use(strategy_name, **config, &block)
+        strategy = Action::Strategies.all[strategy_name.to_sym]
+        raise StrategyNotFound, "Strategy #{strategy_name} not found" if strategy.blank?
+        raise ArgumentError, "Strategy #{strategy_name} does not support config" if config.any? && !strategy.respond_to?(:setup)
+
+        # Allow dynamic setup of strategy (i.e. dynamically define module before returning)
+        if strategy.respond_to?(:setup)
+          configured = strategy.setup(**config, &block)
+          raise ArgumentError, "Strategy #{strategy_name} setup method must return a module" unless configured.is_a?(Module)
+
+          strategy = configured
+        else
+          raise ArgumentError, "Strategy #{strategy_name} does not support config (define #setup method)" if config.any?
+          raise ArgumentError, "Strategy #{strategy_name} does not support blocks (define #setup method)" if block_given?
+        end
+
+        include strategy
+      end
+    end
+  end
+end

data/lib/action/enqueueable.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "enqueueable/via_sidekiq"
-require_relative "enqueueable/enqueue_all_in_background"
 
 module Action
   module Enqueueable
@@ -9,7 +8,6 @@ module Action
 
     included do
       include ViaSidekiq
-      include EnqueueAllInBackground
     end
   end
 end

data/lib/action/strategies/transaction.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Action
+  class Strategies
+    module Transaction
+      extend ActiveSupport::Concern
+
+      included do
+        raise NotImplementedError, "Transaction strategy requires ActiveRecord" unless defined?(ActiveRecord)
+
+        around do |hooked|
+          ActiveRecord::Base.transaction do
+            hooked.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/strategies.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Action
+  class StrategyNotFound < StandardError; end
+  class DuplicateStrategyError < StandardError; end
+
+  class Strategies
+    # rubocop:disable Style/ClassVars
+    class << self
+      def built_in
+        return @@built_in if defined?(@@built_in)
+
+        strategy_files = Dir[File.join(__dir__, "strategies", "*.rb")]
+        strategy_files.each { |file| require file }
+
+        constants = Action::Strategies.constants.map { |const| Action::Strategies.const_get(const) }
+        mods = constants.select { |const| const.is_a?(Module) }
+
+        @@built_in = mods.to_h { |mod| [mod.name.split("::").last.downcase.to_sym, mod] }
+      end
+
+      def register(name, strategy)
+        all # ensure built_in is initialized
+        key = name.to_sym
+        raise DuplicateStrategyError, "Strategy #{name} already registered" if @@strategies.key?(key)
+
+        @@strategies[key] = strategy
+        @@strategies
+      end
+
+      def all
+        @@strategies ||= built_in.dup
+      end
+
+      def clear!
+        @@strategies = built_in.dup
+      end
+
+      def find(name)
+        raise StrategyNotFound, "Strategy name cannot be nil" if name.nil?
+        raise StrategyNotFound, "Strategy name cannot be empty" if name.to_s.strip.empty?
+
+        all[name.to_sym] or raise StrategyNotFound, "Strategy '#{name}' not found"
+      end
+    end
+    # rubocop:enable Style/ClassVars
+  end
+end

data/lib/axn/testing/spec_helpers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rspec"
+
+module Axn
+  module Testing
+    module SpecHelpers
+      def build_action(&block)
+        action = Class.new.send(:include, Action)
+        action.class_eval(&block) if block
+        action
+      end
+
+      def build_axn(**, &)
+        Axn::Factory.build(**, &)
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Axn::Testing::SpecHelpers
+end

data/lib/axn/version.rb

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

data/lib/axn.rb

@@ -18,11 +18,13 @@ require_relative "action/core/contract"
 require_relative "action/core/contract_for_subfields"
 require_relative "action/core/swallow_exceptions"
 require_relative "action/core/hoist_errors"
+require_relative "action/core/use_strategy"
 
 require_relative "axn/factory"
 
 require_relative "action/attachable"
 require_relative "action/enqueueable"
+require_relative "action/strategies"
 
 def Axn(callable, **) # rubocop:disable Naming/MethodName
   return callable if callable.is_a?(Class) && callable < Action
@@ -48,6 +50,8 @@ module Action
 
       include HoistErrors
 
+      include UseStrategy
+
       # --- Extensions ---
       include Attachable
       include Enqueueable
@@ -67,5 +71,3 @@ 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.5.1.1
+  version: 0.1.0.pre.alpha.2.5.2
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-26 00:00:00.000000000 Z
+date: 2025-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -81,6 +81,8 @@ files:
 - docs/reference/class.md
 - docs/reference/configuration.md
 - docs/reference/instance.md
+- docs/strategies/index.md
+- docs/strategies/transaction.md
 - docs/usage/setup.md
 - docs/usage/using.md
 - docs/usage/writing.md
@@ -98,17 +100,19 @@ files:
 - lib/action/core/logging.rb
 - lib/action/core/swallow_exceptions.rb
 - lib/action/core/top_level_around_hook.rb
+- lib/action/core/use_strategy.rb
 - lib/action/core/validation/fields.rb
 - lib/action/core/validation/subfields.rb
 - lib/action/core/validation/validators/model_validator.rb
 - lib/action/core/validation/validators/type_validator.rb
 - lib/action/core/validation/validators/validate_validator.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/action/strategies.rb
+- lib/action/strategies/transaction.rb
 - lib/axn.rb
 - lib/axn/factory.rb
+- lib/axn/testing/spec_helpers.rb
 - lib/axn/version.rb
 - package.json
 - yarn.lock

data/lib/action/enqueueable/enqueue_all_in_background.rb

@@ -1,17 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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