axn 0.1.0.pre.alpha.2.8 → 0.1.0.pre.alpha.3

data/.rubocop.yml

@@ -1,76 +0,0 @@
-# RuboCop cops are not loaded by default in this repo
-# Downstream consumers can enable them by adding:
-# require:
-#   - axn/rubocop
-
-AllCops:
-  TargetRubyVersion: 3.2
-  SuggestExtensions: false
-  NewCops: enable
-
-Style/MultilineBlockChain:
-  Enabled: false
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/Documentation:
-  Enabled: false
-
-Style/TrailingCommaInArguments:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInArrayLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInHashLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/HashSyntax:
-  EnforcedShorthandSyntax: always
-
-Style/DoubleNegation:
-  Enabled: false
-
-Metrics/BlockLength:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/MethodLength:
-  Max: 70
-
-Metrics/PerceivedComplexity:
-  Max: 20
-
-Metrics/AbcSize:
-  Max: 60
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-
-Lint/EmptyBlock:
-  Enabled: false
-
-Naming/MethodParameterName:
-  AllowedNames: e, on, id, if
-
-Metrics/ParameterLists:
-  Max: 9
-
-Layout/LineLength:
-  Max: 160
-
-

data/.tool-versions

@@ -1 +0,0 @@
-ruby 3.3.6

data/docs/reference/action-result.md

@@ -1,37 +0,0 @@
-# `Action::Result`
-
-Every `call` invocation on an Action will return an `Action::Result` instance, which provides a consistent interface:
-
-| Method | Description |
-| -- | -- |
-| `ok?` | `true` if the call succeeded, `false` if not.
-| `error` | User-facing error message (string), if not `ok?` (else nil)
-| `success` | User-facing success message (string), if `ok?` (else nil)
-| `message` | User-facing message (string), always defined (`ok? ? success : error`)
-| `exception` | If not `ok?` because an exception was swallowed, will be set to the swallowed exception (note: rarely used outside development; prefer to let the library automatically handle exception handling for you)
-| `outcome` | The execution outcome as a string inquirer (`success?`, `failure?`, `exception?`)
-| `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 `success` and `error` declarations](/reference/class#success-and-error).
-
-### Clarification of exposed values
-
-In addition to the core interface, your Action's Result class will have methods defined to read the values of any attributes that were explicitly exposed.  For example, given this action and result:
-
-
-```ruby
-class Foo
-  include Action
-
-  exposes :bar, :baz # [!code focus]
-
-  def call
-    expose bar: 1, baz: 2
-  end
-end
-
-result = Foo.call # [!code focus]
-```
-
-`result` will have both `bar` and `baz` reader methods (which will return 1 and 2, respectively).

data/lib/action/attachable/base.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Attachable
-    module Base
-      extend ActiveSupport::Concern
-
-      class_methods do
-        def axn_for_attachment(
-          attachment_type: "Action",
-          name: nil,
-          axn_klass: nil,
-          superclass: nil,
-          **kwargs,
-          &block
-        )
-          raise ArgumentError, "#{attachment_type} name must be a string or symbol" unless name.is_a?(String) || name.is_a?(Symbol)
-          raise ArgumentError, "#{attachment_type} '#{name}' must be given an existing action class or a block" if axn_klass.nil? && !block_given?
-
-          if axn_klass && block_given?
-            raise ArgumentError,
-                  "#{attachment_type} '#{name}' was given both an existing action class and a block - only one is allowed"
-          end
-
-          if axn_klass
-            unless axn_klass.respond_to?(:<) && axn_klass < Action
-              raise ArgumentError,
-                    "#{attachment_type} '#{name}' was given an already-existing class #{axn_klass.name} that does NOT inherit from Action as expected"
-            end
-
-            if kwargs.present?
-              raise ArgumentError, "#{attachment_type} '#{name}' was given an existing action class and also keyword arguments - only one is allowed"
-            end
-
-            return axn_klass
-          end
-
-          Axn::Factory.build(superclass: superclass || self, name:, **kwargs, &block)
-        end
-      end
-    end
-  end
-end

data/lib/action/attachable/steps.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Attachable
-    module Steps
-      extend ActiveSupport::Concern
-
-      included do
-        class_attribute :_axn_steps, default: []
-      end
-
-      class_methods do
-        def steps(*steps)
-          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, error_prefix: nil, **kwargs, &block)
-          axn_klass = axn_for_attachment(
-            name:,
-            axn_klass:,
-            attachment_type: "Step",
-            superclass: Object, # NOTE: steps skip inheriting from the wrapping class (to avoid duplicate field expectations/exposures)
-            **kwargs,
-            &block
-          )
-
-          # Add the step to the list of steps
-          _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
-        _axn_steps.each do |axn|
-          _merge_step_exposures!(axn.call!(**_merged_context_data))
-        end
-      end
-
-      private
-
-      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)
-        step_result.declared_fields.each do |field|
-          @__context.exposed_data[field] = step_result.public_send(field)
-        end
-      end
-    end
-  end
-end

data/lib/action/attachable/subactions.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Attachable
-    module Subactions
-      extend ActiveSupport::Concern
-
-      included do
-        class_attribute :_axnable_methods, default: {}
-        class_attribute :_axns, default: {}
-      end
-
-      class_methods do
-        def axnable_method(name, axn_klass = nil, **action_kwargs, &block)
-          raise ArgumentError, "Unable to attach Axn -- '#{name}' is already taken" if respond_to?(name)
-
-          self._axnable_methods = _axnable_methods.merge(name => { axn_klass:, action_kwargs:, block: })
-
-          action_kwargs[:expose_return_as] ||= :value unless axn_klass
-          axn_klass = axn_for_attachment(name:, axn_klass:, **action_kwargs, &block)
-
-          define_singleton_method("#{name}_axn") do |**kwargs|
-            axn_klass.call(**kwargs)
-          end
-
-          define_singleton_method("#{name}!") do |**kwargs|
-            result = axn_klass.call!(**kwargs)
-            result.public_send(action_kwargs[:expose_return_as])
-          end
-        end
-
-        def axn(name, axn_klass = nil, **action_kwargs, &block)
-          raise ArgumentError, "Unable to attach Axn -- '#{name}' is already taken" if respond_to?(name)
-
-          self._axns = _axns.merge(name => { axn_klass:, action_kwargs:, block: })
-
-          axn_klass = axn_for_attachment(name:, axn_klass:, **action_kwargs, &block)
-
-          define_singleton_method(name) do |**kwargs|
-            axn_klass.call(**kwargs)
-          end
-
-          # 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)
-          end
-
-          self._axns = _axns.merge(name => axn_klass)
-        end
-
-        def inherited(subclass)
-          super
-
-          return unless subclass.name.present? # TODO: not sure why..
-
-          # Need to redefine the axnable methods on the subclass to ensure they properly reference the subclass's
-          # helper method definitions and not the superclass's.
-          _axnable_methods.each do |name, config|
-            subclass.axnable_method(name, config[:axn_klass], **config[:action_kwargs], &config[:block])
-          end
-
-          _axns.each do |name, config|
-            subclass.axn(name, config[:axn_klass], **config[:action_kwargs], &config[:block])
-          end
-        end
-      end
-    end
-  end
-end

data/lib/action/attachable.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "action/attachable/base"
-require "action/attachable/steps"
-require "action/attachable/subactions"
-
-module Action
-  module Attachable
-    extend ActiveSupport::Concern
-
-    included do
-      include Base
-      include Steps
-      include Subactions
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/parameter_filter"
-
-module Action
-  class ContextFacade
-    def initialize(action:, context:, declared_fields:, implicitly_allowed_fields: nil)
-      if self.class.name == "Action::ContextFacade" # rubocop:disable Style/ClassEqualityComparison
-        raise "Action::ContextFacade is an abstract class and should not be instantiated directly"
-      end
-
-      @context = context
-      @action = action
-      @declared_fields = declared_fields
-
-      (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
-        singleton_class.define_method(field) do
-          _context_data_source[field]
-        end
-      end
-    end
-
-    attr_reader :declared_fields
-
-    def inspect = ContextFacadeInspector.new(facade: self, action:, context:).call
-
-    def fail!(...)
-      raise Action::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
-    end
-
-    private
-
-    attr_reader :action, :context
-
-    def action_name = @action.class.name.presence || "The action"
-
-    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/flow/handlers.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Core
-    module Flow
-      module Handlers
-      end
-    end
-  end
-end
-
-require "action/core/flow/handlers/base_descriptor"
-require "action/core/flow/handlers/matcher"
-require "action/core/flow/handlers/resolvers/base_resolver"
-require "action/core/flow/handlers/descriptors/message_descriptor"
-require "action/core/flow/handlers/descriptors/callback_descriptor"
-require "action/core/flow/handlers/invoker"
-require "action/core/flow/handlers/resolvers/callback_resolver"
-require "action/core/flow/handlers/registry"
-require "action/core/flow/handlers/resolvers/message_resolver"

data/lib/action/core/tracing.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Core
-    module Tracing
-      private
-
-      def _with_tracing(&)
-        return yield unless Action.config.wrap_with_trace
-
-        Action.config.wrap_with_trace.call(self.class.name || "AnonymousClass", &)
-      rescue StandardError => e
-        Axn::Util.piping_error("running trace hook", action: self, exception: e)
-      end
-    end
-  end
-end

data/lib/action/core/use_strategy.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Core
-    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
-end

data/lib/action/core/validation/validators/model_validator.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-require "active_model"
-
-module Action
-  module Validators
-    class ModelValidator < ActiveModel::EachValidator
-      def self.model_for(field:, klass: nil)
-        return klass if defined?(ActiveRecord::Base) && klass.is_a?(ActiveRecord::Base)
-
-        field.to_s.delete_suffix("_id").classify.constantize
-      end
-
-      def self.instance_for(field:, klass:, id:)
-        klass = model_for(field:, klass:)
-        return unless klass.respond_to?(:find_by)
-
-        klass.find_by(id:)
-      end
-
-      def validate_each(record, attribute, id)
-        klass = self.class.model_for(field: attribute, klass: options[:with])
-        instance = self.class.instance_for(field: attribute, klass:, id:)
-        return if instance.present?
-
-        msg = id.blank? ? "not found (given a blank ID)" : "not found for class #{klass.name} and ID #{id}"
-        record.errors.add(attribute, msg)
-      rescue StandardError => e
-        Axn::Util.piping_error("applying model validation on field '#{attribute}'", exception: e)
-        record.errors.add(attribute, "error raised while trying to find a valid #{klass.name}")
-      end
-    end
-  end
-end

data/lib/action/core/validation/validators/type_validator.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "active_model"
-
-module Action
-  module Validators
-    class TypeValidator < ActiveModel::EachValidator
-      def validate_each(record, attribute, value)
-        # 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
-
-        msg = types.size == 1 ? "is not a #{types.first}" : "is not one of #{types.join(", ")}"
-        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
-            # NOTE: allow mocks to pass type validation by default (much easier testing ergonomics)
-            next true if Action.config.env.test? && value.class.name&.start_with?("RSpec::Mocks::")
-
-            value.is_a?(type)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/action/core.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-require "action/context"
-
-require "action/strategies"
-require "action/core/hooks"
-require "action/core/logging"
-require "action/core/flow"
-require "action/core/automatic_logging"
-require "action/core/use_strategy"
-require "action/core/timing"
-require "action/core/tracing"
-require "action/core/nesting_tracking"
-
-# CONSIDER: make class names match file paths?
-require "action/core/validation/validators/model_validator"
-require "action/core/validation/validators/type_validator"
-require "action/core/validation/validators/validate_validator"
-
-require "action/core/contract_validation"
-require "action/core/contract"
-require "action/core/contract_for_subfields"
-
-module Action
-  module Core
-    def self.included(base)
-      base.class_eval do
-        extend ClassMethods
-        include Core::Hooks
-        include Core::Logging
-        include Core::AutomaticLogging
-        include Core::Tracing
-        include Core::Timing
-
-        include Core::Flow
-
-        include Core::ContractValidation
-        include Core::Contract
-        include Core::ContractForSubfields
-        include Core::NestingTracking
-
-        include Core::UseStrategy
-      end
-    end
-
-    module ClassMethods
-      def call(**)
-        new(**).tap(&:_run).result
-      end
-
-      def call!(**)
-        result = call(**)
-        return result if result.ok?
-
-        # When we're nested, we want to raise a failure that includes the source action to support
-        # the error message generation's `from` filter
-        raise Action::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
-
-        raise result.exception
-      end
-    end
-
-    def initialize(**)
-      @__context = Action::Context.new(**)
-    end
-
-    # Main entry point for action execution
-    def _run
-      _tracking_nesting(self) do
-        _with_tracing do
-          _with_logging do
-            _with_timing do
-              _with_exception_handling do # Exceptions stop here; outer wrappers access result status (and must not introduce another exception layer)
-                _with_contract do # Library internals -- any failures (e.g. contract violations) *should* fail the Action::Result
-                  _with_hooks do # User hooks -- any failures here *should* fail the Action::Result
-                    call
-                  end
-                end
-              end
-            end
-          end
-        end
-      end
-    ensure
-      _emit_metrics
-    end
-
-    # User-defined action logic - override this method in your action classes
-    def call; end
-
-    def fail!(message = nil)
-      raise Action::Failure, message
-    end
-
-    private
-
-    def _emit_metrics
-      return unless Action.config.emit_metrics
-
-      Action.config.emit_metrics.call(
-        self.class.name || "AnonymousClass",
-        result,
-      )
-    rescue StandardError => e
-      Axn::Util.piping_error("running metrics hook", action: self, exception: e)
-    end
-  end
-end

data/lib/action/enqueueable/via_sidekiq.rb

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