familia 2.0.0.pre17 → 2.0.0.pre18

data/try/support/benchmarks/deserialization_benchmark.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+
+# Benchmark: Field deserialization strategies in find_by_dbkey
+#
+# Compares different approaches to deserializing Redis hash values
+# when loading Horreum objects from the database.
+#
+# Usage:
+#
+#   $ ruby try/support/benchmarks/deserialization_benchmark.rb
+#   ======================================================================
+#   RESULTS SUMMARY (baseline: direct assignment)
+#   ======================================================================
+#
+#   Baseline (no deserialization): 0.151312s
+#
+#   Deserialization strategies:
+#   1. Selective (only JSON-like strings): 0.174016s (1.15x baseline, +15.0% overhead) 🏆 FASTEST
+#   2. Bulk JSON round-trip (parse/dump): 0.183926s (1.22x baseline, +21.6% overhead)
+#   3. Cached instance + transform: 0.320223s (2.12x baseline, +111.6% overhead)
+#   4. Current (field-by-field transform_values): 0.49568s (3.28x baseline, +227.6% overhead)
+
+require_relative '../../../lib/familia'
+require 'benchmark'
+require 'json'
+
+# Setup Redis connection
+Familia.uri = ENV['REDIS_URI'] || 'redis://localhost:2525/3'
+
+# Sample model with various field types
+class BenchmarkUser < Familia::Horreum
+  identifier_field :user_id
+
+  field :user_id
+  field :name
+  field :email
+  field :age
+  field :active
+  field :metadata     # Will store JSON hash
+  field :tags         # Will store JSON array
+  field :created_at   # Will store timestamp
+  field :score        # Will store float
+  field :simple_string
+end
+
+# Create sample data with realistic values
+sample_data = {
+  'user_id' => 'user_12345',
+  'name' => 'John Doe',
+  'email' => 'john.doe@example.com',
+  'age' => '35',
+  'active' => 'true',
+  'metadata' => '{"role":"admin","department":"engineering","level":5}',
+  'tags' => '["ruby","redis","performance","optimization"]',
+  'created_at' => Time.now.to_i.to_s,
+  'score' => '98.7',
+  'simple_string' => 'Just a plain string value',
+}
+
+# Persist sample data to Redis
+user = BenchmarkUser.new(**sample_data)
+user.save
+
+# Get the raw hash data directly from Redis (what find_by_dbkey gets)
+raw_hash = BenchmarkUser.dbclient.hgetall(user.dbkey)
+
+puts 'Benchmarking deserialization strategies'
+puts "Sample data fields: #{raw_hash.keys.size}"
+puts "Raw hash: #{raw_hash.inspect}"
+puts "\n"
+
+# Strategy 1: Current field-by-field with transform_values
+def strategy_current(fields, klass)
+  deserialized = fields.transform_values { |value| klass.new.deserialize_value(value) }
+  klass.new(**deserialized)
+end
+
+# Strategy 2: Bulk JSON round-trip
+def strategy_bulk_json(fields, klass)
+  parsed = JSON.parse(JSON.dump(fields))
+  klass.new(**parsed)
+end
+
+# Strategy 3: Direct assignment without deserialization
+def strategy_direct(fields, klass)
+  klass.new(**fields)
+end
+
+# Strategy 4: Selective deserialization (only JSON-looking strings)
+def strategy_selective(fields, klass)
+  deserialized = fields.transform_values do |value|
+    if value.to_s.start_with?('{', '[')
+      begin
+        JSON.parse(value, symbolize_names: true)
+      rescue JSON::ParserError
+        value
+      end
+    else
+      value
+    end
+  end
+  klass.new(**deserialized)
+end
+
+# Strategy 5: Cached instance + transform
+def strategy_cached_instance(fields, klass)
+  instance = klass.new
+  deserialized = fields.transform_values { |value| instance.deserialize_value(value) }
+  klass.new(**deserialized)
+end
+
+iterations = 10_000
+
+puts "Running #{iterations} iterations per strategy...\n\n"
+
+strategies = {
+  'Current (field-by-field transform_values)' => :strategy_current,
+  'Bulk JSON round-trip (parse/dump)' => :strategy_bulk_json,
+  'Direct (no deserialization)' => :strategy_direct,
+  'Selective (only parse JSON-like strings)' => :strategy_selective,
+  'Cached instance + transform' => :strategy_cached_instance,
+}
+
+results = {}
+
+strategies.each do |name, method_name|
+  time = Benchmark.measure do
+    iterations.times do
+      send(method_name, raw_hash, BenchmarkUser)
+    end
+  end
+  results[name] = time.real
+  puts "#{name}: #{time.real.round(6)} seconds (#{(iterations / time.real).round(0)} ops/sec)"
+end
+
+puts "\n" + ('=' * 70)
+puts 'RESULTS SUMMARY (baseline: direct assignment)'
+puts '=' * 70
+
+# Use direct assignment as baseline (obviously fastest but incorrect)
+baseline = results['Direct (no deserialization)']
+
+# Sort deserialization strategies only (exclude baseline)
+deserialization_strategies = results.reject { |name, _| name == 'Direct (no deserialization)' }
+sorted = deserialization_strategies.sort_by { |_, time| time }
+
+puts "
+Baseline (no deserialization): #{baseline.round(6)}s"
+puts "
+Deserialization strategies:
+"
+
+sorted.each_with_index do |(name, time), index|
+  overhead = ((time / baseline - 1) * 100).round(1)
+  vs_baseline = (time / baseline).round(2)
+  marker = index == 0 ? '🏆 FASTEST' : ''
+  puts "#{index + 1}. #{name}: #{time.round(6)}s (#{vs_baseline}x baseline, +#{overhead}% overhead) #{marker}"
+end
+
+puts "
+" + ('=' * 70)
+puts 'RECOMMENDATIONS'
+puts '=' * 70
+
+puts 'Best strategy depends on your data:'
+puts '  • Mostly simple strings → Direct or Selective'
+puts '  • Mixed types with JSON → Current (field-by-field)'
+puts '  • Heavy JSON payloads → Consider lazy deserialization'
+
+# Cleanup
+user.destroy!
+
+__END__
+
+# Example output expectations:
+#
+# Current approach should be moderately fast
+# Bulk JSON round-trip should be slower (extra serialization step)
+# Direct assignment should be fastest but incorrect for complex types
+# Selective should be fast for simple data, slower for JSON-heavy data

data/try/support/benchmarks/deserialization_correctness_test.rb

@@ -0,0 +1,237 @@
+#!/usr/bin/env ruby
+
+# Correctness Test: Field deserialization strategies
+#
+# Verifies that different deserialization approaches produce identical
+# results for all field types (strings, numbers, JSON, nested structures).
+#
+# Usage:
+#   $ try/support/benchmarks/deserialization_correctness_test.rb
+#
+
+require_relative '../../../lib/familia'
+require 'json'
+
+# Setup Redis connection
+Familia.uri = ENV['REDIS_URI'] || 'redis://localhost:2525/3'
+
+# Sample model with various field types
+class CorrectnessTestUser < Familia::Horreum
+  identifier_field :user_id
+
+  field :user_id
+  field :name
+  field :email
+  field :age
+  field :active
+  field :metadata     # Will store JSON hash
+  field :tags         # Will store JSON array
+  field :created_at   # Will store timestamp
+  field :score        # Will store float
+  field :simple_string
+  field :nested_data  # Will store deeply nested JSON
+  field :empty_string
+  field :nil_value
+end
+
+# Create sample data with comprehensive test cases
+sample_data = {
+  'user_id' => 'user_12345',
+  'name' => 'John Doe',
+  'email' => 'john.doe@example.com',
+  'age' => '35',
+  'active' => 'true',
+  'metadata' => '{"role":"admin","department":"engineering","level":5}',
+  'tags' => '["ruby","redis","performance","optimization"]',
+  'created_at' => Time.now.to_i.to_s,
+  'score' => '98.7',
+  'simple_string' => 'Just a plain string value',
+  'nested_data' => '{"user":{"profile":{"settings":{"theme":"dark","notifications":true}}}}',
+  'empty_string' => '',
+  'nil_value' => nil,
+}
+
+# Persist sample data to Redis
+user = CorrectnessTestUser.new(**sample_data)
+user.save
+
+# Get the raw hash data directly from Redis
+raw_hash = CorrectnessTestUser.dbclient.hgetall(user.dbkey)
+
+puts 'Correctness Test: Deserialization Strategies'
+puts '=' * 70
+puts "\nTesting with #{raw_hash.keys.size} fields"
+puts "\n"
+
+# Strategy 1: Current field-by-field (reference implementation)
+def strategy_current(fields, klass)
+  deserialized = fields.transform_values { |value| klass.new.deserialize_value(value) }
+  klass.new(**deserialized)
+end
+
+# Strategy 2: Bulk JSON round-trip
+def strategy_bulk_json(fields, klass)
+  parsed = JSON.parse(JSON.dump(fields))
+  klass.new(**parsed)
+end
+
+# Strategy 3: Selective deserialization (only JSON-looking strings)
+def strategy_selective(fields, klass)
+  deserialized = fields.transform_values do |value|
+    if value.to_s.start_with?('{', '[')
+      begin
+        JSON.parse(value, symbolize_names: true)
+      rescue JSON::ParserError
+        value
+      end
+    else
+      value
+    end
+  end
+  klass.new(**deserialized)
+end
+
+# Create objects using each strategy
+current_obj = strategy_current(raw_hash, CorrectnessTestUser)
+bulk_obj = strategy_bulk_json(raw_hash, CorrectnessTestUser)
+selective_obj = strategy_selective(raw_hash, CorrectnessTestUser)
+
+# Test helper to compare field values
+def compare_values(field, current_val, test_val, strategy_name)
+  current_class = current_val.class
+  test_class = test_val.class
+
+  if current_val == test_val && current_class == test_class
+    { status: :pass, field: field, strategy: strategy_name }
+  else
+    {
+      status: :fail,
+      field: field,
+      strategy: strategy_name,
+      current: { value: current_val.inspect, class: current_class },
+      test: { value: test_val.inspect, class: test_class },
+    }
+  end
+end
+
+# Run correctness tests
+results = []
+fields_to_test = CorrectnessTestUser.fields
+
+puts "Testing #{fields_to_test.size} fields across strategies...\n\n"
+
+# Test Bulk JSON strategy
+puts 'Strategy: Bulk JSON round-trip'
+puts '-' * 70
+fields_to_test.each do |field|
+  current_val = current_obj.send(field)
+  test_val = bulk_obj.send(field)
+  result = compare_values(field, current_val, test_val, 'Bulk JSON')
+  results << result
+
+  if result[:status] == :pass
+    puts "  ✓ #{field}: #{test_val.inspect} (#{test_val.class})"
+  else
+    puts "  ✗ #{field}: MISMATCH"
+    puts "    Current: #{result[:current][:value]} (#{result[:current][:class]})"
+    puts "    Bulk:    #{result[:test][:value]} (#{result[:test][:class]})"
+  end
+end
+
+puts "\n"
+
+# Test Selective strategy
+puts 'Strategy: Selective (only JSON-like strings)'
+puts '-' * 70
+fields_to_test.each do |field|
+  current_val = current_obj.send(field)
+  test_val = selective_obj.send(field)
+  result = compare_values(field, current_val, test_val, 'Selective')
+  results << result
+
+  if result[:status] == :pass
+    puts "  ✓ #{field}: #{test_val.inspect} (#{test_val.class})"
+  else
+    puts "  ✗ #{field}: MISMATCH"
+    puts "    Current:   #{result[:current][:value]} (#{result[:current][:class]})"
+    puts "    Selective: #{result[:test][:value]} (#{result[:test][:class]})"
+  end
+end
+
+puts "\n" + ('=' * 70)
+puts 'SUMMARY'
+puts '=' * 70
+
+# Group results by strategy
+by_strategy = results.group_by { |r| r[:strategy] }
+
+by_strategy.each do |strategy, strategy_results|
+  passed = strategy_results.count { |r| r[:status] == :pass }
+  failed = strategy_results.count { |r| r[:status] == :fail }
+  total = strategy_results.size
+
+  status_icon = failed == 0 ? '✓' : '✗'
+  puts "\n#{status_icon} #{strategy}: #{passed}/#{total} passed"
+
+  next unless failed > 0
+
+  puts '  Failed fields:'
+  strategy_results.select { |r| r[:status] == :fail }.each do |result|
+    puts "    - #{result[:field]}"
+  end
+end
+
+# Overall assessment
+all_passed = results.all? { |r| r[:status] == :pass }
+
+puts "\n" + ('=' * 70)
+puts 'VERDICT'
+puts '=' * 70
+
+if all_passed
+  puts '✓ All strategies produce identical results to current implementation'
+  puts '  Safe to use for optimization'
+else
+  puts '✗ Some strategies produce different results'
+  puts '  Review failures before implementing'
+end
+
+puts "\n" + ('=' * 70)
+puts 'RECOMMENDATIONS'
+puts '=' * 70
+
+# Analyze which strategies passed
+bulk_passed = by_strategy['Bulk JSON'].all? { |r| r[:status] == :pass }
+selective_passed = by_strategy['Selective'].all? { |r| r[:status] == :pass }
+
+if bulk_passed && selective_passed
+  puts '✓ Both Bulk JSON and Selective strategies are correct'
+  puts '  → Use Selective for best performance (+15-18% overhead)'
+  puts '  → Use Bulk JSON for simplicity (+20% overhead)'
+elsif bulk_passed
+  puts '✓ Bulk JSON strategy is correct'
+  puts '  → Safe to implement (+20% overhead vs baseline)'
+elsif selective_passed
+  puts '✓ Selective strategy is correct'
+  puts '  → Safe to implement (+15-18% overhead vs baseline)'
+else
+  puts '✗ No alternative strategies passed all tests'
+  puts '  → Stick with current implementation'
+  puts '  → Or fix identified issues in failing strategies'
+end
+
+# Cleanup
+user.destroy!
+
+__END__
+
+# Expected output:
+#
+# All strategies should pass if they correctly handle:
+# - Simple strings (no parsing needed)
+# - JSON objects (hashes)
+# - JSON arrays
+# - Numbers as strings
+# - Empty strings
+# - Nil values
+# - Nested JSON structures

data/try/{helpers → support/helpers}/test_helpers.rb

@@ -6,12 +6,21 @@
 
 require 'digest'
 
-require_relative '../../lib/familia'
+require_relative '../../../lib/familia'
 
 Familia.enable_database_logging = true
 Familia.enable_database_counter = true
 Familia.uri = 'redis://127.0.0.1:2525'
 
+def generate_random_email
+  # Generate a random username
+  username = (0...8).map { ('a'..'z').to_a[rand(26)] }.join
+  # Define a domain
+  domain = "example.com"
+  # Combine to form an email address
+  "#{username}@#{domain}"
+end
+
 class Bone < Familia::Horreum
   using Familia::Refinements::TimeLiterals
 
@@ -194,7 +203,7 @@ end
 #
 # NOTE: This will do nothing unless RedactedString is already requried
 unless defined?(RedactedString)
-  require_relative '../../lib/familia/features/transient_fields/redacted_string'
+  require_relative '../../../lib/familia/features/transient_fields/redacted_string'
 end
 module RedactedStringTestHelper
   refine RedactedString do
@@ -206,7 +215,7 @@ module RedactedStringTestHelper
 end
 
 unless defined?(SingleUseRedactedString)
-  require_relative '../../lib/familia/features/transient_fields/single_use_redacted_string'
+  require_relative '../../../lib/familia/features/transient_fields/single_use_redacted_string'
 end
 module SingleUseRedactedStringTestHelper
   refine SingleUseRedactedString do

data/try/{core → unit/core}/autoloader_try.rb

@@ -19,7 +19,7 @@
 # the directory patterns that autoloader.included generates and also the
 # exclusion logic works correctly.
 
-require_relative '../../lib/familia'
+require_relative '../../../lib/familia'
 require 'fileutils'
 require 'tmpdir'
 

data/try/{core → unit/core}/base_enhancements_try.rb

@@ -1,6 +1,6 @@
 # try/core/base_enhancements_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -97,14 +97,6 @@ EmptyBaseTest.respond_to?(:feature)
 Familia::Base.features_available
 #=:> Hash
 
-## Dump and load methods are set
-Familia::Base.dump_method
-#=> :to_json
-
-## Load method is set correctly
-Familia::Base.load_method
-#=> :from_json
-
 ## Base module provides inspect with class name
 @base_uuid.inspect.include?('BaseUuidTest')
 #=> true

data/try/{core → unit/core}/connection_try.rb

@@ -1,6 +1,6 @@
 # try/core/connection_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false
 

data/try/{core → unit/core}/errors_try.rb

@@ -1,6 +1,6 @@
 # try/core/errors_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false
 

data/try/{core → unit/core}/extensions_try.rb

@@ -1,4 +1,4 @@
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 module RefinedContext
   using Familia::Refinements::TimeLiterals

data/try/unit/core/familia_logger_try.rb

@@ -0,0 +1,110 @@
+# try/unit/core/familia_logger_try.rb
+
+require_relative '../../support/helpers/test_helpers'
+require 'logger'
+require 'stringio'
+
+## FamiliaLogger has trace method
+logger = Familia::FamiliaLogger.new(StringIO.new)
+logger.respond_to?(:trace)
+#=> true
+
+## trace method logs with TRACE level
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.trace('Test message')
+output.string
+#=~> /Test message/
+
+## FamiliaLogger has TRACE constant
+Familia::FamiliaLogger::TRACE
+#=> 0
+
+## trace method accepts progname parameter
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.trace('MyApp') { 'Test message' }
+output.string
+#=~> /MyApp/
+#=~> /Test message/
+
+## trace method accepts block for message
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.trace { 'Block message' }
+output.string
+#=~> /Block message/
+
+## LogFormatter properly formats TRACE messages
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace('Trace test')
+output.string
+#=~> /^T,/
+
+## Nested trace calls preserve TRACE context
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace do
+  logger.trace('Inner trace message')
+  'Outer trace message'
+end
+output.string.lines.size
+#=> 2
+
+## Nested trace inner message formatted as TRACE
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace do
+  logger.trace('Inner trace message')
+  'Outer trace message'
+end
+output.string.lines[0]
+#=~> /^T,.*Inner trace message/
+
+## Nested trace outer message formatted as TRACE
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace do
+  logger.trace('Inner trace message')
+  'Outer trace message'
+end
+output.string.lines[1]
+#=~> /^T,.*Outer trace message/
+
+## Nested trace calls clean up context for subsequent debug calls
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace do
+  logger.trace('Inner trace')
+  'Outer trace'
+end
+logger.debug('After nested traces')
+output.string.lines.size
+#=> 3
+
+## Debug call after nested traces formatted as DEBUG not TRACE
+output = StringIO.new
+logger = Familia::FamiliaLogger.new(output)
+logger.level = Familia::FamiliaLogger::TRACE
+logger.formatter = Familia::LogFormatter.new
+logger.trace do
+  logger.trace('Inner trace')
+  'Outer trace'
+end
+logger.debug('After nested traces')
+output.string.lines[2]
+#=~> /^D,.*After nested traces/

data/try/{core → unit/core}/familia_try.rb

@@ -1,6 +1,6 @@
 # try/core/familia_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 ## Check for help class
 Bone.related_fields.keys # consistent b/c hashes are ordered

data/try/{core → unit/core}/middleware_try.rb

@@ -3,7 +3,7 @@
 # Test Valkey/Redis middleware components
 # Mock Valkey/Redis client with middleware for testing
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 class MockDatabase
   attr_reader :logged_commands
@@ -27,6 +27,46 @@ class MockDatabase
   end
 end
 
+## increment_middleware_version! increases version counter
+initial_version = Familia.middleware_version
+Familia.increment_middleware_version!
+Familia.middleware_version > initial_version
+#=> true
+
+## increment_middleware_version! increments by exactly 1
+initial_version = Familia.middleware_version
+Familia.increment_middleware_version!
+Familia.middleware_version - initial_version
+#=> 1
+
+## fiber_connection= stores connection with current version
+mock_connection = "test_connection"
+Familia.fiber_connection=(mock_connection)
+stored = Fiber[:familia_connection]
+[stored[0], stored[1] == Familia.middleware_version]
+#=> ["test_connection", true]
+
+## fiber_connection= updates version when middleware version changes
+mock_connection = "test_connection"
+Familia.fiber_connection=(mock_connection)
+old_version = Fiber[:familia_connection][1]
+Familia.increment_middleware_version!
+Familia.fiber_connection=(mock_connection)
+new_version = Fiber[:familia_connection][1]
+new_version > old_version
+#=> true
+
+## clear_fiber_connection! removes fiber-local connection
+Familia.fiber_connection=("test_connection")
+Familia.clear_fiber_connection!
+Fiber[:familia_connection]
+#=> nil
+
+## clear_fiber_connection! is safe when no connection exists
+Familia.clear_fiber_connection!
+Fiber[:familia_connection]
+#=> nil
+
 ## MockDatabase can log commands with timing
 dbclient = MockDatabase.new
 result = dbclient.get("test_key")

data/try/{core → unit/core}/settings_try.rb

@@ -1,6 +1,6 @@
 # try/core/settings_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false