servactory 2.16.1 → 3.0.0.rc1

data/lib/servactory/tool_kit/dynamic_options/schema.rb

@@ -3,56 +3,219 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates Hash structures against a defined schema.
+      #
+      # ## Purpose
+      #
+      # Schema provides deep validation for Hash-type attributes by checking
+      # that nested keys exist with correct types. It supports required/optional
+      # fields, default values, and nested object validation. This is essential
+      # for validating complex data structures like API payloads or configurations.
+      #
+      # ## Usage
+      #
+      # This option is **included by default** for inputs, internals, and outputs.
+      # No registration required for basic usage.
+      #
+      # To extend supported Hash-compatible types, use the
+      # `hash_mode_class_names` configuration:
+      #
+      # ```ruby
+      # configuration do
+      #   hash_mode_class_names([CustomHashClass])
+      # end
+      # ```
+      #
+      # Define schema in your service:
+      #
+      # ```ruby
+      # class CreateUserService < ApplicationService::Base
+      #   input :user_data,
+      #         type: Hash,
+      #         schema: {
+      #           name: { type: String },
+      #           age: { type: Integer, required: false, default: 18 },
+      #           address: {
+      #             type: Hash,
+      #             street: { type: String },
+      #             city: { type: String, required: false }
+      #           }
+      #         }
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify schema definition directly:
+      #
+      # ```ruby
+      # class CreateUserService < ApplicationService::Base
+      #   input :user_data,
+      #         type: Hash,
+      #         schema: {
+      #           name: { type: String },
+      #           age: { type: Integer, required: false },
+      #           email: { type: String }
+      #         }
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify schema with custom error message using a hash:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :user_data, type: Hash, schema: {
+      #   is: {
+      #     name: { type: String },
+      #     email: { type: String }
+      #   },
+      #   message: "Input `user_data` has invalid structure"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :user_data, type: Hash, schema: {
+      #   is: {
+      #     name: { type: String },
+      #     email: { type: String }
+      #   },
+      #   message: lambda do |input:, reason:, key_name:, expected_type:, given_type:, **|
+      #     "Schema error in `#{input.name}`: " \
+      #       "key `#{key_name}` expected #{expected_type}, got #{given_type}"
+      #   end
+      # }
+      # ```
+      #
+      # Lambda receives the following parameters:
+      # - For inputs: `input:, reason:, key_name:, expected_type:, given_type:, **`
+      # - For internals: `internal:, reason:, key_name:, expected_type:, given_type:, **`
+      # - For outputs: `output:, reason:, key_name:, expected_type:, given_type:, **`
+      #
+      # Use `schema: false` to disable schema validation.
+      #
+      # ## Schema Options
+      #
+      # Each field in the schema supports:
+      # - `type` - Expected type (String, Integer, Array, Hash, etc.)
+      # - `required` - Whether field is required (default: true)
+      # - `default` - Default value when field is missing
+      # - `prepare` - Proc to transform the value (inputs only)
+      #
+      # ## Processing Flow
+      #
+      # 1. **Type check**: Verify attribute is Hash-compatible
+      # 2. **Schema validation**: Recursively check all nested keys and types
+      # 3. **Default application**: Apply defaults to missing optional fields
+      # 4. **Preparation**: Execute prepare callbacks (inputs only)
+      #
+      # ## Important Notes
+      #
+      # - Empty values skip validation for: optional inputs, all internal/output attributes
+      # - Nested Hash types are validated recursively
+      # - The `prepare` option is stripped for internals and outputs
+      # - Reserved options: :type, :required, :default, :prepare
       class Schema < Must # rubocop:disable Metrics/ClassLength
-        RESERVED_OPTIONS = %i[type required default payload].freeze
+        # Reserved keys that are not treated as nested schema definitions.
+        RESERVED_OPTIONS = %i[type required default prepare].freeze
         private_constant :RESERVED_OPTIONS
 
+        # Creates a Schema validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :schema)
+        # @param default_hash_mode_class_names [Array<Class>] Valid Hash-like types
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :schema, default_hash_mode_class_names:)
           instance = new(option_name, :is, false)
           instance.assign(default_hash_mode_class_names)
           instance.must(:schema)
         end
 
+        # Assigns the list of valid Hash-compatible class names.
+        #
+        # @param default_hash_mode_class_names [Array<Class>] Hash-like types to accept
+        # @return [void]
         def assign(default_hash_mode_class_names)
           @default_hash_mode_class_names = default_hash_mode_class_names
         end
 
+        # Validates schema condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Hash value to validate
+        # @param option [WorkOption] Schema configuration
+        # @return [Boolean, Array] true if valid, or [false, reason, meta]
         def condition_for_input_with(input:, value:, option:)
           common_condition_with(attribute: input, value:, option:)
         end
 
+        # Validates schema condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Hash value to validate
+        # @param option [WorkOption] Schema configuration
+        # @return [Boolean, Array] true if valid, or [false, reason, meta]
         def condition_for_internal_with(internal:, value:, option:)
           common_condition_with(attribute: internal, value:, option:)
         end
 
+        # Validates schema condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Hash value to validate
+        # @param option [WorkOption] Schema configuration
+        # @return [Boolean, Array] true if valid, or [false, reason, meta]
         def condition_for_output_with(output:, value:, option:)
           common_condition_with(attribute: output, value:, option:)
         end
 
+        # Common validation logic for all attribute types.
+        #
+        # @param attribute [Object] The attribute being validated
+        # @param value [Object] Hash value to validate
+        # @param option [WorkOption] Schema configuration
+        # @return [Boolean, Array] true if valid, or [false, reason, meta]
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def common_condition_with(attribute:, value:, option:)
+          # Schema disabled, skip validation.
           return true if option.value == false
+
+          # Attribute type must be Hash-compatible.
           return [false, :wrong_type] unless @default_hash_mode_class_names.intersect?(attribute.types)
 
+          # Skip validation for blank optional values.
           if value.blank? && ((attribute.input? && attribute.optional?) || attribute.internal? || attribute.output?)
             return true
           end
 
           schema = option.value.fetch(:is, option.value)
 
+          # Remove :prepare option for internals and outputs.
           if attribute.internal? || attribute.output?
             schema = schema.transform_values { |options| options.except(:prepare) }
           end
 
           is_success, reason, meta = validate_for!(object: value, schema:)
 
+          # Apply defaults and preparations if validation passed.
           prepare_object_with!(object: value, schema:) if is_success
 
           [is_success, reason, meta]
         end
         # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+        # Recursively validates object against schema definition.
+        #
+        # @param object [Hash] The object to validate
+        # @param schema [Hash] Schema definition
+        # @param root_schema_key [Symbol, nil] Parent key for nested validation
+        # @return [Boolean, Array] true if valid, or [false, reason, meta]
         def validate_for!(object:, schema:, root_schema_key: nil) # rubocop:disable Metrics/MethodLength
+          # Object must be Hash-like (respond to :fetch).
           unless object.respond_to?(:fetch)
             return [
               false,
@@ -65,10 +228,12 @@ module Servactory
             ]
           end
 
+          # Validate each schema field.
           errors = schema.map do |schema_key, schema_value|
             attribute_type = schema_value.fetch(:type, String)
 
             if attribute_type == Hash
+              # Recursively validate nested Hash.
               validate_for!(
                 object: object.fetch(schema_key, {}),
                 schema: schema_value.except(*RESERVED_OPTIONS),
@@ -89,10 +254,20 @@ module Servactory
             end
           end
 
+          # Return first error or true.
           errors.compact.first || true
         end
 
+        # Validates a single field against its type specification.
+        #
+        # @param object [Hash] Parent object containing the field
+        # @param schema_key [Symbol] Field key to validate
+        # @param schema_value [Hash] Field schema definition
+        # @param attribute_type [Class, Array<Class>] Expected type(s)
+        # @param attribute_required [Boolean] Whether field is required
+        # @return [Array<Boolean, String>] [success, given_type_name]
         def validate_with(object:, schema_key:, schema_value:, attribute_type:, attribute_required:) # rubocop:disable Metrics/MethodLength
+          # Skip validation if not required and no value present.
           unless should_be_checked_for?(
             object:,
             schema_key:,
@@ -111,6 +286,13 @@ module Servactory
           ]
         end
 
+        # Determines if a field should be validated.
+        #
+        # @param object [Hash] Parent object
+        # @param schema_key [Symbol] Field key
+        # @param schema_value [Hash] Field schema
+        # @param required [Boolean] Whether required
+        # @return [Boolean] true if validation needed
         def should_be_checked_for?(object:, schema_key:, schema_value:, required:)
           required || (
             !required && !fetch_default_from(schema_value).nil?
@@ -119,6 +301,12 @@ module Servactory
           )
         end
 
+        # Prepares value for validation, applying defaults if needed.
+        #
+        # @param schema_value [Hash] Field schema
+        # @param value [Object] Current value
+        # @param required [Boolean] Whether required
+        # @return [Object] Value to validate
         def prepare_value_from(schema_value:, value:, required:)
           if !required && !fetch_default_from(schema_value).nil? && value.blank?
             fetch_default_from(schema_value)
@@ -127,36 +315,50 @@ module Servactory
           end
         end
 
+        # Extracts default value from schema definition.
+        #
+        # @param value [Hash] Schema definition
+        # @return [Object, nil] Default value or nil
         def fetch_default_from(value)
           value.fetch(:default, nil)
         end
 
         ########################################################################
 
-        def prepare_object_with!(object:, schema:) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # Applies defaults and preparations to the validated object.
+        #
+        # @param object [Hash] Object to modify
+        # @param schema [Hash] Schema definition
+        # @return [void]
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def prepare_object_with!(object:, schema:)
           schema.map do |schema_key, schema_value|
             attribute_type = schema_value.fetch(:type, String)
             required = schema_value.fetch(:required, true)
             object_value = object[schema_key]
 
             if attribute_type == Hash
+              # Apply nested Hash defaults.
               default_value = schema_value.fetch(:default, {})
 
               if !required && !default_value.nil? && !Servactory::Utils.value_present?(object_value)
                 object[schema_key] = default_value
               end
 
+              # Recursively prepare nested objects.
               prepare_object_with!(
                 object: object.fetch(schema_key, {}),
                 schema: schema_value.except(*RESERVED_OPTIONS)
               )
             else
+              # Apply scalar defaults.
               default_value = schema_value.fetch(:default, nil)
 
               if !required && !default_value.nil? && !Servactory::Utils.value_present?(object_value)
                 object[schema_key] = default_value
               end
 
+              # Execute prepare callback if defined.
               unless (input_prepare = schema_value.fetch(:prepare, nil)).nil?
                 object[schema_key] = input_prepare.call(value: object[schema_key])
               end
@@ -165,11 +367,19 @@ module Servactory
             end
           end
         end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ########################################################################
         ########################################################################
         ########################################################################
 
+        # Generates error message for input validation failure.
+        #
+        # @param service [Object] Service context
+        # @param input [Object] Input attribute
+        # @param reason [Symbol] Failure reason
+        # @param meta [Hash] Additional metadata
+        # @return [String] Localized error message
         def message_for_input_with(service:, input:, reason:, meta:, **)
           i18n_key = "inputs.validations.must.dynamic_options.schema"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -184,6 +394,13 @@ module Servactory
           )
         end
 
+        # Generates error message for internal validation failure.
+        #
+        # @param service [Object] Service context
+        # @param internal [Object] Internal attribute
+        # @param reason [Symbol] Failure reason
+        # @param meta [Hash] Additional metadata
+        # @return [String] Localized error message
         def message_for_internal_with(service:, internal:, reason:, meta:, **)
           i18n_key = "internals.validations.must.dynamic_options.schema"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -198,6 +415,13 @@ module Servactory
           )
         end
 
+        # Generates error message for output validation failure.
+        #
+        # @param service [Object] Service context
+        # @param output [Object] Output attribute
+        # @param reason [Symbol] Failure reason
+        # @param meta [Hash] Additional metadata
+        # @return [String] Localized error message
         def message_for_output_with(service:, output:, reason:, meta:, **)
           i18n_key = "outputs.validations.must.dynamic_options.schema"
           i18n_key += reason.present? ? ".#{reason}" : ".default"

data/lib/servactory/tool_kit/dynamic_options/target.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Servactory
+  module ToolKit
+    module DynamicOptions
+      # Validates that attribute value matches one of the target values.
+      #
+      # ## Purpose
+      #
+      # Target provides exact value matching validation for attributes.
+      # It ensures that the value is one of the specified target values,
+      # supporting both single values and arrays of acceptable values.
+      # This is useful for enum-like validations where only specific
+      # values are allowed.
+      #
+      # ## Usage
+      #
+      # This option is **NOT included by default**. Register it for each
+      # attribute type where you want to use it:
+      #
+      # ```ruby
+      # configuration do
+      #   input_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Target.use
+      #   ])
+      #
+      #   internal_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Target.use
+      #   ])
+      #
+      #   output_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Target.use
+      #   ])
+      # end
+      # ```
+      #
+      # Use in your service definition:
+      #
+      # ```ruby
+      # class ProcessOrderService < ApplicationService::Base
+      #   input :status, type: Symbol, target: { in: [:pending, :processing, :complete] }
+      #   input :priority, type: Integer, target: { in: [1, 2, 3] }
+      #   input :model_class, type: Class, target: { in: [User, Admin] }
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify target values directly:
+      #
+      # ```ruby
+      # class ProcessOrderService < ApplicationService::Base
+      #   input :status, type: Symbol, target: :pending
+      #   input :priority, type: Integer, target: [1, 2, 3]
+      #   input :model_class, type: Class, target: [User, Admin]
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify target with custom error message using a hash.
+      # Note: Advanced mode uses `:in` key (not `:is`).
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :status, type: Symbol, target: {
+      #   in: [:pending, :processing, :complete],
+      #   message: "Input `status` must be one of: pending, processing, complete"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :status, type: Symbol, target: {
+      #   in: [:pending, :processing, :complete],
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` has invalid value `#{value}`, expected: #{option_value.inspect}"
+      #   end
+      # }
+      # ```
+      #
+      # Lambda receives the following parameters:
+      # - For inputs: `input:, value:, option_value:, reason:, **`
+      # - For internals: `internal:, value:, option_value:, reason:, **`
+      # - For outputs: `output:, value:, option_value:, reason:, **`
+      #
+      # ## Validation Rules
+      #
+      # - Value must exactly match one of the target values
+      # - Supports single value or array of values
+      # - Optional inputs with nil value validate against default
+      #
+      # ## Important Notes
+      #
+      # - Use `target: { in: [...] }` syntax for specifying allowed values
+      # - Returns `:invalid_option` error if target is nil
+      # - For optional inputs with nil value and default, validates the default
+      # - Internal/output attributes do NOT have default value handling (unlike inputs)
+      # - For Class-typed attributes, arrays of classes are preserved as-is rather
+      #   than being wrapped (e.g., `[User, Admin]` stays as array, not `[[User, Admin]]`)
+      class Target < Must
+        # Creates a Target validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :target)
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
+        def self.use(option_name = :target)
+          instance = new(option_name, :in)
+          instance.must(:"be_#{option_name}")
+        end
+
+        # Validates target condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Target configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_input_with(input:, value:, option:) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+          return [false, :invalid_option] if option.value.nil?
+
+          target_values = normalize_target_values(option.value, input.types)
+
+          # Required inputs or optional with non-nil value.
+          return target_values.include?(value) if input.required? || (input.optional? && !value.nil?)
+
+          # Optional with nil value but has default.
+          return target_values.include?(input.default) if input.optional? && value.nil? && !input.default.nil?
+
+          true
+        end
+
+        # Validates target condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Target configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_internal_with(value:, option:, internal: nil, **)
+          return [false, :invalid_option] if option.value.nil?
+
+          target_values = normalize_target_values(option.value, internal.types)
+
+          target_values.include?(value)
+        end
+
+        # Validates target condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Target configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_output_with(value:, option:, output: nil, **)
+          return [false, :invalid_option] if option.value.nil?
+
+          target_values = normalize_target_values(option.value, output.types)
+
+          target_values.include?(value)
+        end
+
+        ########################################################################
+
+        # Generates error message for input validation failure.
+        #
+        # @param service [Object] Service context
+        # @param input [Object] Input attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Expected target values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_input_with(service:, input:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "inputs.validations.must.dynamic_options.target"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
+          service.translate(
+            i18n_key,
+            input_name: input.name,
+            value: value.inspect,
+            expected_target: option_value.inspect,
+            option_name:
+          )
+        end
+
+        # Generates error message for internal validation failure.
+        #
+        # @param service [Object] Service context
+        # @param internal [Object] Internal attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Expected target values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_internal_with(service:, internal:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "internals.validations.must.dynamic_options.target"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
+          service.translate(
+            i18n_key,
+            internal_name: internal.name,
+            value: value.inspect,
+            expected_target: option_value.inspect,
+            option_name:
+          )
+        end
+
+        # Generates error message for output validation failure.
+        #
+        # @param service [Object] Service context
+        # @param output [Object] Output attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Expected target values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_output_with(service:, output:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "outputs.validations.must.dynamic_options.target"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
+          service.translate(
+            i18n_key,
+            output_name: output.name,
+            value: value.inspect,
+            expected_target: option_value.inspect,
+            option_name:
+          )
+        end
+
+        private
+
+        # Normalizes target values into array format.
+        #
+        # Handles special case for Class types where arrays should
+        # be preserved as-is rather than wrapped.
+        #
+        # @param option_value [Object] Target value(s)
+        # @param types [Array<Class>] Attribute types
+        # @return [Array] Normalized array of target values
+        def normalize_target_values(option_value, types)
+          # Special handling for Class type attributes.
+          if types.size == 1 && types.first == Class
+            return [option_value] unless option_value.is_a?(Array)
+
+            return option_value
+          end
+
+          option_value.is_a?(Array) ? option_value : [option_value]
+        end
+      end
+    end
+  end
+end

data/lib/servactory/version.rb

@@ -2,10 +2,10 @@
 
 module Servactory
   module VERSION
-    MAJOR = 2
-    MINOR = 16
-    PATCH = 1
-    PRE = nil
+    MAJOR = 3
+    MINOR = 0
+    PATCH = 0
+    PRE = "rc1"
 
     STRING = [MAJOR, MINOR, PATCH, PRE].compact.join(".")
   end

data/lib/servactory.rb

@@ -14,6 +14,10 @@ loader.inflector.inflect(
 )
 loader.setup
 
+# Eager load DSL to initialize Stroma::Registry.
+# Registry must be populated before any service class is defined.
+require_relative "servactory/dsl"
+
 module Servactory; end
 
 require "servactory/engine" if defined?(Rails::Engine)