castkit 0.1.0

data/lib/castkit/data_object_extensions/config.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DataObjectExtensions
+    # Provides per-class configuration for a Castkit::DataObject,
+    # including root key handling, strict mode, and unknown key behavior.
+    module Config
+      # Automatically extends class-level methods when included.
+      #
+      # @param base [Class]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level configuration methods.
+      module ClassMethods
+        # Sets or retrieves the root key to wrap the object under during (de)serialization.
+        #
+        # @param value [String, Symbol, nil] optional root key
+        # @return [Symbol, nil]
+        def root(value = nil)
+          @root = value.to_s.strip.to_sym if value
+          @root
+        end
+
+        # Sets or retrieves whether to skip `nil` values in output.
+        #
+        # @param value [Boolean, nil]
+        # @return [Boolean, nil]
+        def ignore_nil(value = nil)
+          value.nil? ? @ignore_nil : (@ignore_nil = value)
+        end
+
+        # Sets or retrieves whether to skip blank values (`[]`, `{}`, `""`, etc.) in output.
+        #
+        # Defaults to true unless explicitly set to false.
+        #
+        # @param value [Boolean, nil]
+        # @return [Boolean]
+        def ignore_blank(value = nil)
+          @ignore_blank = value.nil? || value
+        end
+
+        # Sets or retrieves strict mode behavior.
+        #
+        # In strict mode, unknown keys during deserialization raise errors.
+        #
+        # @param value [Boolean, nil]
+        # @return [Boolean]
+        def strict(value = nil)
+          if value.nil?
+            @strict.nil? || @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_unknown_keys : (@warn_unknown_keys = 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
+      end
+
+      # Returns the root key for this instance.
+      #
+      # @return [Symbol]
+      def root_key
+        self.class.root.to_s.strip.to_sym
+      end
+
+      # Whether a root key is configured for this instance.
+      #
+      # @return [Boolean]
+      def root_key_set?
+        !self.class.root.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/castkit/data_object_extensions/deserialization.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DataObjectExtensions
+    # Adds deserialization support for Castkit::DataObject instances.
+    #
+    # Handles attribute loading, alias resolution, and unwrapped field extraction.
+    module Deserialization
+      # Hooks in class methods like `.from_hash` when included.
+      #
+      # @param base [Class]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level deserialization helpers.
+      module ClassMethods
+        # Builds a new instance from a Hash, symbolizing keys as needed.
+        #
+        # @param hash [Hash]
+        # @return [Castkit::DataObject]
+        def from_hash(hash)
+          hash = hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+          new(hash)
+        end
+
+        # @!method from_h(hash)
+        #   Alias for {.from_hash}
+        #
+        # @!method creator(hash)
+        #   Alias for {.from_hash}
+        alias from_h from_hash
+        alias creator from_hash
+      end
+
+      private
+
+      # Loads attribute values from the given hash.
+      #
+      # Respects access control (e.g., `writeable?`) and uses `.load` for casting/validation.
+      #
+      # @param data [Hash]
+      # @return [void]
+      def deserialize_attributes!(data)
+        self.class.attributes.each do |field, attribute|
+          next if attribute.skip_deserialization?
+
+          value = fetch_attribute_key(data, attribute)
+          value = attribute.load(value, context: field)
+
+          instance_variable_set("@#{field}", value)
+        end
+      end
+
+      # Fetches the best matching value from the hash using attribute key and aliases.
+      #
+      # @param data [Hash]
+      # @param attribute [Castkit::Attribute]
+      # @return [Object]
+      def fetch_attribute_key(data, attribute)
+        attribute.key_path(with_aliases: true).each do |path|
+          value = path.reduce(data) { |memo, key| memo.is_a?(Hash) ? memo[key] : nil }
+          return value unless value.nil?
+        end
+
+        nil
+      end
+
+      # Extracts prefixed fields for unwrapped attributes and groups them under the original field key.
+      #
+      # @param data [Hash]
+      # @return [Hash] modified input hash with unwrapped values nested under their base field
+      def unwrap_prefixed_fields!(data)
+        self.class.attributes.each_value do |attribute|
+          next unless attribute.unwrapped?
+
+          unwrapped, keys_to_remove = unwrap_prefixed_values(data, attribute)
+          next if unwrapped.empty?
+
+          data[attribute.field] = unwrapped
+          keys_to_remove.each { |k| data.delete(k) }
+        end
+
+        data
+      end
+
+      # Returns the prefixed key-value pairs for a given unwrapped attribute.
+      #
+      # @param data [Hash]
+      # @param attribute [Castkit::Attribute]
+      # @return [Array<Hash, Array<Symbol>>] extracted key-value pairs and keys to delete
+      def unwrap_prefixed_values(data, attribute)
+        prefix = attribute.prefix.to_s
+        unwrapped_data = {}
+        keys_to_remove = []
+
+        data.each do |k, v|
+          k_str = k.to_s
+          next unless k_str.start_with?(prefix)
+
+          stripped = k_str.sub(prefix, "").to_sym
+          unwrapped_data[stripped] = v
+          keys_to_remove << k
+        end
+
+        [unwrapped_data, keys_to_remove]
+      end
+    end
+  end
+end

data/lib/castkit/default_serializer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "serializer"
+
+module Castkit
+  # Default serializer for Castkit::DataObject instances.
+  #
+  # Serializes attributes based on access rules, nil/blank filtering, and nested structure.
+  class DefaultSerializer < Castkit::Serializer
+    SKIP_ATTRIBUTE = :__castkit_skip_attribute
+
+    # @return [Hash{Symbol => Castkit::Attribute}] attributes to serialize
+    attr_reader :attributes
+
+    # @return [Hash] serialization options (root key, ignore_nil, etc.)
+    attr_reader :options
+
+    # Returns the serialized object as a Hash.
+    #
+    # Includes root wrapping if configured.
+    #
+    # @return [Hash]
+    def call
+      result = serialize_attributes
+      options[:root] ? { options[:root].to_sym => result } : result
+    end
+
+    private
+
+    # Initializes the serializer with the target object and context.
+    #
+    # @param raw [Castkit::DataObject] the object to serialize
+    # @param visited [Set, nil] used to detect circular references
+    def initialize(raw, visited: nil)
+      super
+
+      @attributes = raw.class.attributes
+      @options = {
+        root: raw.class.root,
+        ignore_nil: raw.class.ignore_nil
+      }
+    end
+
+    # Iterates over attributes and serializes each into a result hash.
+    #
+    # @return [Hash]
+    def serialize_attributes
+      attributes.each_with_object({}) do |(_, attribute), hash|
+        next if attribute.skip_serialization?
+
+        serialized_value = serialize_attribute(attribute)
+        next if serialized_value == SKIP_ATTRIBUTE
+
+        assign_attribute_key!(hash, attribute, serialized_value)
+      end
+    end
+
+    # Process and serialize a given attribute.
+    #
+    # @param attribute [Castkit::Attribute] The attribute instance.
+    # @param [Object]
+    def serialize_attribute(attribute)
+      value = obj.public_send(attribute.field)
+      return SKIP_ATTRIBUTE if value.nil? && (attribute.ignore_nil? || options[:ignore_nil])
+
+      serialized_value = attribute.dump(value, visited: visited)
+      return SKIP_ATTRIBUTE if blank?(serialized_value) && (attribute.ignore_blank? || options[:ignore_blank])
+
+      serialized_value
+    end
+
+    # Assigns a serialized value into the hash using nested key paths.
+    #
+    # @param hash [Hash]
+    # @param attribute [Castkit::Attribute]
+    # @param value [Object]
+    # @return [void]
+    def assign_attribute_key!(hash, attribute, value)
+      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
+
+    # Determines if a value is blank (nil or empty).
+    #
+    # @param value [Object, nil]
+    # @return [Boolean]
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value&.empty?)
+    end
+  end
+end

data/lib/castkit/error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Castkit
+  # Base error class for all Castkit-related exceptions.
+  class Error < StandardError
+    # @return [Hash, Object, nil] contextual data to aid in debugging
+    attr_reader :context
+
+    # Initializes a Castkit error.
+    #
+    # @param msg [String] the error message
+    # @param context [Object, nil] optional data object or hash for context
+    def initialize(msg, context: nil)
+      super(msg)
+      @context = context
+    end
+  end
+
+  # Raised for issues related to Castkit::DataObject initialization or usage.
+  class DataObjectError < Error; end
+
+  # Raised for attribute validation, access, or casting failures.
+  class AttributeError < Error
+    # Returns the field name related to the error, if available.
+    #
+    # @return [Symbol]
+    def field
+      context.is_a?(Hash) ? context[:field] : context || :unknown
+    end
+
+    # Formats the error message with field info if available.
+    #
+    # @return [String]
+    def to_s
+      field_info = field ? " (on #{field})" : ""
+      "#{super}#{field_info}"
+    end
+  end
+
+  # Raised during serialization if an object fails to serialize properly.
+  class SerializationError < Error; end
+end

data/lib/castkit/serializer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Castkit
+  # Abstract base class for defining custom serializers for Castkit::DataObject instances.
+  #
+  # Handles circular reference detection and provides a consistent `call` API.
+  #
+  # Subclasses must implement an instance method `#call` that returns a hash-like representation.
+  #
+  # @example Usage
+  #   class CustomSerializer < Castkit::Serializer
+  #     private
+  #
+  #     def call
+  #       { type: obj.class.name, data: obj.to_h }
+  #     end
+  #   end
+  #
+  #   CustomSerializer.call(user_dto)
+  class Serializer
+    class << self
+      # Entrypoint for serializing an object.
+      #
+      # @param obj [Castkit::DataObject] the object to serialize
+      # @param visited [Set, nil] used to track visited object IDs
+      # @return [Object] result of custom serialization
+      def call(obj, visited: nil)
+        new(obj, visited: visited).send(:serialize)
+      end
+    end
+
+    # @return [Castkit::DataObject] the object being serialized
+    attr_reader :obj
+
+    protected
+
+    # Fallback to the default serializer.
+    #
+    # @return [Hash]
+    def serialize_with_default
+      Castkit::DefaultSerializer.call(obj, visited: visited)
+    end
+
+    private
+
+    # @return [Set<Integer>] a set of visited object IDs to detect circular references
+    attr_reader :visited
+
+    # Initializes the serializer instance.
+    #
+    # @param obj [Castkit::DataObject]
+    # @param visited [Set, nil]
+    def initialize(obj, visited: nil)
+      @obj = obj
+      @visited = visited || Set.new
+    end
+
+    # Subclasses must override this method to implement serialization logic.
+    #
+    # @raise [NotImplementedError]
+    # @return [Object]
+    def call
+      raise NotImplementedError, "#{self.class.name} must implement `#call`"
+    end
+
+    # Wraps the actual serialization logic with circular reference detection.
+    #
+    # @return [Object]
+    # @raise [Castkit::SerializationError] if a circular reference is detected
+    def serialize
+      check_circular_reference!
+      visited << obj.object_id
+
+      result = call
+      visited.delete(obj.object_id)
+
+      result
+    end
+
+    # Raises if the object has already been visited (circular reference).
+    #
+    # @raise [Castkit::SerializationError]
+    # @return [void]
+    def check_circular_reference!
+      return unless visited.include?(obj.object_id)
+
+      raise Castkit::SerializationError, "Circular reference detected for #{obj.class}"
+    end
+  end
+end

data/lib/castkit/validator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Castkit
+  # Abstract base class for all attribute validators.
+  #
+  # Validators ensure that a value conforms to specific rules (e.g., type, format, range).
+  # Subclasses must implement the instance method `#call`.
+  #
+  # @abstract
+  class Validator
+    class << self
+      # Invokes the validator with the given arguments.
+      #
+      # @param value [Object] the attribute value to validate
+      # @param options [Hash] the attribute options (e.g., `min`, `max`, `format`)
+      # @param context [Symbol, String, Hash] the attribute name or context for error reporting
+      # @return [void]
+      # @raise [Castkit::AttributeError] if validation fails
+      def call(value, options:, context:)
+        new.call(value, options: options, context: context)
+      end
+    end
+
+    # Validates the attribute value.
+    #
+    # @abstract Override in subclasses.
+    #
+    # @param value [Object] the attribute value to validate
+    # @param options [Hash] the attribute options
+    # @param context [Symbol, String, Hash] the attribute name or context
+    # @return [void]
+    # @raise [NotImplementedError] unless implemented in a subclass
+    def call(value, options:, context:)
+      raise NotImplementedError, "#{self.class.name} must implement `#call`"
+    end
+  end
+end

data/lib/castkit/validators/numeric_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../validator"
+
+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::Validator
+      # Validates the numeric value.
+      #
+      # @param value [Numeric] 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 the value violates min/max bounds
+      # @return [void]
+      def call(value, options:, context:)
+        if options[:min] && value < options[:min]
+          raise Castkit::AttributeError, "#{context} must be >= #{options[:min]}"
+        end
+
+        return unless options[:max] && value > options[:max]
+
+        raise Castkit::AttributeError, "#{context} must be <= #{options[:max]}"
+      end
+    end
+  end
+end

data/lib/castkit/validators/string_validator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../validator"
+
+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::Validator
+      # Validates the string value.
+      #
+      # @param value [Object] the value to validate
+      # @param options [Hash] validation options (e.g., `format: /regex/` or `format: ->(v) { ... }`)
+      # @param context [Symbol, String] the attribute name or key for error messages
+      # @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 unless options[:format]
+
+        case options[:format]
+        when Regexp
+          raise Castkit::AttributeError, "#{context} must match format" unless value =~ options[:format]
+        when Proc
+          raise Castkit::AttributeError, "#{context} failed format validation" unless options[:format].call(value)
+        else
+          raise Castkit::AttributeError, "#{context} has unsupported format validator: #{options[:format].class}"
+        end
+      end
+    end
+  end
+end

data/lib/castkit/validators.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "validators/numeric_validator"
+require_relative "validators/string_validator"

data/lib/castkit/version.rb

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

data/lib/castkit.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "castkit/version"
+require_relative "castkit/data_object"
+
+# Castkit is a lightweight, type-safe data object system for Ruby.
+#
+# It provides a declarative DSL for defining DTOs with typecasting, validation,
+# access control, serialization, deserialization, and OpenAPI-friendly schema generation.
+#
+# @example Defining a simple data object
+#   class UserDto < Castkit::DataObject
+#     string :name
+#     integer :age, required: false
+#   end
+#
+#   user = UserDto.new(name: "Alice", age: 30)
+#   user.to_h #=> { name: "Alice", age: 30 }
+module Castkit; end

data/sig/castkit.rbs

@@ -0,0 +1,4 @@
+module Castkit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end