castkit 0.1.2 → 0.3.0

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::Base>] 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

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    module DataObject
+      # Adds deserialization support for Castkit::DataObject instances.
+      #
+      # Handles attribute loading, alias resolution, default fallback, nested DataObject casting,
+      # unwrapped field extraction, and optional attribute enforcement.
+      module Deserialization
+        # Hooks in class methods like `.from_hash` when included.
+        #
+        # @param base [Class] the class including this module
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level deserialization helpers for Castkit::DataObject.
+        module ClassMethods
+          # Builds a new instance from a hash, symbolizing keys as needed.
+          #
+          # @param hash [Hash] input data
+          # @return [Castkit::DataObject] deserialized instance
+          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}
+          alias from_h from_hash
+
+          # @!method deserialize(hash)
+          #   Alias for {.from_hash}
+          alias deserialize from_hash
+        end
+
+        private
+
+        # Loads and assigns all attributes from input hash.
+        #
+        # @param input [Hash] the input data
+        # @return [void]
+        def deserialize_attributes!(input)
+          self.class.attributes.each_value do |attribute|
+            next if attribute.skip_deserialization?
+
+            value = resolve_input_value(input, attribute)
+            next if value.nil? && attribute.optional?
+
+            value = deserialize_attribute_value!(attribute, value)
+            instance_variable_set("@#{attribute.field}", value)
+          end
+        end
+
+        # Deserializes an attribute's value according to its type.
+        #
+        # @param attribute [Castkit::Attribute]
+        # @param value [Object]
+        # @return [Object]
+        def deserialize_attribute_value!(attribute, value)
+          value = attribute.default if value.nil?
+          raise Castkit::AttributeError, "#{attribute.field} cannot be nil" if required?(attribute, value)
+
+          if attribute.dataobject?
+            attribute.type.cast(value)
+          elsif attribute.dataobject_collection?
+            Array(value).map { |v| attribute.options[:of].cast(v) }
+          else
+            deserialize_primitive_value!(attribute, value)
+          end
+        end
+
+        # Attempts to deserialize a primitive or union-typed value.
+        #
+        # @param attribute [Castkit::Attribute]
+        # @param value [Object]
+        # @return [Object]
+        # @raise [Castkit::AttributeError] if no type matches
+        def deserialize_primitive_value!(attribute, value)
+          Array(attribute.type).each do |type|
+            return Castkit.type_deserializer(type).call(value)
+          rescue Castkit::TypeError, Castkit::AttributeError
+            next
+          end
+
+          raise Castkit::AttributeError,
+                "#{attribute.field} could not be deserialized into any of #{attribute.type.inspect}"
+        end
+
+        # Checks whether an attribute is required and its value is nil.
+        #
+        # @param attribute [Castkit::Attribute]
+        # @param value [Object]
+        # @return [Boolean]
+        def required?(attribute, value)
+          value.nil? && attribute.required?
+        end
+
+        # Finds the first matching value for an attribute using key and alias paths.
+        #
+        # @param input [Hash]
+        # @param attribute [Castkit::Attribute]
+        # @return [Object, nil]
+        def resolve_input_value(input, attribute)
+          attribute.key_path(with_aliases: true).each do |path|
+            value = path.reduce(input) { |memo, key| memo.is_a?(Hash) ? memo[key] : nil }
+            return value unless value.nil?
+          end
+
+          nil
+        end
+
+        # Resolves root-wrapped and unwrapped data.
+        #
+        # @param data [Hash]
+        # @return [Hash] transformed input
+        def unwrap_root(data)
+          root = self.class.root
+          data = data[root] if root && data.key?(root)
+
+          unwrap_prefixed_fields!(data)
+        end
+
+        # Nests prefixed fields under their parent attribute for unwrapped dataobjects.
+        #
+        # @param data [Hash]
+        # @return [Hash] modified input
+        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
+
+        # Extracts and strips prefixed keys for unwrapped nested attributes.
+        #
+        # @param data [Hash]
+        # @param attribute [Castkit::Attribute]
+        # @return [Array<(Hash, Array<Symbol>)] extracted subhash and deleted keys
+        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
+end