familia 2.0.0.pre16 → 2.0.0.pre17

data/lib/familia/horreum/serialization.rb

@@ -0,0 +1,172 @@
+# lib/familia/horreum/serialization.rb
+
+module Familia
+  class Horreum
+    # Serialization - Instance-level methods for object serialization
+    # Handles conversion between Ruby objects and Valkey hash storage
+    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.
+      #
+      # @return [Hash] Hash with field names as keys and serialized values
+      #   safe for external exposure
+      #
+      # @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
+      #
+      # @note Only loggable fields are included for security
+      # @note Only fields with non-nil values are included
+      #
+      def to_h
+        self.class.persistent_fields.each_with_object({}) do |field, hsh|
+          field_type = self.class.field_types[field]
+
+          # 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]'}"
+
+          # Only include non-nil values in the hash for Valkey
+          # Use string key for database compatibility
+          hsh[field.to_s] = prepared unless prepared.nil?
+        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.
+      #
+      # @return [Hash] Hash with field names as keys and serialized values
+      #   ready for database storage
+      #
+      # @note Includes ALL persistent fields, including encrypted fields
+      # @note Only fields with non-nil values are included for storage efficiency
+      #
+      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)
+          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
+          # Use string key for database compatibility
+          hsh[field.to_s] = prepared unless prepared.nil?
+        end
+      end
+
+      # Converts the object's persistent fields to an array.
+      #
+      # Serializes all persistent field values in field definition order,
+      # preparing them for Valkey storage. Each value is processed through
+      # the serialization pipeline to ensure Valkey compatibility.
+      #
+      # @return [Array] Array of serialized field values in field order
+      #
+      # @example Converting an object to array format
+      #   user = User.new(name: "John", email: "john@example.com", age: 30)
+      #   user.to_a
+      #   # => ["John", "john@example.com", "30"]
+      #
+      # @note Values are serialized using the same process as other persistence
+      #   methods to maintain data consistency across operations.
+      #
+      def to_a
+        self.class.persistent_fields.filter_map do |field|
+          field_type = self.class.field_types[field]
+
+          # 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_a] field: #{field} method: #{method_name} val: #{val.class} prepared: #{prepared.class}"
+          prepared
+        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.
+      #
+      # 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
+      #
+      # @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
+      #
+      # @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 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
+      #
+      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
+      end
+
+      # Converts a Database string value back to its original Ruby type
+      #
+      # This method attempts to deserialize JSON strings back to their original
+      # Hash or Array types. Simple string values are returned as-is.
+      #
+      # @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)
+      #
+      def deserialize_value(val, symbolize: true)
+        return val 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)
+        rescue Familia::SerializerError
+          # Not valid JSON, return as-is
+        end
+
+        val
+      end
+    end
+  end
+end

data/lib/familia/horreum.rb

@@ -1,9 +1,14 @@
 # lib/familia/horreum.rb
 
-require_relative 'horreum/subclass/definition'
-require_relative 'horreum/subclass/management'
-require_relative 'horreum/shared/settings'
-require_relative 'horreum/core'
+require_relative 'horreum/settings'
+require_relative 'horreum/connection'
+require_relative 'horreum/database_commands'
+require_relative 'horreum/related_fields'
+require_relative 'horreum/definition'
+require_relative 'horreum/management'
+require_relative 'horreum/persistence'
+require_relative 'horreum/serialization'
+require_relative 'horreum/utils'
 
 module Familia
   #
@@ -44,8 +49,12 @@ module Familia
   #
   class Horreum
     include Familia::Base
-    include Familia::Horreum::Core
+    include Familia::Horreum::Persistence
+    include Familia::Horreum::Serialization
+    include Familia::Horreum::Connection
+    include Familia::Horreum::DatabaseCommands
     include Familia::Horreum::Settings
+    include Familia::Horreum::Utils
 
     using Familia::Refinements::TimeLiterals
 
@@ -223,6 +232,15 @@ module Familia
       init
     end
 
+    # Override this method in subclasses for custom initialization logic.
+    # This is called AFTER fields are set and relatives are initialized.
+    #
+    # DO NOT override initialize() - use this init() hook instead.
+    #
+    # Example:
+    #   def init(name = nil)
+    #     @name = name || SecureRandom.hex(4)
+    #   end
     def init(*args, **kwargs)
       # Default no-op
     end
@@ -233,6 +251,8 @@ module Familia
     # This needs to be called in the initialize method.
     #
     def initialize_relatives
+      # Store initialization flag on singleton class to avoid polluting instance variables
+      return if singleton_class.instance_variable_defined?(:"@relatives_initialized")
       # Generate instances of each DataType. These need to be
       # unique for each instance of this class so they can piggyback
       # on the specifc index of this instance.
@@ -272,6 +292,9 @@ module Familia
         # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
         instance_variable_set :"@#{name}", related_object
       end
+
+      # Mark relatives as initialized on singleton class to avoid polluting instance variables
+      singleton_class.instance_variable_set(:"@relatives_initialized", true)
     end
 
     def initialize_with_keyword_args_deserialize_value(**fields)
@@ -311,7 +334,7 @@ module Familia
                     send(definition)
                   when Proc
                     definition.call(self)
-                  end
+      end
 
       # Return nil for unpopulated identifiers (like unsaved ActiveRecord objects)
       # Only raise errors when the identifier is actually needed for db operations
@@ -331,7 +354,6 @@ module Familia
     # @return [Redis] the Database connection instance.
     #
 
-
     def generate_id
       @objid ||= Familia.generate_id
     end
@@ -390,6 +412,5 @@ module Familia
     end
 
     # Builds the instance-level connection chain with handlers in priority order
-
   end
 end

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre16'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre17'.freeze unless defined?(Familia::VERSION)
 end

data/try/configuration/scenarios_try.rb

@@ -28,7 +28,7 @@ end
 begin
   # Test with custom URI
   original_uri = Familia.uri
-  test_uri = 'redis://localhost:6379/10'
+  test_uri = 'redis://localhost:2525/10'
 
   Familia.uri = test_uri
   current_uri = Familia.uri

data/try/core/connection_try.rb

@@ -12,10 +12,10 @@ Familia.uri
 
 ## Default URI points to localhost database server
 Familia.uri.to_s
-#=> "redis://127.0.0.1"
+#=> "redis://127.0.0.1:2525"
 
 ## Can parse URI from string
-uri = URI.parse('redis://localhost:6379/1')
+uri = URI.parse('redis://localhost:2525/1')
 uri.host
 #=> "localhost"
 
@@ -29,7 +29,7 @@ Familia.connect
 
 ## Can create connection to different URI
 ## Doesn't confirm the logical DB number, dbclient.options raises an error?
-test_uri = 'redis://localhost:6379/2'
+test_uri = 'redis://localhost:2525/2'
 Familia.create_dbclient(test_uri)
 #=:> Redis
 
@@ -48,7 +48,7 @@ Familia.enable_database_counter
 #=> true
 
 ## Middleware gets registered when enabled
-dbclient = Familia.create_dbclient('redis://localhost:6379/3')
+dbclient = Familia.create_dbclient('redis://localhost:2525/2')
 dbclient.ping
 #=> "PONG"
 

data/try/core/database_consistency_try.rb

@@ -214,6 +214,7 @@ exists_after_batch = @batch_obj.exists?
 
 ## Transient fields don't affect exists? behavior
 class TransientConsistencyTest < Familia::Horreum
+  feature :transient_fields
   identifier_field :id
   field :id
   field :name

data/try/core/errors_try.rb

@@ -40,16 +40,16 @@ raise Familia::NotDistinguishableError, 'A customized message'
 #=~> /A customized message/
 
 ## NotConnected error stores URI
-test_uri = URI.parse('redis://localhost:6379')
+test_uri = URI.parse('redis://localhost:2525')
 begin
   raise Familia::NotConnected.new(test_uri)
 rescue Familia::NotConnected => e
   e.uri.to_s
 end
-#=> "redis://localhost"
+#=> "redis://localhost:2525"
 
 ## NotConnected error has custom message
-test_uri = URI.parse('redis://localhost:6379')
+test_uri = URI.parse('redis://localhost:2525')
 begin
   raise Familia::NotConnected.new(test_uri)
 rescue Familia::NotConnected => e

data/try/core/familia_try.rb

@@ -12,7 +12,7 @@ Familia.uri
 
 ## Familia has a uri as a string
 Familia.uri.to_s
-#=> 'redis://127.0.0.1'
+#=> 'redis://127.0.0.1:2525'
 
 ## Familia has a url, an alias to uri
 Familia.url.eql?(Familia.uri)

data/try/core/isolated_dbclient_try.rb

@@ -8,7 +8,7 @@
 require_relative '../helpers/test_helpers'
 
 # Clean up any existing test data in all test databases
-(0..15).each do |db|
+(0..2).each do |db|
   Familia.with_isolated_dbclient(db) do |client|
     client.flushdb
   end
@@ -143,7 +143,7 @@ result
 #=> "seven"
 
 ## isolated_dbclient with String URI argument
-client = Familia.isolated_dbclient("redis://localhost:6379/8")
+client = Familia.isolated_dbclient("redis://localhost:2525/8")
 client.set("uri_test", "eight")
 result = client.get("uri_test")
 client.close

data/try/core/tools_try.rb

@@ -6,8 +6,8 @@ require_relative '../helpers/test_helpers'
 
 ## move_keys across Valkey/Redis instances (if available)
 begin
-  source_redis = Redis.new(db: 10)
-  dest_redis = Redis.new(db: 11)
+  source_redis = Redis.new(db: 1, port: 2525)
+  dest_redis = Redis.new(db: 2, port: 2525)
   source_redis.set('test:key1', 'value1')
   source_redis.set('test:key2', 'value2')