tarsier 0.1.0

data/lib/tarsier/params.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Tarsier
+  # Parameter object with validation and coercion support
+  # Provides type-safe access to request parameters
+  class Params
+    # Boolean type marker (Ruby doesn't have a Boolean class)
+    Boolean = Object.new.freeze
+
+    # Type coercion mappings
+    COERCIONS = {
+      String => ->(v) { v.to_s },
+      Integer => ->(v) { Integer(v) },
+      Float => ->(v) { Float(v) },
+      Boolean => ->(v) { !["false", "0", "", "no", "off"].include?(v.to_s.downcase) },
+      Array => ->(v) { Array(v) },
+      Hash => ->(v) { v.is_a?(Hash) ? v : {} },
+      Date => ->(v) { Date.parse(v.to_s) },
+      Time => ->(v) { Time.parse(v.to_s) },
+      DateTime => ->(v) { DateTime.parse(v.to_s) }
+    }.freeze
+
+    attr_reader :raw
+
+    # @param params [Hash] raw parameters
+    def initialize(params = {})
+      @raw = params.transform_keys(&:to_sym).freeze
+    end
+
+    # Get a parameter value
+    # @param key [Symbol, String] parameter key
+    # @return [Object, nil]
+    def [](key)
+      @raw[key.to_sym]
+    end
+
+    # Check if parameter exists
+    # @param key [Symbol, String] parameter key
+    # @return [Boolean]
+    def key?(key)
+      @raw.key?(key.to_sym)
+    end
+
+    alias has_key? key?
+
+    # Get parameter with default
+    # @param key [Symbol, String] parameter key
+    # @param default [Object] default value
+    # @return [Object]
+    def fetch(key, default = nil, &block)
+      @raw.fetch(key.to_sym, default, &block)
+    end
+
+    # Get required parameter (raises if missing)
+    # @param key [Symbol, String] parameter key
+    # @param type [Class, nil] expected type for coercion
+    # @return [Object]
+    # @raise [MissingParameterError] if parameter is missing
+    def require(key, type: nil)
+      key = key.to_sym
+      raise MissingParameterError, key unless key?(key)
+
+      value = @raw[key]
+      type ? coerce(key, value, type) : value
+    end
+
+    # Get optional parameter with type coercion
+    # @param key [Symbol, String] parameter key
+    # @param type [Class, nil] expected type for coercion
+    # @param default [Object] default value if missing
+    # @return [Object, nil]
+    def optional(key, type: nil, default: nil)
+      key = key.to_sym
+      return default unless key?(key) && !@raw[key].nil?
+
+      value = @raw[key]
+      type ? coerce(key, value, type) : value
+    end
+
+    # Permit only specified keys
+    # @param keys [Array<Symbol>] allowed keys
+    # @return [Hash]
+    def permit(*keys)
+      keys = keys.flatten.map(&:to_sym)
+      @raw.slice(*keys)
+    end
+
+    # Slice parameters
+    # @param keys [Array<Symbol>] keys to include
+    # @return [Hash]
+    def slice(*keys)
+      permit(*keys)
+    end
+
+    # Except parameters
+    # @param keys [Array<Symbol>] keys to exclude
+    # @return [Hash]
+    def except(*keys)
+      keys = keys.flatten.map(&:to_sym)
+      @raw.reject { |k, _| keys.include?(k) }
+    end
+
+    # Merge with another hash
+    # @param other [Hash] hash to merge
+    # @return [Params]
+    def merge(other)
+      Params.new(@raw.merge(other.transform_keys(&:to_sym)))
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      @raw.dup
+    end
+
+    alias to_hash to_h
+
+    # Iterate over parameters
+    def each(&block)
+      @raw.each(&block)
+    end
+
+    # Check if empty
+    # @return [Boolean]
+    def empty?
+      @raw.empty?
+    end
+
+    # Parameter count
+    # @return [Integer]
+    def size
+      @raw.size
+    end
+
+    alias length size
+
+    # String representation
+    # @return [String]
+    def inspect
+      "#<Tarsier::Params #{@raw.inspect}>"
+    end
+
+    private
+
+    def coerce(key, value, type)
+      # Boolean is a special marker object, not a real class
+      return value if type != Boolean && value.is_a?(type)
+
+      coercer = COERCIONS[type]
+      raise TypeCoercionError.new(key, type, value) unless coercer
+
+      coercer.call(value)
+    rescue ArgumentError, TypeError => e
+      raise TypeCoercionError.new(key, type, value)
+    end
+  end
+
+  # Parameter schema for validation
+  class ParamSchema
+    attr_reader :rules
+
+    def initialize
+      @rules = {}
+    end
+
+    # Define a required parameter
+    # @param name [Symbol] parameter name
+    # @param type [Class] expected type
+    # @param options [Hash] validation options
+    def requires(name, type:, **options)
+      @rules[name.to_sym] = { required: true, type: type, **options }
+    end
+
+    # Define an optional parameter
+    # @param name [Symbol] parameter name
+    # @param type [Class] expected type
+    # @param options [Hash] validation options
+    def optional(name, type:, default: nil, **options)
+      @rules[name.to_sym] = { required: false, type: type, default: default, **options }
+    end
+
+    # Validate parameters against schema
+    # @param params [Params, Hash] parameters to validate
+    # @return [Hash] validated and coerced parameters
+    # @raise [ValidationError] if validation fails
+    def validate(params)
+      params = params.is_a?(Params) ? params : Params.new(params)
+      errors = {}
+      result = {}
+
+      @rules.each do |name, rule|
+        value = params[name]
+
+        if value.nil? || value == ""
+          if rule[:required]
+            errors[name] = ["is required"]
+            next
+          else
+            result[name] = rule[:default]
+            next
+          end
+        end
+
+        # Type coercion
+        begin
+          value = coerce_value(value, rule[:type])
+        rescue StandardError
+          errors[name] = ["must be a #{rule[:type]}"]
+          next
+        end
+
+        # Validations
+        validation_errors = validate_value(name, value, rule)
+        if validation_errors.any?
+          errors[name] = validation_errors
+        else
+          result[name] = value
+        end
+      end
+
+      raise ValidationError, errors if errors.any?
+
+      result
+    end
+
+    private
+
+    def coerce_value(value, type)
+      coercer = Params::COERCIONS[type]
+      coercer ? coercer.call(value) : value
+    end
+
+    def validate_value(name, value, rule)
+      errors = []
+
+      # Length validations
+      if rule[:min] && value.respond_to?(:length) && value.length < rule[:min]
+        errors << "must be at least #{rule[:min]} characters"
+      end
+
+      if rule[:max] && value.respond_to?(:length) && value.length > rule[:max]
+        errors << "must be at most #{rule[:max]} characters"
+      end
+
+      # Numeric validations
+      if rule[:greater_than] && value.respond_to?(:<) && value <= rule[:greater_than]
+        errors << "must be greater than #{rule[:greater_than]}"
+      end
+
+      if rule[:less_than] && value.respond_to?(:>) && value >= rule[:less_than]
+        errors << "must be less than #{rule[:less_than]}"
+      end
+
+      # Format validation
+      if rule[:format] && value.respond_to?(:match?) && !value.match?(rule[:format])
+        errors << "has invalid format"
+      end
+
+      # Inclusion validation
+      if rule[:in] && !rule[:in].include?(value)
+        errors << "must be one of: #{rule[:in].join(', ')}"
+      end
+
+      errors
+    end
+  end
+end