castkit 0.1.1 → 0.2.0

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.1"
+  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.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-13 00:00:00.000000000 Z
+date: 2025-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -69,28 +69,43 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- castkit-0.1.0.gem
 - 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)
-
-        warn "[Castkit] #{message}"
-        nil
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/options.rb

@@ -1,131 +0,0 @@
-# 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 a collection of Castkit::DataObjects.
-      #
-      # @return [Boolean]
-      def dataobject_collection?
-        type == :array && Castkit.dataobject?(options[:of])
-      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

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