castkit 0.2.0 → 0.3.1

data/lib/castkit/dsl/attribute.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "attribute/options"
+require_relative "attribute/access"
+require_relative "attribute/validation"
+
+module Castkit
+  module DSL
+    # Provides a unified entry point for attribute-level DSL extensions.
+    #
+    # This module bundles together the core DSL modules for configuring attributes.
+    # It is included internally by systems that support Castkit-style attribute declarations,
+    # such as {Castkit::DataObject} and {Castkit::Contract::Base}.
+    #
+    # When included, it mixes in:
+    # - {Castkit::DSL::Attribute::Options} – option-setting methods (e.g., `required`, `default`, etc.)
+    # - {Castkit::DSL::Attribute::Access} – access control methods (e.g., `readonly`, `access`)
+    # - {Castkit::DSL::Attribute::Validation} – validation helpers (e.g., `format`, `validator`)
+    #
+    # @example Extending a custom DSL that uses Castkit-style attributes
+    #   class MyCustomSchema
+    #     include Castkit::DSL::Attribute
+    #
+    #     def self.required(value)
+    #       # interpret DSL options
+    #     end
+    #   end
+    #
+    #   class MyString < MyCustomSchema
+    #     type :string
+    #     required true
+    #     access [:read]
+    #   end
+    #
+    # @note This module is not intended to be mixed into {Castkit::Attributes::Definition}.
+    module Attribute
+      # Hook called when this module is included.
+      #
+      # @param base [Class, Module] the including class or module
+      def self.included(base)
+        base.include(Castkit::DSL::Attribute::Options)
+        base.include(Castkit::DSL::Attribute::Access)
+        base.include(Castkit::DSL::Attribute::Validation)
+      end
+    end
+  end
+end

data/lib/castkit/{ext → dsl}/data_object/contract.rb

@@ -3,7 +3,7 @@
 require_relative "../../contract"
 
 module Castkit
-  module Ext
+  module DSL
     module DataObject
       # Extension module that adds contract support to Castkit::DataObject classes.
       #
@@ -63,7 +63,7 @@ module Castkit
         #   UserDto = Castkit::DataObject.from_contract(UserContract)
         #   dto = UserDto.new(id: "abc", email: "a@example.com")
         #
-        # @param contract [Class<Castkit::Contract::Generic>] the contract to convert
+        # @param contract [Class<Castkit::Contract::Base>] the contract to convert
         # @return [Class<Castkit::DataObject>] a new anonymous DataObject class
 
         def from_contract(contract)

data/lib/castkit/{ext → dsl}/data_object/deserialization.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module Ext
+  module DSL
     module DataObject
       # Adds deserialization support for Castkit::DataObject instances.
       #
@@ -104,7 +104,11 @@ module Castkit
         # @return [Object, nil]
         def resolve_input_value(input, attribute)
           attribute.key_path(with_aliases: true).each do |path|
-            value = path.reduce(input) { |memo, key| memo.is_a?(Hash) ? memo[key] : nil }
+            value = path.reduce(input) do |memo, key|
+              next memo unless memo.is_a?(Hash)
+
+              memo.key?(key) ? memo[key] : memo[key.to_s]
+            end
             return value unless value.nil?
           end
 

data/lib/castkit/dsl/data_object/plugins.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DSL
+    module DataObject
+      # Provides plugin support for DataObject classes.
+      #
+      # This module allows a Castkit::DataObject to explicitly declare supported plugins,
+      # and ensures all default plugins are enabled on subclassing.
+      #
+      # Plugins should be defined under `Castkit::Plugins::<Name>` and can be registered
+      # globally via `Castkit.configure { |c| c.register_plugin(:name, MyPlugin) }`.
+      #
+      # Example:
+      #   class MyDto < Castkit::DataObject
+      #     enable_plugins :oj, :msgpack
+      #     disable_plugins :yaml
+      #   end
+      #
+      module Plugins
+        # Returns the set of plugins explicitly enabled on the class.
+        #
+        # @return [Set<Symbol>] enabled plugin names
+        def enabled_plugins
+          @enabled_plugins ||= Set.new
+        end
+
+        # Returns the set of default plugins explicitly disabled on the class.
+        #
+        # @return [Set<Symbol>] disabled plugin names
+        def disabled_plugins
+          @disabled_plugins ||= Set.new
+        end
+
+        # Enables one or more plugins on the calling class.
+        #
+        # @param plugins [Array<Symbol>] plugin identifiers (e.g., :oj, :yaml)
+        # @return [void]
+        def enable_plugins(*plugins)
+          return if plugins.empty?
+
+          @enabled_plugins ||= Set.new
+          @enabled_plugins.merge(plugins)
+
+          Castkit::Plugins.activate(self, *plugins)
+        end
+
+        # Disables one or more default plugins on the calling class.
+        #
+        # @example
+        #   Castkit.configure do |config|
+        #     config.default_plugins [:oj, :activerecord]
+        #   end
+        #
+        #   class UserDto < Castkit::DataObject
+        #     disable_plugin :activerecord
+        #   end
+        #
+        # @param plugins [Array<Symbol>] plugin identifiers (e.g., :oj, :yaml)
+        # @return [void]
+        def disable_plugins(*plugins)
+          return if plugins.empty?
+
+          @disabled_plugins ||= Set.new
+          @disabled_plugins.merge(plugins)
+        end
+
+        # Hook that is called when a DataObject subclass is created.
+        #
+        # Automatically applies `Castkit.configuration.default_plugins`
+        # to the subclass.
+        #
+        # @param subclass [Class] the inheriting subclass
+        # @return [void]
+        def inherited(subclass)
+          super
+
+          disabled = instance_variable_get(:@disabled_plugins) || Set.new
+          plugins = Castkit.configuration.default_plugins - disabled.to_a
+
+          subclass.enable_plugins(*plugins)
+        end
+      end
+    end
+  end
+end

data/lib/castkit/{ext → dsl}/data_object/serialization.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module Ext
+  module DSL
     module DataObject
       # Provides per-class serialization configuration for Castkit::Dataobject, including
       # root key handling and ignore rules.

data/lib/castkit/dsl/data_object.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../core/config"
+require_relative "../core/attributes"
+require_relative "../core/attribute_types"
+require_relative "data_object/contract"
+require_relative "data_object/plugins"
+require_relative "data_object/serialization"
+require_relative "data_object/deserialization"
+
+module Castkit
+  module DSL
+    # Provides the complete DSL used by Castkit data objects.
+    #
+    # This module can be included into any class to make it behave like a `Castkit::DataObject`
+    # without requiring subclassing. It wires in the full attribute DSL, type system, contract support,
+    # plugin lifecycle, and (de)serialization logic.
+    #
+    # This is what powers `Castkit::DataObject` internally, and is intended for advanced use
+    # cases where composition is preferred over inheritance.
+    #
+    # When included, this module:
+    #
+    # - `extend`s:
+    #   - {Castkit::Core::Config} – configuration and context behavior
+    #   - {Castkit::Core::Attributes} – the DSL for declaring attributes
+    #   - {Castkit::Core::AttributeTypes} – support for custom type resolution
+    #   - {Castkit::DSL::DataObject::Contract} – validation contract hooks
+    #   - {Castkit::DSL::DataObject::Plugins} – plugin hooks and lifecycle events
+    #
+    # - `include`s:
+    #   - {Castkit::DSL::DataObject::Serialization} – `#to_h`, `#as_json`, etc.
+    #   - {Castkit::DSL::DataObject::Deserialization} – `from_h`, `from_json`, etc.
+    #
+    # @example Including in a custom data object
+    #   class MyObject
+    #     include Castkit::DSL::DataObject
+    #
+    #     string :id
+    #     boolean :active, default: true
+    #   end
+    #
+    # @see Castkit::DataObject for the default implementation
+    module DataObject
+      # Hook triggered when the module is included.
+      #
+      # @param base [Class] the including class
+      # @return [void]
+      def self.included(base)
+        base.extend(Castkit::Core::Config)
+        base.extend(Castkit::Core::Attributes)
+        base.extend(Castkit::Core::AttributeTypes)
+        base.extend(Castkit::DSL::DataObject::Contract)
+        base.extend(Castkit::DSL::DataObject::Plugins)
+
+        base.include(Castkit::DSL::DataObject::Serialization)
+        base.include(Castkit::DSL::DataObject::Deserialization)
+      end
+    end
+  end
+end

data/lib/castkit/inflector.rb

@@ -24,7 +24,7 @@ module Castkit
       # @param string [String, Symbol] the input to convert
       # @return [String] the PascalCase representation
       def pascalize(string)
-        string.to_s.split("_").map(&:capitalize).join
+        underscore(string).to_s.split("_").map(&:capitalize).join
       end
 
       # Converts a PascalCase or camelCase string to snake_case.

data/lib/castkit/plugins.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Castkit
+  # Internal registry for Castkit plugin modules.
+  #
+  # This module supports registering, activating, and looking up Castkit plugins.
+  # Plugins are typically included in Castkit::DataObject subclasses via `.enable_plugins`.
+  #
+  # Plugins can be defined under `Castkit::Plugins::<Name>` or manually registered
+  # through the configuration API.
+  #
+  # @example Registering a custom plugin
+  #   Castkit.configure do |config|
+  #     config.register_plugin(:custom, MyCustomPlugin)
+  #   end
+  #
+  # @example Enabling plugins on a DataObject
+  #   class MyDto < Castkit::DataObject
+  #     enable_plugins :custom, :oj
+  #   end
+  module Plugins
+    @registered_plugins = {}
+
+    class << self
+      # Activates one or more plugins on the given class.
+      #
+      # Each plugin module is included into the class. If the module responds to `setup!`,
+      # it will be called with the class as the argument.
+      #
+      # @param klass [Class] the target class (usually a Castkit::DataObject subclass)
+      # @param names [Array<Symbol>] plugin names (e.g., :oj, :yaml)
+      # @return [void]
+      def activate(klass, *names)
+        names.each do |name|
+          plugin = lookup!(name)
+          klass.include(plugin) if plugin
+          plugin.setup!(klass) if plugin.respond_to?(:setup!)
+        end
+      end
+
+      # (Placeholder) Deactivates plugins by name.
+      #
+      # Currently not implemented, included for future API completeness.
+      #
+      # @param _klass [Class] the class to deactivate plugins on
+      # @param names [Array<Symbol>] plugin names to deactivate
+      # @return [void]
+      def deactivate(_klass, *names)
+        @deactivate_plugins = names
+      end
+
+      # Looks up a plugin module by name.
+      #
+      # This will first check the internal registry, then fall back to
+      # resolving a constant under `Castkit::Plugins::<Name>`.
+      #
+      # @param name [Symbol, String] the plugin name (e.g., :oj)
+      # @return [Module] the plugin module
+      # @raise [Castkit::Error] if no plugin is found
+      def lookup!(name)
+        @registered_plugins[name.to_sym] ||
+          const_get(Castkit::Inflector.pascalize(name.to_s), false)
+      rescue NameError
+        raise Castkit::Error,
+              "Castkit plugin `#{name}` could not be found. Make sure it is " \
+              "defined under Castkit::Plugins or registered using " \
+              "`Castkit.configure { |c| c.register_plugin(:#{name}, MyPlugin) }`."
+      end
+
+      # Registers a plugin module under a custom name.
+      #
+      # This allows developers to register modules not defined under Castkit::Plugins.
+      #
+      # @param name [Symbol] the plugin name (e.g., :custom_plugin)
+      # @param plugin [Module] the plugin module to register
+      # @return [void]
+      def register(name, plugin)
+        @registered_plugins[name] = plugin
+      end
+    end
+  end
+end

data/lib/castkit/serializers/base.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Castkit
+  module Serializers
+    # Abstract base class for defining custom serializers for Castkit::DataObject instances.
+    #
+    # Handles circular reference detection and provides a consistent `call` API.
+    #
+    # Subclasses must implement an instance method `#call` that returns a hash-like representation.
+    #
+    # @example Usage
+    #   class CustomSerializer < Castkit::Serializers::Base
+    #     private
+    #
+    #     def call
+    #       { type: object.class.name, data: object.to_h }
+    #     end
+    #   end
+    #
+    #   CustomSerializer.call(user_dto)
+    class Base
+      class << self
+        # Entrypoint for serializing an object.
+        #
+        # @param object [Castkit::DataObject] the object to serialize
+        # @param visited [Set, nil] used to track visited object IDs
+        # @return [Object] result of custom serialization
+        def call(object, visited: nil)
+          new(object, visited: visited).send(:serialize)
+        end
+      end
+
+      # @return [Castkit::DataObject] the object being serialized
+      attr_reader :object
+
+      protected
+
+      # Fallback to the default serializer.
+      #
+      # @return [Hash]
+      def serialize_with_default
+        Castkit::Serializers::DefaultSerializer.call(object, visited: visited)
+      end
+
+      private
+
+      # @return [Set<Integer>] a set of visited object IDs to detect circular references
+      attr_reader :visited
+
+      # Initializes the serializer instance.
+      #
+      # @param object [Castkit::DataObject]
+      # @param visited [Set, nil]
+      def initialize(object, visited: nil)
+        @object = object
+        @visited = visited || Set.new
+      end
+
+      # Subclasses must override this method to implement serialization logic.
+      #
+      # @raise [NotImplementedError]
+      # @return [Object]
+      def call
+        raise NotImplementedError, "#{self.class.name} must implement `#call`"
+      end
+
+      # Wraps the actual serialization logic with circular reference detection.
+      #
+      # @return [Object]
+      # @raise [Castkit::SerializationError] if a circular reference is detected
+      def serialize
+        check_circular_reference!
+        visited << object.object_id
+
+        result = call
+        visited.delete(object.object_id)
+
+        result
+      end
+
+      # Raises if the object has already been visited (circular reference).
+      #
+      # @raise [Castkit::SerializationError]
+      # @return [void]
+      def check_circular_reference!
+        return unless visited.include?(object.object_id)
+
+        raise Castkit::SerializationError, "Circular reference detected for #{object.class}"
+      end
+    end
+  end
+end

data/lib/castkit/serializers/default_serializer.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Castkit
+  module Serializers
+    # Default serializer for Castkit::DataObject instances.
+    #
+    # Serializes attributes into a plain Ruby hash, applying access rules, nil/blank filtering,
+    # and nested structure handling. The output format supports JSON-compatible structures
+    # and respects the class-level serialization configuration.
+    class DefaultSerializer < Castkit::Serializers::Base
+      # @return [Hash{Symbol => Castkit::Attribute}] the attributes to serialize
+      attr_reader :attributes
+
+      # @return [Hash{Symbol => Object}] unrecognized attributes captured during deserialization
+      attr_reader :unknown_attributes
+
+      # @return [Hash] serialization config flags like :root, :ignore_nil, :allow_unknown
+      attr_reader :options
+
+      # Serializes the object to a hash.
+      #
+      # Includes unknown attributes if configured, and wraps in a root key if defined.
+      #
+      # @return [Hash] the fully serialized result
+      def call
+        result = serialize_attributes
+        result.merge!(unknown_attributes) if options[:allow_unknown]
+
+        options[:root] ? { options[:root].to_sym => result } : result
+      end
+
+      private
+
+      # Initializes the serializer.
+      #
+      # @param object [Castkit::DataObject] the object to serialize
+      # @param visited [Set, nil] tracks circular references
+      def initialize(object, visited: nil)
+        super
+
+        @skip_flag = "__castkit_#{object.object_id}"
+        @attributes = object.class.attributes.freeze
+        @unknown_attributes = object.unknown_attributes.freeze
+        @options = {
+          root: object.class.root,
+          ignore_nil: object.class.ignore_nil || false,
+          allow_unknown: object.class.allow_unknown || false
+        }
+      end
+
+      # Serializes all defined attributes.
+      #
+      # @return [Hash] serialized attribute key-value pairs
+      def serialize_attributes
+        attributes.values.each_with_object({}) do |attribute, hash|
+          next if attribute.skip_serialization?
+
+          serialized_value = serialize_attribute(attribute)
+          next if serialized_value == @skip_flag
+
+          assign_attribute_key!(attribute, serialized_value, hash)
+        end
+      end
+
+      # Serializes a single attribute.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @return [Object] the serialized value or skip flag
+      def serialize_attribute(attribute)
+        value = object.public_send(attribute.field)
+        return @skip_flag if skip_nil?(attribute, value)
+
+        serialized_value = process_attribute(attribute, value)
+        return @skip_flag if skip_blank?(attribute, serialized_value)
+
+        serialized_value
+      end
+
+      # Delegates serialization based on type.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Object]
+      def process_attribute(attribute, value)
+        if attribute.dataobject?
+          serialize_dataobject(attribute, value)
+        elsif attribute.dataobject_collection?
+          Array(value).map { |v| serialize_dataobject(attribute, v) }
+        else
+          type = Array(attribute.type).first
+          Castkit.type_serializer(type).call(value)
+        end
+      end
+
+      # Assigns value into nested hash structure based on key path.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @param hash [Hash]
+      # @return [void]
+      def assign_attribute_key!(attribute, value, hash)
+        key_path = attribute.key_path
+        last = key_path.pop
+        current = hash
+
+        key_path.each do |key|
+          current[key] ||= {}
+          current = current[key]
+        end
+
+        current[last] = value
+      end
+
+      # Whether to skip serialization for nil values.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Boolean]
+      def skip_nil?(attribute, value)
+        value.nil? && (attribute.ignore_nil? || options[:ignore_nil])
+      end
+
+      # Whether to skip serialization for blank values.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Object]
+      # @return [Boolean]
+      def skip_blank?(attribute, value)
+        blank?(value) && (attribute.ignore_blank? || options[:ignore_blank])
+      end
+
+      # True if value is nil or empty.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      # Serializes a DataObject using the proper serializer.
+      #
+      # @param attribute [Castkit::Attribute]
+      # @param value [Castkit::DataObject]
+      # @return [Object]
+      def serialize_dataobject(attribute, value)
+        serializer = attribute.options[:serializer]
+        serializer ||= value.class.serializer
+        serializer ||= Castkit::Serializers::DefaultSerializer
+
+        serializer.call(value, visited: visited)
+      end
+    end
+  end
+end

data/lib/castkit/types/{generic.rb → base.rb}

@@ -2,14 +2,14 @@
 
 module Castkit
   module Types
-    # Generic base class for type definitions in Castkit.
+    # Abstract base class for type definitions in Castkit.
     #
     # Provides default behavior for (de)serialization, validation, and coercion.
     # All primitive types should subclass this and override methods as needed.
     #
     # The `cast!` method is the primary entry point used by attribute processing
     # to validate and coerce values in a predictable order.
-    class Generic
+    class Base
       class << self
         # Coerces and validates a value for use in a Castkit DataObject.
         #
@@ -24,18 +24,19 @@ module Castkit
         # @param options [Hash] options passed to `validate!`, e.g., `min`, `max`, `force_type`
         # @param context [Symbol, String, nil] context label for error messages
         # @return [Object] the deserialized and validated value
-        def cast!(value, validator: nil, options: {}, context: {})
+        def cast!(value, validator: nil, options: {}, context: {}, **extra_options)
+          options = options.merge(extra_options)
           instance = new
           validator ||= options.delete(:validator)
           validator ||= default_validator(instance)
 
           if options[:force_type]
             deserialized_value = instance.deserialize(value)
-            validator.call(deserialized_value, options: options, context: context)
+            invoke_validator(validator, deserialized_value, options: options, context: context)
             return deserialized_value
           end
 
-          validator.call(value, options: options, context: context)
+          invoke_validator(validator, value, options: options, context: context)
           instance.deserialize(value)
         end
 
@@ -69,13 +70,33 @@ module Castkit
 
         # Builds a default validator from the instance itself.
         #
-        # @param instance [Castkit::Types::Generic]
+        # @param instance [Castkit::Types::Base]
         # @return [Proc] a lambda wrapping `#validate!`
         def default_validator(instance)
           lambda do |value, options: {}, context: nil|
             instance.validate!(value, options: options, context: context)
           end
         end
+
+        # Dispatches validation to support callable validators with different arities.
+        #
+        # @param validator [#call, Proc] the validator to invoke
+        # @param value [Object] the value being validated
+        # @param options [Hash] validation options
+        # @param context [Symbol, String, nil] context for error messages
+        # @return [void]
+        def invoke_validator(validator, value, options:, context:)
+          return validator.call(value, options: options, context: context) unless validator.is_a?(Proc)
+
+          case validator.arity
+          when 1
+            validator.call(value)
+          when 2
+            validator.call(value, options)
+          else
+            validator.call(value, options: options, context: context)
+          end
+        end
       end
 
       # Deserializes the value. Override in subclasses to coerce input (e.g., `"123"` → `123`).
@@ -111,10 +132,9 @@ module Castkit
       # @param type [Symbol]
       # @param value [Object, nil]
       # @return [void]
-      def type_error!(type, value)
-        message = "value must be a #{type}, got #{value.inspect}"
-
-        raise Castkit::TypeError, message if Castkit.configuration.raise_type_errors
+      def type_error!(type, value, context: nil)
+        message = "#{context || "value"} must be a #{type}, got #{value}"
+        raise Castkit::AttributeError, message if Castkit.configuration.raise_type_errors
 
         Castkit.warning "[Castkit] #{message}" if Castkit.configuration.enable_warnings
       end