castkit 0.3.0 → 0.4.0

data/lib/castkit/data_object.rb

@@ -5,14 +5,7 @@ require_relative "error"
 require_relative "attribute"
 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/plugins"
-require_relative "ext/data_object/serialization"
+require_relative "dsl/data_object"
 
 module Castkit
   # Base class for defining declarative, typed data transfer objects (DTOs).
@@ -30,25 +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
-    extend Castkit::Ext::DataObject::Plugins
-
-    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?
@@ -99,20 +76,23 @@ module Castkit
     end
 
     # @return [Hash{Symbol => Object}] The raw data provided during instantiation.
-    attr_reader :__raw
+    cattri :__raw, nil, expose: :read
 
     # @return [Hash{Symbol => Object}] Undefined attributes provided during instantiation.
-    attr_reader :unknown_attributes
+    cattri :unknown_attributes, nil, expose: :read
 
     # Initializes the DTO from a hash of attributes.
     #
     # @param data [Hash] raw input hash
     # @raise [Castkit::DataObjectError] if strict mode is enabled and unknown keys are present
     def initialize(data = {})
-      @__raw = data.dup.freeze
+      super()
+
+      cattri_variable_set(:__raw, data.dup.freeze)
       data = unwrap_root(data)
 
-      @unknown_attributes = data.reject { |key, _| self.class.attributes.key?(key.to_sym) }.freeze
+      cattri_variable_set(:unknown_attributes,
+                          data.reject { |key, _| self.class.attributes.key?(key.to_sym) }.freeze)
 
       validate_data!(data)
       deserialize_attributes!(data)

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

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.
       #

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.
       #
@@ -49,7 +49,7 @@ module Castkit
             next if value.nil? && attribute.optional?
 
             value = deserialize_attribute_value!(attribute, value)
-            instance_variable_set("@#{attribute.field}", value)
+            assign_attribute_value!(attribute, value)
           end
         end
 
@@ -104,13 +104,34 @@ 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
 
           nil
         end
 
+        # Stores a deserialized value using Cattri's internal store when available.
+        #
+        # @param attribute [Castkit::Attribute]
+        # @param value [Object]
+        # @return [void]
+        def assign_attribute_value!(attribute, value)
+          if respond_to?(:cattri_variable_set, true)
+            cattri_variable_set(
+              attribute.field,
+              value,
+              final: attribute.options[:final]
+            )
+          else
+            instance_variable_set("@#{attribute.field}", value)
+          end
+        end
+
         # Resolves root-wrapped and unwrapped data.
         #
         # @param data [Hash]

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DSL
+    module DataObject
+      # Provides opt-in attribute introspection for data objects using Cattri's registry
+      # without overriding Castkit's attribute DSL.
+      module Introspection
+        # Enables introspection helpers on the including class.
+        #
+        # @return [void]
+        def enable_cattri_introspection!
+          extend IntrospectionHelpers
+
+          @cattri_attribute_registry = nil
+        end
+
+        # Class-level helpers that read from Cattri's attribute registry but do not
+        # override Castkit's attribute builder.
+        module IntrospectionHelpers
+          def attribute_defined?(name)
+            !!cattri_attribute(name)
+          end
+
+          def attribute_definitions(with_ancestors: false)
+            cattri_attribute_registry.defined_attributes(with_ancestors: with_ancestors)
+          end
+
+          def attribute_methods
+            cattri_attribute_registry.defined_attributes(with_ancestors: true).transform_values do |attribute|
+              Set.new(attribute.allowed_methods)
+            end
+          end
+
+          def attribute_source(name)
+            cattri_attribute(name)&.defined_in
+          end
+
+          private
+
+          def cattri_attribute_registry
+            @cattri_attribute_registry ||= attribute_registry
+          end
+
+          def cattri_attribute(name)
+            cattri_attribute_registry.defined_attributes(with_ancestors: true)[name.to_sym]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Castkit
-  module Ext
+  module DSL
     module DataObject
       # Provides plugin support for DataObject classes.
       #

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.
@@ -38,7 +38,10 @@ module Castkit
           # @param value [Boolean, nil]
           # @return [Boolean]
           def ignore_blank(value = nil)
-            @ignore_blank = value.nil? || value
+            return (@ignore_blank = true) if value.nil? && !defined?(@ignore_blank)
+            return @ignore_blank if value.nil?
+
+            @ignore_blank = value
           end
         end
 

data/lib/castkit/dsl/data_object.rb

@@ -0,0 +1,65 @@
+# 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"
+require_relative "data_object/introspection"
+
+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.include(Cattri)
+
+        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.extend(Castkit::DSL::DataObject::Introspection)
+
+        base.include(Castkit::DSL::DataObject::Serialization)
+        base.include(Castkit::DSL::DataObject::Deserialization)
+      end
+    end
+  end
+end

data/lib/castkit/error.rb

@@ -3,8 +3,10 @@
 module Castkit
   # Base error class for all Castkit-related exceptions.
   class Error < StandardError
+    include Cattri
+
     # @return [Hash, Object, nil] contextual data to aid in debugging
-    attr_reader :context
+    cattri :context, nil, expose: :read
 
     # Initializes a Castkit error.
     #
@@ -12,7 +14,8 @@ module Castkit
     # @param context [Object, String, nil] optional data object or hash for context
     def initialize(msg, context: nil)
       super(msg)
-      @context = context
+
+      cattri_variable_set(:context, context, final: true)
     end
   end
 
@@ -44,11 +47,12 @@ module Castkit
 
   # Raised during contract validation.
   class ContractError < Error
-    attr_reader :errors
+    cattri :errors, {}, expose: :read
 
     def initialize(msg, context: nil, errors: nil)
       super(msg, context: context)
-      @errors = errors || {}
+
+      cattri_variable_set(:errors, errors || {})
     end
   end
 end

data/lib/castkit/plugins.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cattri"
+
 module Castkit
   # Internal registry for Castkit plugin modules.
   #
@@ -19,9 +21,16 @@ module Castkit
   #     enable_plugins :custom, :oj
   #   end
   module Plugins
-    @registered_plugins = {}
+    include Cattri
 
     class << self
+      include Cattri
+      extend Cattri::Dsl
+      extend Cattri::ClassMethods
+      extend Cattri::Visibility
+
+      cattri :registered_plugins, {}, expose: :read_write
+
       # Activates one or more plugins on the given class.
       #
       # Each plugin module is included into the class. If the module responds to `setup!`,
@@ -58,7 +67,7 @@ module Castkit
       # @return [Module] the plugin module
       # @raise [Castkit::Error] if no plugin is found
       def lookup!(name)
-        @registered_plugins[name.to_sym] ||
+        registered_plugins[name.to_sym] ||
           const_get(Castkit::Inflector.pascalize(name.to_s), false)
       rescue NameError
         raise Castkit::Error,
@@ -75,7 +84,7 @@ module Castkit
       # @param plugin [Module] the plugin module to register
       # @return [void]
       def register(name, plugin)
-        @registered_plugins[name] = plugin
+        registered_plugins[name.to_sym] = plugin
       end
     end
   end

data/lib/castkit/serializers/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "set"
+require "cattri"
 
 module Castkit
   module Serializers
@@ -21,6 +22,8 @@ module Castkit
     #
     #   CustomSerializer.call(user_dto)
     class Base
+      include Cattri
+
       class << self
         # Entrypoint for serializing an object.
         #
@@ -33,7 +36,7 @@ module Castkit
       end
 
       # @return [Castkit::DataObject] the object being serialized
-      attr_reader :object
+      cattri :object, nil, expose: :read
 
       protected
 
@@ -47,15 +50,17 @@ module Castkit
       private
 
       # @return [Set<Integer>] a set of visited object IDs to detect circular references
-      attr_reader :visited
+      cattri :visited, nil, expose: :read
 
       # Initializes the serializer instance.
       #
       # @param object [Castkit::DataObject]
       # @param visited [Set, nil]
       def initialize(object, visited: nil)
-        @object = object
-        @visited = visited || Set.new
+        super()
+
+        cattri_variable_set(:object, object)
+        cattri_variable_set(:visited, visited || Set.new)
       end
 
       # Subclasses must override this method to implement serialization logic.

data/lib/castkit/serializers/default_serializer.rb

@@ -11,13 +11,13 @@ module Castkit
     # and respects the class-level serialization configuration.
     class DefaultSerializer < Castkit::Serializers::Base
       # @return [Hash{Symbol => Castkit::Attribute}] the attributes to serialize
-      attr_reader :attributes
+      cattri :attributes, nil, expose: :read
 
       # @return [Hash{Symbol => Object}] unrecognized attributes captured during deserialization
-      attr_reader :unknown_attributes
+      cattri :unknown_attributes, nil, expose: :read
 
       # @return [Hash] serialization config flags like :root, :ignore_nil, :allow_unknown
-      attr_reader :options
+      cattri :options, nil, expose: :read
 
       # Serializes the object to a hash.
       #
@@ -41,13 +41,13 @@ module Castkit
         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
-        }
+        cattri_variable_set(:attributes, object.class.attributes.freeze)
+        cattri_variable_set(:unknown_attributes, object.unknown_attributes.freeze)
+        cattri_variable_set(:options, {
+                              root: object.class.root,
+                              ignore_nil: object.class.ignore_nil || false,
+                              allow_unknown: object.class.allow_unknown || false
+                            })
       end
 
       # Serializes all defined attributes.

data/lib/castkit/types/base.rb

@@ -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
 
@@ -76,6 +77,26 @@ module Castkit
             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`).

data/lib/castkit/validators/boolean_validator.rb

@@ -16,15 +16,15 @@ module Castkit
     #   validator.call("true", _options: {}, context: :enabled) # => true
     #   validator.call("0", _options: {}, context: :enabled)    # => false
     #   validator.call("nope", _options: {}, context: :enabled) # raises Castkit::AttributeError
-    class BooleanValidator
+    class BooleanValidator < Castkit::Validators::Base
       # Validates the Boolean value.
       #
       # @param value [Object] the input to validate
-      # @param _options [Hash] unused, provided for consistency with other validators
+      # @param options [Hash] unused, provided for consistency with other validators
       # @param context [Symbol, String] the attribute name or path for error messages
       # @return [Boolean]
       # @raise [Castkit::AttributeError] if the value is not a recognizable boolean
-      def call(value, _options:, context:)
+      def call(value, options:, context:) # rubocop:disable Lint/UnusedMethodArgument
         case value.to_s.downcase
         when "true", "1"
           true

data/lib/castkit/validators/collection_validator.rb

@@ -17,11 +17,11 @@ module Castkit
       # Validates that the value is an Array.
       #
       # @param value [Object] the value to validate
-      # @param _options [Hash] unused, for interface consistency
+      # @param options [Hash] unused, for interface consistency
       # @param context [Symbol, String] the field or context for error messaging
       # @return [void]
       # @raise [Castkit::AttributeError] if value is not an Array
-      def call(value, _options:, context:)
+      def call(value, options:, context:) # rubocop:disable Lint/UnusedMethodArgument
         type_error!(:array, value, context: context) unless value.is_a?(::Array)
       end
     end

data/lib/castkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Castkit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/castkit.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "castkit/version"
-require_relative "castkit/attribute"
-require_relative "castkit/contract"
-require_relative "castkit/data_object"
+require_relative "castkit/castkit"
 
 # Castkit is a lightweight, type-safe data object system for Ruby.
 #