castkit 0.1.2 → 0.3.0

data/lib/castkit/data_object_extensions/config.rb

@@ -1,113 +0,0 @@
-# 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_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
-      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

@@ -1,110 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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{Symbol => Object}] attributes that are not predefined or known to the object
-    attr_reader :unknown_attributes
-
-    # @return [Hash] serialization options (root key, ignore_nil, allow_unknown, etc.)
-    attr_reader :options
-
-    # Returns the serialized object as a Hash.
-    #
-    # Includes root wrapping if configured. If `allow_unknown` is set to true, unknown attributes
-    # are merged into the final result.
-    #
-    # @return [Hash] The serialized object, potentially wrapped with a root key
-    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 with the target object and context.
-    #
-    # @param raw [Castkit::DataObject] the object to serialize
-    # @param visited [Set, nil] used to detect circular references (default is nil)
-    def initialize(raw, visited: nil)
-      super
-
-      # Setting up attributes, unknown attributes, and options based on the class-level configuration
-      @attributes = raw.class.attributes
-      @unknown_attributes = raw.unknown_attributes
-      @options = {
-        root: raw.class.root,
-        ignore_nil: raw.class.ignore_nil || false,
-        allow_unknown: raw.class.allow_unknown || false
-      }
-    end
-
-    # Iterates over attributes and serializes each into a result hash.
-    #
-    # @return [Hash] The serialized attributes as a hash
-    def serialize_attributes
-      attributes.each_with_object({}) do |(_, attribute), hash|
-        next if attribute.skip_serialization?
-
-        # Serializing each attribute
-        serialized_value = serialize_attribute(attribute)
-        next if serialized_value == SKIP_ATTRIBUTE
-
-        # Assign the serialized value to the correct key in the hash
-        assign_attribute_key!(hash, attribute, serialized_value)
-      end
-    end
-
-    # Process and serialize a given attribute.
-    #
-    # This handles value extraction, skipping when nil values are encountered, and ensuring
-    # attributes are serialized according to their rules.
-    #
-    # @param attribute [Castkit::Attribute] The attribute instance to serialize
-    # @return [Object, nil] The serialized value or SKIP_ATTRIBUTE if the value should be skipped
-    def serialize_attribute(attribute)
-      # Fetch the value of the attribute from the object
-      value = obj.public_send(attribute.field)
-
-      # Skip serialization if value is nil and ignore_nil is set to true
-      return SKIP_ATTRIBUTE if value.nil? && (attribute.ignore_nil? || options[:ignore_nil])
-
-      # Serialize the value using the attribute's dump method
-      serialized_value = attribute.dump(value, visited: visited)
-
-      # Skip if value is blank and ignore_blank is set to true
-      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.
-    #
-    # This ensures attributes with nested key paths (like `address.city`) are placed into nested hashes.
-    #
-    # @param hash [Hash] The resulting hash to populate with the serialized values
-    # @param attribute [Castkit::Attribute] The attribute being serialized
-    # @param value [Object] The serialized value
-    # @return [void] Updates the hash in-place
-    def assign_attribute_key!(hash, attribute, value)
-      key_path = attribute.key_path
-      last = key_path.pop
-      current = hash
-
-      # Traverse the key path and create nested hashes as needed
-      key_path.each do |key|
-        current[key] ||= {}
-        current = current[key]
-      end
-
-      # Assign the final value to the last key in the path
-      current[last] = value
-    end
-
-    # Determines if a value is blank (nil, empty array, empty hash, empty string, etc.)
-    #
-    # @param value [Object, nil] The value to check
-    # @return [Boolean] true if the value is blank, false otherwise
-    def blank?(value)
-      value.nil? || (value.respond_to?(:empty?) && value.empty?)
-    end
-  end
-end

data/lib/castkit/serializer.rb

@@ -1,92 +0,0 @@
-# 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/validators.rb

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