castkit 0.2.0 → 0.3.0

data/lib/castkit/cli.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "cli/main"
+
+module Castkit
+  # Entrypoint for Castkit’s command-line interface.
+  #
+  # Delegates to the `Castkit::CLI::Main` Thor class, which defines all CLI commands.
+  #
+  # @example Executing from a binstub
+  #   Castkit::CLI.start(ARGV)
+  #
+  module CLI
+    # Starts the Castkit CLI.
+    #
+    # @param args [Array<String>] the command-line arguments
+    # @param kwargs [Hash] additional keyword arguments passed to Thor
+    # @return [void]
+    def self.start(*args, **kwargs)
+      Castkit::CLI::Main.start(*args, **kwargs)
+    end
+  end
+end

data/lib/castkit/configuration.rb

@@ -10,14 +10,14 @@ module Castkit
   class Configuration
     # Default mapping of primitive type definitions.
     #
-    # @return [Hash{Symbol => Castkit::Types::Generic}]
+    # @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::Generic.new,
+      hash: Castkit::Types::Base.new,
       integer: Castkit::Types::Integer.new,
       string: Castkit::Types::String.new
     }.freeze
@@ -36,9 +36,15 @@ module Castkit
       uuid: :string
     }.freeze
 
-    # @return [Hash{Symbol => Castkit::Types::Generic}] registered types
+    # @return [Hash{Symbol => Castkit::Types::Base}] registered types
     attr_reader :types
 
+    # 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 values should be validated before deserializing, e.g. true -> "true"
     # @return [Boolean]
     attr_accessor :enforce_typing
@@ -79,6 +85,7 @@ module Castkit
       @raise_type_errors = true
       @enable_warnings = true
       @strict_by_default = true
+      @default_plugins = []
 
       apply_type_aliases!
     end
@@ -86,17 +93,17 @@ module Castkit
     # Registers a new type definition.
     #
     # @param type [Symbol] the symbolic type name (e.g., :uuid)
-    # @param klass [Class<Castkit::Types::Generic>] the class to register
+    # @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 Generic
+    # @raise [Castkit::TypeError] if the type class is invalid or not a subclass of Castkit::Types::Base
     # @return [void]
     def register_type(type, klass, aliases: [], override: false)
       type = type.to_sym
       return if types.key?(type) && !override
 
       instance = klass.new
-      unless instance.is_a?(Castkit::Types::Generic)
-        raise Castkit::TypeError, "Expected subclass of Castkit::Types::Generic for `#{type}`"
+      unless instance.is_a?(Castkit::Types::Base)
+        raise Castkit::TypeError, "Expected subclass of Castkit::Types::Base for `#{type}`"
       end
 
       types[type] = instance
@@ -107,10 +114,26 @@ module Castkit
       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 type handler for a given type symbol.
     #
     # @param type [Symbol]
-    # @return [Castkit::Types::Generic]
+    # @return [Castkit::Types::Base]
     # @raise [Castkit::TypeError] if the type is not registered
     def fetch_type(type)
       @types.fetch(type.to_sym) do

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

@@ -14,7 +14,7 @@ module Castkit
     # ephemeral or reusable contract classes.
     #
     # @example Subclassing directly
-    #   class MyContract < Castkit::Contract::Generic
+    #   class MyContract < Castkit::Contract::Base
     #     string :id
     #     integer :count, required: false
     #   end
@@ -30,7 +30,7 @@ module Castkit
     #   UserContract.validate!(id: "123")
     #
     # @see Castkit::Contract.build
-    class Generic
+    class Base
       extend Castkit::Core::Config
       extend Castkit::Core::AttributeTypes
       extend Castkit::Core::Registerable
@@ -69,7 +69,6 @@ module Castkit
         # @return [Castkit::Contract::Result]
         def validate(input)
           validate!(input)
-          Castkit::Contract::Result.new(definition[:name].to_s, input)
         rescue Castkit::ContractError => e
           Castkit::Contract::Result.new(definition[:name].to_s, input, errors: e.errors)
         end
@@ -81,6 +80,7 @@ module Castkit
         # @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.
@@ -88,7 +88,7 @@ module Castkit
         # @return [Hash]
         def definition
           @definition ||= {
-            name: :ephemeral_contract,
+            name: :ephemeral,
             attributes: {}
           }
         end
@@ -108,7 +108,7 @@ module Castkit
         # @param source [Castkit::DataObject, nil]
         # @param block [Proc, nil]
         # @return [Hash]
-        def define(name = :ephemeral_contract, source = nil, validation_rules: {}, &block)
+        def define(name = :ephemeral, source = nil, validation_rules: {}, &block)
           validate_definition!(source, &block)
 
           if source

data/lib/castkit/contract/result.rb

@@ -52,10 +52,10 @@ module Castkit
       #
       # @return [String]
       def to_s
-        return "[Castkit] Contract validation passed for #{contract.inspect}" if success?
+        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.inspect}:\n#{parsed_errors}"
+        "[Castkit] Contract validation failed for #{contract}:\n#{parsed_errors}"
       end
 
       # @return [Hash{Symbol => Object}] the input validation and error hash

data/lib/castkit/contract.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "contract/generic"
+require_relative "contract/base"
 
 module Castkit
   # Castkit::Contract provides a lightweight mechanism for defining and validating
@@ -31,9 +31,9 @@ module Castkit
       # @param name [String, Symbol, nil] Optional name for the contract.
       # @param validation_rules [Hash] Optional validation rules (e.g., `strict: true`).
       # @yield Optional DSL block to define attributes.
-      # @return [Class<Castkit::Contract::Generic>]
+      # @return [Class<Castkit::Contract::Base>]
       def build(name = nil, **validation_rules, &block)
-        klass = Class.new(Castkit::Contract::Generic)
+        klass = Class.new(Castkit::Contract::Base)
         klass.send(:define, name, nil, validation_rules: validation_rules, &block)
 
         klass
@@ -52,12 +52,12 @@ module Castkit
       #
       # @param source [Class<Castkit::DataObject>] the DataObject to generate the contract from
       # @param as [String, Symbol, nil] Optional custom name to use for the contract
-      # @return [Class<Castkit::Contract::Generic>]
+      # @return [Class<Castkit::Contract::Base>]
       def from_dataobject(source, as: nil)
         name = as || Castkit::Inflector.unqualified_name(source)
         name = Castkit::Inflector.underscore(name).to_sym
 
-        klass = Class.new(Castkit::Contract::Generic)
+        klass = Class.new(Castkit::Contract::Base)
         klass.send(:define, name, source, validation_rules: source.validation_rules)
 
         klass

data/lib/castkit/data_object.rb

@@ -3,7 +3,7 @@
 require "json"
 require_relative "error"
 require_relative "attribute"
-require_relative "default_serializer"
+require_relative "serializers/default_serializer"
 require_relative "contract/validator"
 require_relative "core/config"
 require_relative "core/attributes"
@@ -11,6 +11,7 @@ require_relative "core/attribute_types"
 require_relative "core/registerable"
 require_relative "ext/data_object/contract"
 require_relative "ext/data_object/deserialization"
+require_relative "ext/data_object/plugins"
 require_relative "ext/data_object/serialization"
 
 module Castkit
@@ -34,6 +35,7 @@ module Castkit
     extend Castkit::Core::AttributeTypes
     extend Castkit::Core::Registerable
     extend Castkit::Ext::DataObject::Contract
+    extend Castkit::Ext::DataObject::Plugins
 
     include Castkit::Ext::DataObject::Serialization
     include Castkit::Ext::DataObject::Deserialization
@@ -56,12 +58,14 @@ module Castkit
 
       # Gets or sets the serializer class to use for instances of this object.
       #
-      # @param value [Class<Castkit::Serializer>, nil]
-      # @return [Class<Castkit::Serializer>, nil]
-      # @raise [ArgumentError] if value does not inherit from Castkit::Serializer
+      # @param value [Class<Castkit::Serializers::Base>, nil]
+      # @return [Class<Castkit::Serializers::Base>, nil]
+      # @raise [ArgumentError] if value does not inherit from Castkit::Serializers::Base
       def serializer(value = nil)
         if value
-          raise ArgumentError, "Serializer must inherit from Castkit::Serializer" unless value < Castkit::Serializer
+          unless value < Castkit::Serializers::Base
+            raise ArgumentError, "Serializer must inherit from Castkit::Serializers::Base"
+          end
 
           @serializer = value
         else
@@ -154,9 +158,9 @@ module Castkit
 
     # Returns the serializer instance or default for this object.
     #
-    # @return [Class<Castkit::Serializer>]
+    # @return [Class<Castkit::Serializers::Base>]
     def serializer
-      @serializer ||= self.class.serializer || Castkit::DefaultSerializer
+      @serializer ||= self.class.serializer || Castkit::Serializers::DefaultSerializer
     end
 
     # Returns false if self.class.allow_unknown == true, otherwise the value of self.class.strict.

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

@@ -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/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/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