familia 2.0.0.pre16 → 2.0.0.pre18

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,10 +6,20 @@
 
 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
@@ -44,12 +54,10 @@ class Customer < Familia::Horreum
 
   using Familia::Refinements::TimeLiterals
 
-  logical_database 15 # Use something other than the default DB
+  logical_database 3 # Use something other than the default DB
   default_expiration 5.years
 
   feature :safe_dump
-  # feature :expiration
-  # feature :api_version
 
   # Use new SafeDump DSL instead of @safe_dump_fields
   safe_dump_field :custid
@@ -108,7 +116,7 @@ end
 class Session < Familia::Horreum
   using Familia::Refinements::TimeLiterals
 
-  logical_database 14 # don't use Onetime's default DB
+  logical_database 2 # a non-default database
   default_expiration 180.minutes
 
   identifier_field :sessid
@@ -195,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
@@ -207,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/{memory → support/memory}/memory_docker_ruby_dump.sh

@@ -59,7 +59,7 @@ docker exec $CONTAINER_ID bash -c '
 #   $
 #   $ docker run --rm -d -p 3000:3000 \
 #     -e SECRET=$SECRET \
-#     -e REDIS_URL=redis://host.docker.internal:6379/0 \
+#     -e REDIS_URL=redis://host.docker.internal:2525/0 \
 #     ghcr.io/onetimesecret/devtimesecret-lite:latest
 #
 #     abcd1234

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
 
@@ -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 → 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
 
@@ -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 → 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
@@ -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 → 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
 

data/try/{core → unit/core}/time_utils_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/{core → unit/core}/tools_try.rb

@@ -2,12 +2,12 @@
 
 # Test Familia::Tools - key migration and utility functions
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/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')
 

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

@@ -1,6 +1,6 @@
 # try/core/utils_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -62,26 +62,29 @@ custom_stamp = Familia.qstamp(3600, time: test_time)
 Time.at(custom_stamp).utc.hour
 #=> 14
 
-## distinguisher handles basic types
-str_result = Familia.distinguisher('test')
-int_result = Familia.distinguisher(123)
-sym_result = Familia.distinguisher(:symbol)
-[str_result, int_result, sym_result]
-#=> ["test", "123", "symbol"]
+## identifier_extractor extracts class names
+test_class = Class.new(Familia::Horreum)
+test_class.define_singleton_method(:name) { 'TestClass' }
+Familia.identifier_extractor(test_class)
+#=> "TestClass"
 
-## distinguisher raises error for high-risk types with strict mode
+## identifier_extractor extracts identifiers from Familia objects
+customer_class = Class.new(Familia::Horreum) do
+  identifier_field :custid
+  field :custid
+end
+customer = customer_class.new(custid: 'customer_123')
+Familia.identifier_extractor(customer)
+#=> "customer_123"
+
+## identifier_extractor raises error for non-Familia objects
 begin
-  Familia.distinguisher(true, strict_values: true)
+  Familia.identifier_extractor({ key: 'value' })
 rescue Familia::NotDistinguishableError => e
   e.class
 end
 #=> Familia::NotDistinguishableError
 
-## distinguisher allows high-risk types with non-strict mode
-result = Familia.distinguisher(false, strict_values: false)
-result
-#=> "false"
-
 # Cleanup - restore defaults, leave nothing but footprints
 Familia.delim(':')
 Familia.suffix(:object)