servactory 3.0.4 → 3.1.0.rc1

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Attributes
+      # Collection wrapper for managing attribute objects (inputs, internals, outputs).
+      #
+      # ## Purpose
+      #
+      # Collection provides a polymorphic base for storing and querying attribute
+      # instances. It wraps a Set to ensure uniqueness and delegates common
+      # enumeration methods. Subclasses override `lookup_name` to customize
+      # how attributes are indexed and filtered (e.g., inputs use `internal_name`
+      # for the `as:` parameter).
+      #
+      # ## Usage
+      #
+      # Subclasses are used internally by Input, Internal, and Output DSL modules
+      # to manage their registered attributes:
+      #
+      # ```ruby
+      # collection = Collection.new
+      # collection << attribute
+      #
+      # collection.names                      # => [:first_name, :last_name]
+      # collection.find_by(name: :first_name) # => attribute instance
+      # collection.only(:first_name)          # => filtered Collection
+      # collection.except(:last_name)         # => filtered Collection
+      # ```
+      #
+      # ## Performance
+      #
+      # The collection uses memoization for frequently accessed data:
+      # - `attributes_index` - cached hash for O(1) lookups by name
+      #
+      class Collection
+        extend Forwardable
+
+        def_delegators :@collection,
+                       :<<,
+                       :filter,
+                       :each, :each_with_object,
+                       :map, :to_h,
+                       :merge
+
+        # Initializes the collection with an optional pre-built Set.
+        #
+        # @param collection [Set] initial set of attributes
+        # @return [Collection]
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+
+        # Returns names of all attributes in the collection.
+        #
+        # @return [Array<Symbol>] list of attribute names
+        def names
+          map(&:name)
+        end
+
+        # Returns a new collection containing only the named attributes.
+        #
+        # @param names [Array<Symbol>] attribute names to include
+        # @return [Collection] filtered collection
+        def only(*names)
+          self.class.new(filter { |attribute| names.include?(lookup_name(attribute)) })
+        end
+
+        # Returns a new collection excluding the named attributes.
+        #
+        # @param names [Array<Symbol>] attribute names to exclude
+        # @return [Collection] filtered collection
+        def except(*names)
+          self.class.new(filter { |attribute| names.exclude?(lookup_name(attribute)) })
+        end
+
+        # Finds an attribute by its name using indexed lookup.
+        #
+        # @param name [Symbol] the attribute name to find
+        # @return [Object, nil] the found attribute or nil
+        def find_by(name:)
+          attributes_index[name]
+        end
+
+        private
+
+        # Builds and caches a hash index for O(1) attribute lookups.
+        #
+        # @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
+        end
+
+        # Returns the name used for indexing and filtering a given attribute.
+        #
+        # Subclasses override this to use alternative name fields
+        # (e.g., `internal_name` for inputs with the `as:` parameter).
+        #
+        # @param attribute [Object] the attribute to extract a name from
+        # @return [Symbol] the lookup name
+        def lookup_name(attribute)
+          attribute.name
+        end
+      end
+    end
+  end
+end

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

@@ -3,19 +3,40 @@
 module Servactory
   module Maintenance
     module Attributes
-      class OptionHelper
-        attr_reader :name,
-                    :equivalent,
-                    :meta
-
+      # @deprecated Use {Servactory::Maintenance::Options::Helper} instead.
+      #   This class is maintained for backward compatibility only and will be
+      #   removed in a future major version.
+      #
+      # OptionHelper provides a simple way to define custom option helpers
+      # for service inputs, internals, and outputs configuration.
+      #
+      # @example Creating a custom option helper
+      #   Servactory::Maintenance::Attributes::OptionHelper.new(
+      #     name: :must_be_positive,
+      #     equivalent: {
+      #       must: {
+      #         be_positive: {
+      #           is: ->(value:, **) { value.positive? },
+      #           message: "must be positive"
+      #         }
+      #       }
+      #     }
+      #   )
+      #
+      # @see Servactory::Maintenance::Options::Helper The new preferred class
+      class OptionHelper < Servactory::Maintenance::Options::Helper
+        # @deprecated This class is deprecated. Use Options::Helper instead.
+        #
+        # Creates a new OptionHelper instance.
+        #
+        # @param name [Symbol] The name of the option helper
+        # @param equivalent [Hash, Proc] The equivalent option configuration
+        # @param meta [Hash] Additional metadata for the helper
+        # @return [OptionHelper] A new instance
         def initialize(name:, equivalent:, meta: {})
-          @name = name
-          @equivalent = equivalent
-          @meta = meta
-        end
-
-        def dynamic_option?
-          meta[:type] == :dynamic_option
+          warn "[DEPRECATION] Servactory::Maintenance::Attributes::OptionHelper is deprecated. " \
+               "Use Servactory::Maintenance::Options::Helper instead."
+          super
         end
       end
     end

data/lib/servactory/maintenance/{attributes/options_collection.rb → options/collection.rb}

@@ -2,12 +2,12 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       # Collection wrapper for managing Option objects.
       #
       # ## Purpose
       #
-      # OptionsCollection provides a unified interface for storing and querying
+      # Collection provides a unified interface for storing and querying
       # Option instances associated with service attributes (inputs, internals, outputs).
       # It wraps a Set to ensure uniqueness and delegates common enumeration methods.
       #
@@ -17,7 +17,7 @@ module Servactory
       # to manage their registered options:
       #
       # ```ruby
-      # collection = OptionsCollection.new
+      # collection = Collection.new
       # collection << Option.new(name: :required, ...)
       # collection << Option.new(name: :types, ...)
       #
@@ -32,21 +32,20 @@ module Servactory
       # - `options_for_checks` - cached hash for validation pipeline
       # - `options_index` - cached hash for O(1) lookups by name
       #
-      class OptionsCollection
+      class Collection
         extend Forwardable
 
         def_delegators :@collection,
                        :<<,
                        :filter,
-                       :each, :each_with_object,
+                       :each_with_object,
                        :map, :flat_map,
-                       :find,
                        :size,
                        :empty?
 
         # Initializes an empty collection.
         #
-        # @return [OptionsCollection]
+        # @return [Collection]
         def initialize
           @collection = Set.new
         end

data/lib/servactory/maintenance/{attributes → options}/define_conflict.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       class DefineConflict
         attr_reader :content
 

data/lib/servactory/maintenance/{attributes → options}/define_method.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       class DefineMethod
         attr_reader :name,
                     :content

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Options
+      class Helper
+        attr_reader :name,
+                    :equivalent,
+                    :meta
+
+        def initialize(name:, equivalent:, meta: {})
+          @name = name
+          @equivalent = equivalent
+          @meta = meta
+        end
+
+        def dynamic_option?
+          meta[:type] == :dynamic_option
+        end
+      end
+    end
+  end
+end

data/lib/servactory/maintenance/{attributes → options}/option.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       class Option # rubocop:disable Metrics/ClassLength
         DEFAULT_BODY = ->(key:, body:, message: nil) { { key => body, message: } }
 
@@ -14,9 +14,10 @@ module Servactory
                     :define_conflicts,
                     :need_for_checks,
                     :body,
-                    :body_key
+                    :body_key,
+                    :return_value_on_access
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
         def initialize(
           name:,
           attribute:,
@@ -28,11 +29,15 @@ module Servactory
           body_value: true,
           define_methods: nil,
           define_conflicts: nil,
-          with_advanced_mode: true,
+          detect_advanced_mode: true,
+          return_value_on_access: false,
+          normalizer: nil,
           **options
         )
           @name = name.to_sym
           @body_key = body_key
+          @return_value_on_access = return_value_on_access
+          @normalizer = normalizer
           @validation_class = validation_class
           @define_methods = define_methods
           @define_conflicts = define_conflicts
@@ -44,12 +49,12 @@ module Servactory
             body_key:,
             body_value:,
             body_fallback:,
-            with_advanced_mode:
+            detect_advanced_mode:
           )
 
           apply_dynamic_methods_to(attribute:)
         end
-        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         def value
           return body unless body.is_a?(Hash)
@@ -57,51 +62,69 @@ module Servactory
           body.fetch(@body_key, body)
         end
 
+        def body_for_access
+          @return_value_on_access ? value : body
+        end
+
         def need_for_checks?
           need_for_checks
         end
 
         private
 
+        # rubocop:disable Metrics/MethodLength
         def construct_body(
           original_value:,
           options:,
           body_key:,
           body_value:,
           body_fallback:,
-          with_advanced_mode:
+          detect_advanced_mode:
         )
-          return original_value if original_value.present?
-          return options.fetch(@name, body_fallback) unless with_advanced_mode
+          return wrap_and_normalize(original_value) if original_value.present?
+
+          raw_value = options.fetch(@name, body_fallback)
+
+          result = if detect_advanced_mode
+                     use_advanced_mode(
+                       raw_value:,
+                       body_key:,
+                       body_value:,
+                       body_fallback:
+                     )
+                   else
+                     wrap_value(raw_value)
+                   end
+
+          apply_normalizer(result)
+        end
+        # rubocop:enable Metrics/MethodLength
 
-          use_advanced_mode(
-            options:,
-            body_key:,
-            body_value:,
-            body_fallback:
-          )
+        def wrap_and_normalize(value)
+          result = wrap_value(value)
+          apply_normalizer(result)
         end
 
-        def use_advanced_mode(options:, body_key:, body_value:, body_fallback:)
-          default_body = create_default_body(body_key:, body_fallback:)
-          body = extract_body_from_options(options:, default_body:)
+        def apply_normalizer(body)
+          return body unless @normalizer && body.is_a?(Hash)
+
+          body[@body_key] = @normalizer.call(body[@body_key])
+          body
+        end
+
+        def wrap_value(value)
+          DEFAULT_BODY.call(key: @body_key, body: value)
+        end
 
+        def use_advanced_mode(raw_value:, body_key:, body_value:, body_fallback:)
           construct_advanced_body(
-            body:,
+            body: raw_value,
             body_key:,
             body_value:,
             body_fallback:
           )
         end
 
-        def create_default_body(body_key:, body_fallback:)
-          DEFAULT_BODY.call(key: body_key, body: body_fallback)
-        end
-
-        def extract_body_from_options(options:, default_body:)
-          options.fetch(@name, default_body)
-        end
-
         def construct_advanced_body(body:, body_key:, body_value:, body_fallback:)
           if body.is_a?(Hash)
             build_hash_body(body:, body_key:, body_value:, body_fallback:)

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

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Options
+      class Registrar # rubocop:disable Metrics/ClassLength
+        RESERVED_OPTIONS = %i[
+          type
+          required
+          default
+          collection
+          must
+          prepare
+        ].freeze
+
+        DEFAULT_FEATURES = {
+          required: false,
+          types: false,
+          default: false,
+          must: false,
+          prepare: false
+        }.freeze
+
+        private_constant :DEFAULT_FEATURES
+
+        def self.register(...)
+          new(...).register
+        end
+
+        def initialize(attribute:, options:, features:)
+          @attribute = attribute
+          @options = options
+          @features = DEFAULT_FEATURES.merge(features)
+        end
+
+        ########################################################################
+
+        def register
+          register_feature(:required, Servactory::Inputs::Validations::Required)
+          register_feature(:types, Servactory::Maintenance::Validations::Checkers::Type)
+          register_feature(:default, Servactory::Maintenance::Validations::Checkers::Type)
+          register_feature(:must, Servactory::Maintenance::Validations::Checkers::Must)
+          register_feature(:prepare, nil)
+
+          self
+        end
+
+        def collection
+          @collection ||= Servactory::Maintenance::Options::Collection.new
+        end
+
+        private
+
+        def register_feature(feature_name, validation_class)
+          return unless @features.fetch(feature_name)
+
+          method_name = "register_#{feature_name}_option"
+          send(method_name, validation_class)
+        end
+
+        ########################################################################
+
+        def register_required_option(validation_class) # rubocop:disable Metrics/MethodLength
+          create_option(
+            name: :required,
+            validation_class:,
+            define_methods: required_define_methods,
+            define_conflicts: required_define_conflicts,
+            need_for_checks: true,
+            body_key: :is,
+            body_fallback: true,
+            detect_advanced_mode: true,
+            return_value_on_access: false
+          )
+        end
+
+        def register_types_option(validation_class) # rubocop:disable Metrics/MethodLength
+          create_option(
+            name: :types,
+            validation_class:,
+            original_value: extract_types_value,
+            need_for_checks: true,
+            body_key: :is,
+            body_fallback: nil,
+            detect_advanced_mode: true,
+            return_value_on_access: true,
+            normalizer: ->(v) { Array(v).uniq }
+          )
+        end
+
+        def register_default_option(validation_class) # rubocop:disable Metrics/MethodLength
+          create_option(
+            name: :default,
+            validation_class:,
+            define_methods: [
+              create_define_method(
+                name: :default_value_present?,
+                content: ->(option:) { !option[:is].nil? }
+              )
+            ],
+            need_for_checks: true,
+            body_key: :is,
+            body_fallback: nil,
+            detect_advanced_mode: false,
+            return_value_on_access: true
+          )
+        end
+
+        def register_must_option(validation_class) # rubocop:disable Metrics/MethodLength
+          create_option(
+            name: :must,
+            validation_class:,
+            define_methods: [
+              create_define_method(
+                name: :must_present?,
+                content: ->(option:) { option[:rules].present? }
+              )
+            ],
+            need_for_checks: true,
+            body_key: :rules,
+            body_fallback: nil,
+            detect_advanced_mode: false,
+            return_value_on_access: true
+          )
+        end
+
+        def register_prepare_option(_validation_class) # rubocop:disable Metrics/MethodLength
+          create_option(
+            name: :prepare,
+            validation_class: nil,
+            define_methods: [
+              create_define_method(
+                name: :prepare_present?,
+                content: ->(option:) { option[:in].present? }
+              )
+            ],
+            need_for_checks: false,
+            body_key: :in,
+            body_fallback: false,
+            detect_advanced_mode: true,
+            return_value_on_access: false
+          )
+        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
+          [
+            create_define_method(
+              name: :required?,
+              content: ->(option:) { Servactory::Utils.true?(option[:is]) }
+            ),
+            create_define_method(
+              name: :optional?,
+              content: ->(option:) { !Servactory::Utils.true?(option[:is]) }
+            )
+          ]
+        end
+
+        def required_define_conflicts
+          [
+            Servactory::Maintenance::Options::DefineConflict.new(
+              content: -> { :required_vs_default if @attribute.required? && @attribute.default_value_present? }
+            )
+          ]
+        end
+
+        ########################################################################
+
+        def create_option(name:, validation_class:, **options)
+          collection << Servactory::Maintenance::Options::Option.new(
+            name:,
+            attribute: @attribute,
+            validation_class:,
+            **options,
+            **@options
+          )
+        end
+
+        def create_define_method(name:, content:)
+          Servactory::Maintenance::Options::DefineMethod.new(
+            name:,
+            content:
+          )
+        end
+      end
+    end
+  end
+end

data/lib/servactory/maintenance/{attributes/validations → validations/checkers}/must.rb

@@ -2,8 +2,8 @@
 
 module Servactory
   module Maintenance
-    module Attributes
-      module Validations
+    module Validations
+      module Checkers
         # Validates custom conditions defined with `must` option.
         #
         # ## Purpose
@@ -82,9 +82,10 @@ module Servactory
           # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute being validated
           # @param value [Object] Value to pass to check lambda
           # @param code [Symbol] Condition identifier (e.g., :be_adult)
-          # @param options [Hash] Condition options with :is (lambda) and :message
+          # @param options [Hash, Proc] Condition options with :is (lambda) and :message, or just a lambda
           # @return [String, nil] Error message on failure, nil on success
           def self.validate_condition(context:, attribute:, value:, code:, options:) # rubocop:disable Metrics/MethodLength
+            options = normalize_rule_options(options)
             check, message = options.values_at(:is, :message)
 
             check_result, check_result_code, meta = call_check(
@@ -111,6 +112,22 @@ module Servactory
           end
           private_class_method :validate_condition
 
+          # Normalizes rule options to always have :is and :message keys.
+          #
+          # Supports Simple Mode where only a lambda is provided:
+          #   must: { be_adult: ->(value:) { value >= 18 } }
+          # Converts to Advanced Mode format:
+          #   must: { be_adult: { is: lambda, message: nil } }
+          #
+          # @param options [Hash, Proc] Either { is: lambda, message: ... } or just lambda
+          # @return [Hash] Normalized options with :is and :message keys
+          def self.normalize_rule_options(options)
+            return options if options.is_a?(Hash)
+
+            { is: options, message: nil }
+          end
+          private_class_method :normalize_rule_options
+
           # Executes the check lambda with exception handling.
           #
           # Catches any StandardError from the lambda and converts it to a
@@ -124,7 +141,7 @@ module Servactory
           # @return [Array] On success: [result, reason_code, meta_hash]
           # @return [Array] On exception: [:syntax_error, error_message_string, nil]
           def self.call_check(context:, attribute:, value:, check:, code:)
-            check.call(value:, **Servactory::Utils.fetch_hash_with_desired_attribute(attribute))
+            check.call(value:, **attribute.typed_actor_kwargs)
           rescue StandardError => e
             # Return formatted syntax error message
             syntax_error_message = build_syntax_error_message(
@@ -154,12 +171,12 @@ module Servactory
           # @param message [String, Proc, nil] Custom error message
           # @return [String] Processed error message
           def self.build_error_message(context:, attribute:, value:, code:, reason:, meta:, message:)
-            message = message.presence || Servactory::Maintenance::Attributes::Translator::Must.default_message
+            message = message.presence || Servactory::Maintenance::Validations::Translator::Must.default_message
 
             process_message(
               message,
               service: context.send(:servactory_service_info),
-              **Servactory::Utils.fetch_hash_with_desired_attribute(attribute),
+              **attribute.typed_actor_kwargs,
               value:,
               code:,
               reason:,
@@ -180,12 +197,12 @@ module Servactory
           # @param exception_message [String] Original exception message
           # @return [String] Formatted syntax error message
           def self.build_syntax_error_message(context:, attribute:, value:, code:, exception_message:)
-            message = Servactory::Maintenance::Attributes::Translator::Must.syntax_error_message
+            message = Servactory::Maintenance::Validations::Translator::Must.syntax_error_message
 
             process_message(
               message,
               service: context.send(:servactory_service_info),
-              **Servactory::Utils.fetch_hash_with_desired_attribute(attribute),
+              **attribute.typed_actor_kwargs,
               value:,
               code:,
               exception_message: