castkit 0.1.2 → 0.2.0

data/lib/castkit/types/integer.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 Integer,
+    # 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 Integer < Generic
+      # Deserializes the input value to an Integer.
+      #
+      # @param value [Object]
+      # @return [Integer]
+      def deserialize(value)
+        value.to_i
+      end
+
+      # Serializes the Integer value.
+      #
+      # @param value [Integer]
+      # @return [Integer]
+      def serialize(value)
+        value
+      end
+
+      # Validates the Integer 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/string.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "generic"
+require_relative "../validators/string_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:string` attributes.
+    #
+    # Coerces any input to a string using `to_s`, and validates that the resulting value is a `String`.
+    # Supports optional format validation via a `:format` option (Regexp or Proc).
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `string :id`
+    class String < Generic
+      # Deserializes the value by coercing it to a string using `to_s`.
+      #
+      # @param value [Object]
+      # @return [String]
+      def deserialize(value)
+        value.to_s
+      end
+
+      # Serializes the value as-is.
+      #
+      # @param value [String]
+      # @return [String]
+      def serialize(value)
+        value
+      end
+
+      # Validates the value is a `String` and optionally matches a format.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options (e.g., `format: /regex/`)
+      # @param context [Symbol, String]
+      # @raise [Castkit::AttributeError] if validation fails
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::StringValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "types/collection"
+require_relative "types/boolean"
+require_relative "types/date"
+require_relative "types/date_time"
+require_relative "types/float"
+require_relative "types/generic"
+require_relative "types/integer"
+require_relative "types/string"
+
+module Castkit
+  # Object types supported natively by Castkit.
+  module Types; end
+end

data/lib/castkit/validators/base_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Validators
+    # Abstract base class for all attribute validators.
+    #
+    # Validators ensure that a value conforms to specific rules (e.g., type, format, range).
+    # Subclasses must implement the instance method `#call`.
+    #
+    # @abstract
+    class BaseValidator
+      class << self
+        # Invokes the validator with the given arguments.
+        #
+        # @param value [Object] the attribute value to validate
+        # @param options [Hash] the attribute options (e.g., `min`, `max`, `format`)
+        # @param context [Symbol, String, Hash] the attribute name or context for error reporting
+        # @return [void]
+        # @raise [Castkit::AttributeError] if validation fails
+        def call(value, options:, context:)
+          new.call(value, options: options, context: context)
+        end
+      end
+
+      # Validates the attribute value.
+      #
+      # @abstract Override in subclasses.
+      #
+      # @param value [Object] the attribute value to validate
+      # @param options [Hash] the attribute options
+      # @param context [Symbol, String, Hash] the attribute name or context
+      # @return [void]
+      # @raise [NotImplementedError] unless implemented in a subclass
+      def call(value, options:, context:)
+        raise NotImplementedError, "#{self.class.name} must implement `#call`"
+      end
+    end
+  end
+end

data/lib/castkit/validators/numeric_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../validator"
+require_relative "base_validator"
 
 module Castkit
   module Validators
     # Validates that a numeric value falls within the allowed range.
     #
     # Supports `:min` and `:max` options to enforce bounds.
-    class NumericValidator < Castkit::Validator
+    class NumericValidator < Castkit::Validators::BaseValidator
       # Validates the numeric value.
       #
       # @param value [Numeric] the value to validate

data/lib/castkit/validators/string_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../validator"
+require_relative "base_validator"
 
 module Castkit
   module Validators
     # Validates that a value is a String and optionally conforms to a format.
     #
     # Supports format validation using a Regexp or a custom Proc.
-    class StringValidator < Castkit::Validator
+    class StringValidator < Castkit::Validators::BaseValidator
       # Validates the string value.
       #
       # @param value [Object] the value to validate
@@ -16,7 +16,7 @@ module Castkit
       # @raise [Castkit::AttributeError] if value is not a string or fails format validation
       # @return [void]
       def call(value, options:, context:)
-        raise Castkit::AttributeError, "#{context} must be a String" unless value.is_a?(String)
+        raise Castkit::AttributeError, "#{context} must be a string" unless value.is_a?(String)
 
         return unless options[:format]
 

data/lib/castkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Castkit
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/castkit.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "castkit/version"
+require_relative "castkit/attribute"
+require_relative "castkit/contract"
 require_relative "castkit/data_object"
 
 # Castkit is a lightweight, type-safe data object system for Ruby.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: castkit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-14 00:00:00.000000000 Z
+date: 2025-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -72,24 +72,40 @@ files:
 - castkit.gemspec
 - lib/castkit.rb
 - lib/castkit/attribute.rb
-- lib/castkit/attribute_extensions/access.rb
-- lib/castkit/attribute_extensions/casting.rb
-- lib/castkit/attribute_extensions/error_handling.rb
-- lib/castkit/attribute_extensions/options.rb
-- lib/castkit/attribute_extensions/serialization.rb
-- lib/castkit/attribute_extensions/validation.rb
 - lib/castkit/castkit.rb
 - lib/castkit/configuration.rb
+- lib/castkit/contract.rb
+- lib/castkit/contract/data_object.rb
+- lib/castkit/contract/generic.rb
+- lib/castkit/contract/result.rb
+- lib/castkit/contract/validator.rb
+- lib/castkit/core/attribute_types.rb
+- lib/castkit/core/attributes.rb
+- lib/castkit/core/config.rb
+- lib/castkit/core/registerable.rb
 - lib/castkit/data_object.rb
-- lib/castkit/data_object_extensions/attribute_types.rb
-- lib/castkit/data_object_extensions/attributes.rb
-- lib/castkit/data_object_extensions/config.rb
-- lib/castkit/data_object_extensions/deserialization.rb
 - lib/castkit/default_serializer.rb
 - lib/castkit/error.rb
+- lib/castkit/ext/attribute/access.rb
+- lib/castkit/ext/attribute/error_handling.rb
+- lib/castkit/ext/attribute/options.rb
+- lib/castkit/ext/attribute/validation.rb
+- lib/castkit/ext/data_object/contract.rb
+- lib/castkit/ext/data_object/deserialization.rb
+- lib/castkit/ext/data_object/serialization.rb
+- lib/castkit/inflector.rb
 - lib/castkit/serializer.rb
+- lib/castkit/types.rb
+- lib/castkit/types/boolean.rb
+- lib/castkit/types/collection.rb
+- lib/castkit/types/date.rb
+- lib/castkit/types/date_time.rb
+- lib/castkit/types/float.rb
+- lib/castkit/types/generic.rb
+- lib/castkit/types/integer.rb
+- lib/castkit/types/string.rb
 - lib/castkit/validator.rb
-- lib/castkit/validators.rb
+- lib/castkit/validators/base_validator.rb
 - lib/castkit/validators/numeric_validator.rb
 - lib/castkit/validators/string_validator.rb
 - lib/castkit/version.rb

data/lib/castkit/attribute_extensions/access.rb

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

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

@@ -1,83 +0,0 @@
-# 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)
-
-        Castkit.warning "[Castkit] #{message}"
-        nil
-      end
-    end
-  end
-end