familia 2.0.0.pre17 → 2.0.0.pre18

data/lib/familia/horreum/serialization.rb

@@ -7,21 +7,20 @@ module Familia
     module Serialization
       # Converts the object's persistent fields to a hash for external use.
       #
-      # Serializes persistent field values for external consumption (APIs, logs),
-      # excluding non-loggable fields like encrypted fields for security.
-      # Only non-nil values are included in the resulting hash.
+      # Returns actual Ruby values (String, Integer, Hash, etc.) for API consumption,
+      # NOT JSON-encoded strings. Excludes non-loggable fields like encrypted fields
+      # for security.
       #
-      # @return [Hash] Hash with field names as keys and serialized values
-      #   safe for external exposure
+      # @return [Hash] Hash with field names as string keys and Ruby values
       #
       # @example Converting an object to hash format for API response
       #   user = User.new(name: "John", email: "john@example.com", age: 30)
       #   user.to_h
-      #   # => {"name"=>"John", "email"=>"john@example.com", "age"=>"30"}
-      #   # encrypted fields are excluded for security
+      #   # => {"name"=>"John", "email"=>"john@example.com", "age"=>30}
+      #   # Note: Returns actual Ruby types, not JSON strings
       #
-      # @note Only loggable fields are included for security
-      # @note Only fields with non-nil values are included
+      # @note Only loggable fields are included. Encrypted fields are excluded.
+      # @note Nil values are excluded from the returned hash (storage optimization)
       #
       def to_h
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
@@ -30,40 +29,45 @@ module Familia
           # Security: Skip non-loggable fields (e.g., encrypted fields)
           next unless field_type.loggable
 
-          method_name = field_type.method_name
-          val = send(method_name)
-          prepared = serialize_value(val)
-          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+          val = send(field_type.method_name)
+          Familia.ld " [to_h] field: #{field} val: #{val.class}"
 
-          # Only include non-nil values in the hash for Valkey
-          # Use string key for database compatibility
-          hsh[field.to_s] = prepared unless prepared.nil?
+          # Use string key for external API compatibility
+          # Return Ruby values, not JSON-encoded strings
+          hsh[field.to_s] = val
         end
       end
 
       # Converts the object's persistent fields to a hash for database storage.
       #
-      # Serializes ALL persistent field values for database storage, including
-      # encrypted fields. This is used internally by commit_fields and other
-      # persistence operations.
+      # Returns JSON-encoded strings for ALL persistent field values, ready for
+      # Redis storage. Unlike to_h, this includes encrypted fields and serializes
+      # values using serialize_value (JSON encoding).
+      #
+      # @return [Hash] Hash with field names as string keys and JSON-encoded values
       #
-      # @return [Hash] Hash with field names as keys and serialized values
-      #   ready for database storage
+      # @example Internal storage preparation
+      #   user = User.new(name: "John", age: 30)
+      #   user.to_h_for_storage
+      #   # => {"name"=>"\"John\"", "age"=>"30"}
+      #   # Note: Strings are JSON-encoded with quotes
       #
-      # @note Includes ALL persistent fields, including encrypted fields
-      # @note Only fields with non-nil values are included for storage efficiency
+      # @note This is an internal method used by commit_fields and hmset
+      # @note Nil values are excluded to optimize Redis storage
       #
       def to_h_for_storage
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
           field_type = self.class.field_types[field]
-          method_name = field_type.method_name
-          val = send(method_name)
+
+          val = send(field_type.method_name)
           prepared = serialize_value(val)
-          Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
 
-          # Only include non-nil values in the hash for Valkey
+          if Familia.debug?
+            Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+          end
+
           # Use string key for database compatibility
-          hsh[field.to_s] = prepared unless prepared.nil?
+          hsh[field.to_s] = prepared
         end
       end
 
@@ -84,7 +88,7 @@ module Familia
       #   methods to maintain data consistency across operations.
       #
       def to_a
-        self.class.persistent_fields.filter_map do |field|
+        self.class.persistent_fields.map do |field|
           field_type = self.class.field_types[field]
 
           # Security: Skip non-loggable fields (e.g., encrypted fields)
@@ -92,80 +96,94 @@ module Familia
 
           method_name = field_type.method_name
           val = send(method_name)
-          prepared = serialize_value(val)
-          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class} prepared: #{prepared.class}"
-          prepared
+          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
+
+          # Return actual Ruby values, including nil to maintain array positions
+          val
         end
       end
 
       # Serializes a Ruby object for Valkey storage.
       #
-      # Converts Ruby objects into the DB-compatible string representations using
-      # the Familia distinguisher for type coercion. Falls back to JSON serialization
-      # for complex types (Hash, Array) when the primary distinguisher returns nil.
+      # Converts ALL Ruby values (including strings) to JSON-encoded strings for
+      # type-safe storage. This ensures round-trip type preservation: the type you
+      # save is the type you get back.
       #
       # The serialization process:
-      # 1. Attempts conversion using Familia.distinguisher with relaxed type checking
-      # 2. For Hash/Array types that return nil, tries custom dump_method or Familia::JsonSerializer.dump
-      # 3. Logs warnings when serialization fails completely
+      # 1. ConcealedStrings (encrypted values) → extract encrypted_value
+      # 2. ALL other types → JSON serialization (String, Integer, Boolean, Float, nil, Hash, Array)
       #
       # @param val [Object] The Ruby object to serialize for Valkey storage
       #
-      # @return [String, nil] The serialized value ready for Valkey storage, or nil
-      #   if serialization failed
+      # @return [String] JSON-encoded string representation
+      #
+      # @example Type preservation through JSON encoding
+      #   serialize_value("007")           # => "\"007\"" (JSON string)
+      #   serialize_value(123)             # => "123" (JSON number)
+      #   serialize_value(true)            # => "true" (JSON boolean)
+      #   serialize_value({a: 1})          # => "{\"a\":1}" (JSON object)
       #
-      # @example Serializing different data types
-      #   serialize_value("hello")        # => "hello"
-      #   serialize_value(42)             # => "42"
-      #   serialize_value({name: "John"}) # => '{"name":"John"}'
-      #   serialize_value([1, 2, 3])      # => "[1,2,3]"
+      # @note Strings are JSON-encoded to prevent type coercion bugs where
+      #   string "123" would be indistinguishable from integer 123 in storage
       #
       # @note This method integrates with Familia's type system and supports
       #   custom serialization methods when available on the object
       #
-      # @see Familia.distinguisher The primary serialization mechanism
+      # @see Familia.identifier_extractor For extracting identifiers from Familia objects
       #
       def serialize_value(val)
         # Security: Handle ConcealedString safely - extract encrypted data for storage
         return val.encrypted_value if val.respond_to?(:encrypted_value)
 
-        prepared = Familia.distinguisher(val, strict_values: false)
-
-        # If the distinguisher returns nil, try using the dump_method but only
-        # use JSON serialization for complex types that need it.
-        if prepared.nil? && (val.is_a?(Hash) || val.is_a?(Array))
-          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : Familia::JsonSerializer.dump(val)
-        end
-
-        # If both the distinguisher and dump_method return nil, log an error
-        Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}" if prepared.nil?
-
-        prepared
+        # ALWAYS write valid JSON for type preservation
+        # This includes strings, which get JSON-encoded with wrapping quotes
+        Familia::JsonSerializer.dump(val)
       end
 
-      # Converts a Database string value back to its original Ruby type
+      # Converts a Redis string value back to its original Ruby type
+      #
+      # This method deserializes JSON strings back to their original Ruby types
+      # (Integer, Boolean, Float, nil, Hash, Array). Plain strings that cannot
+      # be parsed as JSON are returned as-is.
       #
-      # This method attempts to deserialize JSON strings back to their original
-      # Hash or Array types. Simple string values are returned as-is.
+      # This pairs with serialize_value which JSON-encodes all non-string values.
+      # The contract ensures type preservation across Redis storage:
+      # - Strings stored as-is → returned as-is
+      # - All other types JSON-encoded → JSON-decoded back to original type
       #
-      # @param val [String] The string value from Database to deserialize
-      # @param symbolize [Boolean] Whether to symbolize hash keys (default: true for compatibility)
-      # @return [Object] The deserialized value (Hash, Array, or original string)
+      # @param val [String] The string value from Redis to deserialize
+      # @param symbolize [Boolean] Whether to symbolize hash keys (default: false)
+      # @param field_name [Symbol, nil] Optional field name for better error context
+      # @return [Object] The deserialized value with original Ruby type, or the original string if not JSON
       #
-      def deserialize_value(val, symbolize: true)
-        return val if val.nil? || val == ''
+      def deserialize_value(val, symbolize: false, field_name: nil)
+        return nil if val.nil? || val == ''
 
-        # Try to parse as JSON first for complex types
         begin
-          parsed = Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
-          # Only return parsed value if it's a complex type (Hash/Array)
-          # Simple values should remain as strings
-          return parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
+          Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
         rescue Familia::SerializerError
-          # Not valid JSON, return as-is
+          log_deserialization_issue(val, field_name)
+          val
+        end
+      end
+
+      private
+
+      def log_deserialization_issue(val, field_name)
+        context = field_name ? "#{self.class}##{field_name}" : self.class.to_s
+        dbkey_info = respond_to?(:dbkey) ? dbkey : 'no dbkey'
+
+        msg = if looks_like_json?(val)
+          "Corrupted JSON in #{context}: #{val.inspect} (#{dbkey_info})"
+        else
+          "Legacy plain string in #{context}: #{val.inspect} (#{dbkey_info})"
         end
 
-        val
+        Familia.le(msg)
+      end
+
+      def looks_like_json?(val)
+        val.start_with?('{', '[', '"') || %w[true false null].include?(val)
       end
     end
   end

data/lib/familia/horreum.rb

@@ -299,7 +299,9 @@ module Familia
 
     def initialize_with_keyword_args_deserialize_value(**fields)
       # Deserialize Database string values back to their original types
-      deserialized_fields = fields.transform_values { |value| deserialize_value(value) }
+      deserialized_fields = fields.each_with_object({}) do |(field_name, value), hsh|
+        hsh[field_name] = deserialize_value(value, field_name: field_name)
+      end
       initialize_with_keyword_args(**deserialized_fields)
     end
 
@@ -308,7 +310,7 @@ module Familia
     #
     # This method is part of horreum.rb rather than serialization.rb because it
     # operates solely on the provided values and doesn't query Database or other
-    # external sources. That's why it's called "optimistic" refresh: it assumes
+    # external sources. That's why it's called "naive" refresh: it assumes
     # the provided values are correct and updates the object accordingly.
     #
     # @see #refresh!
@@ -316,8 +318,8 @@ module Familia
     # @param fields [Hash] A hash of field names and their new values to update
     #   the object with.
     # @return [Array] The list of field names that were updated.
-    def optimistic_refresh(**fields)
-      Familia.ld "[optimistic_refresh] #{self.class} #{dbkey} #{fields.keys}"
+    def naive_refresh(**fields)
+      Familia.ld "[naive_refresh] #{self.class} #{dbkey} #{fields.keys}"
       initialize_with_keyword_args_deserialize_value(**fields)
     end
 
@@ -401,8 +403,10 @@ module Familia
       self.class.fields.filter_map do |field|
         # Database will give us field names as strings back, but internally
         # we use symbols. So we check for both.
-        value = fields[field.to_sym] || fields[field.to_s]
-        if value
+        # Use fetch with default to avoid || operator which skips false values
+        value = fields.fetch(field.to_sym) { fields[field.to_s] }
+        # Check for nil explicitly to allow false and 0 values
+        unless value.nil?
           # Use the mapped method name, not the field name
           method_name = self.class.field_method_map[field] || field
           send(:"#{method_name}=", value)

data/lib/familia/identifier_extractor.rb

@@ -0,0 +1,60 @@
+# lib/familia/identifier_extractor.rb
+
+module Familia
+  # IdentifierExtractor - Extracts identifiers from Familia objects for storage
+  #
+  # This module provides a focused mechanism for converting object references
+  # into Redis-storable strings. It handles two primary cases:
+  #
+  # 1. Class references: Customer → "Customer"
+  # 2. Familia::Base instances: customer_obj → customer_obj.identifier
+  #
+  # This is primarily used by DataType serialization when storing object
+  # references in Redis data structures (lists, sets, zsets). It extracts
+  # the identifier rather than serializing the entire object.
+  #
+  # @example With class_zset
+  #   class Customer < Familia::Horreum
+  #     class_zset :instances, class: self
+  #   end
+  #   # When adding: Customer.instances.add(customer_obj)
+  #   # Stores: customer_obj.identifier (e.g., "customer_123")
+  #
+  module IdentifierExtractor
+    # Extracts a Redis-storable identifier from a Familia object or class.
+    #
+    # @param value [Object] The value to extract an identifier from
+    # @return [String] The extracted identifier or class name
+    # @raise [Familia::NotDistinguishableError] If value is not a Class or Familia::Base
+    #
+    def identifier_extractor(value, strict_values: true)
+      case value
+      when ::Symbol, ::String, ::Integer, ::Float
+        Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'simple_value' if Familia.debug?
+        # DataTypes (lists, sets, zsets) can store simple values directly
+        # Convert to string for Redis storage
+        value.to_s
+
+      when Class
+        Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'class' if Familia.debug?
+        value.name
+
+      when Familia::Base
+        Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'base_instance' if Familia.debug?
+        value.identifier
+
+      else
+        # Check if value's class inherits from Familia::Base
+        if value.class.ancestors.member?(Familia::Base)
+          Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'base_ancestor' if Familia.debug?
+          value.identifier
+        else
+          Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'error' if Familia.debug?
+          raise Familia::NotDistinguishableError, value
+        end
+      end
+    end
+  end
+
+  extend IdentifierExtractor
+end