castkit 0.2.0 → 0.3.0

data/lib/castkit/serializers/default_serializer.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Castkit
+  module Serializers
+    # Default serializer for Castkit::DataObject instances.
+    #
+    # Serializes attributes into a plain Ruby hash, applying access rules, nil/blank filtering,
+    # and nested structure handling. The output format supports JSON-compatible structures
+    # and respects the class-level serialization configuration.
+    class DefaultSerializer < Castkit::Serializers::Base
+      # @return [Hash{Symbol => Castkit::Attribute}] the attributes to serialize
+      attr_reader :attributes
+
+      # @return [Hash{Symbol => Object}] unrecognized attributes captured during deserialization
+      attr_reader :unknown_attributes
+
+      # @return [Hash] serialization config flags like :root, :ignore_nil, :allow_unknown
+      attr_reader :options
+
+      # Serializes the object to a hash.
+      #
+      # Includes unknown attributes if configured, and wraps in a root key if defined.
+      #
+      # @return [Hash] the fully serialized result
+      def call
+        result = serialize_attributes
+        result.merge!(unknown_attributes) if options[:allow_unknown]
+
+        options[:root] ? { options[:root].to_sym => result } : result
+      end
+
+      private
+
+      # Initializes the serializer.
+      #
+      # @param object [Castkit::DataObject] the object to serialize
+      # @param visited [Set, nil] tracks circular references
+      def initialize(object, visited: nil)
+        super
+
+        @skip_flag = "__castkit_#{object.object_id}"
+        @attributes = object.class.attributes.freeze
+        @unknown_attributes = object.unknown_attributes.freeze
+        @options = {
+          root: object.class.root,
+          ignore_nil: object.class.ignore_nil || false,
+          allow_unknown: object.class.allow_unknown || false
+        }
+      end
+
+      # Serializes all defined attributes.
+      #
+      # @return [Hash] serialized attribute key-value pairs
+      def serialize_attributes
+        attributes.values.each_with_object({}) do |attribute, hash|
+          next if attribute.skip_serialization?
+
+          serialized_value = serialize_attribute(attribute)
+          next if serialized_value == @skip_flag
+
+          assign_attribute_key!(attribute, serialized_value, hash)
+        end
+      end
+
+      # Serializes a single attribute.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @return [Object] the serialized value or skip flag
+      def serialize_attribute(attribute)
+        value = object.public_send(attribute.field)
+        return @skip_flag if skip_nil?(attribute, value)
+
+        serialized_value = process_attribute(attribute, value)
+        return @skip_flag if skip_blank?(attribute, serialized_value)
+
+        serialized_value
+      end
+
+      # Delegates serialization based on type.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Object]
+      def process_attribute(attribute, value)
+        if attribute.dataobject?
+          serialize_dataobject(attribute, value)
+        elsif attribute.dataobject_collection?
+          Array(value).map { |v| serialize_dataobject(attribute, v) }
+        else
+          type = Array(attribute.type).first
+          Castkit.type_serializer(type).call(value)
+        end
+      end
+
+      # Assigns value into nested hash structure based on key path.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @param hash [Hash]
+      # @return [void]
+      def assign_attribute_key!(attribute, value, hash)
+        key_path = attribute.key_path
+        last = key_path.pop
+        current = hash
+
+        key_path.each do |key|
+          current[key] ||= {}
+          current = current[key]
+        end
+
+        current[last] = value
+      end
+
+      # Whether to skip serialization for nil values.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Boolean]
+      def skip_nil?(attribute, value)
+        value.nil? && (attribute.ignore_nil? || options[:ignore_nil])
+      end
+
+      # Whether to skip serialization for blank values.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Boolean]
+      def skip_blank?(attribute, value)
+        blank?(value) && (attribute.ignore_blank? || options[:ignore_blank])
+      end
+
+      # True if value is nil or empty.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      # Serializes a DataObject using the proper serializer.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Castkit::DataObject]
+      # @return [Object]
+      def serialize_dataobject(attribute, value)
+        serializer = attribute.options[:serializer]
+        serializer ||= value.class.serializer
+        serializer ||= Castkit::Serializers::DefaultSerializer
+
+        serializer.call(value, visited: visited)
+      end
+    end
+  end
+end

data/lib/castkit/types/{generic.rb → base.rb}

@@ -2,14 +2,14 @@
 
 module Castkit
   module Types
-    # Generic base class for type definitions in Castkit.
+    # Abstract base class for type definitions in Castkit.
     #
     # Provides default behavior for (de)serialization, validation, and coercion.
     # All primitive types should subclass this and override methods as needed.
     #
     # The `cast!` method is the primary entry point used by attribute processing
     # to validate and coerce values in a predictable order.
-    class Generic
+    class Base
       class << self
         # Coerces and validates a value for use in a Castkit DataObject.
         #
@@ -69,7 +69,7 @@ module Castkit
 
         # Builds a default validator from the instance itself.
         #
-        # @param instance [Castkit::Types::Generic]
+        # @param instance [Castkit::Types::Base]
         # @return [Proc] a lambda wrapping `#validate!`
         def default_validator(instance)
           lambda do |value, options: {}, context: nil|
@@ -111,10 +111,9 @@ module Castkit
       # @param type [Symbol]
       # @param value [Object, nil]
       # @return [void]
-      def type_error!(type, value)
-        message = "value must be a #{type}, got #{value.inspect}"
-
-        raise Castkit::TypeError, message if Castkit.configuration.raise_type_errors
+      def type_error!(type, value, context: nil)
+        message = "#{context || "value"} must be a #{type}, got #{value}"
+        raise Castkit::AttributeError, message if Castkit.configuration.raise_type_errors
 
         Castkit.warning "[Castkit] #{message}" if Castkit.configuration.enable_warnings
       end

data/lib/castkit/types/boolean.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "generic"
+require_relative "base"
+require_relative "../validators/boolean_validator"
 
 module Castkit
   module Types
@@ -10,7 +11,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `boolean :is_active`
-    class Boolean < Generic
+    class Boolean < Base
       # Deserializes the input into a boolean value.
       #
       # Accepts:
@@ -21,14 +22,7 @@ module Castkit
       # @return [Boolean]
       # @raise [Castkit::TypeError] if the value cannot be coerced to a boolean
       def deserialize(value)
-        case value.to_s.downcase
-        when "true", "1"
-          true
-        when "false", "0"
-          false
-        else
-          type_error!(:boolean, value)
-        end
+        value
       end
 
       # Serializes the boolean value (pass-through).
@@ -38,6 +32,16 @@ module Castkit
       def serialize(value)
         value
       end
+
+      # Validates the Boolean value.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::BooleanValidator.call(value, options: options, context: context)
+      end
     end
   end
 end

data/lib/castkit/types/collection.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "generic"
+require_relative "base"
+require_relative "../validators/collection_validator"
 
 module Castkit
   module Types
@@ -11,7 +12,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `array :tags, of: :string`
-    class Collection < Generic
+    class Collection < Base
       # Deserializes the value into an array using `Array(value)`.
       #
       # @param value [Object]
@@ -19,6 +20,16 @@ module Castkit
       def deserialize(value)
         Array(value)
       end
+
+      # Validates the Array value.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String, nil] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: nil)
+        Castkit::Validators::CollectionValidator.call(value, options: options, context: context)
+      end
     end
   end
 end

data/lib/castkit/types/date.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
-require_relative "generic"
+require_relative "base"
 
 module Castkit
   module Types
@@ -12,7 +12,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `date :published_on`
-    class Date < Generic
+    class Date < Base
       # Deserializes the input value to a `Date` instance.
       #
       # @param value [Object]

data/lib/castkit/types/date_time.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
-require_relative "generic"
+require_relative "base"
 
 module Castkit
   module Types
@@ -12,7 +12,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `datetime :published_ad`
-    class DateTime < Generic
+    class DateTime < Base
       # Deserializes the input value to a `DateTime` instance.
       #
       # @param value [Object]

data/lib/castkit/types/float.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "generic"
-require_relative "../validators/numeric_validator"
+require_relative "base"
+require_relative "../validators/float_validator"
 
 module Castkit
   module Types
@@ -13,7 +13,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `integer :count`
-    class Float < Generic
+    class Float < Base
       # Deserializes the input value to an Float.
       #
       # @param value [Object]
@@ -30,7 +30,7 @@ module Castkit
         value
       end
 
-      # Validates the Float value using Castkit's NumericValidator.
+      # Validates the Float value using Castkit's FloatValidator.
       #
       # Supports options like `min:` and `max:`.
       #
@@ -39,7 +39,7 @@ module Castkit
       # @param context [Symbol, String] attribute context for error messages
       # @return [void]
       def validate!(value, options: {}, context: {})
-        Castkit::Validators::NumericValidator.call(value, options: options, context: context)
+        Castkit::Validators::FloatValidator.call(value, options: options, context: context)
       end
     end
   end

data/lib/castkit/types/integer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "generic"
-require_relative "../validators/numeric_validator"
+require_relative "base"
+require_relative "../validators/integer_validator"
 
 module Castkit
   module Types
@@ -13,7 +13,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `integer :count`
-    class Integer < Generic
+    class Integer < Base
       # Deserializes the input value to an Integer.
       #
       # @param value [Object]
@@ -30,7 +30,7 @@ module Castkit
         value
       end
 
-      # Validates the Integer value using Castkit's NumericValidator.
+      # Validates the Integer value using Castkit's IntegerValidator.
       #
       # Supports options like `min:` and `max:`.
       #
@@ -39,7 +39,7 @@ module Castkit
       # @param context [Symbol, String] attribute context for error messages
       # @return [void]
       def validate!(value, options: {}, context: {})
-        Castkit::Validators::NumericValidator.call(value, options: options, context: context)
+        Castkit::Validators::IntegerValidator.call(value, options: options, context: context)
       end
     end
   end

data/lib/castkit/types/string.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "generic"
+require_relative "base"
 require_relative "../validators/string_validator"
 
 module Castkit
@@ -12,7 +12,7 @@ module Castkit
     #
     # This class is used internally by Castkit when an attribute is defined with:
     #   `string :id`
-    class String < Generic
+    class String < Base
       # Deserializes the value by coercing it to a string using `to_s`.
       #
       # @param value [Object]

data/lib/castkit/types.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "types/base"
 require_relative "types/collection"
 require_relative "types/boolean"
 require_relative "types/date"
 require_relative "types/date_time"
 require_relative "types/float"
-require_relative "types/generic"
 require_relative "types/integer"
 require_relative "types/string"
 

data/lib/castkit/validators/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Validators
+    # Abstract base class for all attribute validators.
+    #
+    # Validators are responsible for enforcing value constraints (e.g., type checks,
+    # format rules, numerical bounds). All validators must inherit from this base class
+    # and implement the `#call` instance method.
+    #
+    # Supports both instance-level and class-level invocation via `.call`.
+    #
+    # @abstract Subclasses must implement `#call`.
+    class Base
+      class << self
+        # Entry point for validating a value using the validator class.
+        #
+        # Instantiates the validator and invokes `#call` with the provided arguments.
+        #
+        # @param value [Object] the value to validate
+        # @param options [Hash] additional validation options (e.g., `min`, `max`, `format`)
+        # @param context [Symbol, String, Hash] context for the validation (usually the attribute name)
+        # @return [void]
+        # @raise [Castkit::AttributeError] if validation fails and `raise_type_errors` is true
+        def call(value, options:, context:)
+          new.call(value, options: options, context: context)
+        end
+      end
+
+      # Validates the value.
+      #
+      # @abstract
+      # @param value [Object] the value to validate
+      # @param options [Hash] validation options (e.g., min, max, format)
+      # @param context [Symbol, String, Hash] context for validation errors
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented in subclass
+      def call(value, options:, context:)
+        raise NotImplementedError, "#{self.class.name} must implement `#call`"
+      end
+
+      protected
+
+      # Emits or raises a type error depending on global configuration.
+      #
+      # @param type [Symbol] the expected type (e.g., `:integer`)
+      # @param value [Object, nil] the received value
+      # @param context [Symbol, String, nil] context to include in error messages
+      # @raise [Castkit::AttributeError] if `raise_type_errors` is enabled
+      # @return [void]
+      def type_error!(type, value, context: nil)
+        message = "#{context || "value"} must be a #{type}, got #{value}"
+        raise Castkit::AttributeError, message if Castkit.configuration.raise_type_errors
+
+        Castkit.warning "[Castkit] #{message}" if Castkit.configuration.enable_warnings
+      end
+    end
+  end
+end

data/lib/castkit/validators/boolean_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Castkit
+  module Validators
+    # Validator for boolean attributes.
+    #
+    # Accepts various representations of boolean values, including strings and integers.
+    # Converts common truthy/falsy string values into booleans, otherwise raises a type error.
+    #
+    # This validator is typically used internally by `Castkit::Types::Boolean`.
+    #
+    # @example
+    #   validator = Castkit::Validators::BooleanValidator.new
+    #   validator.call("true", _options: {}, context: :enabled) # => true
+    #   validator.call("0", _options: {}, context: :enabled)    # => false
+    #   validator.call("nope", _options: {}, context: :enabled) # raises Castkit::AttributeError
+    class BooleanValidator
+      # Validates the Boolean value.
+      #
+      # @param value [Object] the input to validate
+      # @param _options [Hash] unused, provided for consistency with other validators
+      # @param context [Symbol, String] the attribute name or path for error messages
+      # @return [Boolean]
+      # @raise [Castkit::AttributeError] if the value is not a recognizable boolean
+      def call(value, _options:, context:)
+        case value.to_s.downcase
+        when "true", "1"
+          true
+        when "false", "0"
+          false
+        else
+          type_error!(:boolean, value, context: context)
+        end
+      end
+    end
+  end
+end

data/lib/castkit/validators/collection_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../validators/base"
+
+module Castkit
+  module Validators
+    # Validator for array (collection) attributes.
+    #
+    # Ensures that the provided value is an instance of `Array`. This validator is
+    # typically used by `Castkit::Types::Collection` for attributes defined as arrays.
+    #
+    # @example
+    #   validator = Castkit::Validators::CollectionValidator.new
+    #   validator.call([1, 2, 3], _options: {}, context: :tags) # => passes
+    #   validator.call("foo", _options: {}, context: :tags)     # raises Castkit::AttributeError
+    class CollectionValidator < Castkit::Validators::Base
+      # Validates that the value is an Array.
+      #
+      # @param value [Object] the value to validate
+      # @param _options [Hash] unused, for interface consistency
+      # @param context [Symbol, String] the field or context for error messaging
+      # @return [void]
+      # @raise [Castkit::AttributeError] if value is not an Array
+      def call(value, _options:, context:)
+        type_error!(:array, value, context: context) unless value.is_a?(::Array)
+      end
+    end
+  end
+end

data/lib/castkit/validators/float_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "numeric_validator"
+
+module Castkit
+  module Validators
+    # Validator for Float attributes.
+    #
+    # Ensures the value is a `Float`, and applies any numeric bounds (`min`, `max`)
+    # defined in the attribute options. Inherits shared logic from `NumericValidator`.
+    #
+    # @example
+    #   validator = Castkit::Validators::FloatValidator.new
+    #   validator.call(3.14, options: { min: 0.0 }, context: :price) # => passes
+    #   validator.call(42, options: {}, context: :price)             # raises Castkit::AttributeError
+    class FloatValidator < Castkit::Validators::NumericValidator
+      # Validates that the value is a Float and within optional bounds.
+      #
+      # @param value [Object, nil] the value to validate
+      # @param options [Hash] validation options (e.g., `min`, `max`)
+      # @param context [Symbol, String] the attribute name or key for error messages
+      # @raise [Castkit::AttributeError] if value is not a Float or out of range
+      # @return [void]
+      def call(value, options:, context:)
+        return type_error!(:float, value, context: context) unless value.is_a?(::Float)
+
+        super
+      end
+    end
+  end
+end

data/lib/castkit/validators/integer_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "numeric_validator"
+
+module Castkit
+  module Validators
+    # Validator for Integer attributes.
+    #
+    # Ensures the value is an instance of `Integer` and optionally checks numerical constraints
+    # such as `min` and `max`, inherited from `Castkit::Validators::NumericValidator`.
+    #
+    # @example Validating an Integer attribute
+    #   IntegerValidator.call(42, options: { min: 10, max: 100 }, context: :count)
+    #
+    # @see Castkit::Validators::NumericValidator
+    class IntegerValidator < Castkit::Validators::NumericValidator
+      # Validates the Integer value.
+      #
+      # @param value [Object, nil] the value to validate
+      # @param options [Hash] validation options (e.g., `min`, `max`)
+      # @param context [Symbol, String] the attribute name or context for error messages
+      # @raise [Castkit::AttributeError] if the value is not an Integer or fails validation rules
+      # @return [void]
+      def call(value, options:, context:)
+        return type_error!(:integer, value, context: context) unless value.is_a?(::Integer)
+
+        super
+      end
+    end
+  end
+end

data/lib/castkit/validators/numeric_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "base_validator"
+require_relative "base"
 
 module Castkit
   module Validators
     # Validates that a numeric value falls within the allowed range.
     #
     # Supports `:min` and `:max` options to enforce bounds.
-    class NumericValidator < Castkit::Validators::BaseValidator
+    class NumericValidator < Castkit::Validators::Base
       # Validates the numeric value.
       #
       # @param value [Numeric] the value to validate

data/lib/castkit/validators/string_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "base_validator"
+require_relative "base"
 
 module Castkit
   module Validators
     # Validates that a value is a String and optionally conforms to a format.
     #
     # Supports format validation using a Regexp or a custom Proc.
-    class StringValidator < Castkit::Validators::BaseValidator
+    class StringValidator < Castkit::Validators::Base
       # Validates the string value.
       #
       # @param value [Object] the value to validate
@@ -16,8 +16,7 @@ module Castkit
       # @raise [Castkit::AttributeError] if value is not a string or fails format validation
       # @return [void]
       def call(value, options:, context:)
-        raise Castkit::AttributeError, "#{context} must be a string" unless value.is_a?(String)
-
+        return type_error!(:string, value, context: context) unless value.is_a?(::String)
         return unless options[:format]
 
         case options[:format]

data/lib/castkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Castkit
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end