clickhouse-ruby 0.1.0 → 0.2.0

data/lib/clickhouse_ruby/types/boolean.rb

@@ -8,45 +8,42 @@ module ClickhouseRuby
     # but can accept various truthy/falsy values.
     #
     class Boolean < Base
+      include NullSafe
+
       # Values that represent true
-      TRUE_VALUES = [true, 1, '1', 'true', 'TRUE', 'True', 't', 'T', 'yes', 'YES', 'Yes', 'y', 'Y', 'on', 'ON', 'On'].freeze
+      TRUE_VALUES = [true, 1, "1", "true", "TRUE", "True", "t", "T", "yes", "YES", "Yes", "y", "Y", "on", "ON",
+                     "On",].freeze
 
       # Values that represent false
-      FALSE_VALUES = [false, 0, '0', 'false', 'FALSE', 'False', 'f', 'F', 'no', 'NO', 'No', 'n', 'N', 'off', 'OFF', 'Off'].freeze
+      FALSE_VALUES = [false, 0, "0", "false", "FALSE", "False", "f", "F", "no", "NO", "No", "n", "N", "off", "OFF",
+                      "Off",].freeze
+
+      protected
 
       # Converts a Ruby value to a boolean
       #
-      # @param value [Object] the value to convert
-      # @return [Boolean, nil] the boolean value
+      # @param value [Object] the value to convert (guaranteed non-nil)
+      # @return [Boolean] the boolean value
       # @raise [TypeCastError] if the value cannot be interpreted as boolean
-      def cast(value)
-        return nil if value.nil?
-
+      def cast_value(value)
         if TRUE_VALUES.include?(value)
           true
         elsif FALSE_VALUES.include?(value)
           false
         else
-          raise TypeCastError.new(
-            "Cannot cast '#{value}' to Bool",
-            from_type: value.class.name,
-            to_type: name,
-            value: value
-          )
+          raise_cast_error(value, "Cannot cast '#{value}' to Bool")
         end
       end
 
       # Converts a value from ClickHouse to Ruby boolean
       #
-      # @param value [Object] the value from ClickHouse
-      # @return [Boolean, nil] the boolean value
-      def deserialize(value)
-        return nil if value.nil?
-
+      # @param value [Object] the value from ClickHouse (guaranteed non-nil)
+      # @return [Boolean] the boolean value
+      def deserialize_value(value)
         case value
-        when true, 1, '1', 'true'
+        when true, 1, "1", "true"
           true
-        when false, 0, '0', 'false'
+        when false, 0, "0", "false"
           false
         else
           # Default to truthy evaluation
@@ -56,12 +53,18 @@ module ClickhouseRuby
 
       # Converts a boolean to SQL literal
       #
-      # @param value [Boolean, nil] the value to serialize
+      # @param value [Boolean] the value to serialize (guaranteed non-nil)
       # @return [String] the SQL literal (1 or 0)
-      def serialize(value)
-        return 'NULL' if value.nil?
-
-        value ? '1' : '0'
+      def serialize_value(value)
+        # Check explicit FALSE_VALUES first since Ruby's 0 is truthy
+        if FALSE_VALUES.include?(value)
+          "0"
+        elsif TRUE_VALUES.include?(value)
+          "1"
+        else
+          # Default to truthy evaluation for other values
+          value ? "1" : "0"
+        end
       end
     end
   end

data/lib/clickhouse_ruby/types/date_time.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'time'
-require 'date'
+require "time"
+require "date"
 
 module ClickhouseRuby
   module Types
@@ -51,12 +51,7 @@ module ClickhouseRuby
           # Unix timestamp
           date_only? ? Time.at(value).to_date : Time.at(value)
         else
-          raise TypeCastError.new(
-            "Cannot cast #{value.class} to #{name}",
-            from_type: value.class.name,
-            to_type: name,
-            value: value
-          )
+          raise_cast_error(value)
         end
       end
 
@@ -84,7 +79,7 @@ module ClickhouseRuby
       # @param value [Time, Date, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         if date_only?
           format_date(value)
@@ -97,7 +92,7 @@ module ClickhouseRuby
       #
       # @return [Boolean] true if date-only
       def date_only?
-        name.start_with?('Date') && !name.start_with?('DateTime')
+        name.start_with?("Date") && !name.start_with?("DateTime")
       end
 
       private
@@ -110,14 +105,7 @@ module ClickhouseRuby
       def parse_string(value)
         stripped = value.strip
 
-        if stripped.empty?
-          raise TypeCastError.new(
-            "Cannot cast empty string to #{name}",
-            from_type: 'String',
-            to_type: name,
-            value: value
-          )
-        end
+        raise_empty_string_error(value) if stripped.empty?
 
         if date_only?
           ::Date.parse(stripped)
@@ -125,12 +113,7 @@ module ClickhouseRuby
           ::Time.parse(stripped)
         end
       rescue ArgumentError => e
-        raise TypeCastError.new(
-          "Cannot cast '#{value}' to #{name}: #{e.message}",
-          from_type: 'String',
-          to_type: name,
-          value: value
-        )
+        raise_cast_error(value, "Cannot cast '#{value}' to #{name}: #{e.message}")
       end
 
       # Formats a date value for SQL
@@ -139,7 +122,7 @@ module ClickhouseRuby
       # @return [String] the formatted SQL literal
       def format_date(value)
         date = value.respond_to?(:to_date) ? value.to_date : value
-        "'#{date.strftime('%Y-%m-%d')}'"
+        "'#{date.strftime("%Y-%m-%d")}'"
       end
 
       # Formats a datetime value for SQL
@@ -149,13 +132,13 @@ module ClickhouseRuby
       def format_datetime(value)
         time = value.respond_to?(:to_time) ? value.to_time : value
 
-        if @precision && @precision > 0
+        if @precision&.positive?
           # DateTime64 with fractional seconds
           format_str = "%Y-%m-%d %H:%M:%S.%#{@precision}N"
           "'#{time.strftime(format_str)}'"
         else
           # Regular DateTime
-          "'#{time.strftime('%Y-%m-%d %H:%M:%S')}'"
+          "'#{time.strftime("%Y-%m-%d %H:%M:%S")}'"
         end
       end
     end

data/lib/clickhouse_ruby/types/decimal.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Decimal types
+    #
+    # Handles: Decimal(P, S), Decimal32(S), Decimal64(S), Decimal128(S), Decimal256(S)
+    #
+    # Uses BigDecimal for arbitrary precision arithmetic to avoid floating point errors.
+    # Validates precision and scale according to ClickHouse constraints.
+    #
+    class Decimal < Base
+      # Precision limits for each Decimal variant
+      PRECISION_LIMITS = {
+        32 => 9,
+        64 => 18,
+        128 => 38,
+        256 => 76,
+      }.freeze
+
+      # @return [Integer] the precision (total number of significant digits)
+      attr_reader :precision
+
+      # @return [Integer] the scale (number of digits after decimal point)
+      attr_reader :scale
+
+      # Initializes a Decimal type
+      #
+      # @param name [String] the ClickHouse type name (e.g., 'Decimal(18, 4)')
+      # @param precision [Integer, nil] optional precision override
+      # @param scale [Integer, nil] optional scale override
+      # @param arg_types [Array, nil] optional parsed argument types (ignored for Decimal)
+      # @raise [ConfigurationError] if precision/scale are invalid
+      def initialize(name, precision: nil, scale: nil, arg_types: nil)
+        super(name)
+        @precision, @scale = parse_decimal_params(name, precision, scale)
+        validate_params!
+      end
+
+      # Converts a Ruby value to BigDecimal
+      #
+      # @param value [Object] the value to convert
+      # @return [BigDecimal, nil] the BigDecimal value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        bd = case value
+             when ::BigDecimal
+               value
+             when ::Integer
+               BigDecimal(value)
+             when ::Float
+               BigDecimal(value.to_s)
+             when ::String
+               BigDecimal(value)
+             else
+               raise_cast_error(value)
+             end
+
+        validate_value!(bd)
+        bd
+      end
+
+      # Converts a value from ClickHouse response to Ruby BigDecimal
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [BigDecimal, nil] the BigDecimal value
+      def deserialize(value)
+        return nil if value.nil?
+
+        BigDecimal(value.to_s)
+      end
+
+      # Converts a BigDecimal to ClickHouse SQL literal
+      #
+      # @param value [BigDecimal, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return "NULL" if value.nil?
+
+        bd = cast(value)
+        # Use 'F' format to preserve precision (fixed-point notation)
+        bd.to_s("F")
+      end
+
+      # Returns the internal ClickHouse type based on precision
+      #
+      # @return [Symbol] the internal type (:Decimal32, :Decimal64, :Decimal128, or :Decimal256)
+      def internal_type
+        case precision
+        when 1..9
+          :Decimal32
+        when 10..18
+          :Decimal64
+        when 19..38
+          :Decimal128
+        when 39..76
+          :Decimal256
+        end
+      end
+
+      private
+
+      # Parses precision and scale from type string
+      #
+      # Handles:
+      # - Decimal(18, 4) → precision=18, scale=4
+      # - Decimal64(4) → precision=max_for_variant, scale=4
+      #
+      # @param name [String] the type string
+      # @param precision [Integer, nil] optional override
+      # @param scale [Integer, nil] optional override
+      # @return [Array<Integer>] [precision, scale]
+      def parse_decimal_params(name, precision, scale)
+        # Match: Decimal(P, S) or Decimal32(S), Decimal64(S), etc.
+        # Allow negative numbers to be parsed (for proper error reporting)
+        if name =~ /^Decimal(\d{2,3})?\((-?\d+)(?:,\s*(-?\d+))?\)$/
+          variant = Regexp.last_match(1)&.to_i
+          first_arg = Regexp.last_match(2).to_i
+          second_arg = Regexp.last_match(3)&.to_i
+
+          if variant
+            # Decimal32(4) → variant determines precision, first_arg is scale
+            max_p = PRECISION_LIMITS[variant]
+            [max_p, first_arg]
+          else
+            # Decimal(18, 4) → first_arg is precision, second_arg is scale
+            second_arg ||= 0
+            [first_arg, second_arg]
+          end
+        else
+          # Fallback to parameters or defaults
+          [precision || 10, scale || 0]
+        end
+      end
+
+      # Validates that precision and scale parameters are valid
+      #
+      # @raise [ConfigurationError] if validation fails
+      def validate_params!
+        unless (1..76).include?(@precision)
+          raise ConfigurationError, "Decimal precision must be 1-76, got #{@precision}"
+        end
+
+        return if (0..@precision).include?(@scale)
+
+        raise ConfigurationError, "Decimal scale must be 0-#{@precision}, got #{@scale}"
+      end
+
+      # Validates that a BigDecimal value doesn't exceed type limits
+      #
+      # @param bd [BigDecimal] the value to validate
+      # @raise [TypeCastError] if the value exceeds limits
+      def validate_value!(bd)
+        # Check integer part doesn't exceed allowed digits
+        max_integer_digits = @precision - @scale
+
+        # Use 'F' format to get fixed-point notation
+        bd_str = bd.to_s("F")
+        # Split on decimal point to get integer and fractional parts
+        parts = bd_str.split(".")
+        integer_part = parts[0].gsub(/[^0-9]/, "") # Remove sign
+        # Remove leading zeros
+        integer_digits = integer_part.sub(/^0+/, "") || "0"
+
+        return unless integer_digits.length > max_integer_digits
+
+        raise_cast_error(bd, "Value #{bd} exceeds maximum integer digits (#{max_integer_digits}) for #{name}")
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/enum.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Enum types
+    #
+    # Handles: Enum, Enum8, Enum16
+    #
+    # Enum types store predefined string values as integers for efficient storage.
+    # Supports both explicit value assignment ('name' = value) and auto-increment syntax.
+    #
+    class Enum < Base
+      # @return [Array<String>] the list of possible enum values
+      attr_reader :possible_values
+
+      # @return [Hash{String => Integer}] mapping of string values to integers
+      attr_reader :value_to_int
+
+      # @return [Hash{Integer => String}] mapping of integers to string values
+      attr_reader :int_to_value
+
+      def initialize(name, arg_types: nil)
+        super(name)
+
+        # When called from registry, we get arg_types with parsed enum entries.
+        # When called directly (for testing), we get the full name like "Enum8('active' = 1, 'inactive' = 2)"
+        if arg_types && !arg_types.empty?
+          @possible_values, @value_to_int, @int_to_value = parse_enum_from_args(name, arg_types)
+        else
+          @possible_values, @value_to_int, @int_to_value = parse_enum_definition(name)
+        end
+      end
+
+      # Converts a Ruby value to a valid enum value
+      #
+      # @param value [String, Integer, nil] the value to convert
+      # @return [String, nil] the enum value (string)
+      # @raise [TypeCastError] if value is not a valid enum value
+      def cast(value)
+        return nil if value.nil?
+
+        case value
+        when ::String
+          validate_string_value!(value)
+          value
+        when ::Integer
+          validate_int_value!(value)
+          @int_to_value[value]
+        else
+          raise_cast_error(value, "Cannot cast #{value.class} to #{self}")
+        end
+      end
+
+      # Converts a value from ClickHouse response format to Ruby
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [String] the string value
+      def deserialize(value)
+        value.to_s
+      end
+
+      # Converts a Ruby value to ClickHouse SQL literal format
+      #
+      # @param value [String, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return "NULL" if value.nil?
+
+        escaped = value.to_s.gsub("'", "\\\\'")
+        "'#{escaped}'"
+      end
+
+      private
+
+      # Parses an Enum from registry arg_types
+      #
+      # The arg_types are Base type objects where the :type is the enum entry string
+      #
+      # @param name [String] the type name (e.g., "Enum8")
+      # @param arg_types [Array<Base>] the parsed enum entries
+      # @return [Array] [possible_values, value_to_int, int_to_value]
+      def parse_enum_from_args(_name, arg_types)
+        possible_values = []
+        value_to_int = {}
+        int_to_value = {}
+        auto_index = 1
+
+        arg_types.each do |arg_type|
+          # The arg_type.name contains the enum entry string
+          entry = arg_type.name
+          enum_name, int_val = parse_enum_entry(entry)
+
+          possible_values << enum_name
+
+          # If no explicit value, use auto-increment
+          if int_val.nil?
+            int_val = auto_index
+            auto_index += 1
+          elsif int_val >= auto_index
+            auto_index = int_val + 1
+          end
+
+          value_to_int[enum_name] = int_val
+          int_to_value[int_val] = enum_name
+        end
+
+        [possible_values, value_to_int, int_to_value]
+      end
+
+      # Parses an Enum type definition to extract values and mappings
+      #
+      # Handles both syntaxes:
+      # - Explicit: Enum8('active' = 1, 'inactive' = 2)
+      # - Auto-increment: Enum('hello', 'world')  # hello=1, world=2
+      #
+      # @param type_string [String] the full type string (e.g., "Enum8('active' = 1)")
+      # @return [Array] [possible_values, value_to_int, int_to_value]
+      def parse_enum_definition(type_string)
+        # Extract the part inside parentheses
+        # e.g., Enum8('active' = 1, 'inactive' = 2) -> 'active' = 1, 'inactive' = 2
+        match = type_string.match(/\((.*)\)\z/m)
+        raise TypeCastError, "Invalid Enum definition: #{type_string}" unless match
+
+        enum_args = match[1]
+
+        possible_values = []
+        value_to_int = {}
+        int_to_value = {}
+
+        # Split by comma, but need to handle escaped quotes
+        # Parse each enum entry: 'name' = value or 'name'
+        entries = parse_enum_entries(enum_args)
+
+        auto_index = 1 # For auto-increment values
+
+        entries.each do |entry|
+          name, int_val = parse_enum_entry(entry)
+          possible_values << name
+
+          # If no explicit value, use auto-increment
+          if int_val.nil?
+            int_val = auto_index
+            auto_index += 1
+          elsif int_val >= auto_index
+            auto_index = int_val + 1
+          end
+          # Update auto_index to be the next number after the highest seen
+
+          value_to_int[name] = int_val
+          int_to_value[int_val] = name
+        end
+
+        [possible_values, value_to_int, int_to_value]
+      end
+
+      # Splits enum entries by comma, handling escaped quotes
+      #
+      # @param enum_args [String] the enum arguments string
+      # @return [Array<String>] list of enum entries
+      def parse_enum_entries(enum_args)
+        entries = []
+        current_entry = +""
+        in_quotes = false
+        i = 0
+
+        while i < enum_args.length
+          char = enum_args[i]
+
+          if char == "'" && (i.zero? || enum_args[i - 1] != "\\")
+            in_quotes = !in_quotes
+            current_entry += char
+          elsif char == "," && !in_quotes
+            entries << current_entry.strip
+            current_entry = +""
+          else
+            current_entry += char
+          end
+
+          i += 1
+        end
+
+        entries << current_entry.strip if current_entry.strip.length.positive?
+        entries
+      end
+
+      # Parses a single enum entry
+      #
+      # @param entry [String] e.g., "'active' = 1", "'value'", or "active" (from parser)
+      # @return [Array<String, Integer>] [name, integer_value]
+      def parse_enum_entry(entry)
+        entry = entry.strip
+
+        # Check if it has explicit assignment: 'name' = value or name = value (from parser)
+        if entry.include?("=")
+          parts = entry.split("=", 2)
+          name_part = parts[0].strip
+          value_part = parts[1].strip
+
+          # Extract name - might be quoted or unquoted
+          name = if name_part.start_with?("'") && name_part.end_with?("'")
+                   extract_quoted_string(name_part)
+                 else
+                   # Already unquoted (from parser)
+                   name_part
+                 end
+
+          # Parse integer value
+          int_val = value_part.to_i
+
+          [name, int_val]
+        else
+          # Auto-increment: just 'name' or name (from parser)
+          name = if entry.start_with?("'") && entry.end_with?("'")
+                   extract_quoted_string(entry)
+                 else
+                   # Already unquoted (from parser)
+                   entry
+                 end
+          # Will assign index + 1 later
+          [name, nil]
+        end
+      end
+
+      # Extracts a string value from quotes, handling escapes
+      #
+      # @param quoted_str [String] e.g., "'hello'" or "'it\\'s'"
+      # @return [String] the unquoted string with escapes processed
+      def extract_quoted_string(quoted_str)
+        quoted_str = quoted_str.strip
+        # Remove surrounding quotes
+        unless quoted_str.start_with?("'") && quoted_str.end_with?("'")
+          raise TypeCastError, "Invalid enum value format: #{quoted_str}"
+        end
+
+        # Remove quotes
+        unquoted = quoted_str[1...-1]
+        # Unescape single quotes
+        unquoted.gsub("\\'", "'")
+      end
+
+      # Validates that a string value is a valid enum value
+      #
+      # @param value [String] the value to validate
+      # @raise [TypeCastError] if value is not valid
+      def validate_string_value!(value)
+        return if @possible_values.include?(value)
+
+        raise_cast_error(value, "Unknown enum value '#{value}'. Valid values: #{@possible_values.join(", ")}")
+      end
+
+      # Validates that an integer value maps to a valid enum value
+      #
+      # @param value [Integer] the value to validate
+      # @raise [TypeCastError] if value is not valid
+      def validate_int_value!(value)
+        return if @int_to_value.key?(value)
+
+        raise_cast_error(value, "Unknown enum integer #{value}. Valid integers: #{@int_to_value.keys.join(", ")}")
+      end
+    end
+  end
+end