castkit 0.1.2 → 0.3.0

data/lib/castkit/contract/validator.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Castkit
+  module Contract
+    # Responsible for validating input against a set of Castkit::Attribute definitions.
+    #
+    # The validator supports:
+    # - Primitive type validation
+    # - Nested Castkit::DataObject validation
+    # - Collections of DataObjects
+    # - Strict or relaxed key handling
+    #
+    # Returns a hash of errors if validation fails, keyed by attribute name.
+    class Validator
+      class << self
+        # Validates input against the provided attribute definitions.
+        #
+        # @param attributes [Array<Castkit::Attribute>] the attributes to validate
+        # @param input [Hash] the raw input data
+        # @param options [Hash] validator options:
+        #   - strict: whether unknown keys should raise
+        #   - allow_unknown: whether unknown keys are permitted
+        #   - warn_on_unknown: whether to log warnings for unknown keys
+        #
+        # @return [Hash{Symbol => String, Hash, nil}] validation errors per attribute
+        def call(attributes, input, **options)
+          new(attributes, **options).call(input)
+        end
+
+        def call!(attributes, input, **options)
+          errors = call(attributes, input, **options)
+          raise Castkit::ContractError.new("Validation failed", errors: errors) if errors.any?
+        end
+      end
+
+      # Executes validation against the input data.
+      #
+      # @param input [Hash] the incoming data to validate
+      # @return [Hash{Symbol => String, Hash}] validation errors, empty if valid
+      def call(input)
+        validate_access_config!
+        errors = {}
+
+        @attributes.each do |attribute|
+          value = resolve_input_value(input, attribute)
+          error = validate_attribute(attribute, value)
+
+          errors[attribute.field] = error if error
+        end
+
+        validate_unknown_attributes!(input, errors)
+        errors
+      end
+
+      private
+
+      # @param attributes [Array<Castkit::Attribute>] attributes to validate
+      # @param options [Hash] validation options
+      def initialize(attributes, **options)
+        @attributes = attributes
+        @options = options
+      end
+
+      # Validates a single attribute value.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [String, Hash, nil] error message, nested error hash, or nil if valid
+      def validate_attribute(attribute, value)
+        return nil if value.nil? && attribute.optional?
+        return "#{attribute.field} is required" if value.nil? && attribute.required?
+
+        if attribute.dataobject?
+          validate_nested_dataobject(attribute, value)
+        elsif attribute.type == :array
+          validate_nested_array(attribute, value)
+        else
+          validate_primitives(attribute, value)
+        end
+      end
+
+      # Validates a nested DataObject instance.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Castkit::DataObject]
+      # @return [Hash, nil] validation errors or nil
+      def validate_nested_dataobject(attribute, value)
+        return nil unless value.respond_to?(:to_h)
+
+        validate_nested(attribute, value, attribute.type)
+      end
+
+      # Validates a collection of nested DataObject instances.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Array<Castkit::DataObject | Symbol>]
+      # @return [Hash{Integer => Hash}, String, nil] indexed validation errors or message
+      def validate_nested_array(attribute, value)
+        return "must be an array" unless value.is_a?(Array)
+
+        errors = {}
+
+        value.each_with_index do |item, index|
+          error = validate_nested(attribute, item, attribute.options[:of], context: "#{attribute.field}[#{index}]")
+          errors[index] = error if error
+        end
+
+        errors.empty? ? nil : errors
+      end
+
+      # Helper method used to validate nested types for Castkit::DataObject and array types.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object] the data to validate against
+      # @param type [Castkit::DataObject, Symbol]
+      def validate_nested(attribute, value, type, context: nil)
+        return validate_primitive_type(attribute, value, type, context: context) unless Castkit.dataobject?(type)
+
+        errors = Castkit::Contract::Validator.call(
+          type.attributes.values,
+          value.to_h,
+          **dataobject_options(type)
+        )
+
+        errors.empty? ? nil : errors
+      end
+
+      # Validates a primitive value against a union of allowed types.
+      #
+      # Attempts each type in order until one successfully casts and validates.
+      # If all types fail, the last error message is returned.
+      #
+      # @param attribute [Castkit::Attribute] the attribute definition
+      # @param value [Object] the value to validate
+      # @return [String, nil] the validation error message, or nil if valid
+      def validate_primitives(attribute, value)
+        last_error = nil
+
+        Array(attribute.type).each do |type|
+          last_error = validate_primitive_type(attribute, value, type)
+          return nil if last_error.nil?
+        end
+
+        last_error || "could not match attribute type(s): #{attribute.type.inspect}"
+      end
+
+      # Validates a primitive value against a specific type.
+      #
+      # @param attribute [Castkit::Attribute] the attribute definition
+      # @param value [Object] the value to validate
+      # @param type [Symbol, Class] the specific type to attempt validation with
+      # @return [String, nil] the error message if validation fails, otherwise nil
+      def validate_primitive_type(attribute, value, type, context: nil)
+        context ||= attribute.field
+
+        Castkit.type_caster(type).call(
+          value,
+          validator: attribute.options[:validator],
+          options: attribute.options,
+          context: context
+        )
+
+        nil
+      rescue Castkit::AttributeError => e
+        e.message
+      end
+
+      # Validates unknown attributes based on strict/allow config.
+      #
+      # @param input [Hash]
+      # @param errors [Hash]
+      # @return [void]
+      def validate_unknown_attributes!(input, errors)
+        return if @options[:allow_unknown]
+
+        unknown_keys = unknown_attributes(input)
+        unknown_keys.each { |key| errors[key] = "#{key} is not allowed" } if @options[:strict]
+
+        handle_unknown_keys!(unknown_keys) unless unknown_keys.empty?
+      end
+
+      # Resolves the value for a given attribute from the input hash.
+      #
+      # @param input [Hash]
+      # @param attribute [Castkit::Attribute]
+      # @return [Object, nil]
+      def resolve_input_value(input, attribute)
+        attribute.key_path(with_aliases: true).each do |path|
+          value = path.reduce(input) { |memo, key| memo.is_a?(Hash) ? memo[key] : nil }
+          return value unless value.nil?
+        end
+
+        nil
+      end
+
+      # Collects all keys present in the input hash that don't have attribute definitions.
+      #
+      # @param input [Hash]
+      # @return [Array<Symbol>]
+      def unknown_attributes(input)
+        valid_keys = @attributes.flat_map { |attr| [attr.key] + attr.options[:aliases] }.map(&:to_sym).uniq
+        input.keys.map(&:to_sym) - valid_keys
+      end
+
+      # Warns if both `strict` and `allow_unknown` are enabled.
+      #
+      # @return [void]
+      def validate_access_config!
+        return unless @options[:strict] && @options[:allow_unknown]
+
+        Castkit.warning "⚠️ [Castkit] Both `strict` and `allow_unknown` are enabled, which can lead to " \
+                        "conflicting behavior. `strict` is being disabled to respect `allow_unknown`."
+      end
+
+      # Raises or warns on unknown input keys based on config.
+      #
+      # @param unknown_keys [Array<Symbol>]
+      # @return [void]
+      def handle_unknown_keys!(unknown_keys)
+        raise Castkit::ContractError, "Unknown attribute(s): #{unknown_keys.join(", ")}" if strict?
+        return unless @options[:warn_on_unknown]
+
+        Castkit.warning "⚠️  [Castkit] Unknown attribute(s) ignored: #{unknown_keys.join(", ")}"
+      end
+
+      # Returns nested validation options from a DataObject class.
+      #
+      # @param obj [Castkit::DataObject]
+      # @return [Hash]
+      def dataobject_options(obj)
+        {
+          strict: obj.strict,
+          allow_unknown: obj.allow_unknown,
+          warn_on_unknown: obj.warn_on_unknown
+        }
+      end
+
+      # Whether strict validation mode is enabled (unless allow_unknown overrides).
+      #
+      # @return [Boolean]
+      def strict?
+        @options[:allow_unknown] ? false : !!@options[:strict]
+      end
+    end
+  end
+end

data/lib/castkit/contract.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "contract/base"
+
+module Castkit
+  # Castkit::Contract provides a lightweight mechanism for defining and validating
+  # structured input using a DSL similar to Castkit::DataObject, but without requiring
+  # a full data model. Contracts are ideal for validating operation inputs, service payloads,
+  # or external API request data.
+  #
+  # Contracts support primitive type coercion, nested data object validation, and configurable
+  # strictness for unknown attributes. Each contract is defined as a standalone class
+  # with its own rules and validation logic.
+  module Contract
+    class << self
+      # Builds a contract from a DSL block and optional validation rules.
+      #
+      # @example Using a block to define a contract
+      #   UserContract = Castkit::Contract.build(:user) do
+      #     string :id
+      #     string :email, required: false
+      #   end
+      #
+      #   UserContract.validate!(id: "abc") # => passes
+      #
+      # @example With custom validation rules
+      #   LooseContract = Castkit::Contract.build(:loose, strict: false) do
+      #     string :token
+      #   end
+      #
+      # @param name [String, Symbol, nil] Optional name for the contract.
+      # @param validation_rules [Hash] Optional validation rules (e.g., `strict: true`).
+      # @yield Optional DSL block to define attributes.
+      # @return [Class<Castkit::Contract::Base>]
+      def build(name = nil, **validation_rules, &block)
+        klass = Class.new(Castkit::Contract::Base)
+        klass.send(:define, name, nil, validation_rules: validation_rules, &block)
+
+        klass
+      end
+
+      # Builds a contract from an existing Castkit::DataObject class.
+      #
+      # @example Generating a contract from a DTO
+      #   class UserDto < Castkit::DataObject
+      #     string :id
+      #     string :email
+      #   end
+      #
+      #   UserContract = Castkit::Contract.from_dataobject(UserDto)
+      #   UserContract.validate!(id: "123", email: "a@example.com")
+      #
+      # @param source [Class<Castkit::DataObject>] the DataObject to generate the contract from
+      # @param as [String, Symbol, nil] Optional custom name to use for the contract
+      # @return [Class<Castkit::Contract::Base>]
+      def from_dataobject(source, as: nil)
+        name = as || Castkit::Inflector.unqualified_name(source)
+        name = Castkit::Inflector.underscore(name).to_sym
+
+        klass = Class.new(Castkit::Contract::Base)
+        klass.send(:define, name, source, validation_rules: source.validation_rules)
+
+        klass
+      end
+    end
+  end
+end

data/lib/castkit/{data_object_extensions → core}/attribute_types.rb

@@ -1,11 +1,31 @@
 # frozen_string_literal: true
 
 module Castkit
-  module DataObjectExtensions
+  module Core
     # Provides DSL methods to define typed attributes in a Castkit::DataObject.
     #
     # These helpers are shortcuts for calling `attribute` with a specific type.
     module AttributeTypes
+      # Inclusion hook: ensures config is loaded and extends the including class with DSL
+      def self.included(base)
+        Castkit.configuration # triggers type/alias registration
+        base.extend(self)
+      end
+
+      class << self
+        # Dynamically defines a DSL method for a registered type.
+        #
+        # @param type [Symbol] the name of the type
+        # @return [void]
+        def define_type_dsl(type)
+          AttributeTypes.module_eval do
+            define_method(type) do |field, **options|
+              attribute(field, type.to_sym, **options)
+            end
+          end
+        end
+      end
+
       # Defines a string attribute.
       #
       # @param field [Symbol]
@@ -95,12 +115,6 @@ module Castkit
         attribute(field, type, **options, unwrapped: true)
       end
 
-      # Alias for `array`
-      alias collection array
-
-      # Alias for `dataobject`
-      alias object dataobject
-
       # Alias for `dataobject`
       alias dto dataobject
     end

data/lib/castkit/{data_object_extensions → core}/attributes.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module DataObjectExtensions
+  module Core
     # Provides DSL and implementation for declaring attributes within a Castkit::DataObject.
     #
     # Includes support for regular, composite, transient, readonly/writeonly, and grouped attribute definitions.
@@ -127,8 +127,13 @@ module Castkit
       # @param attribute [Castkit::Attribute]
       def define_typed_writer(field, attribute)
         define_method("#{field}=") do |value|
-          casted = attribute.load(value, context: field)
-          instance_variable_set("@#{field}", casted)
+          deserialized_value = Castkit.type_caster(attribute.type).call(
+            value,
+            options: attribute.options,
+            context: attribute.field
+          )
+
+          instance_variable_set("@#{field}", deserialized_value)
         end
       end
 

data/lib/castkit/core/config.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Core
+    # Provides per-class configuration for a Castkit::DataObject,
+    # including root key handling, strict mode, and unknown key behavior.
+    module Config
+      # Sets or retrieves strict mode behavior.
+      #
+      # In strict mode, unknown keys during deserialization raise errors. If unset, falls back
+      # to `Castkit.configuration.strict_by_default`.
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean]
+      def strict(value = nil)
+        if value.nil?
+          @strict.nil? ? Castkit.configuration.strict_by_default : @strict
+        else
+          @strict = !!value
+        end
+      end
+
+      # Enables or disables ignoring unknown keys during deserialization.
+      #
+      # This is the inverse of `strict`.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def ignore_unknown(value = nil)
+        @strict = !value
+      end
+
+      # Sets or retrieves whether to emit warnings when unknown keys are encountered.
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean, nil]
+      def warn_on_unknown(value = nil)
+        value.nil? ? @warn_on_unknown : (@warn_on_unknown = value)
+      end
+
+      # Sets or retrieves whether to allow unknown keys when they are encountered.
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean, nil]
+      def allow_unknown(value = nil)
+        value.nil? ? @allow_unknown : (@allow_unknown = value)
+      end
+
+      # Returns a relaxed version of the current class with strict mode off.
+      #
+      # Useful for tolerant parsing scenarios.
+      #
+      # @param warn_on_unknown [Boolean]
+      # @return [Class] a subclass with relaxed rules
+      def relaxed(warn_on_unknown: true)
+        klass = Class.new(self)
+        klass.strict(false)
+        klass.warn_on_unknown(warn_on_unknown)
+        klass
+      end
+
+      # Returns a hash of config settings used during validation.
+      #
+      # @return [Hash{Symbol => Boolean}]
+      def validation_rules
+        @validation_rules ||= {
+          strict: strict,
+          allow_unknown: allow_unknown,
+          warn_on_unknown: warn_on_unknown
+        }
+      end
+    end
+  end
+end

data/lib/castkit/core/registerable.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../castkit"
+
+module Castkit
+  module Core
+    # Provides methods to register dynamically generated contracts and data objects
+    # into the appropriate Castkit namespaces (`Castkit::Contracts`, `Castkit::DataObjects`).
+    #
+    # This is useful when working with ephemeral classes (e.g., from `Contract.build` or
+    # `.to_dataobject`) that should be persisted and referenced as constants.
+    #
+    # @example Registering a contract class
+    #   contract = Castkit::Contract.build(:user) { string :id }
+    #   contract.extend(Castkit::Core::Registerable)
+    #   contract.register! # => Castkit::Contracts::User
+    #
+    # @example Registering a DTO
+    #   dto = contract.to_dataobject
+    #   dto.extend(Castkit::Core::Registerable)
+    #   dto.register!(as: :UserDto) # => Castkit::DataObjects::UserDto
+    module Registerable
+      CASTKIT_NAMESPACES = {
+        contracts: Castkit::Contracts,
+        dataobjects: Castkit::DataObjects
+      }.freeze
+
+      # Registers the current class in the specified Castkit namespace.
+      #
+      # @param namespace [Symbol] `:contracts` or `:dataobjects`
+      # @param as [String, Symbol, nil] Optional constant name override (PascalCase).
+      #   If not provided, falls back to the class's name (via `Inflector.pascalize(self.name)`).
+      #
+      # @raise [Castkit::Error] if class is anonymous or name already exists in the namespace
+      # @return [Class] the registered class
+      def register!(namespace:, as: nil)
+        name = Castkit::Inflector.pascalize(as || self.name)
+        raise Castkit::Error, "Unable to register anonymous classes, use as: ClassName" if name.nil?
+
+        ns = Castkit.const_get(namespace.to_s.capitalize, false)
+        raise Castkit::Error, "#{name} is already registered in #{ns}" if defined_in_namespace?(ns, name)
+
+        ns.const_set(name, self)
+        self
+      end
+
+      private
+
+      # Checks whether a constant is already defined in the given namespace.
+      #
+      # @param namespace [Module] target module (e.g., `Castkit::Contracts`)
+      # @param name [String, Symbol]
+      # @return [Boolean]
+      def defined_in_namespace?(namespace, name)
+        namespace.const_defined?(name.to_s.to_sym, false)
+      end
+    end
+  end
+end

data/lib/castkit/data_object.rb

@@ -3,11 +3,16 @@
 require "json"
 require_relative "error"
 require_relative "attribute"
-require_relative "default_serializer"
-require_relative "data_object_extensions/config"
-require_relative "data_object_extensions/attributes"
-require_relative "data_object_extensions/attribute_types"
-require_relative "data_object_extensions/deserialization"
+require_relative "serializers/default_serializer"
+require_relative "contract/validator"
+require_relative "core/config"
+require_relative "core/attributes"
+require_relative "core/attribute_types"
+require_relative "core/registerable"
+require_relative "ext/data_object/contract"
+require_relative "ext/data_object/deserialization"
+require_relative "ext/data_object/plugins"
+require_relative "ext/data_object/serialization"
 
 module Castkit
   # Base class for defining declarative, typed data transfer objects (DTOs).
@@ -25,21 +30,42 @@ module Castkit
   #   user = UserDto.new(name: "Alice", age: 30)
   #   user.to_json #=> '{"name":"Alice","age":30}'
   class DataObject
-    extend Castkit::DataObjectExtensions::Attributes
-    extend Castkit::DataObjectExtensions::AttributeTypes
+    extend Castkit::Core::Config
+    extend Castkit::Core::Attributes
+    extend Castkit::Core::AttributeTypes
+    extend Castkit::Core::Registerable
+    extend Castkit::Ext::DataObject::Contract
+    extend Castkit::Ext::DataObject::Plugins
 
-    include Castkit::DataObjectExtensions::Config
-    include Castkit::DataObjectExtensions::Deserialization
+    include Castkit::Ext::DataObject::Serialization
+    include Castkit::Ext::DataObject::Deserialization
 
     class << self
+      # Registers the current class under `Castkit::DataObjects`.
+      #
+      # @param as [String, Symbol, nil] The constant name to use (PascalCase). Defaults to class name or "Anonymous".
+      # @return [Class] the registered dataobject class
+      def register!(as: nil)
+        super(namespace: :dataobjects, as: as)
+      end
+
+      def build(&block)
+        klass = Class.new(self)
+        klass.class_eval(&block) if block_given?
+
+        klass
+      end
+
       # Gets or sets the serializer class to use for instances of this object.
       #
-      # @param value [Class<Castkit::Serializer>, nil]
-      # @return [Class<Castkit::Serializer>, nil]
-      # @raise [ArgumentError] if value does not inherit from Castkit::Serializer
+      # @param value [Class<Castkit::Serializers::Base>, nil]
+      # @return [Class<Castkit::Serializers::Base>, nil]
+      # @raise [ArgumentError] if value does not inherit from Castkit::Serializers::Base
       def serializer(value = nil)
         if value
-          raise ArgumentError, "Serializer must inherit from Castkit::Serializer" unless value < Castkit::Serializer
+          unless value < Castkit::Serializers::Base
+            raise ArgumentError, "Serializer must inherit from Castkit::Serializers::Base"
+          end
 
           @serializer = value
         else
@@ -80,20 +106,16 @@ module Castkit
 
     # Initializes the DTO from a hash of attributes.
     #
-    # @param fields [Hash] raw input hash
+    # @param data [Hash] raw input hash
     # @raise [Castkit::DataObjectError] if strict mode is enabled and unknown keys are present
-    def initialize(fields = {})
-      @__raw = fields
-
-      root = self.class.root
-      fields = fields[root] if root && fields.key?(root)
-      fields = unwrap_prefixed_fields!(fields)
+    def initialize(data = {})
+      @__raw = data.dup.freeze
+      data = unwrap_root(data)
 
-      @unknown_attributes = fields.reject { |key, _| self.class.attributes.key?(key.to_sym) }
+      @unknown_attributes = data.reject { |key, _| self.class.attributes.key?(key.to_sym) }.freeze
 
-      validate_access_config!
-      validate_keys!(fields)
-      deserialize_attributes!(fields)
+      validate_data!(data)
+      deserialize_attributes!(data)
     end
 
     # Serializes the DTO to a Ruby hash.
@@ -101,7 +123,6 @@ module Castkit
     # @param visited [Set, nil] used to track circular references
     # @return [Hash]
     def to_hash(visited: nil)
-      serializer = self.class.serializer || Castkit::DefaultSerializer
       serializer.call(self, visited: visited)
     end
 
@@ -123,55 +144,23 @@ module Castkit
 
     private
 
-    # Validates that the input only contains known keys unless configured otherwise.
+    # Helper method to call Castkit::Contract::Validator on the provided input data.
     #
     # @param data [Hash]
-    # @raise [Castkit::DataObjectError] in strict mode if unknown keys are present
-    # @return [void]
-    def validate_keys!(data)
-      valid_keys = self.class.attributes.flat_map do |_, attr|
-        [attr.key] + attr.options[:aliases]
-      end.map(&:to_sym).uniq
-
-      unknown_keys = data.keys.map(&:to_sym) - valid_keys
-      return if unknown_keys.empty?
-
-      handle_unknown_keys!(unknown_keys)
-    end
-
-    # Validates the `strict` and `allow_unknown` config flags and generates a warning if they are conflicting.
-    # - If strict == true, allow_unknown cannot be true.
-    # - If strict == false, allow_unknown can be true | false.
-    #
-    # @return [void]
-    def validate_access_config!
-      return unless self.class.strict && self.class.allow_unknown
-
-      Castkit.warning "⚠️ [Castkit] Both `strict` and `allow_unknown` are enabled, which can lead to " \
-                      "conflicting behavior. `strict` is being disabled to respect `allow_unknown`."
-    end
-
-    # Handles unknown keys found during initialization.
-    #
-    # Behavior depends on the class-level configuration:
-    # - Raises a `Castkit::DataObjectError` if strict mode is enabled.
-    # - Logs a warning if `warn_on_unknown` is enabled and `allow_unknown` is false.
-    #
-    # @param unknown_keys [Array<Symbol>] List of unknown keys not declared as attributes or aliases.
-    # @raise [Castkit::DataObjectError] If `strict` mode is enabled and unknown keys are found.
-    # @return [void]
-    def handle_unknown_keys!(unknown_keys)
-      raise Castkit::DataObjectError, "Unknown attribute(s): #{unknown_keys.join(", ")}" if strict?
-      return unless self.class.warn_on_unknown
-
-      Castkit.warning "⚠️  [Castkit] Unknown attribute(s) ignored: #{unknown_keys.join(", ")}"
+    # @raise [Castkit::ContractError]
+    def validate_data!(data)
+      Castkit::Contract::Validator.call!(
+        self.class.attributes.values,
+        data,
+        **self.class.validation_rules
+      )
     end
 
     # Returns the serializer instance or default for this object.
     #
-    # @return [Class<Castkit::Serializer>]
+    # @return [Class<Castkit::Serializers::Base>]
     def serializer
-      @serializer ||= self.class.serializer || Castkit::DefaultSerializer
+      @serializer ||= self.class.serializer || Castkit::Serializers::DefaultSerializer
     end
 
     # Returns false if self.class.allow_unknown == true, otherwise the value of self.class.strict.