castkit 0.1.1 → 0.2.0

data/lib/castkit/default_serializer.rb

@@ -5,77 +5,101 @@ require_relative "serializer"
 module Castkit
   # Default serializer for Castkit::DataObject instances.
   #
-  # Serializes attributes based on access rules, nil/blank filtering, and nested structure.
+  # 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::Serializer
-    SKIP_ATTRIBUTE = :__castkit_skip_attribute
-
-    # @return [Hash{Symbol => Castkit::Attribute}] attributes to serialize
+    # @return [Hash{Symbol => Castkit::Attribute}] the attributes to serialize
     attr_reader :attributes
 
-    # @return [Hash] serialization options (root key, ignore_nil, etc.)
+    # @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
 
-    # Returns the serialized object as a Hash.
+    # Serializes the object to a hash.
     #
-    # Includes root wrapping if configured.
+    # Includes unknown attributes if configured, and wraps in a root key if defined.
     #
-    # @return [Hash]
+    # @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 with the target object and context.
+    # Initializes the serializer.
     #
-    # @param raw [Castkit::DataObject] the object to serialize
-    # @param visited [Set, nil] used to detect circular references
-    def initialize(raw, visited: nil)
+    # @param obj [Castkit::DataObject] the object to serialize
+    # @param visited [Set, nil] tracks circular references
+    def initialize(obj, visited: nil)
       super
 
-      @attributes = raw.class.attributes
+      @skip_flag = "__castkit_#{obj.object_id}"
+      @attributes = obj.class.attributes.freeze
+      @unknown_attributes = obj.unknown_attributes.freeze
       @options = {
-        root: raw.class.root,
-        ignore_nil: raw.class.ignore_nil
+        root: obj.class.root,
+        ignore_nil: obj.class.ignore_nil || false,
+        allow_unknown: obj.class.allow_unknown || false
       }
     end
 
-    # Iterates over attributes and serializes each into a result hash.
+    # Serializes all defined attributes.
     #
-    # @return [Hash]
+    # @return [Hash] serialized attribute key-value pairs
     def serialize_attributes
-      attributes.each_with_object({}) do |(_, attribute), hash|
+      attributes.values.each_with_object({}) do |attribute, hash|
         next if attribute.skip_serialization?
 
         serialized_value = serialize_attribute(attribute)
-        next if serialized_value == SKIP_ATTRIBUTE
+        next if serialized_value == @skip_flag
 
-        assign_attribute_key!(hash, attribute, serialized_value)
+        assign_attribute_key!(attribute, serialized_value, hash)
       end
     end
 
-    # Process and serialize a given attribute.
+    # Serializes a single attribute.
     #
-    # @param attribute [Castkit::Attribute] The attribute instance.
-    # @param [Object]
+    # @param attribute [Castkit::Attribute]
+    # @return [Object] the serialized value or skip flag
     def serialize_attribute(attribute)
       value = obj.public_send(attribute.field)
-      return SKIP_ATTRIBUTE if value.nil? && (attribute.ignore_nil? || options[:ignore_nil])
+      return @skip_flag if skip_nil?(attribute, value)
 
-      serialized_value = attribute.dump(value, visited: visited)
-      return SKIP_ATTRIBUTE if blank?(serialized_value) && (attribute.ignore_blank? || options[:ignore_blank])
+      serialized_value = process_attribute(attribute, value)
+      return @skip_flag if skip_blank?(attribute, serialized_value)
 
       serialized_value
     end
 
-    # Assigns a serialized value into the hash using nested key paths.
+    # Delegates serialization based on type.
     #
-    # @param hash [Hash]
     # @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!(hash, attribute, value)
+    def assign_attribute_key!(attribute, value, hash)
       key_path = attribute.key_path
       last = key_path.pop
       current = hash
@@ -88,12 +112,43 @@ module Castkit
       current[last] = value
     end
 
-    # Determines if a value is blank (nil or empty).
+    # Whether to skip serialization for nil values.
     #
-    # @param value [Object, nil]
+    # @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?)
+      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::DefaultSerializer
+
+      serializer.call(value, visited: visited)
     end
   end
 end

data/lib/castkit/error.rb

@@ -9,13 +9,15 @@ module Castkit
     # Initializes a Castkit error.
     #
     # @param msg [String] the error message
-    # @param context [Object, nil] optional data object or hash for context
+    # @param context [Object, String, nil] optional data object or hash for context
     def initialize(msg, context: nil)
       super(msg)
       @context = context
     end
   end
 
+  class TypeError < Error; end
+
   # Raised for issues related to Castkit::DataObject initialization or usage.
   class DataObjectError < Error; end
 
@@ -23,9 +25,9 @@ module Castkit
   class AttributeError < Error
     # Returns the field name related to the error, if available.
     #
-    # @return [Symbol]
+    # @return [Symbol, nil]
     def field
-      context.is_a?(Hash) ? context[:field] : context || :unknown
+      context.is_a?(Hash) ? context[:field] : context || nil
     end
 
     # Formats the error message with field info if available.
@@ -39,4 +41,14 @@ module Castkit
 
   # Raised during serialization if an object fails to serialize properly.
   class SerializationError < Error; end
+
+  # Raised during contract validation.
+  class ContractError < Error
+    attr_reader :errors
+
+    def initialize(msg, context: nil, errors: nil)
+      super(msg, context: context)
+      @errors = errors || {}
+    end
+  end
 end

data/lib/castkit/ext/attribute/access.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    module Attribute
+      # Provides access control helpers for attributes.
+      #
+      # These helpers determine whether an attribute is readable, writeable,
+      # or should be included during serialization/deserialization based on the
+      # configured `:access` and `:ignore` options.
+      module Access
+        # Returns the normalized access modes for the attribute (e.g., [:read, :write]).
+        #
+        # @return [Array<Symbol>] list of access symbols
+        def access
+          Array(options[:access]).map(&:to_sym)
+        end
+
+        # Whether the attribute should be included during serialization.
+        #
+        # @return [Boolean]
+        def readable?
+          access.include?(:read)
+        end
+
+        # Whether the attribute should be accepted during deserialization.
+        #
+        # Composite attributes are excluded from writeability.
+        #
+        # @return [Boolean]
+        def writeable?
+          access.include?(:write) && !composite?
+        end
+
+        # Whether the attribute is both readable and writeable.
+        #
+        # @return [Boolean]
+        def full_access?
+          readable? && writeable?
+        end
+
+        # Whether the attribute should be skipped during serialization.
+        #
+        # This is true if it's not readable or is marked as ignored.
+        #
+        # @return [Boolean]
+        def skip_serialization?
+          !readable? || ignore?
+        end
+
+        # Whether the attribute should be skipped during deserialization.
+        #
+        # @return [Boolean]
+        def skip_deserialization?
+          !writeable?
+        end
+
+        # Whether the attribute is ignored completely.
+        #
+        # @return [Boolean]
+        def ignore?
+          options[:ignore]
+        end
+      end
+    end
+  end
+end

data/lib/castkit/ext/attribute/error_handling.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    module Attribute
+      # Provides centralized handling of attribute casting and validation errors.
+      #
+      # The behavior of each error is controlled by configuration flags in `Castkit.configuration`.
+      module ErrorHandling
+        # Maps known error types to their handling behavior.
+        #
+        # Each entry includes:
+        # - `:config` – the config flag that determines enforcement
+        # - `:message` – a lambda that generates an error message
+        # - `:error` – the error class to raise
+        #
+        # @return [Hash{Symbol => Hash}]
+        ERROR_OPTIONS = {
+          access: {
+            config: :enforce_attribute_access,
+            message: ->(_attr, mode:) { "invalid access mode `#{mode}`" },
+            error: Castkit::AttributeError
+          },
+          unwrapped: {
+            config: :enforce_unwrapped_prefix,
+            message: ->(*_) { "prefix can only be used with unwrapped attribute" },
+            error: Castkit::AttributeError
+          },
+          array_options: {
+            config: :enforce_array_options,
+            message: ->(*_) { "array attribute must specify `of:` type" },
+            error: Castkit::AttributeError
+          }
+        }.freeze
+
+        private
+
+        # Handles a validation or casting error based on the provided error key and context.
+        #
+        # If the corresponding configuration flag is enabled, an exception is raised.
+        # Otherwise, a warning is logged and the method returns `nil`.
+        #
+        # @param key [Symbol] the type of error (must match a key in ERROR_OPTIONS)
+        # @param kwargs [Hash] additional values passed to the message lambda
+        # @option kwargs [Symbol] :context (optional) the attribute context (e.g., field name)
+        # @return [nil]
+        # @raise [Castkit::AttributeError] if enforcement is enabled for the given error type
+        def handle_error(key, **kwargs)
+          config_key = ERROR_OPTIONS.dig(key, :config)
+          message_fn = ERROR_OPTIONS.dig(key, :message)
+          error_class = ERROR_OPTIONS.dig(key, :error) || Castkit::Error
+
+          context = kwargs.delete(:context)
+          message = message_fn.call(self, **kwargs)
+          raise error_class.new(message, context: context) if Castkit.configuration.public_send(config_key)
+
+          Castkit.warning "[Castkit] #{message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/castkit/ext/attribute/options.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "../../data_object"
+
+module Castkit
+  module Ext
+    module Attribute
+      # 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,
+          transient: false,
+          unwrapped: false,
+          prefix: nil,
+          access: %i[read write],
+          force_type: !Castkit.configuration.enforce_typing
+        }.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.
+        #
+        # @return [Boolean]
+        def composite?
+          options[:composite]
+        end
+
+        # Whether the attribute is considered transient (not exposed in serialized output).
+        #
+        # @return [Boolean]
+        def transient?
+          options[:transient]
+        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
+end

data/lib/castkit/ext/attribute/validation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "error_handling"
+require_relative "options"
+
+module Castkit
+  module Ext
+    module Attribute
+      # Provides validation logic for attribute configuration.
+      #
+      # These checks are typically performed at attribute initialization to catch misconfigurations early.
+      module Validation
+        include Castkit::Ext::Attribute::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_type!
+          validate_custom_validator!
+          validate_access!
+          validate_unwrapped_options!
+          validate_array_options!
+        end
+
+        def validate_type!
+          types ||= Array(type) # used to test single type and type unions.
+
+          types.each do |t|
+            next if Castkit.dataobject?(t) || Castkit.configuration.type_registered?(t)
+
+            raise_error!("Type is not registered, register with Castkit.configuration.register_type(:#{t})")
+          end
+        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::Ext::Attribute::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
+end

data/lib/castkit/ext/data_object/contract.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../../contract"
+
+module Castkit
+  module Ext
+    module DataObject
+      # Extension module that adds contract support to Castkit::DataObject classes.
+      #
+      # This allows any DataObject to be:
+      # - Converted into a contract definition (via `.to_contract`)
+      # - Validated against its contract (via `.validate` and `.validate!`)
+      # - Reconstructed from a contract class (via `.from_contract`)
+      #
+      # Example:
+      #
+      #   class UserDto < Castkit::DataObject
+      #     string :id
+      #     string :email
+      #   end
+      #
+      #   contract = UserDto.to_contract
+      #   result = UserDto.validate(id: "abc")
+      #
+      #   UserDto.from_contract(contract) # => builds an equivalent DataObject class
+      #
+      # This module is automatically extended by Castkit::DataObject and is not intended
+      # to be included manually.
+      module Contract
+        # Returns the associated Castkit::Contract for this DataObject.
+        #
+        # Memoizes the contract once it's built. Uses `to_contract` internally.
+        #
+        # @return [Class<Castkit::Contract::Definition>]
+        def contract
+          @contract ||= to_contract
+        end
+
+        # Converts the current DataObject into a Castkit::Contract subclass.
+        #
+        # If the contract has already been defined, returns the existing definition.
+        # Otherwise, generates and registers a new contract class under Castkit::Contracts.
+        #
+        # @param as [String, Symbol, nil] Optional name for the contract.
+        #   If omitted, inferred from the DataObject name.
+        #
+        # @return [Class<Castkit::Contract::Definition>] the generated or existing contract
+        def to_contract(as: nil)
+          Castkit::Contract.from_dataobject(self, as: as)
+        end
+
+        # Constructs a new Castkit::DataObject class from a given contract.
+        #
+        # This method is the inverse of `.to_contract` and provides a way to
+        # generate a DataObject from an existing contract definition.
+        #
+        # @example
+        #   UserContract = Castkit::Contract.build(:user) do
+        #     string :id
+        #     string :email
+        #   end
+        #
+        #   UserDto = Castkit::DataObject.from_contract(UserContract)
+        #   dto = UserDto.new(id: "abc", email: "a@example.com")
+        #
+        # @param contract [Class<Castkit::Contract::Generic>] the contract to convert
+        # @return [Class<Castkit::DataObject>] a new anonymous DataObject class
+
+        def from_contract(contract)
+          Class.new(Castkit::DataObject).tap do |klass|
+            contract.attributes.each_value do |attr|
+              klass.attribute(attr.field, attr.type, **attr.options)
+            end
+          end
+        end
+
+        # Validates input data using the contract associated with this DataObject.
+        #
+        # @param data [Hash] The input to validate
+        # @return [Castkit::Contract::Result] the result of validation
+        def validate(data)
+          contract.validate(data)
+        end
+
+        # Validates input data and raises if validation fails.
+        #
+        # @param data [Hash] The input to validate
+        # @raise [Castkit::ContractError] if validation fails
+        # @return [void]
+        def validate!(data)
+          contract.validate!(data)
+        end
+      end
+    end
+  end
+end