castkit 0.1.0

data/lib/castkit/attribute_extensions/validation.rb

@@ -0,0 +1,72 @@
+# 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/castkit.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+# Castkit is a lightweight, type-safe data object system for Ruby.
+#
+# It provides a declarative DSL for defining DTOs with typecasting, validation,
+# access control, serialization, deserialization, and OpenAPI-friendly schema generation.
+#
+# @example Defining a simple data object
+#   class UserDto < Castkit::DataObject
+#     string :name
+#     integer :age, required: false
+#   end
+#
+#   user = UserDto.new(name: "Alice", age: 30)
+#   user.to_h #=> { name: "Alice", age: 30 }
+module Castkit
+  class << self
+    # Yields the global configuration object for customization.
+    #
+    # @example
+    #   Castkit.configure do |config|
+    #     config.enforce_boolean_casting = false
+    #   end
+    #
+    # @yieldparam config [Castkit::Configuration]
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+
+    # Retrieves the global Castkit configuration.
+    #
+    # @return [Castkit::Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def dataobject?(obj)
+      obj.is_a?(Class) && obj.ancestors.include?(Castkit::DataObject)
+    end
+  end
+end

data/lib/castkit/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "validators"
+
+module Castkit
+  # Configuration container for global Castkit settings.
+  #
+  # This includes validator registration and enforcement flags for various runtime checks.
+  class Configuration
+    # Default mapping of primitive types to validators.
+    #
+    # @return [Hash<Symbol, Class>]
+    DEFAULT_VALIDATORS = {
+      string: Castkit::Validators::StringValidator,
+      integer: Castkit::Validators::NumericValidator,
+      float: Castkit::Validators::NumericValidator
+    }.freeze
+
+    # @return [Hash<Symbol, #call>] registered validators by type
+    attr_reader :validators
+
+    # Whether to raise an error if `of:` is missing for array types.
+    # @return [Boolean]
+    attr_accessor :enforce_array_of_type
+
+    # Whether to raise an error for unrecognized primitive types.
+    # @return [Boolean]
+    attr_accessor :enforce_known_primitive_type
+
+    # Whether to raise an error on invalid boolean coercion.
+    # @return [Boolean]
+    attr_accessor :enforce_boolean_casting
+
+    # Whether to raise an error if a union type has no matching candidate.
+    # @return [Boolean]
+    attr_accessor :enforce_union_match
+
+    # Whether to raise an error if access mode is not recognized.
+    # @return [Boolean]
+    attr_accessor :enforce_attribute_access
+
+    # Whether to raise an error if a prefix is defined without `unwrapped: true`.
+    # @return [Boolean]
+    attr_accessor :enforce_unwrapped_prefix
+
+    # Whether to raise an error if an array attribute is missing the `of:` type.
+    # @return [Boolean]
+    attr_accessor :enforce_array_options
+
+    # Initializes the configuration with default validators and enforcement settings.
+    #
+    # @return [void]
+    def initialize
+      @validators = DEFAULT_VALIDATORS.dup
+      @enforce_array_of_type = true
+      @enforce_known_primitive_type = true
+      @enforce_boolean_casting = true
+      @enforce_union_match = true
+      @enforce_attribute_access = true
+      @enforce_unwrapped_prefix = true
+      @enforce_array_options = true
+    end
+
+    # Registers a custom validator for a given type.
+    #
+    # @param type [Symbol] the type symbol (e.g., :string, :integer)
+    # @param validator [#call] a callable object that implements `call(value, options:, context:)`
+    # @param override [Boolean] whether to override an existing validator
+    # @raise [Castkit::Error] if validator does not respond to `.call`
+    # @return [void]
+    def register_validator(type, validator, override: false)
+      return if @validators.key?(type.to_sym) && !override
+
+      unless validator.respond_to?(:call)
+        raise Castkit::Error, "Validator for `#{type}` must respond to `.call(value, options:, context:)`"
+      end
+
+      @validators[type.to_sym] = validator
+    end
+
+    # Returns the registered validator for the given type.
+    #
+    # @param type [Symbol]
+    # @return [#call, nil]
+    def validator_for(type)
+      validators[type.to_sym]
+    end
+
+    # Resets all validators to their default mappings.
+    #
+    # @return [void]
+    def reset_validators!
+      @validators = DEFAULT_VALIDATORS.dup
+    end
+  end
+end

data/lib/castkit/data_object.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "error"
+require_relative "attribute"
+require_relative "default_serializer"
+require_relative "data_object_extensions/config"
+require_relative "data_object_extensions/attributes"
+require_relative "data_object_extensions/attribute_types"
+require_relative "data_object_extensions/deserialization"
+
+module Castkit
+  # Base class for defining declarative, typed data transfer objects (DTOs).
+  #
+  # Includes typecasting, validation, access control, serialization, deserialization,
+  # and support for custom serializers.
+  #
+  # @example Defining a DTO
+  #   class UserDto < Castkit::DataObject
+  #     string :name
+  #     integer :age, required: false
+  #   end
+  #
+  # @example Instantiating and serializing
+  #   user = UserDto.new(name: "Alice", age: 30)
+  #   user.to_json #=> '{"name":"Alice","age":30}'
+  class DataObject
+    extend Castkit::DataObjectExtensions::Attributes
+    extend Castkit::DataObjectExtensions::AttributeTypes
+
+    include Castkit::DataObjectExtensions::Config
+    include Castkit::DataObjectExtensions::Deserialization
+
+    class << self
+      # Gets or sets the serializer class to use for instances of this object.
+      #
+      # @param value [Class<Castkit::Serializer>, nil]
+      # @return [Class<Castkit::Serializer>, nil]
+      # @raise [ArgumentError] if value does not inherit from Castkit::Serializer
+      def serializer(value = nil)
+        if value
+          raise ArgumentError, "Serializer must inherit from Castkit::Serializer" unless value < Castkit::Serializer
+
+          @serializer = value
+        else
+          @serializer
+        end
+      end
+
+      # Casts a value into an instance of this class.
+      #
+      # @param obj [self, Hash]
+      # @return [self]
+      # @raise [Castkit::DataObjectError] if obj is not castable
+      def cast(obj)
+        case obj
+        when self
+          obj
+        when Hash
+          from_h(obj)
+        else
+          raise Castkit::DataObjectError, "Can't cast #{obj.class} to #{name}"
+        end
+      end
+
+      # Converts an object to its JSON representation.
+      #
+      # @param obj [Castkit::DataObject]
+      # @return [String]
+      def dump(obj)
+        obj.to_json
+      end
+    end
+
+    # Initializes the DTO from a hash of attributes.
+    #
+    # @param fields [Hash] raw input hash
+    # @raise [Castkit::DataObjectError] if strict mode is enabled and unknown keys are present
+    def initialize(fields = {})
+      root = self.class.root
+      fields = fields[root] if root && fields.key?(root)
+      fields = unwrap_prefixed_fields!(fields)
+
+      validate_keys!(fields)
+      deserialize_attributes!(fields)
+    end
+
+    # Serializes the DTO to a Ruby hash.
+    #
+    # @param visited [Set, nil] used to track circular references
+    # @return [Hash]
+    def to_hash(visited: nil)
+      serializer = self.class.serializer || Castkit::DefaultSerializer
+      serializer.call(self, visited: visited)
+    end
+
+    # Serializes the DTO to a JSON string.
+    #
+    # @param options [Hash, nil] options passed to `JSON.generate`
+    # @return [String]
+    def to_json(options = nil)
+      JSON.generate(serializer.call(self), options)
+    end
+
+    # @!method to_h
+    #   Alias for {#to_hash}
+    #
+    # @!method serialize
+    #   Alias for {#to_hash}
+    alias to_h to_hash
+    alias serialize to_hash
+
+    private
+
+    # Validates that the input only contains known keys unless configured otherwise.
+    #
+    # @param data [Hash]
+    # @raise [Castkit::DataObjectError] in strict mode if unknown keys are present
+    # @return [void]
+    def validate_keys!(data)
+      valid_keys = self.class.attributes.flat_map do |_, attr|
+        [attr.key] + attr.options[:aliases]
+      end.map(&:to_sym).uniq
+
+      unknown_keys = data.keys.map(&:to_sym) - valid_keys
+      return if unknown_keys.empty?
+
+      handle_unknown_keys!(unknown_keys)
+    end
+
+    # Handles unknown keys found during initialization.
+    #
+    # Behavior depends on the class-level configuration:
+    # - Raises a `Castkit::DataObjectError` if strict mode is enabled.
+    # - Logs a warning if `warn_on_unknown` is enabled.
+    #
+    # @param unknown_keys [Array<Symbol>] list of unknown keys not declared as attributes or aliases
+    # @raise [Castkit::DataObjectError] if strict mode is active
+    # @return [void]
+    def handle_unknown_keys!(unknown_keys)
+      raise Castkit::DataObjectError, "Unknown attribute(s): #{unknown_keys.join(", ")}" if self.class.strict
+
+      warn "⚠️  [Castkit] Unknown attribute(s) ignored: #{unknown_keys.join(", ")}" if self.class.warn_on_unknown
+    end
+
+    # Returns the serializer instance or default for this object.
+    #
+    # @return [Class<Castkit::Serializer>]
+    def serializer
+      @serializer ||= self.class.serializer || Castkit::DefaultSerializer
+    end
+  end
+end

data/lib/castkit/data_object_extensions/attribute_types.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DataObjectExtensions
+    # Provides DSL methods to define typed attributes in a Castkit::DataObject.
+    #
+    # These helpers are shortcuts for calling `attribute` with a specific type.
+    module AttributeTypes
+      # Defines a string attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def string(field, **options)
+        attribute(field, :string, **options)
+      end
+
+      # Defines an integer attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def integer(field, **options)
+        attribute(field, :integer, **options)
+      end
+
+      # Defines a boolean attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def boolean(field, **options)
+        attribute(field, :boolean, **options)
+      end
+
+      # Defines a float attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def float(field, **options)
+        attribute(field, :float, **options)
+      end
+
+      # Defines a date attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def date(field, **options)
+        attribute(field, :date, **options)
+      end
+
+      # Defines a datetime attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def datetime(field, **options)
+        attribute(field, :datetime, **options)
+      end
+
+      # Defines an array attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def array(field, **options)
+        attribute(field, :array, **options)
+      end
+
+      # Defines a hash attribute.
+      #
+      # @param field [Symbol]
+      # @param options [Hash]
+      def hash(field, **options)
+        attribute(field, :hash, **options)
+      end
+
+      # Defines a nested Castkit::DataObject attribute.
+      #
+      # @param field [Symbol]
+      # @param type [Class<Castkit::DataObject>]
+      # @param options [Hash]
+      # @raise [Castkit::AttributeError] if type is not a subclass of Castkit::DataObject
+      def dataobject(field, type, **options)
+        unless type < Castkit::DataObject
+          raise Castkit::AttributeError, "Data objects must extend from Castkit::DataObject"
+        end
+
+        attribute(field, type, **options)
+      end
+
+      # Defines an unwrapped nested Castkit::DataObject attribute.
+      #
+      # All keys from this object will be flattened with an optional prefix.
+      #
+      # @param field [Symbol]
+      # @param type [Class<Castkit::DataObject>]
+      # @param options [Hash]
+      def unwrapped(field, type, **options)
+        attribute(field, type, **options, unwrapped: true)
+      end
+
+      # Alias for `array`
+      alias collection array
+
+      # Alias for `dataobject`
+      alias object dataobject
+
+      # Alias for `dataobject`
+      alias dto dataobject
+    end
+  end
+end

data/lib/castkit/data_object_extensions/attributes.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DataObjectExtensions
+    # Provides DSL and implementation for declaring attributes within a Castkit::DataObject.
+    #
+    # Includes support for regular, composite, transient, readonly/writeonly, and grouped attribute definitions.
+    module Attributes
+      # Declares an attribute with the given type and options.
+      #
+      # If `:transient` is true, defines only standard accessors and skips serialization logic.
+      #
+      # @param field [Symbol]
+      # @param type [Symbol, Class]
+      # @param options [Hash]
+      # @return [void]
+      # @raise [Castkit::DataObjectError] if the attribute is already defined
+      def attribute(field, type, **options)
+        field = field.to_sym
+        raise Castkit::DataObjectError, "Attribute '#{field}' already defined" if attributes.key?(field)
+
+        options = build_options(options)
+        return define_attribute(field, type, **options) unless options[:transient]
+
+        attr_accessor field
+      end
+
+      # Declares a computed (composite) attribute.
+      #
+      # The provided block defines the read behavior.
+      #
+      # @param field [Symbol]
+      # @param type [Symbol, Class]
+      # @param options [Hash]
+      # @yieldreturn [Object] evaluated composite value
+      def composite(field, type, **options, &block)
+        attribute(field, type, **options, composite: true)
+        define_method(field, &block)
+      end
+
+      # Declares a group of transient attributes within the given block.
+      #
+      # These attributes are not serialized or included in `to_h`.
+      #
+      # @yield defines one or more transient attributes via `attribute`
+      # @return [void]
+      def transient(&block)
+        @__transient_context = true
+        instance_eval(&block)
+      ensure
+        @__transient_context = nil
+      end
+
+      # Declares a group of readonly attributes within the given block.
+      #
+      # @param options [Hash] shared options for attributes inside the block
+      # @yield defines attributes with `access: [:read]`
+      # @return [void]
+      def readonly(**options, &block)
+        with_access([:read], options, &block)
+      end
+
+      # Declares a group of writeonly attributes within the given block.
+      #
+      # @param options [Hash] shared options for attributes inside the block
+      # @yield defines attributes with `access: [:write]`
+      # @return [void]
+      def writeonly(**options, &block)
+        with_access([:write], options, &block)
+      end
+
+      # Declares a group of required attributes within the given block.
+      #
+      # @param options [Hash] shared options for attributes inside the block
+      # @yield defines attributes with `required: true`
+      # @return [void]
+      def required(**options, &block)
+        with_required(true, options, &block)
+      end
+
+      # Declares a group of optional attributes within the given block.
+      #
+      # @param options [Hash] shared options for attributes inside the block
+      # @yield defines attributes with `required: false`
+      # @return [void]
+      def optional(**options, &block)
+        with_required(false, options, &block)
+      end
+
+      # Returns all declared non-transient attributes.
+      #
+      # @return [Hash{Symbol => Castkit::Attribute}]
+      def attributes
+        @attributes ||= {}
+      end
+
+      # Alias for `composite`
+      #
+      # @see #composite
+      alias property composite
+
+      private
+
+      # Defines a full attribute, including accessor methods and type logic.
+      #
+      # @param field [Symbol]
+      # @param type [Symbol, Class]
+      # @param options [Hash]
+      def define_attribute(field, type, **options)
+        attribute = Castkit::Attribute.new(field, type, **options)
+        attributes[field] = attribute
+
+        if attribute.full_access?
+          attr_reader field
+
+          define_typed_writer(field, attribute)
+        elsif attribute.writeable?
+          define_typed_writer(field, attribute)
+        elsif attribute.readable?
+          attr_reader field
+        end
+      end
+
+      # Defines a type-aware writer method for the attribute.
+      #
+      # @param field [Symbol]
+      # @param attribute [Castkit::Attribute]
+      def define_typed_writer(field, attribute)
+        define_method("#{field}=") do |value|
+          casted = attribute.load(value, context: field)
+          instance_variable_set("@#{field}", casted)
+        end
+      end
+
+      # Applies scoped access control to all attributes declared in the given block.
+      #
+      # @param access [Array<Symbol>] e.g., [:read] or [:write]
+      # @param options [Hash]
+      # @yield the block containing one or more `attribute` calls
+      def with_access(access, options = {}, &block)
+        @__access_context = access
+        @__block_options = options
+        instance_eval(&block)
+      ensure
+        @__access_context = nil
+        @__block_options = nil
+      end
+
+      # Applies scoped required/optional flag to all attributes declared in the given block.
+      #
+      # @param flag [Boolean]
+      # @param options [Hash]
+      # @yield the block containing one or more `attribute` calls
+      def with_required(flag, options = {}, &block)
+        @__required_context = flag
+        @__block_options = options
+        instance_eval(&block)
+      ensure
+        @__required_context = nil
+        @__block_options = nil
+      end
+
+      # Builds effective options for the current attribute definition.
+      #
+      # Merges scoped flags like `required`, `access`, and `transient` if present.
+      #
+      # @param options [Hash]
+      # @return [Hash]
+      def build_options(options)
+        base = @__block_options || {}
+        base = base.merge(required: @__required_context) unless @__required_context.nil?
+        base = base.merge(access: @__access_context) unless @__access_context.nil?
+        base = base.merge(transient: true) if @__transient_context
+
+        base.merge(options)
+      end
+    end
+  end
+end