castkit 0.1.2 → 0.2.0

data/lib/castkit/attribute_extensions/options.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../data_object"
-
-module Castkit
-  module AttributeExtensions
-    # Provides access to normalized attribute options and helper predicates.
-    #
-    # These methods support Castkit attribute behavior such as default values,
-    # key mapping, optionality, and structural roles (e.g. composite or unwrapped).
-    module Options
-      # Default options for attributes.
-      #
-      # @return [Hash<Symbol, Object>]
-      DEFAULT_OPTIONS = {
-        required: true,
-        ignore_nil: false,
-        ignore_blank: false,
-        ignore: false,
-        composite: false,
-        unwrapped: false,
-        prefix: nil,
-        access: %i[read write]
-      }.freeze
-
-      # Returns the default value for the attribute.
-      #
-      # If the default is callable, it is invoked.
-      #
-      # @return [Object]
-      def default
-        val = @default
-        val.respond_to?(:call) ? val.call : val
-      end
-
-      # Returns the serialization/deserialization key.
-      #
-      # Falls back to the field name if `:key` is not specified.
-      #
-      # @return [Symbol, String]
-      def key
-        options[:key] || field
-      end
-
-      # Returns the key path for accessing nested keys.
-      #
-      # Optionally includes alias key paths if `with_aliases` is true.
-      #
-      # @param with_aliases [Boolean]
-      # @return [Array<Array<Symbol>>] nested key paths
-      def key_path(with_aliases: false)
-        path = key.to_s.split(".").map(&:to_sym) || []
-        return path unless with_aliases
-
-        [path] + alias_paths
-      end
-
-      # Returns all alias key paths as arrays of symbols.
-      #
-      # @return [Array<Array<Symbol>>]
-      def alias_paths
-        options[:aliases].map { |a| a.to_s.split(".").map(&:to_sym) }
-      end
-
-      # Whether the attribute is required for object construction.
-      #
-      # @return [Boolean]
-      def required?
-        options[:required]
-      end
-
-      # Whether the attribute is optional.
-      #
-      # @return [Boolean]
-      def optional?
-        !required?
-      end
-
-      # Whether to ignore `nil` values during serialization.
-      #
-      # @return [Boolean]
-      def ignore_nil?
-        options[:ignore_nil]
-      end
-
-      # Whether to ignore blank values (`[]`, `{}`, empty strings) during serialization.
-      #
-      # @return [Boolean]
-      def ignore_blank?
-        options[:ignore_blank]
-      end
-
-      # Whether the attribute is a nested Castkit::DataObject.
-      #
-      # @return [Boolean]
-      def dataobject?
-        Castkit.dataobject?(type)
-      end
-
-      # Whether the attribute is a collection of Castkit::DataObjects.
-      #
-      # @return [Boolean]
-      def dataobject_collection?
-        type == :array && Castkit.dataobject?(options[:of])
-      end
-
-      # Whether the attribute is considered composite (not exposed in serialized output).
-      #
-      # @return [Boolean]
-      def composite?
-        options[:composite]
-      end
-
-      # Whether the attribute is unwrapped into the parent object.
-      #
-      # Only applies to Castkit::DataObject types.
-      #
-      # @return [Boolean]
-      def unwrapped?
-        dataobject? && options[:unwrapped]
-      end
-
-      # Returns the prefix used for unwrapped attributes.
-      #
-      # @return [String, nil]
-      def prefix
-        options[:prefix]
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/serialization.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-module Castkit
-  module AttributeExtensions
-    # Handles serialization (`dump`) and deserialization (`load`) of attribute values.
-    #
-    # Supports primitive types, arrays, and nested Castkit::DataObject instances.
-    module Serialization
-      # Serializes a value into a format suitable for output (e.g., JSON or Hash).
-      #
-      # If the value is a Castkit::DataObject, a custom serializer is used if configured.
-      #
-      # @param value [Object, nil] the value to serialize
-      # @param visited [Set, nil] used for circular reference detection
-      # @return [Object, nil] the serialized value
-      def dump(value, visited: nil)
-        return value if value.nil?
-
-        if type == :array
-          Array(value).map { |val| dump_element(val, visited: visited) }
-        else
-          dump_element(value, visited: visited)
-        end
-      end
-
-      # Deserializes and validates a value during object instantiation.
-      #
-      # Applies default value, casts, and runs validators.
-      #
-      # @param value [Object] the input value
-      # @param context [Symbol] the attribute name or context key
-      # @return [Object] the deserialized and validated value
-      # @raise [Castkit::AttributeError] if value is required but missing
-      def load(value, context:)
-        value = default if value.nil?
-        return raise_error!("#{field} is required for instantiation") if value.nil? && required?
-
-        value = cast(value)
-        validate_value!(value, context: context)
-
-        value
-      end
-
-      private
-
-      # Serializes a single element value.
-      #
-      # - Uses a serializer if the value is a Castkit::DataObject.
-      # - Converts `to_h` if the value is hash-like.
-      #
-      # @param value [Object, nil] the element to dump
-      # @param visited [Set, nil]
-      # @return [Object, nil]
-      def dump_element(value, visited: nil)
-        return value if value.nil? || primitive?(value)
-
-        if value.is_a?(Castkit::DataObject)
-          serializer = options[:serializer] || value.class.serializer || Castkit::DefaultSerializer
-          serializer.call(value, visited: visited)
-        elsif hashable?(value)
-          value.to_h(visited)
-        else
-          value
-        end
-      end
-
-      # Checks whether a value is a hashable object suitable for `to_h` dumping.
-      #
-      # @param value [Object, nil]
-      # @return [Boolean]
-      def hashable?(value)
-        value.respond_to?(:to_h) && !primitive?(value) && !value.is_a?(Castkit::Attribute)
-      end
-
-      # Determines if a value is a primitive type.
-      #
-      # @param value [Object, nil]
-      # @return [Boolean]
-      def primitive?(value)
-        case value
-        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass, Hash, Array
-          true
-        else
-          false
-        end
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/validation.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "error_handling"
-require_relative "options"
-
-module Castkit
-  module AttributeExtensions
-    # Provides validation logic for attribute configuration.
-    #
-    # These checks are typically performed at attribute initialization to catch misconfigurations early.
-    module Validation
-      include Castkit::AttributeExtensions::ErrorHandling
-
-      private
-
-      # Runs all validation checks on the attribute definition.
-      #
-      # This includes:
-      # - Custom validator integrity
-      # - Access mode validity
-      # - Unwrapped prefix usage
-      # - Array `of:` type presence
-      #
-      # @return [void]
-      def validate!
-        validate_custom_validator!
-        validate_access!
-        validate_unwrapped_options!
-        validate_array_options!
-      end
-
-      # Validates the presence and interface of a custom validator.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if the validator is not callable
-      def validate_custom_validator!
-        return unless options[:validator]
-        return if options[:validator].respond_to?(:call)
-
-        raise_error!("Custom validator for `#{field}` must respond to `.call`")
-      end
-
-      # Validates that each declared access mode is valid.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if any access mode is invalid and enforcement is enabled
-      def validate_access!
-        access.each do |mode|
-          next if Castkit::AttributeExtensions::Options::DEFAULT_OPTIONS[:access].include?(mode)
-
-          handle_error(:access, mode: mode, context: to_h)
-        end
-      end
-
-      # Ensures prefix is only used with unwrapped attributes.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if prefix is used without `unwrapped: true`
-      def validate_unwrapped_options!
-        handle_error(:unwrapped, context: to_h) if prefix && !unwrapped?
-      end
-
-      # Ensures `of:` is provided for array-typed attributes.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if `of:` is missing for `type: :array`
-      def validate_array_options!
-        handle_error(:array_options, context: to_h) if type == :array && options[:of].nil?
-      end
-    end
-  end
-end

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/validators.rb

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