clickhouse-ruby 0.1.0 → 0.2.0

data/lib/clickhouse_ruby/types/float.rb

@@ -27,12 +27,7 @@ module ClickhouseRuby
         when ::BigDecimal
           value.to_f
         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
 
@@ -40,6 +35,7 @@ module ClickhouseRuby
       #
       # @param value [Object] the value from ClickHouse
       # @return [Float, nil] the float value
+      # @raise [TypeCastError] if the value cannot be converted
       def deserialize(value)
         return nil if value.nil?
 
@@ -48,8 +44,10 @@ module ClickhouseRuby
           value
         when ::String
           parse_string(value)
-        else
+        when ::Integer, ::BigDecimal, ::Rational
           value.to_f
+        else
+          raise_cast_error(value, "Cannot deserialize #{value.class} to #{name}")
         end
       end
 
@@ -58,14 +56,14 @@ module ClickhouseRuby
       # @param value [Float, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         if value.nan?
-          'nan'
+          "nan"
         elsif value.infinite? == 1
-          'inf'
+          "inf"
         elsif value.infinite? == -1
-          '-inf'
+          "-inf"
         else
           value.to_s
         end
@@ -83,32 +81,20 @@ module ClickhouseRuby
 
         # Handle special values
         case stripped
-        when 'inf', '+inf', 'infinity', '+infinity'
+        when "inf", "+inf", "infinity", "+infinity"
           ::Float::INFINITY
-        when '-inf', '-infinity'
+        when "-inf", "-infinity"
           -::Float::INFINITY
-        when 'nan'
+        when "nan"
           ::Float::NAN
         else
           # Handle empty strings
-          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?
 
           Float(stripped)
         end
       rescue ArgumentError
-        raise TypeCastError.new(
-          "Cannot cast '#{value}' to #{name}",
-          from_type: 'String',
-          to_type: name,
-          value: value
-        )
+        raise_cast_error(value, "Cannot cast '#{value}' to #{name}")
       end
     end
   end

data/lib/clickhouse_ruby/types/integer.rb

@@ -13,18 +13,18 @@ module ClickhouseRuby
     class Integer < Base
       # Size limits for each integer type
       LIMITS = {
-        'Int8' => { min: -128, max: 127 },
-        'Int16' => { min: -32_768, max: 32_767 },
-        'Int32' => { min: -2_147_483_648, max: 2_147_483_647 },
-        'Int64' => { min: -9_223_372_036_854_775_808, max: 9_223_372_036_854_775_807 },
-        'Int128' => { min: -(2**127), max: (2**127) - 1 },
-        'Int256' => { min: -(2**255), max: (2**255) - 1 },
-        'UInt8' => { min: 0, max: 255 },
-        'UInt16' => { min: 0, max: 65_535 },
-        'UInt32' => { min: 0, max: 4_294_967_295 },
-        'UInt64' => { min: 0, max: 18_446_744_073_709_551_615 },
-        'UInt128' => { min: 0, max: (2**128) - 1 },
-        'UInt256' => { min: 0, max: (2**256) - 1 }
+        "Int8" => { min: -128, max: 127 },
+        "Int16" => { min: -32_768, max: 32_767 },
+        "Int32" => { min: -2_147_483_648, max: 2_147_483_647 },
+        "Int64" => { min: -9_223_372_036_854_775_808, max: 9_223_372_036_854_775_807 },
+        "Int128" => { min: -(2**127), max: (2**127) - 1 },
+        "Int256" => { min: -(2**255), max: (2**255) - 1 },
+        "UInt8" => { min: 0, max: 255 },
+        "UInt16" => { min: 0, max: 65_535 },
+        "UInt32" => { min: 0, max: 4_294_967_295 },
+        "UInt64" => { min: 0, max: 18_446_744_073_709_551_615 },
+        "UInt128" => { min: 0, max: (2**128) - 1 },
+        "UInt256" => { min: 0, max: (2**256) - 1 },
       }.freeze
 
       # Converts a Ruby value to an integer
@@ -52,12 +52,7 @@ module ClickhouseRuby
         when false
           0
         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
 
@@ -85,7 +80,7 @@ module ClickhouseRuby
       # @param value [Integer, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         value.to_s
       end
@@ -94,14 +89,14 @@ module ClickhouseRuby
       #
       # @return [Boolean] true if unsigned
       def unsigned?
-        name.start_with?('U')
+        name.start_with?("U")
       end
 
       # Returns the bit size of this integer type
       #
       # @return [Integer] the bit size (8, 16, 32, 64, 128, or 256)
       def bit_size
-        name.gsub(/[^0-9]/, '').to_i
+        name.gsub(/[^0-9]/, "").to_i
       end
 
       private
@@ -115,24 +110,12 @@ module ClickhouseRuby
         stripped = value.strip
 
         # Handle empty strings
-        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?
 
         # Use Integer() for strict parsing
         Integer(stripped)
       rescue ArgumentError
-        raise TypeCastError.new(
-          "Cannot cast '#{value}' to #{name}",
-          from_type: 'String',
-          to_type: name,
-          value: value
-        )
+        raise_cast_error(value, "Cannot cast '#{value}' to #{name}")
       end
 
       # Validates that a value is within the type's range
@@ -143,14 +126,9 @@ module ClickhouseRuby
         limits = LIMITS[name]
         return unless limits  # Unknown type, skip validation
 
-        if value < limits[:min] || value > limits[:max]
-          raise TypeCastError.new(
-            "Value #{value} is out of range for #{name} (#{limits[:min]}..#{limits[:max]})",
-            from_type: value.class.name,
-            to_type: name,
-            value: value
-          )
-        end
+        return unless value < limits[:min] || value > limits[:max]
+
+        raise_range_error(value, limits[:min], limits[:max])
       end
     end
   end

data/lib/clickhouse_ruby/types/low_cardinality.rb

@@ -20,7 +20,7 @@ module ClickhouseRuby
       # @param element_type [Base] the wrapped type
       def initialize(name, element_type: nil)
         super(name)
-        @element_type = element_type || Base.new('String')
+        @element_type = element_type || Base.new("String")
       end
 
       # Converts a Ruby value using the wrapped type

data/lib/clickhouse_ruby/types/map.rb

@@ -23,9 +23,9 @@ module ClickhouseRuby
       # @param arg_types [Array<Base>] array of [key_type, value_type]
       def initialize(name, arg_types: nil)
         super(name)
-        arg_types ||= [Base.new('String'), Base.new('String')]
+        arg_types ||= [Base.new("String"), Base.new("String")]
         @key_type = arg_types[0]
-        @value_type = arg_types[1] || Base.new('String')
+        @value_type = arg_types[1] || Base.new("String")
       end
 
       # Converts a Ruby value to a map (Hash)
@@ -42,16 +42,11 @@ module ClickhouseRuby
                when ::String
                  parse_map_string(value)
                else
-                 raise TypeCastError.new(
-                   "Cannot cast #{value.class} to Map",
-                   from_type: value.class.name,
-                   to_type: to_s,
-                   value: value
-                 )
+                 raise_cast_error(value, "Cannot cast #{value.class} to Map")
                end
 
         hash.transform_keys { |k| @key_type.cast(k) }
-            .transform_values { |v| @value_type.cast(v) }
+          .transform_values { |v| @value_type.cast(v) }
       end
 
       # Converts a value from ClickHouse to a Ruby Hash
@@ -71,7 +66,7 @@ module ClickhouseRuby
                end
 
         hash.transform_keys { |k| @key_type.deserialize(k) }
-            .transform_values { |v| @value_type.deserialize(v) }
+          .transform_values { |v| @value_type.deserialize(v) }
       end
 
       # Converts a hash to SQL literal
@@ -79,13 +74,13 @@ module ClickhouseRuby
       # @param value [Hash, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         pairs = value.map do |k, v|
           "#{@key_type.serialize(k)}: #{@value_type.serialize(v)}"
         end
 
-        "{#{pairs.join(', ')}}"
+        "{#{pairs.join(", ")}}"
       end
 
       # Returns the full type string including key and value types
@@ -105,16 +100,11 @@ module ClickhouseRuby
         stripped = value.strip
 
         # Handle empty map
-        return {} if stripped == '{}'
+        return {} if stripped == "{}"
 
         # Remove outer braces
-        unless stripped.start_with?('{') && stripped.end_with?('}')
-          raise TypeCastError.new(
-            "Invalid map format: '#{value}'",
-            from_type: 'String',
-            to_type: to_s,
-            value: value
-          )
+        unless stripped.start_with?("{") && stripped.end_with?("}")
+          raise_format_error(value, "map")
         end
 
         inner = stripped[1...-1]
@@ -130,7 +120,7 @@ module ClickhouseRuby
       # @return [Hash] the parsed pairs
       def parse_pairs(str)
         result = {}
-        current = ''
+        current = ""
         depth = 0
         in_string = false
         escape_next = false
@@ -143,23 +133,23 @@ module ClickhouseRuby
           end
 
           case char
-          when '\\'
+          when "\\"
             escape_next = true
             current += char
           when "'"
             in_string = !in_string
             current += char
-          when '{', '[', '('
+          when "{", "[", "("
             depth += 1 unless in_string
             current += char
-          when '}', ']', ')'
+          when "}", "]", ")"
             depth -= 1 unless in_string
             current += char
-          when ','
+          when ","
             if depth.zero? && !in_string
               key, value = parse_pair(current.strip)
               result[key] = value
-              current = ''
+              current = ""
             else
               current += char
             end
@@ -183,15 +173,10 @@ module ClickhouseRuby
       # @return [Array] [key, value]
       def parse_pair(str)
         # Find the colon separator (not inside quotes or nested structures)
-        colon_idx = find_separator(str, ':')
+        colon_idx = find_separator(str, ":")
 
         if colon_idx.nil?
-          raise TypeCastError.new(
-            "Invalid map pair format: '#{str}'",
-            from_type: 'String',
-            to_type: to_s,
-            value: str
-          )
+          raise_format_error(str, "map pair")
         end
 
         key = parse_value(str[0...colon_idx].strip)
@@ -217,13 +202,13 @@ module ClickhouseRuby
           end
 
           case char
-          when '\\'
+          when "\\"
             escape_next = true
           when "'"
             in_string = !in_string
-          when '{', '[', '('
+          when "{", "[", "("
             depth += 1 unless in_string
-          when '}', ']', ')'
+          when "}", "]", ")"
             depth -= 1 unless in_string
           when sep
             return idx if depth.zero? && !in_string

data/lib/clickhouse_ruby/types/null_safe.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Provides automatic null handling for type classes
+    #
+    # When included, wraps cast, deserialize, and serialize methods
+    # to handle nil values automatically. Subclasses implement
+    # cast_value, deserialize_value, and serialize_value instead.
+    #
+    # @example
+    #   class Integer < Base
+    #     include NullSafe
+    #
+    #     protected
+    #
+    #     def cast_value(value)
+    #       # value is guaranteed non-nil here
+    #       value.to_i
+    #     end
+    #   end
+    #
+    module NullSafe
+      # Converts a Ruby value, returning nil for nil input
+      #
+      # @param value [Object] the value to cast
+      # @return [Object, nil] the cast value or nil
+      def cast(value)
+        return nil if value.nil?
+
+        cast_value(value)
+      end
+
+      # Deserializes a value from ClickHouse, returning nil for nil input
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Object, nil] the deserialized value or nil
+      def deserialize(value)
+        return nil if value.nil?
+
+        deserialize_value(value)
+      end
+
+      # Serializes a value for ClickHouse, returning "NULL" for nil input
+      #
+      # @param value [Object] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return "NULL" if value.nil?
+
+        serialize_value(value)
+      end
+
+      protected
+
+      # Override in subclass - actual casting logic (value guaranteed non-nil)
+      #
+      # @param value [Object] the non-nil value to cast
+      # @return [Object] the cast value
+      def cast_value(value)
+        value
+      end
+
+      # Override in subclass - actual deserialization logic (value guaranteed non-nil)
+      #
+      # @param value [Object] the non-nil value to deserialize
+      # @return [Object] the deserialized value
+      def deserialize_value(value)
+        value
+      end
+
+      # Override in subclass - actual serialization logic (value guaranteed non-nil)
+      #
+      # @param value [Object] the non-nil value to serialize
+      # @return [String] the SQL literal
+      def serialize_value(value)
+        value.to_s
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/nullable.rb

@@ -21,7 +21,7 @@ module ClickhouseRuby
       # @param element_type [Base] the wrapped type
       def initialize(name, element_type: nil)
         super(name)
-        @element_type = element_type || Base.new('String')
+        @element_type = element_type || Base.new("String")
       end
 
       # Converts a Ruby value, allowing nil
@@ -50,7 +50,7 @@ module ClickhouseRuby
       # @param value [Object, nil] the value to serialize
       # @return [String] the SQL literal
       def serialize(value)
-        return 'NULL' if value.nil?
+        return "NULL" if value.nil?
 
         @element_type.serialize(value)
       end

data/lib/clickhouse_ruby/types/parser.rb

@@ -58,12 +58,12 @@ module ClickhouseRuby
       # @return [Hash] the parsed AST with :type and optional :args keys
       # @raise [ParseError] if the type string is invalid
       def parse(type_string)
-        raise ParseError.new('Type string cannot be nil') if type_string.nil?
+        raise ParseError, "Type string cannot be nil" if type_string.nil?
 
         @input = type_string.strip
         @pos = 0
 
-        raise ParseError.new('Type string cannot be empty', input: type_string) if @input.empty?
+        raise ParseError.new("Type string cannot be empty", input: type_string) if @input.empty?
 
         result = parse_type
         skip_whitespace
@@ -84,6 +84,7 @@ module ClickhouseRuby
       # - Type names: String, UInt64
       # - Numeric literals: 3 (precision), 9 (scale)
       # - String literals: 'UTC' (timezone)
+      # - Enum entries: 'active' = 1 (for Enum8/Enum16)
       #
       # @return [Hash] the parsed type/value
       def parse_type
@@ -95,19 +96,32 @@ module ClickhouseRuby
           return { type: value }
         end
 
-        # Handle string literals (e.g., DateTime64(3, 'UTC'))
+        # Handle string literals (e.g., DateTime64(3, 'UTC') or Enum8('active' = 1))
         if peek == "'"
           value = parse_string_literal
+          skip_whitespace
+          # Handle Enum value assignment: 'name' = value (or 'name' = -1)
+          if peek == "="
+            consume("=")
+            skip_whitespace
+            # Skip optional negative sign
+            if peek == "-"
+              @pos += 1
+              skip_whitespace
+            end
+            # Skip the numeric value
+            parse_numeric if numeric_char?(peek)
+          end
           return { type: value }
         end
 
         name = parse_identifier
 
         skip_whitespace
-        if peek == '('
-          consume('(')
+        if peek == "("
+          consume("(")
           args = parse_type_list
-          consume(')')
+          consume(")")
           { type: name, args: args }
         else
           { type: name }
@@ -122,12 +136,12 @@ module ClickhouseRuby
         skip_whitespace
 
         # Handle empty argument list
-        return types if peek == ')'
+        return types if peek == ")"
 
         types << parse_type
 
-        while peek == ','
-          consume(',')
+        while peek == ","
+          consume(",")
           types << parse_type
         end
 
@@ -144,15 +158,13 @@ module ClickhouseRuby
 
         # First character must be letter or underscore
         unless @pos < @input.length && identifier_start_char?(@input[@pos])
-          raise ParseError.new('Expected type name', position: @pos, input: @input)
+          raise ParseError.new("Expected type name", position: @pos, input: @input)
         end
 
         @pos += 1
 
         # Subsequent characters can be letters, digits, or underscores
-        while @pos < @input.length && identifier_char?(@input[@pos])
-          @pos += 1
-        end
+        @pos += 1 while @pos < @input.length && identifier_char?(@input[@pos])
 
         @input[start_pos...@pos]
       end
@@ -187,9 +199,7 @@ module ClickhouseRuby
       def parse_numeric
         start_pos = @pos
 
-        while @pos < @input.length && numeric_char?(@input[@pos])
-          @pos += 1
-        end
+        @pos += 1 while @pos < @input.length && numeric_char?(@input[@pos])
 
         @input[start_pos...@pos]
       end
@@ -203,7 +213,7 @@ module ClickhouseRuby
 
         while @pos < @input.length && @input[@pos] != "'"
           # Handle escaped quotes
-          @pos += 1 if @input[@pos] == '\\' && @pos + 1 < @input.length
+          @pos += 1 if @input[@pos] == "\\" && @pos + 1 < @input.length
           @pos += 1
         end
 
@@ -226,7 +236,7 @@ module ClickhouseRuby
       # @raise [ParseError] if the character doesn't match
       def consume(expected)
         skip_whitespace
-        actual = @pos < @input.length ? @input[@pos] : 'end of input'
+        actual = @pos < @input.length ? @input[@pos] : "end of input"
 
         unless actual == expected
           raise ParseError.new("Expected '#{expected}', got '#{actual}'", position: @pos, input: @input)