servactory 3.1.0.rc3 → 3.1.0.rc4

data/lib/servactory/context/workspace.rb

@@ -8,7 +8,7 @@ module Servactory
 
         def initialize(context)
           @class_name = context.class.name
-          @i18n_root_key = context.config.i18n_root_key
+          @i18n_root_key = context.class.config.i18n_root_key
         end
 
         def translate(key, **options)
@@ -42,11 +42,11 @@ module Servactory
       end
 
       def success!
-        raise config.success_class.new(context: self)
+        raise self.class.config.success_class.new(context: self)
       end
 
       def fail_input!(input_name, message:, meta: nil)
-        raise config.input_exception_class.new(
+        raise self.class.config.input_exception_class.new(
           context: self,
           input_name:,
           message:,
@@ -55,7 +55,7 @@ module Servactory
       end
 
       def fail_internal!(internal_name, message:, meta: nil)
-        raise config.internal_exception_class.new(
+        raise self.class.config.internal_exception_class.new(
           context: self,
           internal_name:,
           message:,
@@ -64,7 +64,7 @@ module Servactory
       end
 
       def fail_output!(output_name, message:, meta: nil)
-        raise config.output_exception_class.new(
+        raise self.class.config.output_exception_class.new(
           context: self,
           output_name:,
           message:,
@@ -73,7 +73,7 @@ module Servactory
       end
 
       def fail!(type = :base, message:, meta: nil)
-        raise config.failure_class.new(type:, message:, meta:)
+        raise self.class.config.failure_class.new(type:, message:, meta:)
       end
 
       def fail_result!(service_result)
@@ -118,7 +118,7 @@ module Servactory
       end
 
       def call
-        raise config.failure_class.new(
+        raise self.class.config.failure_class.new(
           type: :base,
           message: servactory_service_info.translate(
             "methods.call.not_used"

data/lib/servactory/info/builder.rb

@@ -26,7 +26,7 @@ module Servactory
 
       private
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def build_all_attributes(inputs:, internals:, outputs:, stages:, config:)
         build_input_attributes_with(
           collection: inputs,
@@ -45,7 +45,6 @@ module Servactory
 
         build_action_stages_with(collection: stages)
       end
-      # rubocop:enable Metrics/MethodLength
 
       def build_input_attributes_with(collection:, dynamic_options:)
         @inputs = build_attributes_with(
@@ -142,11 +141,13 @@ module Servactory
       end
 
       def enrich_options_with_common_fields(attribute:, options:)
+        types = attribute.collection_of_options.find_by(name: :types)
         must = attribute.collection_of_options.find_by(name: :must)
 
         options.merge(
           actor: attribute.actor,
-          types: attribute.types,
+          type: { is: types.value, message: types.body[:message] },
+          types: types.value,
           must: must&.value
         )
       end

data/lib/servactory/inputs/dsl.rb

@@ -18,12 +18,16 @@ module Servactory
         private
 
         def input(name, *helpers, **options)
-          collection_of_inputs << Input.new(
+          input = Input.new(
             name,
             *helpers,
             option_helpers: config.input_option_helpers,
             **options
           )
+
+          raise ArgumentError, "[#{self.name}] Input `#{name}` must have the `type` option" if input.types.empty?
+
+          collection_of_inputs << input
         end
 
         def collection_of_inputs

data/lib/servactory/inputs/input.rb

@@ -52,7 +52,7 @@ module Servactory
 
       attr_reader :internal_name
 
-      # rubocop:disable Style/KeywordParametersOrder
+      # rubocop:disable-next Style/KeywordParametersOrder
       def initialize(
         name,
         *helpers,
@@ -64,7 +64,6 @@ module Servactory
 
         super(name, *helpers, option_helpers:, **options)
       end
-      # rubocop:enable Style/KeywordParametersOrder
 
       def conflict_code
         @collection_of_options.defined_conflict_code

data/lib/servactory/internals/dsl.rb

@@ -17,12 +17,18 @@ module Servactory
         private
 
         def internal(name, *helpers, **options)
-          collection_of_internals << Internal.new(
+          internal = Internal.new(
             name,
             *helpers,
             option_helpers: config.internal_option_helpers,
             **options
           )
+
+          if internal.types.empty?
+            raise ArgumentError, "[#{self.name}] Internal attribute `#{name}` must have the `type` option"
+          end
+
+          collection_of_internals << internal
         end
 
         def collection_of_internals

data/lib/servactory/maintenance/attributes/base.rb

@@ -39,8 +39,11 @@ module Servactory
           @collection_of_options = options_registrar.collection
         end
 
+        # @deprecated Use collection_of_options.validations_for_checks instead.
         def options_for_checks
-          @collection_of_options.options_for_checks
+          warn "[DEPRECATION] Servactory::Maintenance::Attributes::Base#options_for_checks is deprecated. " \
+               "Use collection_of_options.validations_for_checks instead."
+          @collection_of_options.send(:check_options_by_key)
         end
 
         def system_name

data/lib/servactory/maintenance/attributes/collection.rb

@@ -13,6 +13,10 @@ module Servactory
       # how attributes are indexed and filtered (e.g., inputs use `internal_name`
       # for the `as:` parameter).
       #
+      # An attribute is declared once per name: adding an attribute whose
+      # `name` is already declared (e.g., redeclaring a parent's input in
+      # a child service) replaces the earlier declaration in place.
+      #
       # ## Usage
       #
       # Subclasses are used internally by Input, Internal, and Output DSL modules
@@ -32,16 +36,15 @@ module Servactory
       #
       # The collection uses memoization for frequently accessed data:
       # - `attributes_index` - cached hash for O(1) lookups by name
+      # - `declarations_index` - cached hash for O(1) redeclaration checks
       #
       class Collection
         extend Forwardable
 
         def_delegators :@collection,
-                       :<<,
                        :filter,
                        :each, :each_with_object,
-                       :map, :to_h,
-                       :merge
+                       :map, :to_h
 
         # Initializes the collection with an optional pre-built Set.
         #
@@ -51,6 +54,50 @@ module Servactory
           @collection = collection
         end
 
+        # Duplicates the collection, resetting memoized caches.
+        #
+        # @param original [Collection] the collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+          @attributes_index = nil
+          @declarations_index = nil
+        end
+
+        # Adds an attribute to the collection, invalidating the index cache.
+        #
+        # An attribute with an already declared `name` replaces
+        # the earlier declaration in place, keeping its position.
+        #
+        # @param attribute [Object] the attribute to add
+        # @return [Collection] self
+        def <<(attribute)
+          redeclared = declarations_index[attribute.name]
+
+          if redeclared.nil?
+            @collection << attribute
+          else
+            @collection = Set.new(@collection) { |declared| declared.equal?(redeclared) ? attribute : declared }
+          end
+
+          declarations_index[attribute.name] = attribute
+          @attributes_index = nil
+          self
+        end
+
+        # Merges attributes from another collection, invalidating the index cache.
+        #
+        # Each attribute is added as with `<<`, so redeclarations replace
+        # the earlier declarations in place.
+        #
+        # @param other [Collection, Enumerable] attributes to merge
+        # @return [Collection] self
+        def merge(other)
+          other.each { |attribute| self << attribute }
+          self
+        end
+
         # Returns names of all attributes in the collection.
         #
         # @return [Array<Symbol>] list of attribute names
@@ -88,9 +135,17 @@ module Servactory
         #
         # @return [Hash{Symbol => Object}] attribute names mapped to attribute instances
         def attributes_index
-          @attributes_index ||= each_with_object({}) do |attribute, index|
-            index[lookup_name(attribute)] = attribute
-          end
+          @attributes_index ||= to_h { |attribute| [lookup_name(attribute), attribute] }
+        end
+
+        # Builds and caches a hash index of declared attributes by `name`.
+        #
+        # Unlike `attributes_index`, it is keyed by the declared name
+        # (the external name for inputs), which identifies a redeclaration.
+        #
+        # @return [Hash{Symbol => Object}] declared names mapped to attribute instances
+        def declarations_index
+          @declarations_index ||= to_h { |attribute| [attribute.name, attribute] }
         end
 
         # Returns the name used for indexing and filtering a given attribute.

data/lib/servactory/maintenance/options/collection.rb

@@ -28,15 +28,13 @@ module Servactory
       # ## Performance
       #
       # The collection uses memoization for frequently accessed data:
-      # - `validation_classes` - cached list of unique validation classes
-      # - `options_for_checks` - cached hash for validation pipeline
+      # - `validations_for_checks` - cached tuples for validation pipeline
       # - `options_index` - cached hash for O(1) lookups by name
       #
       class Collection
         extend Forwardable
 
         def_delegators :@collection,
-                       :<<,
                        :filter,
                        :each, :each_with_object,
                        :map,
@@ -50,6 +48,26 @@ module Servactory
           @collection = Set.new
         end
 
+        # Duplicates the collection, resetting memoized caches.
+        #
+        # @param original [Collection] the collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+          reset_memoized_caches
+        end
+
+        # Adds an option to the collection, invalidating memoized caches.
+        #
+        # @param option [Option] the option to add
+        # @return [Collection] self
+        def <<(option)
+          @collection << option
+          reset_memoized_caches
+          self
+        end
+
         # Returns all option names in the collection.
         #
         # @return [Array<Symbol>] list of option names
@@ -57,23 +75,22 @@ module Servactory
           map(&:name)
         end
 
-        # Returns unique validation classes from all options.
+        # @deprecated Use {#validations_for_checks} instead.
         #
         # @return [Array<Class>] deduplicated list of validation classes
         def validation_classes
-          @validation_classes ||=
-            filter { |option| option.validation_class.present? }
-            .map(&:validation_class)
-            .uniq
+          warn "[DEPRECATION] Servactory::Maintenance::Options::Collection#validation_classes is deprecated. " \
+               "Use #validations_for_checks instead."
+          validations_for_checks.map(&:last).uniq
         end
 
-        # Returns options that need validation checks as a hash.
+        # @deprecated Use {#validations_for_checks} instead.
         #
         # @return [Hash{Symbol => Object}] option names mapped to normalized bodies
         def options_for_checks
-          @options_for_checks ||= filter(&:need_for_checks?).to_h do |option|
-            [option.name, extract_normalized_body_from(option:)]
-          end
+          warn "[DEPRECATION] Servactory::Maintenance::Options::Collection#options_for_checks is deprecated. " \
+               "Use #validations_for_checks instead."
+          check_options_by_key
         end
 
         # Returns options that need validation checks as an array of tuples.
@@ -115,13 +132,27 @@ module Servactory
 
         private
 
+        # Builds the result of the deprecated `options_for_checks` methods
+        # without emitting a deprecation warning.
+        #
+        # @return [Hash{Symbol => Object}] option names mapped to normalized bodies
+        def check_options_by_key
+          validations_for_checks.to_h { |check_key, check_options, _| [check_key, check_options] }
+        end
+
+        # Resets memoized data derived from the collection contents.
+        #
+        # @return [void]
+        def reset_memoized_caches
+          @validations_for_checks = nil
+          @options_index = nil
+        end
+
         # Builds and caches a hash index for O(1) option lookups.
         #
         # @return [Hash{Symbol => Option}] option names mapped to Option instances
         def options_index
-          @options_index ||= each_with_object({}) do |option, index|
-            index[option.name] = option
-          end
+          @options_index ||= @collection.to_h { |option| [option.name, option] }
         end
 
         # Extracts the normalized body value from an option.

data/lib/servactory/maintenance/options/option.rb

@@ -17,7 +17,7 @@ module Servactory
                     :body_key,
                     :return_value_on_access
 
-        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
         def initialize(
           name:,
           attribute:,
@@ -54,7 +54,6 @@ module Servactory
 
           apply_dynamic_methods_to(attribute:)
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         def value
           return body unless body.is_a?(Hash)
@@ -72,7 +71,7 @@ module Servactory
 
         private
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable-next Metrics/MethodLength
         def construct_body(
           original_value:,
           options:,
@@ -81,9 +80,7 @@ module Servactory
           body_fallback:,
           detect_advanced_mode:
         )
-          return wrap_and_normalize(original_value) if original_value.present?
-
-          raw_value = options.fetch(@name, body_fallback)
+          raw_value = original_value.nil? ? options.fetch(@name, body_fallback) : original_value
 
           result = if detect_advanced_mode
                      use_advanced_mode(
@@ -98,12 +95,6 @@ module Servactory
 
           apply_normalizer(result)
         end
-        # rubocop:enable Metrics/MethodLength
-
-        def wrap_and_normalize(value)
-          result = wrap_value(value)
-          apply_normalizer(result)
-        end
 
         def apply_normalizer(body)
           return body unless @normalizer && body.is_a?(Hash)

data/lib/servactory/maintenance/options/registrar.rb

@@ -78,9 +78,10 @@ module Servactory
           create_option(
             name: :types,
             validation_class:,
-            original_value: extract_types_value,
+            original_value: @options[:type],
             need_for_checks: true,
             body_key: :is,
+            body_value: nil,
             body_fallback: nil,
             detect_advanced_mode: true,
             return_value_on_access: true,
@@ -142,17 +143,6 @@ module Servactory
           )
         end
 
-        def extract_types_value
-          type_option = @options[:type]
-          return nil if type_option.nil?
-
-          # Advanced Mode: type: { is: String, message: "..." }
-          return nil if type_option.is_a?(Hash) && type_option.key?(:is)
-
-          # Simple Mode: type: String or type: [String, Integer]
-          Array(type_option).uniq
-        end
-
         ########################################################################
 
         def required_define_methods

data/lib/servactory/maintenance/validations/checkers/type.rb

@@ -21,11 +21,19 @@ module Servactory
         #   input :id, type: Integer
         #   input :data, type: [Hash, Array]  # union type
         #   input :status, type: String, required: false
+        #   input :email, type: { is: String, message: "Email must be a String" }
         #
         #   internal :result, type: CustomType
         #   output :response, type: Hash
         # end
         # ```
+        #
+        # ## Custom Message
+        #
+        # Advanced mode `type: { is:, message: }` replaces the default error
+        # message for every type failure of the attribute. A Proc message
+        # receives `service:`, `input:`/`internal:`/`output:`, `value:`,
+        # `expected_type:` and `given_type:`.
         class Type
           extend Concerns::ErrorBuilder
 
@@ -51,7 +59,7 @@ module Servactory
 
             return if error_data.nil?
 
-            build_error_message(error_data)
+            build_error_message(attribute:, error_data:)
           end
 
           # Determines if type validation should run for given attribute.
@@ -67,7 +75,7 @@ module Servactory
           # @param value [Object] Current value (for optional input check)
           # @param check_key [Symbol] Current validation check key
           # @return [Boolean] true if type validation should run
-          # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          # rubocop:disable-next Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           def self.should_be_checked_for?(attribute, value, check_key)
             check_key == :types && (
               (
@@ -81,7 +89,6 @@ module Servactory
               ) || attribute.internal? || attribute.output?
             )
           end
-          # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           private_class_method :should_be_checked_for?
 
           # Computes prepared value with default substitution for optional inputs.
@@ -100,10 +107,21 @@ module Servactory
 
           # Builds error message from validation error data.
           #
+          # Uses the custom message from `type: { is:, message: }` if provided,
+          # otherwise falls back to the default message.
+          #
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Failed attribute
           # @param error_data [Hash] Error data from TypeValidator.validate
           # @return [String] Processed error message
-          def self.build_error_message(error_data)
-            process_message(error_data[:message], **error_data)
+          def self.build_error_message(attribute:, error_data:)
+            message = attribute.collection_of_options.find_by(name: :types).body[:message]
+            return process_message(error_data[:message], **error_data) if message.blank?
+
+            process_message(
+              message,
+              **attribute.typed_actor_kwargs,
+              **error_data.slice(:service, :value, :expected_type, :given_type)
+            )
           end
           private_class_method :build_error_message
         end

data/lib/servactory/outputs/dsl.rb

@@ -17,12 +17,18 @@ module Servactory
         private
 
         def output(name, *helpers, **options)
-          collection_of_outputs << Output.new(
+          output = Output.new(
             name,
             *helpers,
             option_helpers: config.output_option_helpers,
             **options
           )
+
+          if output.types.empty?
+            raise ArgumentError, "[#{self.name}] Output attribute `#{name}` must have the `type` option"
+          end
+
+          collection_of_outputs << output
         end
 
         def collection_of_outputs

data/lib/servactory/result.rb

@@ -41,7 +41,7 @@ module Servactory
   # ```ruby
   # result.active?  # Equivalent to Utils.query_attribute(result.active)
   # ```
-  class Result
+  class Result # rubocop:disable Metrics/ClassLength
     # Internal container for service output values.
     #
     # Provides dynamic method access to output values.
@@ -120,6 +120,10 @@ module Servactory
 
     private_constant :Outputs
 
+    # Result state keys exposed by {#deconstruct_keys}.
+    STATE_KEYS = %i[success failure error].freeze
+    private_constant :STATE_KEYS
+
     ############################################################################
 
     # Creates a success result for the given context.
@@ -198,20 +202,27 @@ module Servactory
 
     # Converts outputs to hash.
     #
-    # Excludes predicate methods from the result hash.
+    # Returns only outputs that were assigned during the call, including
+    # outputs explicitly assigned nil. Declared outputs that were never
+    # assigned are absent. Excludes predicate methods from the result hash.
     #
-    # @return [Hash<Symbol, Object>] Output name-value pairs
+    # @return [Hash<Symbol, Object>] Assigned output name-value pairs
     #
     # @example
-    #   result.to_h # => { user: #<User>, token: "abc123" }
+    #   result.to_h # => { user: #<User>, token: nil }
     def to_h
-      outputs.send(:output_names).to_h { |key| [key, outputs.public_send(key)] }.compact
+      hash = {}
+      outputs.send(:output_names).each { |key| hash[key] = outputs.public_send(key) }
+      hash
     end
 
     # Pattern matching support.
     #
     # Returns hash of result state and output values for use with case/in.
-    # State keys (:success, :failure, :error) take priority over output names.
+    # Output keys match {#to_h}: only assigned outputs are present.
+    # State keys (:success, :failure, :error) take priority over output names:
+    # outputs with these names are not included, and :error is present only
+    # for failures.
     #
     # @param keys [Array<Symbol>, nil] Keys to include, or nil for all
     # @return [Hash<Symbol, Object>] Hash of state and outputs for pattern matching
@@ -234,6 +245,8 @@ module Servactory
       available[:error] = error if failure?
 
       outputs.send(:output_names).each do |name|
+        next if STATE_KEYS.include?(name)
+
         available[name] = outputs.public_send(name)
       end
 
@@ -347,7 +360,7 @@ module Servactory
       Outputs.new(
         outputs: build_outputs_hash,
         predicate_methods_enabled:
-          @context.is_a?(Servactory::TestKit::Result) || @context.config.predicate_methods_enabled
+          @context.is_a?(Servactory::TestKit::Result) || @context.class.config.predicate_methods_enabled
       )
     end
 
@@ -374,7 +387,7 @@ module Servactory
     def rescue_no_method_error_with(exception:) # rubocop:disable Metrics/MethodLength
       raise exception if @context.blank? || @context.instance_of?(Servactory::TestKit::Result)
 
-      raise @context.config.failure_class.new(
+      raise @context.class.config.failure_class.new(
         type: :base,
         message: @context.send(:servactory_service_info).translate(
           "common.undefined_method.missing_name",