validrb 0.5.0

data/lib/validrb/result.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Validrb
+  # Represents a successful validation result
+  class Success
+    attr_reader :data
+
+    def initialize(data)
+      @data = data.freeze
+      freeze
+    end
+
+    def success?
+      true
+    end
+
+    def failure?
+      false
+    end
+
+    def errors
+      ErrorCollection.new
+    end
+
+    def value_or(_default = nil)
+      @data
+    end
+
+    def map
+      Success.new(yield(@data))
+    end
+
+    def flat_map
+      yield(@data)
+    end
+
+    def ==(other)
+      other.is_a?(Success) && data == other.data
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, data].hash
+    end
+  end
+
+  # Represents a failed validation result
+  class Failure
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors.is_a?(ErrorCollection) ? errors : ErrorCollection.new(Array(errors))
+      freeze
+    end
+
+    def success?
+      false
+    end
+
+    def failure?
+      true
+    end
+
+    def data
+      nil
+    end
+
+    def value_or(default = nil)
+      block_given? ? yield(@errors) : default
+    end
+
+    def map
+      self
+    end
+
+    def flat_map
+      self
+    end
+
+    def ==(other)
+      other.is_a?(Failure) && errors.to_a == other.errors.to_a
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, errors.to_a].hash
+    end
+  end
+end

data/lib/validrb/schema.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Validrb
+  # Schema class with DSL for defining fields
+  class Schema
+    attr_reader :fields, :validators, :options
+
+    # Options:
+    #   strict: true - raise error on unknown keys
+    #   strip: true - remove unknown keys (default behavior)
+    #   passthrough: true - keep unknown keys in output
+    def initialize(**options, &block)
+      @fields = {}
+      @validators = []
+      @options = normalize_options(options)
+      @builder = Builder.new(self)
+      @builder.instance_eval(&block) if block_given?
+      @fields.freeze
+      @validators.freeze
+      freeze
+    end
+
+    # Parse data and raise ValidationError on failure
+    # @param data [Hash] The data to validate
+    # @param path_prefix [Array] Path prefix for error messages
+    # @param context [Context, Hash, nil] Optional validation context
+    def parse(data, path_prefix: [], context: nil)
+      result = safe_parse(data, path_prefix: path_prefix, context: context)
+
+      raise ValidationError, result.errors if result.failure?
+
+      result.data
+    end
+
+    # Parse data and return Result (Success or Failure)
+    # @param data [Hash] The data to validate
+    # @param path_prefix [Array] Path prefix for error messages
+    # @param context [Context, Hash, nil] Optional validation context
+    def safe_parse(data, path_prefix: [], context: nil)
+      normalized = normalize_input(data)
+      ctx = normalize_context(context)
+      errors = []
+      result_data = {}
+
+      # Check for unknown keys if strict mode
+      if @options[:strict]
+        unknown_keys = normalized.keys - @fields.keys
+        unknown_keys.each do |key|
+          errors << Error.new(path: path_prefix + [key], message: "is not allowed", code: :unknown_key)
+        end
+      end
+
+      # Validate each field
+      @fields.each do |name, field|
+        value = fetch_value(normalized, name)
+        # Pass full data and context for conditional validation (when:/unless:)
+        coerced, field_errors = field.call(value, path: path_prefix, data: normalized, context: ctx)
+
+        if field_errors.empty?
+          # Only include in result if value is not nil or field has a value
+          # Also skip if field was conditionally skipped (conditional? && value is nil)
+          should_include = !(coerced.nil? && field.optional? && !field.has_default?)
+          should_include &&= !(coerced.nil? && field.conditional?)
+          result_data[name] = coerced if should_include
+        else
+          errors.concat(field_errors)
+        end
+      end
+
+      # Passthrough unknown keys
+      if @options[:passthrough]
+        unknown_keys = normalized.keys - @fields.keys
+        unknown_keys.each do |key|
+          result_data[key] = normalized[key]
+        end
+      end
+
+      # Run custom validators only if no field errors
+      if errors.empty?
+        validator_errors = run_validators(result_data, path_prefix, ctx)
+        errors.concat(validator_errors)
+      end
+
+      if errors.empty?
+        Success.new(result_data)
+      else
+        Failure.new(errors)
+      end
+    end
+
+    # Add a field to the schema (used by Builder)
+    def add_field(field)
+      raise ArgumentError, "Field #{field.name} already defined" if @fields.key?(field.name)
+
+      @fields[field.name] = field
+    end
+
+    # Add a custom validator (used by Builder)
+    def add_validator(validator)
+      @validators << validator
+    end
+
+    # Schema composition methods
+
+    # Create a new schema extending this one with additional fields
+    def extend(**options, &block)
+      parent_fields = @fields
+      parent_validators = @validators
+      parent_options = @options
+
+      Schema.new(**parent_options.merge(options)) do
+        # Copy parent fields
+        parent_fields.each_value do |f|
+          @schema.add_field(f)
+        end
+        # Copy parent validators
+        parent_validators.each do |v|
+          @schema.add_validator(v)
+        end
+        # Add new fields/validators from block
+        instance_eval(&block) if block
+      end
+    end
+
+    # Create a new schema with only specified fields
+    def pick(*field_names, **options)
+      field_names = field_names.map(&:to_sym)
+      selected_fields = @fields.slice(*field_names)
+      parent_options = @options
+
+      Schema.new(**parent_options.merge(options)) do
+        selected_fields.each_value do |f|
+          @schema.add_field(f)
+        end
+      end
+    end
+
+    # Create a new schema without specified fields
+    def omit(*field_names, **options)
+      field_names = field_names.map(&:to_sym)
+      remaining_fields = @fields.reject { |k, _| field_names.include?(k) }
+      parent_options = @options
+
+      Schema.new(**parent_options.merge(options)) do
+        remaining_fields.each_value do |f|
+          @schema.add_field(f)
+        end
+      end
+    end
+
+    # Merge another schema into this one (other schema's fields take precedence)
+    def merge(other, **options)
+      raise ArgumentError, "Expected Schema, got #{other.class}" unless other.is_a?(Schema)
+
+      parent_fields = @fields
+      parent_validators = @validators
+      other_fields = other.fields
+      other_validators = other.validators
+      parent_options = @options
+
+      Schema.new(**parent_options.merge(options)) do
+        parent_fields.each_value do |f|
+          @schema.add_field(f) unless other_fields.key?(f.name)
+        end
+        other_fields.each_value do |f|
+          @schema.add_field(f)
+        end
+        parent_validators.each { |v| @schema.add_validator(v) }
+        other_validators.each { |v| @schema.add_validator(v) }
+      end
+    end
+
+    # Create a new schema with all fields optional
+    def partial(**options)
+      parent_fields = @fields
+      parent_options = @options
+
+      Schema.new(**parent_options.merge(options)) do
+        parent_fields.each do |name, f|
+          # Rebuild field as optional
+          field = Field.new(
+            name,
+            f.type,
+            optional: true,
+            **f.options.reject { |k, _| k == :optional }
+          )
+          @schema.add_field(field)
+        end
+      end
+    end
+
+    private
+
+    def normalize_options(options)
+      {
+        strict: options[:strict] || false,
+        passthrough: options[:passthrough] || false
+      }
+    end
+
+    def normalize_context(context)
+      case context
+      when Context
+        context
+      when Hash
+        Context.new(**context)
+      when nil
+        Context.empty
+      else
+        raise ArgumentError, "Expected Context or Hash, got #{context.class}"
+      end
+    end
+
+    def normalize_input(data)
+      return {} if data.nil?
+
+      raise ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(Hash)
+
+      # Convert string keys to symbols
+      data.transform_keys(&:to_sym)
+    end
+
+    def fetch_value(data, name)
+      return data[name] if data.key?(name)
+
+      # Also check string key
+      string_key = name.to_s
+      return data[string_key] if data.key?(string_key)
+
+      Field::MISSING
+    end
+
+    def run_validators(data, path_prefix, context = nil)
+      errors = []
+      validator_ctx = ValidatorContext.new(data, path_prefix, context)
+
+      @validators.each do |validator|
+        if validator.arity <= 1
+          validator_ctx.instance_exec(data, &validator)
+        else
+          validator_ctx.instance_exec(data, context, &validator)
+        end
+      end
+
+      validator_ctx.errors
+    end
+
+    # Context object for custom validators
+    class ValidatorContext
+      attr_reader :errors, :context
+
+      def initialize(data, path_prefix, context = nil)
+        @data = data
+        @path_prefix = path_prefix
+        @context = context
+        @errors = []
+      end
+
+      # Add an error for a specific field
+      def error(field, message, code: :custom)
+        path = @path_prefix + [field.to_sym]
+        @errors << Error.new(path: path, message: message, code: code)
+      end
+
+      # Add a base-level error (not tied to a specific field)
+      def base_error(message, code: :custom)
+        @errors << Error.new(path: @path_prefix, message: message, code: code)
+      end
+
+      # Access field values
+      def [](field)
+        @data[field.to_sym]
+      end
+    end
+
+    # DSL Builder for defining fields
+    class Builder
+      def initialize(schema)
+        @schema = schema
+      end
+
+      def field(name, type, **options)
+        field = Field.new(name, type, **options)
+        @schema.add_field(field)
+      end
+
+      # Shorthand for optional field
+      def optional(name, type, **options)
+        field(name, type, **options.merge(optional: true))
+      end
+
+      # Shorthand for required field (explicit)
+      def required(name, type, **options)
+        field(name, type, **options.merge(optional: false))
+      end
+
+      # Add a custom validator block
+      def validate(&block)
+        @schema.add_validator(block)
+      end
+    end
+  end
+end

data/lib/validrb/serializer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Validrb
+  # Serializer for converting validated data back to primitives
+  # Useful for JSON serialization, database storage, etc.
+  class Serializer
+    # Serialize a value to a primitive representation
+    def self.dump(value, format: :hash)
+      serialized = serialize_value(value)
+
+      case format
+      when :hash
+        serialized
+      when :json
+        JSON.generate(serialized)
+      else
+        raise ArgumentError, "Unknown format: #{format}"
+      end
+    end
+
+    # Serialize a value recursively
+    def self.serialize_value(value)
+      case value
+      when nil, true, false, ::Integer, ::Float, ::String
+        value
+      when ::Symbol
+        value.to_s
+      when ::BigDecimal
+        value.to_s("F")
+      when ::Date
+        value.iso8601
+      when ::DateTime
+        value.iso8601
+      when ::Time
+        value.iso8601
+      when ::Array
+        value.map { |v| serialize_value(v) }
+      when ::Hash
+        value.transform_keys(&:to_s).transform_values { |v| serialize_value(v) }
+      else
+        # Try to_h, to_s as fallbacks
+        if value.respond_to?(:to_h)
+          serialize_value(value.to_h)
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+
+  # Add serialization to Result
+  class Success
+    def dump(format: :hash)
+      Serializer.dump(@data, format: format)
+    end
+
+    def to_json(*args)
+      dump(format: :json)
+    end
+  end
+
+  class Failure
+    def dump(format: :hash)
+      serialized_errors = @errors.map do |e|
+        {
+          "path" => e.path.map(&:to_s),
+          "message" => e.message,
+          "code" => e.code.to_s
+        }
+      end
+
+      case format
+      when :hash
+        { "errors" => serialized_errors }
+      when :json
+        JSON.generate({ "errors" => serialized_errors })
+      else
+        raise ArgumentError, "Unknown format: #{format}"
+      end
+    end
+
+    def to_json(*args)
+      dump(format: :json)
+    end
+  end
+
+  # Add serialization to Schema
+  class Schema
+    # Serialize validated data
+    def dump(data, format: :hash)
+      result = safe_parse(data)
+
+      if result.success?
+        result.dump(format: format)
+      else
+        raise ValidationError, result.errors
+      end
+    end
+
+    # Parse and serialize in one step (returns Result with serialized data)
+    def safe_dump(data, format: :hash)
+      result = safe_parse(data)
+
+      if result.success?
+        Success.new(Serializer.dump(result.data, format: :hash))
+      else
+        result
+      end
+    end
+  end
+end

data/lib/validrb/types/array.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Validrb
+  module Types
+    # Array type with optional item type validation
+    class Array < Base
+      attr_reader :item_type
+
+      def initialize(of: nil, **options)
+        @item_type = of
+        super(**options)
+      end
+
+      def coerce(value)
+        return COERCION_FAILED unless value.is_a?(::Array)
+
+        value
+      end
+
+      def valid?(value)
+        value.is_a?(::Array)
+      end
+
+      # Override call to handle item validation
+      def call(value, path: [])
+        coerced = coerce(value)
+
+        if coerced.equal?(COERCION_FAILED)
+          return [nil, [Error.new(path: path, message: coercion_error_message(value), code: :type_error)]]
+        end
+
+        return [coerced, []] unless @item_type
+
+        validate_items(coerced, path)
+      end
+
+      def type_name
+        @item_type ? "array<#{item_type_name}>" : "array"
+      end
+
+      private
+
+      def validate_items(array, path)
+        type_instance = resolve_item_type
+        result_array = []
+        errors = []
+
+        array.each_with_index do |item, index|
+          item_path = path + [index]
+          coerced_item, item_errors = type_instance.call(item, path: item_path)
+
+          if item_errors.empty?
+            result_array << coerced_item
+          else
+            errors.concat(item_errors)
+          end
+        end
+
+        errors.empty? ? [result_array, []] : [nil, errors]
+      end
+
+      def resolve_item_type
+        case @item_type
+        when Symbol
+          Types.build(@item_type)
+        when Types::Base
+          @item_type
+        when Class
+          @item_type.new
+        else
+          raise ArgumentError, "Invalid item type: #{@item_type.inspect}"
+        end
+      end
+
+      def item_type_name
+        case @item_type
+        when Symbol
+          @item_type.to_s
+        when Types::Base
+          @item_type.type_name
+        when Class
+          @item_type.name.split("::").last.downcase
+        else
+          "unknown"
+        end
+      end
+    end
+
+    register(:array, Array)
+  end
+end

data/lib/validrb/types/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Validrb
+  module Types
+    # Sentinel object for failed coercion (distinguishes from nil)
+    COERCION_FAILED = Object.new.tap do |obj|
+      def obj.inspect
+        "COERCION_FAILED"
+      end
+
+      def obj.to_s
+        "COERCION_FAILED"
+      end
+    end.freeze
+
+    # Registry for types
+    @registry = {}
+
+    class << self
+      attr_reader :registry
+
+      def register(name, klass)
+        @registry[name.to_sym] = klass
+      end
+
+      def lookup(name)
+        @registry[name.to_sym]
+      end
+
+      def build(name, **options)
+        klass = lookup(name)
+        raise ArgumentError, "Unknown type: #{name}" unless klass
+
+        klass.new(**options)
+      end
+    end
+
+    # Base class for all types
+    class Base
+      attr_reader :options
+
+      def initialize(**options)
+        @options = options.freeze
+        freeze
+      end
+
+      # Main entry point: coerce and validate a value
+      # Returns [coerced_value, errors_array]
+      def call(value, path: [])
+        coerced = coerce(value)
+
+        if coerced.equal?(COERCION_FAILED)
+          return [nil, [Error.new(path: path, message: coercion_error_message(value), code: :type_error)]]
+        end
+
+        unless valid?(coerced)
+          return [nil, [Error.new(path: path, message: validation_error_message(coerced), code: :type_error)]]
+        end
+
+        [coerced, []]
+      end
+
+      # Override in subclasses: attempt to coerce value to target type
+      # Return COERCION_FAILED if coercion is not possible
+      def coerce(value)
+        value
+      end
+
+      # Override in subclasses: validate that value is correct type
+      def valid?(_value)
+        true
+      end
+
+      # Override in subclasses: type name for error messages
+      def type_name
+        self.class.name.split("::").last.downcase
+      end
+
+      # Override in subclasses: error message for failed coercion
+      def coercion_error_message(value)
+        "cannot coerce #{value.class} to #{type_name}"
+      end
+
+      # Override in subclasses: error message for failed validation
+      def validation_error_message(_value)
+        "must be a #{type_name}"
+      end
+    end
+  end
+end

data/lib/validrb/types/boolean.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Validrb
+  module Types
+    # Boolean type with coercion from String/Integer
+    class Boolean < Base
+      TRUTHY_VALUES = [true, 1, "1", "true", "yes", "on", "t", "y"].freeze
+      FALSY_VALUES = [false, 0, "0", "false", "no", "off", "f", "n"].freeze
+
+      def coerce(value)
+        return true if TRUTHY_VALUES.include?(normalize(value))
+        return false if FALSY_VALUES.include?(normalize(value))
+
+        COERCION_FAILED
+      end
+
+      def valid?(value)
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      end
+
+      def type_name
+        "boolean"
+      end
+
+      private
+
+      def normalize(value)
+        return value.downcase if value.is_a?(::String)
+
+        value
+      end
+    end
+
+    register(:boolean, Boolean)
+    register(:bool, Boolean)
+  end
+end