castkit 0.1.2 → 0.2.0

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

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

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    module DataObject
+      # Provides per-class serialization configuration for Castkit::Dataobject, including
+      # root key handling and ignore rules.
+      module Serialization
+        # 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)
+            value.nil? ? @root : (@root = value.to_s.strip.to_sym)
+          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
+        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
+end

data/lib/castkit/inflector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Castkit
+  # Provides string transformation utilities used internally by Castkit
+  module Inflector
+    class << self
+      # Returns the unqualified class name from a namespaced class.
+      #
+      # @example
+      #   Castkit::Inflector.class_name(Foo::Bar) # => "Bar"
+      #
+      # @param klass [Class]
+      # @return [String]
+      def unqualified_name(klass)
+        klass.name.to_s.split("::").last
+      end
+
+      # Converts a snake_case or underscored string into PascalCase.
+      #
+      # @example
+      #   Castkit::Inflector.pascalize("user_contract") # => "UserContract"
+      #   Castkit::Inflector.pascalize(:admin_dto)      # => "AdminDto"
+      #
+      # @param string [String, Symbol] the input to convert
+      # @return [String] the PascalCase representation
+      def pascalize(string)
+        string.to_s.split("_").map(&:capitalize).join
+      end
+
+      # Converts a PascalCase or camelCase string to snake_case.
+      #
+      # @example
+      #   Castkit::Inflector.underscore("UserContract") # => "user_contract"
+      #   Castkit::Inflector.underscore("XMLParser")    # => "xml_parser"
+      #
+      # @param string [String, Symbol]
+      # @return [String]
+      def underscore(string)
+        string
+          .to_s
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+    end
+  end
+end

data/lib/castkit/types/boolean.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "generic"
+
+module Castkit
+  module Types
+    # Type definition for `:boolean` attributes.
+    #
+    # Converts strings or numbers into boolean values based on common truthy/falsy indicators.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `boolean :is_active`
+    class Boolean < Generic
+      # Deserializes the input into a boolean value.
+      #
+      # Accepts:
+      # - `"true"`, `"1"` (case-insensitive) → `true`
+      # - `"false"`, `"0"` (case-insensitive) → `false`
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      # @raise [Castkit::TypeError] if the value cannot be coerced to a boolean
+      def deserialize(value)
+        case value.to_s.downcase
+        when "true", "1"
+          true
+        when "false", "0"
+          false
+        else
+          type_error!(:boolean, value)
+        end
+      end
+
+      # Serializes the boolean value (pass-through).
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def serialize(value)
+        value
+      end
+    end
+  end
+end

data/lib/castkit/types/collection.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "generic"
+
+module Castkit
+  module Types
+    # Type definition for `:array` attributes.
+    #
+    # Wraps any value in an array using `Array(value)` coercion. This ensures consistent array representation
+    # even if the input is a single value or nil.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `array :tags, of: :string`
+    class Collection < Generic
+      # Deserializes the value into an array using `Array(value)`.
+      #
+      # @param value [Object]
+      # @return [::Array]
+      def deserialize(value)
+        Array(value)
+      end
+    end
+  end
+end

data/lib/castkit/types/date.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "generic"
+
+module Castkit
+  module Types
+    # Type definition for `:date` attributes.
+    #
+    # Handles deserialization from strings and other input into `Date` objects,
+    # and serializes `Date` values into ISO8601 strings.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `date :published_on`
+    class Date < Generic
+      # Deserializes the input value to a `Date` instance.
+      #
+      # @param value [Object]
+      # @return [::Date]
+      # @raise [ArgumentError] if parsing fails
+      def deserialize(value)
+        ::Date.parse(value.to_s)
+      end
+
+      # Serializes a `Date` object to ISO8601 string format.
+      #
+      # @param value [::Date]
+      # @return [String]
+      def serialize(value)
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/castkit/types/date_time.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "generic"
+
+module Castkit
+  module Types
+    # Type definition for `:datetime` attributes.
+    #
+    # Handles deserialization from strings and other input into `DateTime` objects,
+    # and serializes `DateTime` values into ISO8601 strings.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `datetime :published_ad`
+    class DateTime < Generic
+      # Deserializes the input value to a `DateTime` instance.
+      #
+      # @param value [Object]
+      # @return [::DateTime]
+      # @raise [ArgumentError] if parsing fails
+      def deserialize(value)
+        ::DateTime.parse(value.to_s)
+      end
+
+      # Serializes a `DateTime` object to ISO8601 string format.
+      #
+      # @param value [::DateTime]
+      # @return [String]
+      def serialize(value)
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/castkit/types/float.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "generic"
+require_relative "../validators/numeric_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:integer` attributes.
+    #
+    # Handles deserialization from raw input (e.g., strings, floats) to Float,
+    # applies optional numeric validation rules (e.g., `min`, `max`), and returns
+    # the value unchanged during serialization.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `integer :count`
+    class Float < Generic
+      # Deserializes the input value to an Float.
+      #
+      # @param value [Object]
+      # @return [Float]
+      def deserialize(value)
+        value.to_f
+      end
+
+      # Serializes the Float value.
+      #
+      # @param value [Float]
+      # @return [Float]
+      def serialize(value)
+        value
+      end
+
+      # Validates the Float value using Castkit's NumericValidator.
+      #
+      # Supports options like `min:` and `max:`.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::NumericValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types/generic.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Types
+    # Generic base class for type definitions in Castkit.
+    #
+    # Provides default behavior for (de)serialization, validation, and coercion.
+    # All primitive types should subclass this and override methods as needed.
+    #
+    # The `cast!` method is the primary entry point used by attribute processing
+    # to validate and coerce values in a predictable order.
+    class Generic
+      class << self
+        # Coerces and validates a value for use in a Castkit DataObject.
+        #
+        # When `force_type` is true, the value is deserialized (coerced) first,
+        # then validated. This is useful when a value may need to be converted
+        # before it can pass validation (e.g. `"123"` → `123`).
+        #
+        # Otherwise, the raw value is validated before coercion.
+        #
+        # @param value [Object] the input value
+        # @param validator [#call, nil] optional custom validator (default uses `validate!`)
+        # @param options [Hash] options passed to `validate!`, e.g., `min`, `max`, `force_type`
+        # @param context [Symbol, String, nil] context label for error messages
+        # @return [Object] the deserialized and validated value
+        def cast!(value, validator: nil, options: {}, context: {})
+          instance = new
+          validator ||= options.delete(:validator)
+          validator ||= default_validator(instance)
+
+          if options[:force_type]
+            deserialized_value = instance.deserialize(value)
+            validator.call(deserialized_value, options: options, context: context)
+            return deserialized_value
+          end
+
+          validator.call(value, options: options, context: context)
+          instance.deserialize(value)
+        end
+
+        # Deserializes the value using the default type behavior.
+        #
+        # @param value [Object]
+        # @return [Object] the coerced value
+        def deserialize(value)
+          new.deserialize(value)
+        end
+
+        # Serializes the value using the default type behavior.
+        #
+        # @param value [Object]
+        # @return [Object]
+        def serialize(value)
+          new.serialize(value)
+        end
+
+        # Validates the value using the default validator.
+        #
+        # @param value [Object] the value to check
+        # @param options [Hash] validation rules (e.g., min, max, format)
+        # @param context [Symbol, String] label for error reporting
+        # @return [void]
+        def validate!(value, options: {}, context: {})
+          new.validate!(value, options: options, context: context)
+        end
+
+        private
+
+        # Builds a default validator from the instance itself.
+        #
+        # @param instance [Castkit::Types::Generic]
+        # @return [Proc] a lambda wrapping `#validate!`
+        def default_validator(instance)
+          lambda do |value, options: {}, context: nil|
+            instance.validate!(value, options: options, context: context)
+          end
+        end
+      end
+
+      # Deserializes the value. Override in subclasses to coerce input (e.g., `"123"` → `123`).
+      #
+      # @param value [Object]
+      # @return [Object]
+      def deserialize(value)
+        value
+      end
+
+      # Serializes the value. Override in subclasses if the output should be transformed.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def serialize(value)
+        value
+      end
+
+      # Validates the value. No-op by default.
+      #
+      # @param value [Object]
+      # @param options [Hash]
+      # @param context [Symbol, String]
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        # override in subclasses
+      end
+
+      protected
+
+      # Emits or raises a type error depending on configuration.
+      #
+      # @param type [Symbol]
+      # @param value [Object, nil]
+      # @return [void]
+      def type_error!(type, value)
+        message = "value must be a #{type}, got #{value.inspect}"
+
+        raise Castkit::TypeError, message if Castkit.configuration.raise_type_errors
+
+        Castkit.warning "[Castkit] #{message}" if Castkit.configuration.enable_warnings
+      end
+    end
+  end
+end