castkit 0.3.0 → 0.3.1

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

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

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.
       #
@@ -104,7 +104,11 @@ module Castkit
         # @return [Object, nil]
         def resolve_input_value(input, attribute)
           attribute.key_path(with_aliases: true).each do |path|
-            value = path.reduce(input) { |memo, key| memo.is_a?(Hash) ? memo[key] : nil }
+            value = path.reduce(input) do |memo, key|
+              next memo unless memo.is_a?(Hash)
+
+              memo.key?(key) ? memo[key] : memo[key.to_s]
+            end
             return value unless value.nil?
           end
 

data/lib/castkit/{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.

data/lib/castkit/dsl/data_object.rb

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

data/lib/castkit/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Castkit
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 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.
 #

data/lib/generators/attribute.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating Castkit attribute definitions.
+    #
+    # Generates a class inheriting from `Castkit::Attributes::Definition`
+    # and an optional spec file.
+    #
+    # Example:
+    #   $ castkit generate attribute OptionalString required:false default:"N/A"
+    #
+    # This will generate:
+    # - lib/castkit/attributes/optional_string.rb
+    # - spec/castkit/attributes/optional_string_spec.rb
+    #
+    # @see Castkit::Generators::Base
+    class Attribute < Castkit::Generators::Base
+      component :attribute
+
+      argument :type,
+               type: :string,
+               desc: "The base type (e.g., string, integer)"
+
+      private
+
+      # @return [Hash] configuration passed into templates
+      def config
+        super.merge(
+          type: type.first.gsub(/^:/, "")
+        )
+      end
+    end
+  end
+end