castkit 0.1.0

data/lib/castkit/attribute.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "data_object"
+require_relative "attribute_extensions/options"
+require_relative "attribute_extensions/casting"
+require_relative "attribute_extensions/access"
+require_relative "attribute_extensions/validation"
+require_relative "attribute_extensions/serialization"
+
+module Castkit
+  # Represents a typed attribute on a Castkit::DataObject.
+  #
+  # Provides casting, validation, access control, and serialization behavior.
+  class Attribute
+    include Castkit::AttributeExtensions::Options
+    include Castkit::AttributeExtensions::Casting
+    include Castkit::AttributeExtensions::Access
+    include Castkit::AttributeExtensions::Validation
+    include Castkit::AttributeExtensions::Serialization
+
+    # @return [Symbol] the attribute name
+    attr_reader :field
+
+    # @return [Symbol, Class, Array] the declared type (normalized)
+    attr_reader :type
+
+    # @return [Hash] attribute options (including aliases, default, access, etc.)
+    attr_reader :options
+
+    # Initializes a new attribute definition.
+    #
+    # @param field [Symbol] the name of the attribute
+    # @param type [Symbol, Class, Array] the type or array of types
+    # @param default [Object, Proc] optional default value
+    # @param options [Hash] additional configuration options
+    def initialize(field, type, default: nil, **options)
+      @field = field
+      @type = normalize_type(type)
+      @default = default
+      @options = populate_options(options)
+
+      validate!
+    end
+
+    # Returns a hash representation of the attribute definition.
+    #
+    # @return [Hash]
+    def to_hash
+      {
+        field: field,
+        type: type,
+        options: options,
+        default: default
+      }
+    end
+
+    # @see #to_hash
+    alias to_h to_hash
+
+    private
+
+    # Populates default values and normalizes internal options.
+    #
+    # @param options [Hash]
+    # @return [Hash]
+    def populate_options(options)
+      options = DEFAULT_OPTIONS.merge(options)
+      options[:aliases] = Array(options[:aliases] || [])
+      options[:of] = normalize_type(options[:of]) if options[:of]
+
+      options
+    end
+
+    # Normalizes a declared type to a symbol or class reference.
+    #
+    # @param type [Symbol, Class, Array]
+    # @return [Symbol, Class, Array]
+    # @raise [Castkit::AttributeError] if the type is not valid
+    def normalize_type(type)
+      return type.map { |t| normalize_type(t) } if type.is_a?(Array)
+      return type if Castkit.dataobject?(type)
+
+      process_type(type)
+    end
+
+    # Converts a single type value into a normalized internal representation.
+    #
+    # - Maps `TrueClass`/`FalseClass` to `:boolean`
+    # - Converts class names (e.g., `String`, `Integer`) to lowercase symbols
+    # - Accepts already-symbolized types (e.g., `:string`)
+    #
+    # @param type [Class, Symbol] the declared type to process
+    # @return [Symbol] the normalized type
+    # @raise [Castkit::AttributeError] if the type is not a recognized form
+    def process_type(type)
+      case type
+      when Class
+        return :boolean if [TrueClass, FalseClass].include?(type)
+
+        type.name.downcase.to_sym
+      when Symbol
+        type
+      else
+        raise_error!("Unknown type: #{type.inspect}")
+      end
+    end
+
+    # Validates the final value against a validator if required.
+    #
+    # @param value [Object]
+    # @param context [Symbol, String]
+    # @return [void]
+    def validate_value!(value, context:)
+      return if value.nil? && optional?
+      return if type.is_a?(Array) || dataobject?
+
+      validator = options[:validator] || Castkit.configuration.validator_for(type)
+      validator&.call(value, options: options, context: context)
+    end
+
+    # Raises a Castkit::AttributeError with optional context.
+    #
+    # @param message [String]
+    # @param context [Hash, nil]
+    # @raise [Castkit::AttributeError]
+    def raise_error!(message, context: nil)
+      raise Castkit::AttributeError.new(message, context: context || to_h)
+    end
+  end
+end

data/lib/castkit/attribute_extensions/access.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Castkit
+  module AttributeExtensions
+    # 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

data/lib/castkit/attribute_extensions/casting.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../data_object"
+require_relative "error_handling"
+
+module Castkit
+  module AttributeExtensions
+    # Provides typecasting logic for attributes based on their declared type.
+    #
+    # Supports primitive types, arrays, nested Castkit::DataObject types, and union types.
+    module Casting
+      include Castkit::AttributeExtensions::ErrorHandling
+
+      PRIMITIVE_CASTERS = {
+        integer: lambda(&:to_i),
+        float: lambda(&:to_f),
+        string: lambda(&:to_s),
+        hash: ->(v) { v },
+        array: ->(v) { Array(v) }
+      }.freeze
+
+      private
+
+      # Casts a value based on the attribute's declared type.
+      #
+      # @param value [Object] the input value to cast
+      # @return [Object, nil] the cast value
+      # @raise [Castkit::AttributeError] if the value cannot be cast
+      def cast(value)
+        handle_error(:array_of_type) if type == :array && options[:of].nil?
+        value = default if value.nil?
+        return if value.nil? && optional?
+
+        cast_value(value)
+      end
+
+      # Delegates casting logic based on the attribute's type.
+      #
+      # This method is invoked internally by `#cast` after nil handling and default fallback.
+      #
+      # - For union types (`Array` of types), attempts each in order.
+      # - For array types, maps over elements with `#cast_element`.
+      # - For nested data objects, delegates to `.cast`.
+      # - For primitive types, uses `#cast_primitive`.
+      #
+      # @param value [Object] the raw input value to cast
+      # @return [Object, nil] the cast value
+      # @raise [Castkit::AttributeError] if casting fails for all union types or invalid primitives
+      def cast_value(value)
+        if type.is_a?(Array)
+          try_union_cast(value)
+        elsif type == :array
+          Array(value).map { |v| cast_element(v) }
+        elsif dataobject?
+          type.cast(value)
+        else
+          cast_primitive(value)
+        end
+      end
+
+      # Attempts to cast the value against a union of possible types.
+      #
+      # @param value [Object]
+      # @return [Object] the first successful cast result
+      # @raise [Castkit::AttributeError] if no types match
+      def try_union_cast(value)
+        last_error = nil
+
+        type.each do |t|
+          return try_cast_type(value, t)
+        rescue Castkit::AttributeError => e
+          last_error = e
+        end
+
+        raise last_error || handle_error(:union, types: type)
+      end
+
+      # Tries to cast a value to a specific type.
+      #
+      # @param value [Object]
+      # @param type [Symbol, Class] the type to try
+      # @return [Object, nil]
+      def try_cast_type(value, type)
+        return type.cast(value) if Castkit.dataobject?(type)
+
+        cast_primitive(value, type: type)
+      end
+
+      # Casts an element of an array attribute.
+      #
+      # @param value [Object]
+      # @return [Object, nil]
+      def cast_element(value)
+        if Castkit.dataobject?(options[:of])
+          options[:of].cast(value)
+        else
+          validate_element_type!(value)
+          cast_primitive(value, type: options[:of])
+        end
+      end
+
+      # Casts a primitive value based on its type.
+      #
+      # @param value [Object]
+      # @param type [Symbol]
+      # @return [Object, nil]
+      # @raise [Castkit::AttributeError]
+      def cast_primitive(value, type: self.type)
+        return cast_boolean(value) if type == :boolean
+        return Date.parse(value.to_s) if type == :date
+        return DateTime.parse(value.to_s) if type == :datetime
+
+        PRIMITIVE_CASTERS.fetch(type) do
+          handle_error(:primitive, type: type)
+        end.call(value)
+      end
+
+      # Casts a value to boolean.
+      #
+      # @param value [Object]
+      # @return [Boolean, nil]
+      # @raise [Castkit::AttributeError]
+      def cast_boolean(value)
+        case value.to_s.downcase
+        when "true", "1"
+          true
+        when "false", "0"
+          false
+        else
+          handle_error(:boolean, value: value)
+        end
+      end
+
+      # Validates element type for arrays, if `enforce_array_of_type` is enabled.
+      #
+      # @param value [Object]
+      # @return [void]
+      def validate_element_type!(value)
+        return unless Castkit.configuration.enforce_array_of_type
+
+        validator = Castkit.configuration.validator_for(options[:of])
+        validator.call(value, options: options, context: "#{field}[]")
+      end
+    end
+  end
+end

data/lib/castkit/attribute_extensions/error_handling.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../castkit"
+
+module Castkit
+  module AttributeExtensions
+    # 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 = {
+        array_of_type: {
+          config: :enforce_array_of_type,
+          message: ->(*_) { "`of:` must be provided for array type" },
+          error: Castkit::AttributeError
+        },
+        primitive: {
+          config: :enforce_known_primitive_type,
+          message: ->(_attr, type:) { "unknown primitive type: #{type.inspect}" },
+          error: Castkit::AttributeError
+        },
+        boolean: {
+          config: :enforce_boolean_casting,
+          message: ->(_attr, value:) { "must be a boolean, got: #{value.inspect}" },
+          error: Castkit::AttributeError
+        },
+        union: {
+          config: :enforce_union_match,
+          message: ->(_attr, types:) { "could not be cast to any of #{types.inspect}" },
+          error: Castkit::AttributeError
+        },
+        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)
+
+        warn "[Castkit] #{message}"
+        nil
+      end
+    end
+  end
+end

data/lib/castkit/attribute_extensions/options.rb

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

@@ -0,0 +1,89 @@
+# 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] the value to serialize
+      # @param visited [Set, nil] used for circular reference detection
+      # @return [Object] 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] the element to dump
+      # @param visited [Set, nil]
+      # @return [Object]
+      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]
+      # @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]
+      # @return [Boolean]
+      def primitive?(value)
+        case value
+        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass, Hash, Array
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end