castkit 0.2.0 → 0.3.1

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}

@@ -2,7 +2,6 @@
 
 require_relative "../core/config"
 require_relative "../core/attribute_types"
-require_relative "../core/registerable"
 require_relative "result"
 
 module Castkit
@@ -14,7 +13,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,26 +29,15 @@ 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
 
       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.
@@ -69,7 +57,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 +68,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 +76,7 @@ module Castkit
         # @return [Hash]
         def definition
           @definition ||= {
-            name: :ephemeral_contract,
+            name: :ephemeral,
             attributes: {}
           }
         end
@@ -108,7 +96,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/validator.rb

@@ -188,7 +188,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/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/core/attributes.rb

@@ -4,45 +4,51 @@ module Castkit
   module Core
     # Provides DSL and implementation for declaring attributes within a Castkit::DataObject.
     #
-    # Includes support for regular, composite, transient, readonly/writeonly, and grouped attribute definitions.
+    # Supports reusable attribute definitions, transient fields, composite readers, and
+    # grouped declarations such as `readonly`, `optional`, and `transient` blocks.
+    #
+    # This module is included into `Castkit::DataObject` and handles attribute registration,
+    # accessor generation, and typed writing behavior.
     module Attributes
-      # Declares an attribute with the given type and options.
+      # Declares an attribute on the data object.
       #
+      # Accepts either inline options or a reusable attribute definition (`using` or `definition`).
       # If `:transient` is true, defines only standard accessors and skips serialization logic.
       #
-      # @param field [Symbol]
-      # @param type [Symbol, Class]
-      # @param options [Hash]
+      # @param field [Symbol] the attribute name
+      # @param type [Symbol, Class] the attribute's declared type
+      # @param definition [Hash, nil] an optional pre-built definition object (`{ type:, options: }`)
+      # @param using [Castkit::Attributes::Base, nil] an optional class-based definition (`.definition`)
+      # @param options [Hash] additional options like `default`, `access`, `required`, etc.
       # @return [void]
-      # @raise [Castkit::DataObjectError] if the attribute is already defined
-      def attribute(field, type, **options)
+      # @raise [Castkit::DataObjectError] if attribute already defined or type mismatch
+      def attribute(field, type = nil, definition = nil, using: nil, **options)
         field = field.to_sym
         raise Castkit::DataObjectError, "Attribute '#{field}' already defined" if attributes.key?(field)
 
-        options = build_options(options)
+        type, options = use_definition(field, definition || using&.definition, type, options)
         return define_attribute(field, type, **options) unless options[:transient]
 
         attr_accessor field
       end
 
-      # Declares a computed (composite) attribute.
+      # Declares a composite (computed) attribute.
       #
-      # The provided block defines the read behavior.
-      #
-      # @param field [Symbol]
-      # @param type [Symbol, Class]
-      # @param options [Hash]
-      # @yieldreturn [Object] evaluated composite value
+      # @param field [Symbol] the name of the attribute
+      # @param type [Symbol, Class] the attribute type
+      # @param options [Hash] additional attribute options
+      # @yieldreturn [Object] the value to return when the reader is called
+      # @return [void]
       def composite(field, type, **options, &block)
         attribute(field, type, **options, composite: true)
         define_method(field, &block)
       end
 
-      # Declares a group of transient attributes within the given block.
+      # Declares a group of transient attributes within a block.
       #
-      # These attributes are not serialized or included in `to_h`.
+      # These attributes are excluded from serialization (`to_h`) and not stored.
       #
-      # @yield defines one or more transient attributes via `attribute`
+      # @yield a block containing `attribute` calls
       # @return [void]
       def transient(&block)
         @__transient_context = true
@@ -51,61 +57,97 @@ module Castkit
         @__transient_context = nil
       end
 
-      # Declares a group of readonly attributes within the given block.
+      # Declares a group of readonly attributes (accessible for read only).
       #
-      # @param options [Hash] shared options for attributes inside the block
-      # @yield defines attributes with `access: [:read]`
+      # @param options [Hash] shared options for all attributes inside the block
+      # @yield a block containing `attribute` calls
       # @return [void]
       def readonly(**options, &block)
         with_access([:read], options, &block)
       end
 
-      # Declares a group of writeonly attributes within the given block.
+      # Declares a group of writeonly attributes (accessible for write only).
       #
-      # @param options [Hash] shared options for attributes inside the block
-      # @yield defines attributes with `access: [:write]`
+      # @param options [Hash] shared options for all attributes inside the block
+      # @yield a block containing `attribute` calls
       # @return [void]
       def writeonly(**options, &block)
         with_access([:write], options, &block)
       end
 
-      # Declares a group of required attributes within the given block.
+      # Declares a group of required attributes.
       #
-      # @param options [Hash] shared options for attributes inside the block
-      # @yield defines attributes with `required: true`
+      # @param options [Hash] shared options for all attributes inside the block
+      # @yield a block containing `attribute` calls
       # @return [void]
       def required(**options, &block)
         with_required(true, options, &block)
       end
 
-      # Declares a group of optional attributes within the given block.
+      # Declares a group of optional attributes.
       #
-      # @param options [Hash] shared options for attributes inside the block
-      # @yield defines attributes with `required: false`
+      # @param options [Hash] shared options for all attributes inside the block
+      # @yield a block containing `attribute` calls
       # @return [void]
       def optional(**options, &block)
         with_required(false, options, &block)
       end
 
-      # Returns all declared non-transient attributes.
+      # Returns all non-transient attributes defined on the class.
       #
       # @return [Hash{Symbol => Castkit::Attribute}]
       def attributes
         @attributes ||= {}
       end
 
-      # Alias for `composite`
+      def inherited(subclass)
+        super
+
+        parent_attributes = instance_variable_get(:@attributes)
+        subclass.instance_variable_set(:@attributes, parent_attributes.dup) if parent_attributes
+      end
+
+      # Alias for {#attribute}
+      #
+      # @see #attribute
+      alias attr attribute
+
+      # Alias for {#composite}
       #
       # @see #composite
       alias property composite
 
       private
 
-      # Defines a full attribute, including accessor methods and type logic.
+      # Applies a reusable definition to the current attribute call.
+      #
+      # Ensures the declared type matches and merges options.
+      #
+      # @param field [Symbol] the attribute name
+      # @param definition [Hash{Symbol => Object}, nil]
+      # @param type [Symbol, Class]
+      # @param options [Hash]
+      # @return [Array<(Symbol, Hash)>] the final type and options
+      # @raise [Castkit::DataObjectError] if type mismatch occurs
+      def use_definition(field, definition, type, options)
+        type ||= definition&.fetch(:type, nil)
+        raise Castkit::AttributeError, "Attribute `#{field}  has no type" if type.nil?
+
+        if definition && type != definition[:type]
+          raise Castkit::AttributeError,
+                "Attribute `#{field}` type mismatch: expected #{definition[:type].inspect}, got #{type.inspect}"
+        end
+
+        options = definition[:options].merge(options) if definition
+        [type, build_options(options)]
+      end
+
+      # Instantiates and stores a Castkit::Attribute, defining accessors as needed.
       #
       # @param field [Symbol]
       # @param type [Symbol, Class]
       # @param options [Hash]
+      # @return [void]
       def define_attribute(field, type, **options)
         attribute = Castkit::Attribute.new(field, type, **options)
         attributes[field] = attribute
@@ -121,13 +163,14 @@ module Castkit
         end
       end
 
-      # Defines a type-aware writer method for the attribute.
+      # Defines a writer method that enforces type coercion.
       #
       # @param field [Symbol]
       # @param attribute [Castkit::Attribute]
+      # @return [void]
       def define_typed_writer(field, attribute)
         define_method("#{field}=") do |value|
-          deserialized_value = Castkit.type_caster(attribute.type).call(
+          deserialized_value = Castkit.type_caster(attribute.type.to_sym).call(
             value,
             options: attribute.options,
             context: attribute.field
@@ -137,11 +180,12 @@ module Castkit
         end
       end
 
-      # Applies scoped access control to all attributes declared in the given block.
+      # Applies a temporary `access` context to all attributes within a block.
       #
-      # @param access [Array<Symbol>] e.g., [:read] or [:write]
+      # @param access [Array<Symbol>] e.g. `[:read]` or `[:write]`
       # @param options [Hash]
-      # @yield the block containing one or more `attribute` calls
+      # @yield the block containing `attribute` calls
+      # @return [void]
       def with_access(access, options = {}, &block)
         @__access_context = access
         @__block_options = options
@@ -151,11 +195,12 @@ module Castkit
         @__block_options = nil
       end
 
-      # Applies scoped required/optional flag to all attributes declared in the given block.
+      # Applies a temporary `required` context to all attributes within a block.
       #
       # @param flag [Boolean]
       # @param options [Hash]
-      # @yield the block containing one or more `attribute` calls
+      # @yield the block containing `attribute` calls
+      # @return [void]
       def with_required(flag, options = {}, &block)
         @__required_context = flag
         @__block_options = options
@@ -165,12 +210,10 @@ module Castkit
         @__block_options = nil
       end
 
-      # Builds effective options for the current attribute definition.
-      #
-      # Merges scoped flags like `required`, `access`, and `transient` if present.
+      # Merges any current context flags (e.g., required, access) into the options hash.
       #
       # @param options [Hash]
-      # @return [Hash]
+      # @return [Hash] effective options for the attribute
       def build_options(options)
         base = @__block_options || {}
         base = base.merge(required: @__required_context) unless @__required_context.nil?

data/lib/castkit/data_object.rb

@@ -3,15 +3,9 @@
 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"
-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/serialization"
+require_relative "dsl/data_object"
 
 module Castkit
   # Base class for defining declarative, typed data transfer objects (DTOs).
@@ -29,24 +23,9 @@ module Castkit
   #   user = UserDto.new(name: "Alice", age: 30)
   #   user.to_json #=> '{"name":"Alice","age":30}'
   class DataObject
-    extend Castkit::Core::Config
-    extend Castkit::Core::Attributes
-    extend Castkit::Core::AttributeTypes
-    extend Castkit::Core::Registerable
-    extend Castkit::Ext::DataObject::Contract
-
-    include Castkit::Ext::DataObject::Serialization
-    include Castkit::Ext::DataObject::Deserialization
+    include Castkit::DSL::DataObject
 
     class << self
-      # Registers the current class under `Castkit::DataObjects`.
-      #
-      # @param as [String, Symbol, nil] The constant name to use (PascalCase). Defaults to class name or "Anonymous".
-      # @return [Class] the registered dataobject class
-      def register!(as: nil)
-        super(namespace: :dataobjects, as: as)
-      end
-
       def build(&block)
         klass = Class.new(self)
         klass.class_eval(&block) if block_given?
@@ -56,12 +35,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 +135,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 → dsl}/attribute/access.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module Ext
+  module DSL
     module Attribute
       # Provides access control helpers for attributes.
       #

data/lib/castkit/{ext → dsl}/attribute/error_handling.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module Ext
+  module DSL
     module Attribute
       # Provides centralized handling of attribute casting and validation errors.
       #

data/lib/castkit/{ext → dsl}/attribute/options.rb

@@ -3,7 +3,7 @@
 require_relative "../../data_object"
 
 module Castkit
-  module Ext
+  module DSL
     module Attribute
       # Provides access to normalized attribute options and helper predicates.
       #

data/lib/castkit/{ext → dsl}/attribute/validation.rb

@@ -4,13 +4,13 @@ require_relative "error_handling"
 require_relative "options"
 
 module Castkit
-  module Ext
+  module DSL
     module Attribute
       # Provides validation logic for attribute configuration.
       #
       # These checks are typically performed at attribute initialization to catch misconfigurations early.
       module Validation
-        include Castkit::Ext::Attribute::ErrorHandling
+        include Castkit::DSL::Attribute::ErrorHandling
 
         private
 
@@ -58,7 +58,7 @@ module Castkit
         # @raise [Castkit::AttributeError] if any access mode is invalid and enforcement is enabled
         def validate_access!
           access.each do |mode|
-            next if Castkit::Ext::Attribute::Options::DEFAULT_OPTIONS[:access].include?(mode)
+            next if Castkit::Attributes::Options::DEFAULTS[:access].include?(mode)
 
             handle_error(:access, mode: mode, context: to_h)
           end