castkit 0.1.2 → 0.3.0

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    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/data_object/serialization.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Ext
+    module DataObject
+      # Provides per-class serialization configuration for Castkit::Dataobject, including
+      # root key handling and ignore rules.
+      module Serialization
+        # Automatically extends class-level methods when included.
+        #
+        # @param base [Class]
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level configuration methods.
+        module ClassMethods
+          # Sets or retrieves the root key to wrap the object under during (de)serialization.
+          #
+          # @param value [String, Symbol, nil] optional root key
+          # @return [Symbol, nil]
+          def root(value = nil)
+            value.nil? ? @root : (@root = value.to_s.strip.to_sym)
+          end
+
+          # Sets or retrieves whether to skip `nil` values in output.
+          #
+          # @param value [Boolean, nil]
+          # @return [Boolean, nil]
+          def ignore_nil(value = nil)
+            value.nil? ? @ignore_nil : (@ignore_nil = value)
+          end
+
+          # Sets or retrieves whether to skip blank values (`[]`, `{}`, `""`, etc.) in output.
+          #
+          # Defaults to true unless explicitly set to false.
+          #
+          # @param value [Boolean, nil]
+          # @return [Boolean]
+          def ignore_blank(value = nil)
+            @ignore_blank = value.nil? || value
+          end
+        end
+
+        # Returns the root key for this instance.
+        #
+        # @return [Symbol]
+        def root_key
+          self.class.root.to_s.strip.to_sym
+        end
+
+        # Whether a root key is configured for this instance.
+        #
+        # @return [Boolean]
+        def root_key_set?
+          !self.class.root.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/castkit/inflector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Castkit
+  # Provides string transformation utilities used internally by Castkit
+  module Inflector
+    class << self
+      # Returns the unqualified class name from a namespaced class.
+      #
+      # @example
+      #   Castkit::Inflector.class_name(Foo::Bar) # => "Bar"
+      #
+      # @param klass [Class]
+      # @return [String]
+      def unqualified_name(klass)
+        klass.name.to_s.split("::").last
+      end
+
+      # Converts a snake_case or underscored string into PascalCase.
+      #
+      # @example
+      #   Castkit::Inflector.pascalize("user_contract") # => "UserContract"
+      #   Castkit::Inflector.pascalize(:admin_dto)      # => "AdminDto"
+      #
+      # @param string [String, Symbol] the input to convert
+      # @return [String] the PascalCase representation
+      def pascalize(string)
+        underscore(string).to_s.split("_").map(&:capitalize).join
+      end
+
+      # Converts a PascalCase or camelCase string to snake_case.
+      #
+      # @example
+      #   Castkit::Inflector.underscore("UserContract") # => "user_contract"
+      #   Castkit::Inflector.underscore("XMLParser")    # => "xml_parser"
+      #
+      # @param string [String, Symbol]
+      # @return [String]
+      def underscore(string)
+        string
+          .to_s
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+    end
+  end
+end

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/base.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Types
+    # 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 Base
+      class << self
+        # Coerces and validates a value for use in a Castkit DataObject.
+        #
+        # When `force_type` is true, the value is deserialized (coerced) first,
+        # then validated. This is useful when a value may need to be converted
+        # before it can pass validation (e.g. `"123"` → `123`).
+        #
+        # Otherwise, the raw value is validated before coercion.
+        #
+        # @param value [Object] the input value
+        # @param validator [#call, nil] optional custom validator (default uses `validate!`)
+        # @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: {})
+          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)
+            return deserialized_value
+          end
+
+          validator.call(value, options: options, context: context)
+          instance.deserialize(value)
+        end
+
+        # Deserializes the value using the default type behavior.
+        #
+        # @param value [Object]
+        # @return [Object] the coerced value
+        def deserialize(value)
+          new.deserialize(value)
+        end
+
+        # Serializes the value using the default type behavior.
+        #
+        # @param value [Object]
+        # @return [Object]
+        def serialize(value)
+          new.serialize(value)
+        end
+
+        # Validates the value using the default validator.
+        #
+        # @param value [Object] the value to check
+        # @param options [Hash] validation rules (e.g., min, max, format)
+        # @param context [Symbol, String] label for error reporting
+        # @return [void]
+        def validate!(value, options: {}, context: {})
+          new.validate!(value, options: options, context: context)
+        end
+
+        private
+
+        # Builds a default validator from the instance itself.
+        #
+        # @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
+      end
+
+      # Deserializes the value. Override in subclasses to coerce input (e.g., `"123"` → `123`).
+      #
+      # @param value [Object]
+      # @return [Object]
+      def deserialize(value)
+        value
+      end
+
+      # Serializes the value. Override in subclasses if the output should be transformed.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def serialize(value)
+        value
+      end
+
+      # Validates the value. No-op by default.
+      #
+      # @param value [Object]
+      # @param options [Hash]
+      # @param context [Symbol, String]
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        # override in subclasses
+      end
+
+      protected
+
+      # Emits or raises a type error depending on configuration.
+      #
+      # @param type [Symbol]
+      # @param value [Object, nil]
+      # @return [void]
+      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
+    end
+  end
+end

data/lib/castkit/types/boolean.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../validators/boolean_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:boolean` attributes.
+    #
+    # Converts strings or numbers into boolean values based on common truthy/falsy indicators.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `boolean :is_active`
+    class Boolean < Base
+      # Deserializes the input into a boolean value.
+      #
+      # Accepts:
+      # - `"true"`, `"1"` (case-insensitive) → `true`
+      # - `"false"`, `"0"` (case-insensitive) → `false`
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      # @raise [Castkit::TypeError] if the value cannot be coerced to a boolean
+      def deserialize(value)
+        value
+      end
+
+      # Serializes the boolean value (pass-through).
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      def serialize(value)
+        value
+      end
+
+      # Validates the Boolean value.
+      #
+      # @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::BooleanValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end