castkit 0.1.2 → 0.3.0

data/lib/castkit/configuration.rb

@@ -1,39 +1,53 @@
 # frozen_string_literal: true
 
-require_relative "validators"
+require_relative "types"
 
 module Castkit
   # Configuration container for global Castkit settings.
   #
-  # This includes validator registration and enforcement flags for various runtime checks.
+  # This includes type registration, validation, and enforcement flags
+  # used throughout Castkit's attribute system.
   class Configuration
-    # Default mapping of primitive types to validators.
+    # Default mapping of primitive type definitions.
     #
-    # @return [Hash<Symbol, Class>]
-    DEFAULT_VALIDATORS = {
-      string: Castkit::Validators::StringValidator,
-      integer: Castkit::Validators::NumericValidator,
-      float: Castkit::Validators::NumericValidator
+    # @return [Hash{Symbol => Castkit::Types::Base}]
+    DEFAULT_TYPES = {
+      array: Castkit::Types::Collection.new,
+      boolean: Castkit::Types::Boolean.new,
+      date: Castkit::Types::Date.new,
+      datetime: Castkit::Types::DateTime.new,
+      float: Castkit::Types::Float.new,
+      hash: Castkit::Types::Base.new,
+      integer: Castkit::Types::Integer.new,
+      string: Castkit::Types::String.new
     }.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
+    # Type aliases for primitive type definitions.
+    #
+    # @return [Hash{Symbol => Symbol}]
+    TYPE_ALIASES = {
+      collection: :array,
+      bool: :boolean,
+      int: :integer,
+      map: :hash,
+      number: :float,
+      str: :string,
+      timestamp: :datetime,
+      uuid: :string
+    }.freeze
 
-    # Whether to raise an error for unrecognized primitive types.
-    # @return [Boolean]
-    attr_accessor :enforce_known_primitive_type
+    # @return [Hash{Symbol => Castkit::Types::Base}] registered types
+    attr_reader :types
 
-    # Whether to raise an error on invalid boolean coercion.
-    # @return [Boolean]
-    attr_accessor :enforce_boolean_casting
+    # Set default plugins that will be used globally in all Castkit::DataObject subclasses.
+    # This is equivalent to calling `enable_plugins` in every class.
+    #
+    # @return [Array<Symbol>] default plugin names to be applied to all DataObject subclasses
+    attr_accessor :default_plugins
 
-    # Whether to raise an error if a union type has no matching candidate.
+    # Whether to raise an error if values should be validated before deserializing, e.g. true -> "true"
     # @return [Boolean]
-    attr_accessor :enforce_union_match
+    attr_accessor :enforce_typing
 
     # Whether to raise an error if access mode is not recognized.
     # @return [Boolean]
@@ -47,55 +61,111 @@ module Castkit
     # @return [Boolean]
     attr_accessor :enforce_array_options
 
-    # Whether to generating warnings or not, defaults to `true`.
+    # Whether to raise an error for unknown and invalid type definitions.
+    # @return [Boolean]
+    attr_accessor :raise_type_errors
+
+    # Whether to emit warnings when Castkit detects misconfigurations.
     # @return [Boolean]
     attr_accessor :enable_warnings
 
-    # Initializes the configuration with default validators and enforcement settings.
+    # Whether the strict flag is enabled by default for all DataObjects and Contracts.
+    # @return [Boolean]
+    attr_accessor :strict_by_default
+
+    # Initializes the configuration with default types and enforcement flags.
     #
     # @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
+      @types = DEFAULT_TYPES.dup
+      @enforce_typing = true
       @enforce_attribute_access = true
       @enforce_unwrapped_prefix = true
       @enforce_array_options = true
+      @raise_type_errors = true
       @enable_warnings = true
+      @strict_by_default = true
+      @default_plugins = []
+
+      apply_type_aliases!
     end
 
-    # Registers a custom validator for a given type.
+    # Registers a new type definition.
     #
-    # @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`
+    # @param type [Symbol] the symbolic type name (e.g., :uuid)
+    # @param klass [Class<Castkit::Types::Base>] the class to register
+    # @param override [Boolean] whether to allow overwriting existing registration
+    # @raise [Castkit::TypeError] if the type class is invalid or not a subclass of Castkit::Types::Base
     # @return [void]
-    def register_validator(type, validator, override: false)
-      return if @validators.key?(type.to_sym) && !override
+    def register_type(type, klass, aliases: [], override: false)
+      type = type.to_sym
+      return if types.key?(type) && !override
 
-      unless validator.respond_to?(:call)
-        raise Castkit::Error, "Validator for `#{type}` must respond to `.call(value, options:, context:)`"
+      instance = klass.new
+      unless instance.is_a?(Castkit::Types::Base)
+        raise Castkit::TypeError, "Expected subclass of Castkit::Types::Base for `#{type}`"
       end
 
-      @validators[type.to_sym] = validator
+      types[type] = instance
+
+      Castkit::Core::AttributeTypes.define_type_dsl(type) if Castkit::Core::AttributeTypes.respond_to?(:define_type_dsl)
+      return unless aliases.any?
+
+      aliases.each { |alias_type| register_type(alias_type, klass, override: override) }
+    end
+
+    # Register a custom plugin for use with Castkit::DataObject.
+    #
+    # @example Loading as a default plugin
+    #   Castkit.configure do |config|
+    #     config.register_plugin(:custom, CustomPlugin)
+    #     config.default_plugins [:custom]
+    #   end
+    #
+    # @example Loading it directly in a Castkit::DataObject
+    #   class UserDto < Castkit::DataObject
+    #     enable_plugins :custom
+    #   end
+    def register_plugin(name, plugin)
+      Castkit::Plugins.register(name, plugin)
     end
 
-    # Returns the registered validator for the given type.
+    # Returns the type handler for a given type symbol.
     #
     # @param type [Symbol]
-    # @return [#call, nil]
-    def validator_for(type)
-      validators[type.to_sym]
+    # @return [Castkit::Types::Base]
+    # @raise [Castkit::TypeError] if the type is not registered
+    def fetch_type(type)
+      @types.fetch(type.to_sym) do
+        raise Castkit::TypeError, "Unknown type `#{type.inspect}`" if raise_type_errors
+      end
     end
 
-    # Resets all validators to their default mappings.
+    # Returns whether a type is currently registered.
+    #
+    # @param type [Symbol]
+    # @return [Boolean]
+    def type_registered?(type)
+      @types.key?(type.to_sym)
+    end
+
+    # Restores the type registry to its default state.
     #
     # @return [void]
-    def reset_validators!
-      @validators = DEFAULT_VALIDATORS.dup
+    def reset_types!
+      @types = DEFAULT_TYPES.dup
+      apply_type_aliases!
+    end
+
+    private
+
+    # Registers aliases for primitive type definitions.
+    #
+    # @return [void]
+    def apply_type_aliases!
+      TYPE_ALIASES.each do |alias_key, canonical|
+        register_type(alias_key, DEFAULT_TYPES[canonical].class)
+      end
     end
   end
 end

data/lib/castkit/contract/base.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "../core/config"
+require_relative "../core/attribute_types"
+require_relative "../core/registerable"
+require_relative "result"
+
+module Castkit
+  module Contract
+    # Base class for all Castkit contracts.
+    #
+    # Castkit contracts define validation logic over a set of attributes using a DSL.
+    # You can either subclass this directly or use {Castkit::Contract.build} to generate
+    # ephemeral or reusable contract classes.
+    #
+    # @example Subclassing directly
+    #   class MyContract < Castkit::Contract::Base
+    #     string :id
+    #     integer :count, required: false
+    #   end
+    #
+    #   MyContract.validate!(id: "abc")
+    #
+    # @example Using Contract.build (preferred for dynamic generation)
+    #   UserContract = Castkit::Contract.build(:user) do
+    #     string :id
+    #     string :email, required: false
+    #   end
+    #
+    #   UserContract.validate!(id: "123")
+    #
+    # @see Castkit::Contract.build
+    class Base
+      extend Castkit::Core::Config
+      extend Castkit::Core::AttributeTypes
+      extend Castkit::Core::Registerable
+
+      ATTRIBUTE_OPTIONS = %i[
+        required aliases min max format of validator unwrapped prefix force_type
+      ].freeze
+
+      class << self
+        # Registers the current class under `Castkit::Contracts`.
+        #
+        # @param as [String, Symbol, nil] The constant name to use (PascalCase). Defaults to the name used when building
+        #   the contract. If no name was provided, an error is raised.
+        # @return [Class] the registered contract class
+        # @raise [Castkit::Error] If a name cannot be resolved.
+        def register!(as: nil)
+          super(namespace: :contracts, as: as || definition[:name])
+        end
+
+        # Defines an attribute for the contract.
+        #
+        # Only a subset of options is allowed inside a contract.
+        #
+        # @param field [Symbol] the field name
+        # @param type [Symbol, Class, Array] the type or union of types
+        # @param options [Hash] allowed options like :required or :validator
+        # @return [void]
+        def attribute(field, type, **options)
+          options = options.slice(*ATTRIBUTE_OPTIONS)
+          attributes[field] = Castkit::Attribute.new(field, type, **options)
+        end
+
+        # Validates input against the contract and returns a Result.
+        #
+        # @param input [Hash]
+        # @return [Castkit::Contract::Result]
+        def validate(input)
+          validate!(input)
+        rescue Castkit::ContractError => e
+          Castkit::Contract::Result.new(definition[:name].to_s, input, errors: e.errors)
+        end
+
+        # Validates input and raises on failure.
+        #
+        # @param input [Hash]
+        # @raise [Castkit::ContractError]
+        # @return [void]
+        def validate!(input)
+          Castkit::Contract::Validator.call!(attributes.values, input, **validation_rules)
+          Castkit::Contract::Result.new(definition[:name].to_s, input)
+        end
+
+        # Returns internal contract metadata.
+        #
+        # @return [Hash]
+        def definition
+          @definition ||= {
+            name: :ephemeral,
+            attributes: {}
+          }
+        end
+
+        # Returns the defined attributes.
+        #
+        # @return [Hash{Symbol => Castkit::Attribute}]
+        def attributes
+          definition[:attributes]
+        end
+
+        private
+
+        # Defines the contract from a source or block.
+        #
+        # @param name [Symbol, String]
+        # @param source [Castkit::DataObject, nil]
+        # @param block [Proc, nil]
+        # @return [Hash]
+        def define(name = :ephemeral, source = nil, validation_rules: {}, &block)
+          validate_definition!(source, &block)
+
+          if source
+            define_from_source(name, source)
+          else
+            define_from_block(name, &block)
+          end
+
+          validation_rules.each { |k, v| self.validation_rules[k] = v }
+          attributes
+        end
+
+        # Copies attributes from a DataObject.
+        #
+        # @param name [Symbol, String]
+        # @param source [Castkit::DataObject]
+        # @return [void]
+        def define_from_source(name, source)
+          source_attributes = source.attributes.dup
+
+          @definition = {
+            name: name,
+            attributes: source_attributes.transform_values do |attr|
+              Castkit::Attribute.new(attr.field, attr.type, **attr.options.slice(*ATTRIBUTE_OPTIONS))
+            end
+          }
+        end
+
+        # Executes DSL block in the contract context.
+        #
+        # @param name [Symbol, String]
+        # @yield [block]
+        # @return [void]
+        def define_from_block(name, &block)
+          definition[:name] = name
+
+          @__castkit_contract_dsl = true
+          instance_eval(&block)
+        ensure
+          @__castkit_contract_dsl = false
+        end
+
+        # Ensures a valid contract definition input.
+        #
+        # @param source [Object, nil]
+        # @raise [Castkit::ContractError]
+        # @return [void]
+        def validate_definition!(source)
+          raise Castkit::ContractError, "Received both source and block" if source && block_given?
+          return if block_given? || Castkit.dataobject?(source)
+
+          raise Castkit::ContractError, "Expected a Castkit::DataObject or contract block"
+        end
+      end
+    end
+  end
+end

data/lib/castkit/contract/data_object.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Contract
+    # Extension module that adds `.to_dataobject` and `.dataobject` support to Castkit contracts.
+    #
+    # This allows any contract to be dynamically converted into a Castkit::DataObject class,
+    # enabling reuse of validation schemas for serialization, coercion, or API response modeling.
+    #
+    # This module is automatically included by Castkit contract classes and is not
+    # intended to be used manually.
+    #
+    # @example
+    #   contract = Castkit::Contract.build(:user) do
+    #     string :id
+    #     string :email
+    #   end
+    #
+    #   UserDto = contract.to_dataobject
+    #   UserDto.new(id: "123", email: "a@example.com")
+    module DataObject
+      # Returns or builds a Castkit::DataObject from the current contract.
+      #
+      # Memoizes the result to avoid repeated regeneration.
+      #
+      # @example
+      #   contract = Castkit::Contract.build(:user) do
+      #     string :id
+      #     string :name
+      #   end
+      #
+      #   dto_class = contract.dataobject
+      #   dto = dto_class.new(id: "123", name: "Alice")
+      #
+      # @return [Class<Castkit::DataObject>] the generated DTO class
+      def dataobject
+        @dataobject ||= to_dataobject
+      end
+
+      # Constructs an ephemeral Castkit::DataObject class from the current contract.
+      #
+      # This creates a new anonymous class each time unless memoized via {#dataobject}.
+      #
+      # @example
+      #   dto_class = contract.to_dataobject
+      #
+      # @return [Class<Castkit::DataObject>] the dynamically generated DTO
+      def to_dataobject
+        Class.new(Castkit::DataObject).tap do |klass|
+          attributes.each_value do |attr|
+            klass.attribute(attr.field, attr.type, **attr.options)
+          end
+        end
+      end
+
+      # Alias for {#to_dataobject}
+      #
+      # @see #to_dataobject
+      alias to_dto to_dataobject
+    end
+  end
+end

data/lib/castkit/contract/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Contract
+    # Represents the result of a contract validation.
+    #
+    # Provides access to the validation outcome, including whether it succeeded or failed,
+    # and includes the full list of errors if any.
+    class Result
+      # @return [Symbol] the name of the contract
+      attr_reader :contract
+
+      # @return [Hash{Symbol => Object}] the validated input
+      attr_reader :input
+
+      # @return [Hash{Symbol => Object}] the validation error hash
+      attr_reader :errors
+
+      # Initializes a new result object.
+      #
+      # @param contract [Symbol, String] the name of the contract
+      # @param input [Hash{Symbol => Object}] the validated input
+      # @param errors [Hash{Symbol => Object}] the validation errors
+      def initialize(contract, input, errors: {})
+        @contract = contract.to_sym.freeze
+        @input = input.freeze
+        @errors = errors.freeze
+      end
+
+      # A debug-friendly representation of the validation result.
+      #
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} contract=#{contract.inspect} success=#{success?} errors=#{errors.inspect}>"
+      end
+
+      # Whether the validation passed with no errors.
+      #
+      # @return [Boolean]
+      def success?
+        errors.empty?
+      end
+
+      # Whether the validation failed with one or more errors.
+      #
+      # @return [Boolean]
+      def failure?
+        !success?
+      end
+
+      # A readable string representation of the validation result.
+      #
+      # @return [String]
+      def to_s
+        return "[Castkit] Contract validation passed for #{contract}" if success?
+
+        parsed_errors = errors.map { |k, v| "  #{k}: #{v.inspect}" }.join("\n")
+        "[Castkit] Contract validation failed for #{contract}:\n#{parsed_errors}"
+      end
+
+      # @return [Hash{Symbol => Object}] the input validation and error hash
+      def to_hash
+        @to_hash ||= {
+          contract: contract,
+          input: input,
+          errors: errors
+        }.freeze
+      end
+
+      # @return [Hash{Symbol => Object}] the input and validation error hash
+      alias to_h to_hash
+    end
+  end
+end