axn 0.1.0.pre.alpha.2 → 0.1.0.pre.alpha.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6ba4df4f3ce11e1a31eb8dfadde856141ed9dc6d10002efe1b544abcb580431
-  data.tar.gz: 0a27844c8b7c341315c8a1d9212fa0745866086cd3fbb65140b813a125ac8496
+  metadata.gz: dcfb310e364c4fb2c7159a6bdc1ff6766c0025b3b0741a62316d3e18cb5f3bf7
+  data.tar.gz: 7af1c3d88a69c0d109983c85fb6dc1b5ddf162568ee1e1aa516f15bf1d12a1d2
 SHA512:
-  metadata.gz: 250b751b9a583d7206c9ada4e162ce8d2ee96816466515812e187e3dcdeb50f7024a595968c4e42f3f91a63909a38074e59b738a4f0216a0aaf1f15154e99452
-  data.tar.gz: cba3bee954fb153a99a65ff30478ae1d048fd49fe7834d4ba2446e4ff5e6ff70b3cfe588bc20a5d042665aa5bd9797cc4df10a4483cd59ce5b5d99b85bc4f645
+  metadata.gz: 13868e68f4a7b9a45bebbcf793bba1855ec2fa524ccd6f24fdaf1364bb143fcd4cfd862f0906d6455d10e61492b723ffbdc2c836a887052b030d509bf18171b0
+  data.tar.gz: 53014437d7a3972ec584195b2c20955ff9f2c1138dba3eeb35df2e82db8d62ec3b3561ec6b1d870472fc7fcea79dd1c2abe759cf341c46e024ae143d266bfa64

data/.rubocop.yml

@@ -48,7 +48,7 @@ Naming/MethodParameterName:
   AllowedNames: e
 
 Metrics/ParameterLists:
-  Max: 6
+  Max: 7
 
 Layout/LineLength:
   Max: 160

data/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
 ## UNRELEASED
-* N/A
 
+## 0.1.0-alpha.2.2
+* Expands `Action::Result.ok` and `Action::Result.error` to better support mocking in specs
+
+## 0.1.0-alpha.2.1
+* Expects/Exposes: Add `allow_nil` option
+* Expects/Exposes: Replace `boolean: true` with `type: :boolean`
+* Truncate default debug line at 100 chars
+* Support complex Axn::Factory configurations
+* Auto-generate self.class.name for attachables
 
 ## 0.1.0-alpha.2
 * Renamed `.rescues` to `.error_from`

data/docs/recipes/testing.md

@@ -4,7 +4,36 @@
 * TODO: document testing patterns
 :::
 
-Configuring rspec to treat files in spec/actions as service specs:
+## Mocking Axn calls
+
+Say you're writing unit specs for PrimaryAction that calls Subaction, and you want to mock out the Subaction call.
+
+To generate a successful Action::Result:
+
+* Base case: `Action::Result.ok`
+* [Optional] Custom message: `Action::Result.ok("It went awesome")`
+* [Optional] Custom exposures: `Action::Result.ok("It went awesome", some_var: 123)`
+
+To generate a failed Action::Result:
+
+* Base case: `Action::Result.error`
+* [Optional] Custom message: `Action::Result.error("It went poorly")`
+* [Optional] Custom exposures: `Action::Result.error("It went poorly", some_var: 123)`
+* [Optional] Custom exception: `Action::Result.error(some_var: 123) { raise FooBarException.new("bad thing") }`
+
+Either way, using those to mock an actual call would look something like this in your rspec:
+
+```ruby
+let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+
+before do
+  expect(Subaction).to receive(:call).and_return(subaction_response)
+end
+```
+
+## RSpec configuration
+
+Configuring rspec to treat files in spec/actions as service specs (very optional):
 
 ```ruby
 RSpec.configure do |config|

data/docs/reference/class.md

@@ -10,6 +10,7 @@ Both `expects` and `exposes` support the same core options:
 | -- | -- | -- |
 | `sensitive` | `expects :password, sensitive: true` | Filters the field's value when logging, reporting errors, or calling `inspect`
 | `default` | `expects :foo, default: 123` | If `foo` isn't explicitly set, it'll default to this value
+| `allow_nil` | `expects :foo, allow_nil: true` | Don't fail if the value is `nil`
 | `allow_blank` | `expects :foo, allow_blank: true` | Don't fail if the value is blank
 | `type` | `expects :foo, type: String` | Custom type validation -- fail unless `name.is_a?(String)`
 | anything else | `expects :foo, inclusion: { in: [:apple, :peach] }` | Any other arguments will be processed [as ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html) (i.e. as if passed to `validates :foo, <...>` on an ActiveRecord model)
@@ -21,9 +22,9 @@ Both `expects` and `exposes` support the same core options:
 While we _support_ complex interface validations, in practice you usually just want a `type`, if anything.  Remember this is your validation about how the action is called, _not_ pretty user-facing errors (there's [a different pattern for that](/recipes/validating-user-input)).
 :::
 
-In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support three additional custom validators:
+In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support two additional custom validators:
 * `type: Foo` - fails unless the provided value `.is_a?(Foo)`
-* `boolean: true` - wrapper to handle a boolean field (since ruby doesn't have a Boolean class, so we can't use `type:` directly)
+  * Edge case: use `type: :boolean` to handle a boolean field (since ruby doesn't have a Boolean class to pass in directly)
 * `validate: [callable]` - Support custom validations (fails if any string is returned OR if it raises an exception)
   * Example:
     ```ruby

data/docs/usage/writing.md

@@ -22,7 +22,7 @@ The first step is to determine what arguments you expect to be passed into `call
 
 If you want to expose any results to the caller, declare that via the `exposes` keyword.
 
-Both of these optionally accept `type:`, `allow_blank:`, and any other ActiveModel validation (see: [reference](/reference/class)).
+Both of these optionally accept `type:`, `allow_nil:`, `allow_blank:`, and any other ActiveModel validation (see: [reference](/reference/class)).
 
 
 ```ruby
@@ -116,6 +116,8 @@ If you define a `#rollback` method, it'll be called (_before_ returning an `Acti
 
 `before` and `after` hooks are also supported. They can receive a block directly, or the symbol name of a local method.
 
+Note execution is halted whenever `fail!` is called or an exception is raised (so a `before` block failure won't execute `call` or `after`, while an `after` block failure will make `resuilt.ok?` be false even though `call` completed successfully).
+
 ### Concrete example
 
 Given this series of methods and hooks:
@@ -129,7 +131,6 @@ class Foo
 
   def call
     log("in call")
-    raise "oh no something borked"
   end
 
   def rollback
@@ -140,6 +141,8 @@ class Foo
 
   def log_after
     log("after hook")
+    raise "oh no something borked"
+    log("after after hook raised")
   end
 end
 ```

data/lib/action/attachable/base.rb

@@ -35,7 +35,7 @@ module Action
             return axn_klass
           end
 
-          Axn::Factory.build(superclass: superclass || self, **kwargs, &block)
+          Axn::Factory.build(superclass: superclass || self, name:, **kwargs, &block)
         end
       end
     end

data/lib/action/attachable/subactions.rb

@@ -5,11 +5,18 @@ module Action
     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)
 
-          action_kwargs[:expose_return_as] ||= :value
+          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|
@@ -25,6 +32,8 @@ module Action
         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|
@@ -36,6 +45,24 @@ module Action
           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

data/lib/action/core/context_facade.rb

@@ -94,11 +94,21 @@ module Action
   class Result < ContextFacade
     # For ease of mocking return results in tests
     class << self
-      def ok = Class.new { include(Action) }.call
+      def ok(msg = nil, **exposures)
+        Axn::Factory.build(exposes: exposures.keys, messages: { success: msg }) do
+          exposures.each do |key, value|
+            expose(key, value)
+          end
+        end.call
+      end
 
-      def error(msg = "Something went wrong")
-        Class.new { include(Action) }.tap do |klass|
-          klass.define_method(:call) { fail!(msg) }
+      def error(msg = nil, **exposures, &block)
+        Axn::Factory.build(exposes: exposures.keys, messages: { error: msg }) do
+          exposures.each do |key, value|
+            expose(key, value)
+          end
+          block.call if block_given?
+          fail!
         end.call
       end
     end

data/lib/action/core/contract.rb

@@ -34,9 +34,9 @@ module Action
     FieldConfig = Data.define(:field, :validations, :default, :preprocess, :sensitive)
 
     module ClassMethods
-      def expects(*fields, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
+      def expects(*fields, allow_blank: false, allow_nil: false, default: nil, preprocess: nil, sensitive: false,
                   **validations)
-        _parse_field_configs(*fields, allow_blank:, default:, preprocess:, sensitive:, **validations).tap do |configs|
+        _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?
 
@@ -45,8 +45,8 @@ module Action
         end
       end
 
-      def exposes(*fields, allow_blank: false, default: nil, sensitive: false, **validations)
-        _parse_field_configs(*fields, allow_blank:, default:, preprocess: nil, sensitive:, **validations).tap do |configs|
+      def exposes(*fields, allow_blank: false, allow_nil: false, default: nil, sensitive: false, **validations)
+        _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?
 
@@ -63,7 +63,7 @@ module Action
         called! rollback! each_pair success? exception ok ok? error success message
       ].freeze
 
-      def _parse_field_configs(*fields, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
+      def _parse_field_configs(*fields, allow_nil: false, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
                                **validations)
         # 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)
@@ -78,10 +78,13 @@ module Action
             v = { value: v } unless v.is_a?(Hash)
             { allow_blank: true }.merge(v)
           end
-        elsif validations.key?(:boolean)
-          validations[:presence] = false
+        elsif allow_nil
+          validations.transform_values! do |v|
+            v = { value: v } unless v.is_a?(Hash)
+            { allow_nil: true }.merge(v)
+          end
         else
-          validations[:presence] = true unless validations.key?(:presence)
+          validations[:presence] = true unless validations.key?(:presence) || Array(validations[:type]).include?(:boolean)
         end
 
         fields.map { |field| FieldConfig.new(field:, validations:, default:, preprocess:, sensitive:) }

data/lib/action/core/contract_validator.rb

@@ -43,23 +43,21 @@ module Action
       end
     end
 
-    class BooleanValidator < ActiveModel::EachValidator
-      def validate_each(record, attribute, value)
-        return if [true, false].include?(value)
-
-        record.errors.add(attribute, "must be true or false")
-      end
-    end
-
     class TypeValidator < ActiveModel::EachValidator
       def validate_each(record, attribute, value)
-        return if value.blank? # Handled with a separate default presence validator
-
         # TODO: 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? { |type| value.is_a?(type) }
+        record.errors.add attribute, (options[:message] || msg) unless types.any? do |type|
+          if type == :boolean
+            [true, false].include?(value)
+          else
+            value.is_a?(type)
+          end
+        end
       end
     end
   end

data/lib/action/core/top_level_around_hook.rb

@@ -44,10 +44,21 @@ module Action
 
         debug [
           "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
-          context_for_logging(:outbound).presence&.inspect,
+          _log_after_data_peak,
         ].compact.join(". Set: ")
       end
 
+      def _log_after_data_peak
+        return unless (data = context_for_logging(:outbound)).present?
+
+        max_length = 100
+        suffix = "...<truncated>...}"
+
+        data.inspect.tap do |str|
+          return str[0, max_length - suffix.length] + suffix if str.length > max_length
+        end
+      end
+
       def _call_and_return_outcome(hooked)
         hooked.call
 

data/lib/axn/factory.rb

@@ -6,12 +6,13 @@ module Axn
       # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
       def build(
         # Builder-specific options
+        name: nil,
         superclass: nil,
         expose_return_as: :nil,
 
         # Expose standard class-level options
-        exposes: {},
-        expects: {},
+        exposes: [],
+        expects: [],
         messages: {},
         before: nil,
         after: nil,
@@ -21,7 +22,7 @@ module Axn
         rollback: nil,
         &block
       )
-        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, name), hash| hash[type] << name }
+        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
 
         if args[:opt].present? || args[:req].present? || args[:rest].present?
           raise ArgumentError,
@@ -38,32 +39,39 @@ module Axn
         expects = _hydrate_hash(expects)
         exposes = _hydrate_hash(exposes)
 
-        Array(args[:keyreq]).each do |name|
-          expects[name] ||= {}
+        Array(args[:keyreq]).each do |field|
+          expects[field] ||= {}
         end
 
         # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
         Class.new(superclass || Object) do
           include Action unless self < Action
 
+          define_singleton_method(:name) do
+            [
+              superclass&.name.presence || "AnonymousAction",
+              name,
+            ].compact.join("#")
+          end
+
           define_method(:call) do
-            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |name, hash|
-              hash[name] = public_send(name)
+            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |field, hash|
+              hash[field] = public_send(field)
             end
 
             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
-          expects.each do |name, opts|
-            axn.expects(name, **opts)
+          expects.each do |field, opts|
+            axn.expects(field, **opts)
           end
 
-          exposes.each do |name, opts|
-            axn.exposes(name, **opts)
+          exposes.each do |field, opts|
+            axn.exposes(field, **opts)
           end
 
-          axn.messages(**messages) if messages.present?
+          axn.messages(**messages) if messages.present? && messages.values.any?(&:present?)
 
           # Hooks
           axn.before(before) if before.present?
@@ -94,7 +102,13 @@ module Axn
         return given if given.is_a?(Hash)
 
         Array(given).each_with_object({}) do |key, acc|
-          acc[key] = {}
+          if key.is_a?(Hash)
+            key.each_key do |k|
+              acc[k] = key[k]
+            end
+          else
+            acc[key] = {}
+          end
         end
       end
     end

data/lib/axn/version.rb

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

metadata

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