rbdantic 0.1.0

data/lib/rbdantic/json_schema/defs_registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Rbdantic
+  module JsonSchema
+    # Registry for tracking model schemas during generation
+    # Used to implement $defs/$ref pattern for circular references
+    class DefsRegistry
+      def initialize
+        @defs = {}
+        @being_processed = Set.new  # Currently being processed (for cycle detection)
+        @referenced = Set.new
+      end
+
+      def key_for(model_class)
+        model_class.name || "AnonymousModel_#{model_class.object_id}"
+      end
+
+      # Check if a model is currently being processed (for cycle detection)
+      # @param model_class [Class] the model class
+      # @return [Boolean]
+      def being_processed?(model_class)
+        @being_processed.include?(model_class)
+      end
+
+      # Mark a model as being processed
+      # @param model_class [Class] the model class
+      def mark_processing(model_class)
+        @being_processed.add(model_class)
+      end
+
+      # Register a model's completed schema and return its key
+      # @param model_class [Class] the model class
+      # @param schema [Hash] the generated schema
+      # @return [String] the key used in $defs
+      def register(model_class, schema)
+        key = key_for(model_class)
+        @defs[key] = schema
+        @being_processed.delete(model_class)  # No longer being processed
+        key
+      end
+
+      # Check if a model's schema is registered (completed)
+      # @param model_class [Class] the model class
+      # @return [Boolean]
+      def registered?(model_class)
+        @defs.key?(key_for(model_class))
+      end
+
+      def referenced?(model_class)
+        @referenced.include?(key_for(model_class))
+      end
+
+      # Generate a $ref for a registered model
+      # @param model_class [Class] the model class
+      # @return [Hash] the $ref object
+      def ref_for(model_class)
+        key = key_for(model_class)
+        @referenced.add(key)
+        { "$ref" => "#/$defs/#{key}" }
+      end
+
+      # Get the $defs hash for inclusion in top-level schema
+      # @return [Hash, nil] the defs hash or nil if empty
+      def defs_hash(except: nil)
+        defs = except ? @defs.reject { |key, _| key == key_for(except) } : @defs
+        defs.empty? ? nil : defs
+      end
+
+      # Clear the registry (for fresh generation)
+      def clear
+        @defs.clear
+        @being_processed.clear
+        @referenced.clear
+      end
+    end
+  end
+end

data/lib/rbdantic/json_schema/generator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "defs_registry"
+
+module Rbdantic
+  module JsonSchema
+    # Generate JSON Schema from model class
+    class Generator
+      # JSON Schema version
+      SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema"
+
+      # Generate schema for a model class
+      # @param model_class [Class] the model class
+      # @param options [Hash] generation options
+      # @option options [String] :title optional title (defaults to class name)
+      # @option options [String] :description optional description
+      # @option options [String] :schema_id optional $id for the schema
+      # @option options [Boolean] :include_defaults include default values in schema
+      # @option options [DefsRegistry] :defs_registry registry for $defs/$ref pattern
+      # @return [Hash] JSON Schema
+      def self.generate(model_class, **options)
+        new(model_class, **options).generate
+      end
+
+      def initialize(model_class, title: nil, description: nil, schema_id: nil,
+                     include_defaults: true, top_level: true, defs_registry: nil, by_alias: false)
+        @model_class = model_class
+        @title = title || model_class.name
+        @description = description
+        @schema_id = schema_id
+        @include_defaults = include_defaults
+        @top_level = top_level
+        @by_alias = by_alias
+        # Use provided registry or create one at top level
+        @defs_registry = defs_registry || (top_level ? DefsRegistry.new : nil)
+      end
+
+      def generate
+        # Handle circular references - if being processed, return $ref
+        if @defs_registry && @defs_registry.being_processed?(@model_class)
+          return @defs_registry.ref_for(@model_class)
+        end
+
+        schema = {}
+
+        # Only add $schema and $id at top level
+        if @top_level
+          schema["$schema"] = SCHEMA_VERSION
+          schema["$id"] = @schema_id if @schema_id
+        end
+
+        schema["type"] = "object"
+
+        # Add optional metadata
+        schema["title"] = @title if @title && @top_level
+        schema["description"] = @description if @description
+
+        # Mark as being processed before processing fields (for cycle detection)
+        if @defs_registry
+          @defs_registry.mark_processing(@model_class)
+        end
+
+        # Generate properties
+        properties = {}
+        required = []
+
+        @model_class.fields.each do |name, field_info|
+          property_name = schema_property_name(name, field_info)
+          properties[property_name] = generate_property(field_info)
+          required << property_name if field_info.required?
+        end
+
+        schema["properties"] = properties
+        schema["required"] = required if required.any?
+
+        # Create a copy of schema for $defs (without $defs key to avoid circular JSON)
+        defs_schema = {
+          "type" => "object",
+          "title" => @title,
+          "description" => @description,
+          "properties" => properties
+        }.compact
+        defs_schema["required"] = required if required.any?
+
+        # Register this model's schema in defs registry
+        if @defs_registry
+          @defs_registry.register(@model_class, defs_schema)
+        end
+
+        # Add $defs at top level if we have referenced models
+        if @top_level && @defs_registry
+          defs = if @defs_registry.referenced?(@model_class)
+                   @defs_registry.defs_hash
+                 else
+                   @defs_registry.defs_hash(except: @model_class)
+                 end
+          if defs && defs.any?
+            schema["$defs"] = defs
+          end
+        end
+
+        schema
+      end
+
+      private
+
+      def generate_property(field_info)
+        schema = Types.to_schema(
+          field_info.type,
+          **field_info.constraints,
+          defs_registry: @defs_registry,
+          by_alias: @by_alias
+        )
+
+        # Handle optional fields - allow null
+        schema = handle_optional(schema) if field_info.optional
+
+        # Include default value if present and not a factory
+        if @include_defaults && field_info.has_default? && !field_info.default_factory
+          schema["default"] = field_info.default
+        end
+
+        schema
+      end
+
+      def handle_optional(schema)
+        if schema["$ref"]
+          # For $ref, use oneOf to allow null
+          { "oneOf" => [schema, { "type" => "null" }] }
+        elsif schema["type"].is_a?(Array)
+          schema["type"] = schema["type"] + ["null"]
+          schema
+        else
+          schema["type"] = [schema["type"], "null"]
+          schema
+        end
+      end
+
+      def schema_property_name(name, field_info)
+        if @by_alias && field_info.alias_name
+          field_info.alias_name.to_s
+        else
+          name.to_s
+        end
+      end
+    end
+  end
+end

data/lib/rbdantic/json_schema/types.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Rbdantic
+  module JsonSchema
+    # Type-to-schema mappings
+    module Types
+      # Map Ruby type to JSON Schema type
+      # @param type [Class] Ruby type
+      # @param constraints [Hash] field constraints
+      # @param defs_registry [DefsRegistry] registry for $defs/$ref pattern
+      # @return [Hash] JSON Schema for the type
+      def self.to_schema(type, **constraints)
+        defs_registry = constraints[:defs_registry]
+        by_alias = constraints[:by_alias]
+        constraints = constraints.reject { |k, _| k == :defs_registry || k == :by_alias }
+
+        schema = base_schema(type, defs_registry: defs_registry, by_alias: by_alias)
+
+        # Add constraints
+        add_string_constraints(schema, constraints) if type == ::String
+        add_numeric_constraints(schema, constraints) if type == ::Integer || type == ::Float
+        add_array_constraints(schema, constraints, defs_registry: defs_registry, by_alias: by_alias) if type == ::Array
+        add_hash_constraints(schema, constraints) if type == ::Hash
+
+        schema
+      end
+
+      def self.base_schema(type, defs_registry: nil, by_alias: false)
+        # Use direct class comparison (type == Class), not === (which checks instance type)
+        if type == ::String
+          { "type" => "string" }
+        elsif type == ::Integer
+          { "type" => "integer" }
+        elsif type == ::Float
+          { "type" => "number" }
+        elsif type == ::Time
+          { "type" => "string", "format" => "date-time" }
+        elsif type == ::Rbdantic::Boolean
+          { "type" => "boolean" }
+        elsif type == ::Array
+          { "type" => "array" }
+        elsif type == ::Hash
+          { "type" => "object" }
+        elsif type.is_a?(Class) && type < ::Rbdantic::BaseModel
+          if defs_registry
+            unless defs_registry.registered?(type) || defs_registry.being_processed?(type)
+              Generator.generate(type, top_level: false, defs_registry: defs_registry, by_alias: by_alias)
+            end
+
+            defs_registry.ref_for(type)
+          else
+            Generator.generate(type, top_level: false, defs_registry: nil, by_alias: by_alias)
+          end
+        else
+          { "type" => "object" }
+        end
+      end
+
+      def self.add_string_constraints(schema, constraints)
+        schema["minLength"] = constraints[:min_length] if constraints[:min_length]
+        schema["maxLength"] = constraints[:max_length] if constraints[:max_length]
+        schema["pattern"] = constraints[:pattern].source if constraints[:pattern]
+
+        if constraints[:format]
+          format_map = {
+            email: "email",
+            uri: "uri",
+            uuid: "uuid"
+          }
+          schema["format"] = format_map[constraints[:format]] if format_map[constraints[:format]]
+        end
+      end
+
+      def self.add_numeric_constraints(schema, constraints)
+        schema["minimum"] = constraints[:ge] if constraints[:ge]
+        schema["exclusiveMinimum"] = constraints[:gt] if constraints[:gt]
+        schema["maximum"] = constraints[:le] if constraints[:le]
+        schema["exclusiveMaximum"] = constraints[:lt] if constraints[:lt]
+        schema["multipleOf"] = constraints[:multiple_of] if constraints[:multiple_of]
+      end
+
+      def self.add_array_constraints(schema, constraints, defs_registry: nil, by_alias: false)
+        schema["minItems"] = constraints[:min_items] if constraints[:min_items]
+        schema["maxItems"] = constraints[:max_items] if constraints[:max_items]
+        schema["uniqueItems"] = constraints[:unique_items] if constraints[:unique_items]
+        if constraints[:element_type]
+          schema["items"] =
+            to_schema(constraints[:element_type], defs_registry: defs_registry, by_alias: by_alias)
+        end
+      end
+
+      def self.add_hash_constraints(schema, constraints)
+        schema["minProperties"] = constraints[:min_properties] if constraints[:min_properties]
+        schema["maxProperties"] = constraints[:max_properties] if constraints[:max_properties]
+      end
+    end
+  end
+end

data/lib/rbdantic/serialization/dumper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Rbdantic
+  module Serialization
+    # Handles model_dump with various options
+    class Dumper
+      def self.dump(model, **options)
+        new(model, **options).dump
+      end
+
+      def initialize(model, mode: nil, include: nil, exclude: nil,
+                     exclude_unset: false, exclude_defaults: false, by_alias: false)
+        @model = model
+        @mode = mode
+        @include = include
+        @exclude = exclude
+        @exclude_unset = exclude_unset
+        @exclude_defaults = exclude_defaults
+        @by_alias = by_alias
+        @set_fields = Array(model.instance_variable_get("@__fields_set__"))
+      end
+
+      def dump
+        result = {}
+
+        @model.class.fields.each do |name, field_info|
+          next if should_exclude?(name, field_info)
+          
+          # Use alias if requested and present
+          output_name = (@by_alias && field_info.alias_name) ? field_info.alias_name.to_sym : name.to_sym
+          
+          result[output_name] = serialize_item(
+            @model.instance_variable_get("@#{name}"),
+            **nested_dump_options(name, field_info)
+          )
+        end
+
+        extra_fields.each do |name|
+          next if should_exclude_extra?(name)
+          result[name.to_sym] = serialize_item(@model.instance_variable_get("@#{name}"))
+        end
+
+        result
+      end
+
+      private
+
+      def extra_fields
+        Array(@model.instance_variable_get("@__extra_fields__"))
+      end
+
+      def should_exclude?(name, field_info)
+        return true if filter_matches?(@exclude, name, field_info)
+        return true if @include && !filter_matches?(@include, name, field_info)
+        return true if @exclude_unset && !@set_fields.include?(name)
+
+        if @exclude_defaults && field_info.has_default? && field_info.default_factory.nil?
+          current_val = @model.instance_variable_get("@#{name}")
+          return true if current_val == field_info.default
+        end
+
+        false
+      end
+
+      def should_exclude_extra?(name)
+        return true if extra_filter_matches?(@exclude, name)
+        return true if @include && !extra_filter_matches?(@include, name)
+        return true if @exclude_unset && !@set_fields.include?(name)
+        false
+      end
+
+      def nested_dump_options(field_name, field_info)
+        {
+          mode: @mode,
+          exclude_defaults: @exclude_defaults,
+          exclude_unset: @exclude_unset,
+          by_alias: @by_alias,
+          include: nested_filter_for(@include, field_name, field_info),
+          exclude: nested_filter_for(@exclude, field_name, field_info)
+        }
+      end
+
+      def nested_filter_for(filter, field_name, field_info = nil)
+        return unless filter.is_a?(Hash)
+
+        filter_keys_for(field_name, field_info).each do |key|
+          return filter[key] if filter.key?(key)
+        end
+
+        nil
+      end
+
+      def serialize_item(item, **options)
+        case item
+        when Rbdantic::BaseModel then Dumper.dump(item, **options)
+        when Array then item.map { |v| serialize_item(v, **options) }
+        when Hash then item.transform_values { |v| serialize_item(v, **options) }
+        else item
+        end
+      end
+
+      def filter_matches?(filter, field_name, field_info)
+        return false unless filter
+
+        if filter.is_a?(Hash)
+          filter_keys_for(field_name, field_info).any? { |key| filter.key?(key) }
+        else
+          filter_keys_for(field_name, field_info).any? { |key| filter.include?(key) }
+        end
+      end
+
+      def extra_filter_matches?(filter, field_name)
+        return false unless filter
+
+        keys = filter_keys_for(field_name)
+        if filter.is_a?(Hash)
+          keys.any? { |key| filter.key?(key) }
+        else
+          keys.any? { |key| filter.include?(key) }
+        end
+      end
+
+      def filter_keys_for(field_name, field_info = nil)
+        keys = [field_name, field_name.to_s]
+        if @by_alias && field_info&.alias_name
+          keys << field_info.alias_name.to_sym
+          keys << field_info.alias_name.to_s
+        end
+        keys.uniq
+      end
+    end
+  end
+end

data/lib/rbdantic/serialization/json_serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rbdantic
+  module Serialization
+    # JSON serialization and deserialization
+    class JsonSerializer
+      # Serialize model to JSON string
+      # @param model [BaseModel] the model instance
+      # @param indent [Integer, nil] JSON indentation
+      # @return [String] JSON string
+      def self.dump(model, indent: nil, **options)
+        data = Dumper.dump(model, mode: :json, **options)
+
+        if indent
+          JSON.pretty_generate(data, indent: normalize_indent(indent))
+        else
+          JSON.generate(data)
+        end
+      end
+
+      # Parse JSON string into model
+      # @param json_string [String] JSON data
+      # @param model_class [Class] target model class
+      # @return [BaseModel] model instance
+      def self.load(json_string, model_class)
+        data = JSON.parse(json_string, symbolize_names: true)
+        model_class.new(data)
+      end
+
+      # Parse JSON string into model (raises on error)
+      # @param json_string [String] JSON data
+      # @param model_class [Class] target model class
+      # @return [BaseModel] model instance
+      def self.parse!(json_string, model_class)
+        load(json_string, model_class)
+      end
+
+      # Parse JSON string safely, returns nil on error
+      # @param json_string [String] JSON data
+      # @param model_class [Class] target model class
+      # @return [BaseModel, nil] model instance or nil
+      def self.parse(json_string, model_class)
+        begin
+          load(json_string, model_class)
+        rescue JSON::ParserError, ValidationError
+          nil
+        end
+      end
+
+      def self.normalize_indent(indent)
+        return indent if indent.is_a?(String)
+
+        " " * indent.to_i
+      end
+      private_class_method :normalize_indent
+    end
+  end
+end

data/lib/rbdantic/validators/field_validator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Rbdantic
+  module Validators
+    # Decorator for field-level validators
+    # Usage:
+    #   field_validator :age, mode: :after do |value|
+    #     raise "must be at least 18" if value < 18
+    #   end
+    class FieldValidator
+      MODES = %i[before after plain wrap].freeze
+
+      attr_reader :field_name, :mode, :validator_proc
+
+      def initialize(field_name, mode: :after, &block)
+        @field_name = field_name
+        @mode = validate_mode!(mode)
+        @validator_proc = block
+      end
+
+      # Execute the validator
+      # @param value the field value
+      # @param context [ValidatorContext] validation context
+      # @return [Array<ErrorDetail>] errors from validation
+      def call(value, context)
+        errors, = apply(value, context)
+        errors
+      end
+
+      # Execute the validator and optionally transform the value
+      # @param value the field value
+      # @param context [ValidatorContext] validation context
+      # @param handler [Proc, nil] callable for inner validation (wrap mode only)
+      # @return [Array] tuple of [errors, transformed_value]
+      def apply(value, context, handler = nil, &handler_block)
+        errors = []
+        transformed_value = value
+
+        begin
+          handler ||= handler_block
+
+          # For wrap mode, pass handler if available (Issue 4 fix)
+          if @mode == :wrap && handler
+            result = @validator_proc.call(value, context, handler)
+          else
+            result = @validator_proc.call(value, context)
+          end
+
+          # Returning false signals validation failure.
+          # Any other non-nil/non-true return value is treated as a transformed value.
+          if result == false
+            errors << ErrorDetail.new(
+              type: :validation_failed,
+              loc: [@field_name],
+              msg: "Custom validation failed",
+              input: value
+            )
+          elsif !result.nil? && result != true
+            transformed_value = result
+          end
+        rescue StandardError => e
+          errors << ErrorDetail.new(
+            type: :validation_failed,
+            loc: [@field_name],
+            msg: e.message,
+            input: value
+          )
+        end
+
+        [errors, transformed_value]
+      end
+
+      private
+
+      def validate_mode!(mode)
+        unless MODES.include?(mode)
+          raise ArgumentError, "mode must be one of #{MODES.join(", ")}"
+        end
+        mode
+      end
+    end
+  end
+end

data/lib/rbdantic/validators/model_validator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rbdantic
+  module Validators
+    # Decorator for model-level validators
+    # Usage:
+    #   model_validator mode: :before do |data|
+    #     data[:email] = data[:email]&.downcase
+    #     data
+    #   end
+    class ModelValidator
+      MODES = %i[before after].freeze
+
+      attr_reader :mode, :validator_proc
+
+      def initialize(mode: :after, &block)
+        @mode = validate_mode!(mode)
+        @validator_proc = block
+      end
+
+      # Execute the :before validator, which receives and must return a Hash.
+      # Only valid to call when mode == :before.
+      # @param data [Hash] the input data
+      # @return [Hash] modified data
+      def call(data)
+        @validator_proc.call(data)
+      end
+
+      # Run validation and collect errors
+      # @param model_instance the model instance (for after mode)
+      # @return [Array<ErrorDetail>] errors from validation
+      def validate(model_instance)
+        errors = []
+
+        begin
+          @validator_proc.call(model_instance)
+        rescue StandardError => e
+          errors << ErrorDetail.new(
+            type: :model_validation_failed,
+            loc: [],
+            msg: e.message,
+            input: nil
+          )
+        end
+
+        errors
+      end
+
+      private
+
+      def validate_mode!(mode)
+        unless MODES.include?(mode)
+          raise ArgumentError, "mode must be one of #{MODES.join(", ")}"
+        end
+        mode
+      end
+    end
+  end
+end