axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/{action → axn}/core/contract_for_subfields.rb

@@ -1,22 +1,17 @@
 # frozen_string_literal: true
 
-require "action/core/validation/subfields"
+require "axn/core/validation/subfields"
 
-module Action
+module Axn
   module Core
     module ContractForSubfields
-      # TODO: add default, preprocess, sensitive options for subfields?
-      # SubfieldConfig = Data.define(:field, :validations, :default, :preprocess, :sensitive)
-      SubfieldConfig = Data.define(:field, :validations, :on)
+      SubfieldConfig = Data.define(:field, :validations, :on, :sensitive, :preprocess, :default)
 
       def self.included(base)
         base.class_eval do
           class_attribute :subfield_configs, default: []
 
           extend ClassMethods
-          include InstanceMethods
-
-          before { _validate_subfields_contract! }
         end
       end
 
@@ -27,19 +22,13 @@ module Action
           readers: true,
           allow_blank: false,
           allow_nil: false,
-
-          # TODO: add support for these three options for subfields
+          optional: false,
           default: nil,
           preprocess: nil,
           sensitive: false,
 
           **validations
         )
-          # TODO: add support for these three options for subfields
-          raise ArgumentError, "expects does not support :default key when also given :on" if default.present?
-          raise ArgumentError, "expects does not support :preprocess key when also given :on" if preprocess.present?
-          raise ArgumentError, "expects does not support :sensitive key when also given :on" if sensitive.present?
-
           unless internal_field_configs.map(&:field).include?(on) || subfield_configs.map(&:field).include?(on)
             raise ArgumentError,
                   "expects called with `on: #{on}`, but no such method exists (are you sure you've declared `expects :#{on}`?)"
@@ -47,10 +36,10 @@ module Action
 
           raise ArgumentError, "expects does not support expecting fields on nested attributes (i.e. `on` cannot contain periods)" if on.to_s.include?(".")
 
-          # TODO: consider adding support for default, preprocess, sensitive options for subfields?
-          _parse_subfield_configs(*fields, on:, readers:, allow_blank:, allow_nil:, **validations).tap do |configs|
+          _parse_subfield_configs(*fields, on:, readers:, allow_blank:, allow_nil:, optional:, preprocess:, sensitive:, default:,
+                                           **validations).tap do |configs|
             duplicated = subfield_configs.map(&:field) & configs.map(&:field)
-            raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
+            raise Axn::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(', ')}" if duplicated.any?
 
             # NOTE: avoid <<, which would update value for parents and children
             self.subfield_configs += configs
@@ -65,14 +54,18 @@ module Action
           readers:,
           allow_blank: false,
           allow_nil: false,
-          # default: nil,
-          # preprocess: nil,
-          # sensitive: false,
+          optional: false,
+          preprocess: nil,
+          sensitive: false,
+          default: nil,
           **validations
         )
+          # Handle optional: true by setting allow_blank: true
+          allow_blank ||= optional
+
           _parse_field_validations(*fields, allow_nil:, allow_blank:, **validations).map do |field, parsed_validations|
             _define_subfield_reader(field, on:, validations: parsed_validations) if readers
-            SubfieldConfig.new(field:, validations: parsed_validations, on:)
+            SubfieldConfig.new(field:, validations: parsed_validations, on:, sensitive:, preprocess:, default:)
           end
         end
 
@@ -82,24 +75,26 @@ 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
-            Action::Validation::Subfields.extract(field, public_send(on))
+          Axn::Util::Memoization.define_memoized_reader_method(self, field) do
+            Axn::Core::FieldResolvers.resolve(type: :extract, field:, provided_data: public_send(on))
           end
 
-          _define_model_reader(field, validations[:model]) { Action::Validation::Subfields.extract(field, public_send(on)) } if validations.key?(:model)
+          _define_subfield_model_reader(field, validations[:model], on:) if validations.key?(:model)
         end
-      end
 
-      module InstanceMethods
-        def _validate_subfields_contract!
-          return if subfield_configs.blank?
+        def _define_subfield_model_reader(field, options, on:)
+          # Apply the same syntactic sugar processing as the main contract system
+          processed_options = Axn::Validators::ModelValidator.apply_syntactic_sugar(options, [field])
+
+          Axn::Util::Memoization.define_memoized_reader_method(self, field) do
+            # Create a data source that contains the subfield data for the resolver
+            subfield_data = public_send(on)
 
-          subfield_configs.each do |config|
-            Validation::Subfields.validate!(
-              field: config.field,
-              validations: config.validations,
-              source: public_send(config.on),
-              exception_klass: Action::InboundValidationError,
+            Axn::Core::FieldResolvers.resolve(
+              type: :model,
+              field:,
+              options: processed_options,
+              provided_data: subfield_data,
             )
           end
         end

data/lib/{action → axn}/core/contract_validation.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module ContractValidation
       private
@@ -10,11 +10,16 @@ module Action
           next unless config.preprocess
 
           initial_value = @__context.provided_data[config.field]
-          new_value = config.preprocess.call(initial_value)
-          @__context.provided_data[config.field] = new_value
-        rescue StandardError => e
-          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}", cause: e
+          @__context.provided_data[config.field] = Axn::Util::ContractErrorHandling.with_contract_error_handling(
+            exception_class: Axn::ContractViolation::PreprocessingError,
+            message: ->(field, error) { "Error preprocessing field '#{field}': #{error.message}" },
+            field_identifier: config.field,
+          ) do
+            instance_exec(initial_value, &config.preprocess)
+          end
         end
+
+        _apply_inbound_preprocessing_for_subfields!
       end
 
       def _validate_contract!(direction)
@@ -25,9 +30,12 @@ module Action
           hash[config.field] = config.validations
         end
         context = direction == :inbound ? internal_context : result
-        exception_klass = direction == :inbound ? Action::InboundValidationError : Action::OutboundValidationError
+        exception_klass = direction == :inbound ? Axn::InboundValidationError : Axn::OutboundValidationError
 
         Validation::Fields.validate!(validations:, context:, exception_klass:)
+
+        # Validate subfields for inbound direction
+        _validate_subfields_contract! if direction == :inbound
       end
 
       def _apply_defaults!(direction)
@@ -37,9 +45,9 @@ module Action
           # For outbound defaults, first copy values from provided_data for fields that are both expected and exposed
           external_field_configs.each do |config|
             field = config.field
-            next if @__context.exposed_data[field].present? # Already has a value
+            next if @__context.exposed_data.key?(field) # Already has a value
 
-            @__context.exposed_data[field] = @__context.provided_data[field] if @__context.provided_data[field].present?
+            @__context.exposed_data[field] = @__context.provided_data[field] if @__context.provided_data.key?(field)
           end
         end
 
@@ -50,12 +58,19 @@ module Action
 
         defaults_mapping.each do |field, default_value_getter|
           data_hash = direction == :inbound ? @__context.provided_data : @__context.exposed_data
-          next if data_hash[field].present?
+          next if data_hash.key?(field) && !data_hash[field].nil?
 
-          default_value = default_value_getter.respond_to?(:call) ? instance_exec(&default_value_getter) : default_value_getter
-
-          data_hash[field] = default_value
+          data_hash[field] = Axn::Util::ContractErrorHandling.with_contract_error_handling(
+            exception_class: Axn::ContractViolation::DefaultAssignmentError,
+            message: ->(field_name, error) { "Error applying default for field '#{field_name}': #{error.message}" },
+            field_identifier: field,
+          ) do
+            default_value_getter.respond_to?(:call) ? instance_exec(&default_value_getter) : default_value_getter
+          end
         end
+
+        # Apply subfield defaults for inbound direction
+        _apply_defaults_for_subfields! if direction == :inbound
       end
     end
   end

data/lib/axn/core/contract_validation_for_subfields.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module ContractValidationForSubfields
+      private
+
+      # Applies preprocessing to all subfield configurations
+      def _apply_inbound_preprocessing_for_subfields!
+        _for_each_relevant_subfield_config(:preprocess) do |config, parent_field, subfield, parent_value|
+          current_subfield_value = Axn::Core::FieldResolvers.resolve(type: :extract, field: subfield, provided_data: parent_value)
+          preprocessed_value = Axn::Util::ContractErrorHandling.with_contract_error_handling(
+            exception_class: Axn::ContractViolation::PreprocessingError,
+            message: ->(_field, error) { "Error preprocessing subfield '#{config.field}' on '#{config.on}': #{error.message}" },
+            field_identifier: "#{config.field} on #{config.on}",
+          ) do
+            instance_exec(current_subfield_value, &config.preprocess)
+          end
+          _update_subfield_value(parent_field, subfield, preprocessed_value)
+        end
+      end
+
+      # Applies default values to all subfield configurations
+      def _apply_defaults_for_subfields!
+        _for_each_relevant_subfield_config(:default) do |config, parent_field, subfield, parent_value|
+          next if parent_value && !Axn::Core::FieldResolvers.resolve(type: :extract, field: subfield, provided_data: parent_value).nil?
+
+          @__context.provided_data[parent_field] = {} if parent_value.nil?
+
+          default_value = Axn::Util::ContractErrorHandling.with_contract_error_handling(
+            exception_class: Axn::ContractViolation::DefaultAssignmentError,
+            message: ->(_field, error) { "Error applying default for subfield '#{config.field}' on '#{config.on}': #{error.message}" },
+            field_identifier: "#{config.field} on #{config.on}",
+          ) do
+            config.default.respond_to?(:call) ? instance_exec(&config.default) : config.default
+          end
+          _update_subfield_value(parent_field, subfield, default_value)
+        end
+      end
+
+      # Validates all subfield configurations against their defined validations
+      def _validate_subfields_contract!
+        _for_each_relevant_subfield_config do |config, parent_field, subfield, _parent_value|
+          Validation::Subfields.validate!(
+            field: subfield,
+            validations: config.validations,
+            source: public_send(parent_field),
+            exception_klass: Axn::InboundValidationError,
+            action: self,
+          )
+        end
+      end
+
+      #
+      # Here down - helpers for the above methods
+      #
+
+      # Iterates over subfield configurations, optionally filtered by attribute, yielding to a block
+      def _for_each_relevant_subfield_config(attribute = nil)
+        subfield_configs.each do |config|
+          next if attribute && !config.public_send(attribute)
+
+          parent_field = config.on
+          subfield = config.field
+          parent_value = @__context.provided_data[parent_field]
+
+          yield(config, parent_field, subfield, parent_value)
+        end
+      end
+
+      # Updates a subfield value, handling nested paths, hash objects, and method-based setters
+      def _update_subfield_value(parent_field, subfield, new_value)
+        parent_value = @__context.provided_data[parent_field]
+
+        if _is_nested_subfield?(subfield)
+          _update_nested_subfield_value(parent_field, subfield, new_value)
+        elsif parent_value.is_a?(Hash)
+          _update_simple_hash_subfield(parent_field, subfield, new_value)
+        elsif parent_value.respond_to?("#{subfield}=")
+          _update_object_subfield(parent_value, subfield, new_value)
+        end
+      end
+
+      # Checks if a subfield path contains nested access (e.g., "user.profile.name")
+      def _is_nested_subfield?(subfield) = subfield.to_s.include?(".")
+
+      # Parses a subfield path into an array of parts
+      def _parse_subfield_path(subfield) = subfield.to_s.split(".")
+
+      # Updates a simple hash subfield value
+      def _update_simple_hash_subfield(parent_field, subfield, new_value)
+        parent_value = @__context.provided_data[parent_field].dup
+        parent_value[subfield] = new_value
+        @__context.provided_data[parent_field] = parent_value
+      end
+
+      # Updates an object subfield using method assignment
+      def _update_object_subfield(parent_value, subfield, new_value)
+        parent_value.public_send("#{subfield}=", new_value)
+      end
+
+      # Updates a nested subfield value by navigating the path and creating intermediate hashes
+      def _update_nested_subfield_value(parent_field, subfield, new_value)
+        parent_value = @__context.provided_data[parent_field]
+        path_parts = _parse_subfield_path(subfield)
+
+        target_parent = _navigate_to_parent(parent_value, path_parts)
+        target_parent[path_parts.last.to_sym] = new_value
+      end
+
+      # Navigates to the parent of the target field, creating intermediate hashes as needed
+      def _navigate_to_parent(parent_value, path_parts)
+        path_parts[0..-2].reduce(parent_value) do |current, part|
+          current[part.to_sym] || current[part] || (current[part.to_sym] = {})
+        end
+      end
+
+      # Checks if a subfield exists in the parent value, handling both hash and object types
+      def _subfield_exists?(parent_value, subfield)
+        if parent_value.is_a?(Hash)
+          _hash_subfield_exists?(parent_value, subfield)
+        elsif parent_value.respond_to?(subfield)
+          _object_subfield_exists?(parent_value, subfield)
+        else
+          false
+        end
+      end
+
+      # Checks if a subfield exists in a hash, handling both simple and nested paths
+      def _hash_subfield_exists?(parent_value, subfield)
+        if _is_nested_subfield?(subfield)
+          _nested_hash_subfield_exists?(parent_value, subfield)
+        else
+          _simple_hash_subfield_exists?(parent_value, subfield)
+        end
+      end
+
+      # Checks if a simple (non-nested) hash subfield exists
+      def _simple_hash_subfield_exists?(parent_value, subfield)
+        parent_value.key?(subfield.to_sym) || parent_value.key?(subfield)
+      end
+
+      # Checks if a nested hash subfield exists by navigating the path
+      def _nested_hash_subfield_exists?(parent_value, subfield)
+        path_parts = _parse_subfield_path(subfield)
+        current = parent_value
+
+        path_parts.each do |part|
+          return false unless current.is_a?(Hash)
+          return false unless current.key?(part.to_sym) || current.key?(part)
+
+          current = current[part.to_sym] || current[part]
+        end
+
+        true
+      end
+
+      # Checks if an object subfield exists (not nil)
+      # This ensures we apply defaults for nil values on objects
+      def _object_subfield_exists?(parent_value, subfield)
+        !parent_value.public_send(subfield).nil?
+      end
+    end
+  end
+end

data/lib/axn/core/default_call.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    # Default implementation of the call method that automatically exposes
+    # all declared exposures by calling methods with matching names.
+    module DefaultCall
+      # User-defined action logic - override this method in your action classes
+      # Default implementation automatically exposes all declared exposures by calling
+      # methods with matching names. Raises if a method is missing and no default is provided.
+      def call
+        return if self.class.external_field_configs.empty?
+
+        exposures = {}
+
+        self.class.external_field_configs.each do |config|
+          field = config.field
+          # Check if field is optional (allow_blank or no presence validation)
+          is_optional = _field_is_optional?(config)
+
+          # If method exists, call it (user-defined methods override auto-generated ones)
+          # The auto-generated method for exposed-only fields returns nil (field not in provided_data)
+          next unless respond_to?(field, true)
+
+          value = send(field)
+          # If it returns nil and it's an exposed-only field with no default,
+          # it's likely the auto-generated method (user methods can also return nil, but
+          # we'll assume it's auto-generated in this case)
+          is_exposed_only = !self.class.internal_field_configs.map(&:field).include?(field)
+          is_not_in_provided = !@__context.provided_data.key?(field)
+
+          # Only expose if we have a value, or if it's nil but there's a default
+          # If it's nil and optional, don't expose - let validation handle it
+          if value.nil? && is_exposed_only && is_not_in_provided && config.default.nil? && !is_optional
+            # This is the auto-generated method returning nil for a required field
+            # Don't expose it - let outbound validation catch the missing exposure
+          else
+            exposures[field] = value unless value.nil? && config.default.nil?
+          end
+          # If method doesn't exist:
+          # - If optional, skip it - validation will handle it
+          # - If not optional and no default, skip it - let outbound validation catch it
+          # - If there's a default, skip it - the default will be applied later
+        end
+
+        expose(**exposures) if exposures.any?
+      end
+
+      private
+
+      def _field_is_optional?(config)
+        validations = config.validations
+        # Field is optional if:
+        # 1. It doesn't have presence: true validation (presence is the default for non-optional fields)
+        # 2. Any validator has allow_blank: true
+        return true unless validations.key?(:presence) && validations[:presence] == true
+
+        # Check if any validator has allow_blank: true
+        validations.values.any? { |v| v.is_a?(Hash) && v[:allow_blank] == true }
+      end
+    end
+  end
+end

data/lib/axn/core/field_resolvers/extract.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+
+module Axn
+  module Core
+    module FieldResolvers
+      class Extract
+        def initialize(field:, provided_data:, options: {})
+          @field = field
+          @options = options
+          @provided_data = provided_data
+        end
+
+        def call
+          # Handle method calls if the source responds to the field
+          return provided_data.public_send(field) if provided_data.respond_to?(field)
+
+          # For hash-like objects, use digging with indifferent access
+          raise "Unclear how to extract #{field} from #{provided_data.inspect}" unless provided_data.respond_to?(:dig)
+
+          base = provided_data.respond_to?(:with_indifferent_access) ? provided_data.with_indifferent_access : provided_data
+          base.dig(*field.to_s.split("."))
+        end
+
+        private
+
+        attr_reader :field, :options, :provided_data
+      end
+    end
+  end
+end

data/lib/axn/core/field_resolvers/model.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module FieldResolvers
+      class Model
+        def initialize(field:, options:, provided_data:)
+          @field = field
+          @options = options
+          @provided_data = provided_data
+        end
+
+        def call
+          provided_value.presence || derive_value
+        end
+
+        private
+
+        attr_reader :field, :options, :provided_data
+
+        def provided_value
+          @provided_value ||= provided_data[field]
+        end
+
+        def derive_value
+          return nil if id_value.blank?
+
+          # Handle different finder types
+          if finder.is_a?(Method)
+            # Method object - call it directly
+            finder.call(id_value)
+          elsif klass.respond_to?(finder)
+            # Symbol/string method name on the klass
+            klass.public_send(finder, id_value)
+          else
+            raise "Unknown finder: #{finder}"
+          end
+        rescue StandardError => e
+          # Log the exception but don't re-raise
+          finder_name = finder.is_a?(Method) ? finder.name : finder
+          Axn::Internal::Logging.piping_error("finding #{field} with #{finder_name}", exception: e)
+          nil
+        end
+
+        def klass
+          @klass ||= options[:klass]
+        end
+
+        def finder
+          @finder ||= options[:finder]
+        end
+
+        def id_field
+          @id_field ||= :"#{field}_id"
+        end
+
+        def id_value
+          @id_value ||= provided_data[id_field]
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/field_resolvers.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "axn/core/field_resolvers/model"
+require "axn/core/field_resolvers/extract"
+
+module Axn
+  module Core
+    module FieldResolvers
+      # Registry for field resolvers
+      # This allows us to easily add new field types in the future
+      RESOLVERS = {
+        model: FieldResolvers::Model,
+        extract: FieldResolvers::Extract,
+      }.freeze
+
+      def self.resolve(type:, field:, provided_data:, options: {})
+        resolver_class = RESOLVERS[type]
+        raise ArgumentError, "Unknown field resolver type: #{type}" unless resolver_class
+
+        resolver_class.new(field:, options:, provided_data:).call
+      end
+    end
+  end
+end

data/lib/{action → axn}/core/flow/callbacks.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers"
-require "action/core/flow/handlers/resolvers/callback_resolver"
+require "axn/core/flow/handlers"
+require "axn/core/flow/handlers/resolvers/callback_resolver"
 
-module Action
+module Axn
   module Core
     module Flow
       module Callbacks
         def self.included(base)
           base.class_eval do
-            class_attribute :_callbacks_registry, default: Action::Core::Flow::Handlers::Registry.empty
+            class_attribute :_callbacks_registry, default: Axn::Core::Flow::Handlers::Registry.empty
 
             extend ClassMethods
           end
@@ -18,7 +18,7 @@ module Action
         module ClassMethods
           # Internal dispatcher
           def _dispatch_callbacks(event_type, action:, exception: nil)
-            resolver = Action::Core::Flow::Handlers::Resolvers::CallbackResolver.new(
+            resolver = Axn::Core::Flow::Handlers::Resolvers::CallbackResolver.new(
               _callbacks_registry,
               event_type,
               action:,
@@ -48,12 +48,12 @@ module Action
             raise ArgumentError, "on_#{event_type} must be called with a block or symbol" unless block || handler
 
             # If handler is already a descriptor, use it directly
-            entry = if handler.is_a?(Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+            entry = if handler.is_a?(Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
                       raise ArgumentError, "Cannot pass additional configuration with prebuilt descriptor" if kwargs.any? || block
 
                       handler
                     else
-                      Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor.build(
+                      Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor.build(
                         handler: handler || block,
                         **kwargs,
                       )

data/lib/{action → axn}/core/flow/exception_execution.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module Flow
       module ExceptionExecution
@@ -10,14 +10,15 @@ module Action
 
             def _trigger_on_exception(exception)
               # Call any handlers registered on *this specific action* class
+              # (handlers can call context_for_logging themselves if needed)
               self.class._dispatch_callbacks(:exception, action: self, exception:)
 
               # Call any global handlers
-              Action.config.on_exception(exception, action: self, context: context_for_logging)
+              Axn.config.on_exception(exception, action: self, context: context_for_logging)
             rescue StandardError => e
               # No action needed -- downstream #on_exception implementation should ideally log any internal failures, but
               # we don't want exception *handling* failures to cascade and overwrite the original exception.
-              Axn::Util.piping_error("executing on_exception hooks", action: self, exception: e)
+              Axn::Internal::Logging.piping_error("executing on_exception hooks", action: self, exception: e)
             end
 
             def _trigger_on_success
@@ -32,6 +33,10 @@ module Action
 
           def _with_exception_handling
             yield
+          rescue Axn::Internal::EarlyCompletion
+            # Early completion is not an error - it's a control flow mechanism
+            # It should propagate through to be handled by the result builder
+            raise
           rescue StandardError => e
             @__context.__record_exception(e)
 
@@ -39,22 +44,13 @@ module Action
             self.class._dispatch_callbacks(:error, action: self, exception: e)
 
             # on_failure handlers run ONLY for fail!
-            if e.is_a?(Action::Failure)
+            if e.is_a?(Axn::Failure)
               self.class._dispatch_callbacks(:failure, action: self, exception: e)
             else
               # on_exception handlers run for ONLY for unhandled exceptions.
               _trigger_on_exception(e)
             end
           end
-
-          def try
-            yield
-          rescue Action::Failure => e
-            # NOTE: re-raising so we can still fail! from inside the block
-            raise e
-          rescue StandardError => e
-            _trigger_on_exception(e)
-          end
         end
       end
     end

data/lib/{action → axn}/core/flow/handlers/base_descriptor.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/matcher"
+require "axn/core/flow/handlers/matcher"
 
-module Action
+module Axn
   module Core
     module Flow
       # "Handlers" doesn't feel like *quite* the right name for this, but basically things in this namespace
@@ -12,6 +12,7 @@ module Action
           def initialize(matcher: nil, handler: nil)
             @matcher = matcher
             @handler = handler
+            freeze
           end
 
           attr_reader :handler, :matcher