familia 1.2.1 → 2.0.0.pre2

data/try/core/errors_try.rb

@@ -0,0 +1,93 @@
+# try/core/errors_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+# Test Familia error classes and exception handling
+
+## Familia::Problem is base error class
+Familia::Problem.new.class.superclass
+#=> RuntimeError
+
+## NoIdentifier error can be raised
+begin
+  raise Familia::NoIdentifier, "Missing identifier"
+rescue Familia::NoIdentifier => e
+  e.class
+end
+#=> Familia::NoIdentifier
+
+## NonUniqueKey error can be raised
+begin
+  raise Familia::NonUniqueKey, "Duplicate key"
+rescue Familia::NonUniqueKey => e
+  e.class
+end
+#=> Familia::NonUniqueKey
+
+## HighRiskFactor error stores value
+begin
+  raise Familia::HighRiskFactor.new("dangerous_value")
+rescue Familia::HighRiskFactor => e
+  e.value
+end
+#=> "dangerous_value"
+
+## HighRiskFactor error has custom message
+begin
+  raise Familia::HighRiskFactor.new(123)
+rescue Familia::HighRiskFactor => e
+  e.message.include?("High risk factor")
+end
+#=> true
+
+## NotConnected error stores URI
+test_uri = URI.parse('redis://localhost:6379')
+begin
+  raise Familia::NotConnected.new(test_uri)
+rescue Familia::NotConnected => e
+  e.uri.to_s
+end
+#=> "redis://localhost"
+
+## NotConnected error has custom message
+test_uri = URI.parse('redis://localhost:6379')
+begin
+  raise Familia::NotConnected.new(test_uri)
+rescue Familia::NotConnected => e
+  e.message.include?("No client for")
+end
+#> true
+
+## KeyNotFoundError stores key
+begin
+  raise Familia::KeyNotFoundError.new("missing:key")
+rescue Familia::KeyNotFoundError => e
+  e.key
+end
+#=> "missing:key"
+
+## KeyNotFoundError has custom message
+begin
+  raise Familia::KeyNotFoundError.new("test:key")
+rescue Familia::KeyNotFoundError => e
+  e.message.include?("Key not found in Redis")
+end
+#=> true
+
+## KeyNotFoundError has custom message again
+raise Familia::KeyNotFoundError.new("test:key")
+#=!> error.message.include?("Key not found in Redis")
+#=!> error.class == Familia::KeyNotFoundError
+
+## All error classes inherit from Problem
+[
+  Familia::NoIdentifier,
+  Familia::NonUniqueKey,
+  Familia::HighRiskFactor,
+  Familia::NotConnected,
+  Familia::KeyNotFoundError
+].all? { |klass| klass.superclass == Familia::Problem }
+##=> true

data/try/core/extensions_try.rb

@@ -0,0 +1,26 @@
+require_relative '../helpers/test_helpers'
+
+# Test core extensions
+group "Core Extensions"
+
+try "String time parsing with in_seconds" do
+  "60s".in_seconds == 60 &&
+    "5m".in_seconds == 300 &&
+    "2h".in_seconds == 7200 &&
+    "1d".in_seconds == 86400
+end
+
+try "Time::Units conversions" do
+  1.second == 1 &&
+    1.minute == 60 &&
+    1.hour == 3600 &&
+    1.day == 86400 &&
+    1.week == 604800
+end
+
+try "Numeric extensions to_ms and to_bytes" do
+  1000.to_ms == 1000 &&
+    1.to_bytes == 1 &&
+    1024.to_bytes == "1.0 KiB" &&
+    (1024 * 1024).to_bytes == "1.0 MiB"
+end

data/try/{10_familia_try.rb → core/familia_extended_try.rb}

@@ -1,28 +1,29 @@
+# try/core/familia_extended_try.rb
 
 require 'time'
 
-require_relative '../lib/familia'
-require_relative './test_helpers'
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
 
-## Has all redistype relativess
-registered_types = Familia::RedisType.registered_types.keys
+## Has all datatype relativess
+registered_types = Familia::DataType.registered_types.keys
 registered_types.collect(&:to_s).sort
 #=> ["counter", "hash", "hashkey", "list", "lock", "set", "sorted_set", "string", "zset"]
 
-## Familia created class methods for redistype list class
+## Familia created class methods for datatype list class
 Familia::Horreum::ClassMethods.public_method_defined? :list?
 #=> true
 
-## Familia created class methods for redistype list class
+## Familia created class methods for datatype list class
 Familia::Horreum::ClassMethods.public_method_defined? :list
 #=> true
 
-## Familia created class methods for redistype list class
+## Familia created class methods for datatype list class
 Familia::Horreum::ClassMethods.public_method_defined? :lists
 #=> true
 
-## A Familia object knows its redistype relatives
-Bone.redis_types.is_a?(Hash) && Bone.redis_types.has_key?(:owners)
+## A Familia object knows its datatype relatives
+Bone.related_fields.is_a?(Hash) && Bone.related_fields.has_key?(:owners)
 #=> true
 
 ## A Familia object knows its lists
@@ -33,7 +34,7 @@ Bone.lists.size
 Bone.list? :owners
 #=> true
 
-## A Familia object can get a specific redistype relatives def
+## A Familia object can get a specific datatype relatives def
 definition = Bone.list :owners
 definition.klass
 #=> Familia::List

data/try/{00_familia_try.rb → core/familia_try.rb}

@@ -1,17 +1,19 @@
+# try/core/familia_try.rb
 
-require_relative '../lib/familia'
-require_relative './test_helpers'
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
 
 #Familia.apiversion = 'v1'
 
 
 ## Check for help class
-Bone.redis_types.keys # consistent b/c hashes are ordered
+Bone.related_fields.keys # consistent b/c hashes are ordered
 #=> [:owners, :tags, :metrics, :props, :value]
 
 ## Familia has a uri
-Familia.uri.class
-#=> URI::Redis
+Familia.uri
+#=:> URI::Generic
 
 ## Familia has a uri as a string
 Familia.uri.to_s

data/try/core/middleware_try.rb

@@ -0,0 +1,68 @@
+require_relative '../helpers/test_helpers'
+
+# Test Redis middleware components
+group "Redis Middleware"
+
+try "RedisLogger logs commands with timing" do
+  # Mock Redis client with middleware
+  class MockRedis
+    attr_reader :logged_commands
+
+    def initialize
+      @logged_commands = []
+      extend RedisLogger
+    end
+
+    def get(key)
+      log_command("GET", key) { "test_value" }
+    end
+
+    private
+
+    def log_command(cmd, *args)
+      start_time = Time.now
+      result = yield
+      duration = Time.now - start_time
+      @logged_commands << { command: cmd, args: args, duration: duration }
+      result
+    end
+  end
+
+  redis = MockRedis.new
+  result = redis.get("test_key")
+
+  result == "test_value" &&
+    redis.logged_commands.length == 1 &&
+    redis.logged_commands.first[:command] == "GET"
+end
+
+try "RedisCommandCounter tracks command metrics" do
+  # Mock counter implementation
+  counter = RedisCommandCounter.new
+
+  counter.increment("GET")
+  counter.increment("SET")
+  counter.increment("GET")
+
+  counter.count("GET") == 2 &&
+    counter.count("SET") == 1 &&
+    counter.total == 3
+rescue NameError
+  # Skip if RedisCommandCounter not available
+  true
+end
+
+try "Command counting with count_commands utility" do
+  redis = Familia.redis
+
+  count = count_commands do
+    redis.set("test_key", "value")
+    redis.get("test_key")
+    redis.del("test_key")
+  end
+
+  count >= 3  # At least 3 commands executed
+rescue NameError, NoMethodError
+  # Skip if count_commands not available
+  true
+end

data/try/core/refinements_try.rb

@@ -0,0 +1,39 @@
+require_relative '../helpers/test_helpers'
+
+# Test Familia refinements
+group "Familia Refinements"
+
+using Familia::FlexibleHashAccess
+
+try "FlexibleHashAccess allows string/symbol key interchange" do
+  hash = { name: "test", "email" => "test@example.com" }
+
+  hash[:name] == "test" &&
+    hash["name"] == "test" &&
+    hash[:email] == "test@example.com" &&
+    hash["email"] == "test@example.com"
+end
+
+try "LoggerTraceRefinement adds trace level when FAMILIA_TRACE enabled" do
+  old_env = ENV['FAMILIA_TRACE']
+  ENV['FAMILIA_TRACE'] = '1'
+
+  logger = Logger.new(STDOUT)
+  logger.respond_to?(:trace)
+ensure
+  ENV['FAMILIA_TRACE'] = old_env
+end
+
+try "FAMILIA_TRACE environment control" do
+  old_env = ENV['FAMILIA_TRACE']
+
+  ENV['FAMILIA_TRACE'] = '1'
+  trace_enabled = ENV['FAMILIA_TRACE']
+
+  ENV['FAMILIA_TRACE'] = nil
+  trace_disabled = ENV['FAMILIA_TRACE']
+
+  trace_enabled == '1' && trace_disabled.nil?
+ensure
+  ENV['FAMILIA_TRACE'] = old_env
+end

data/try/core/settings_try.rb

@@ -0,0 +1,76 @@
+# try/core/settings_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+# Test Familia configuration and settings management
+
+## Familia has default delim
+Familia.delim
+#=> ":"
+
+## Can set custom delim
+Familia.delim('|')
+Familia.delim
+#=> "|"
+
+## Familia has default suffix
+Familia.suffix
+#=> :object
+
+## Can set custom suffix
+Familia.suffix(:data)
+Familia.suffix
+#=> :data
+
+## Familia has default TTL
+Familia.default_expiration
+#=> 0
+
+## Can set default expiration value
+Familia.default_expiration(3600)
+Familia.default_expiration
+#=> 3600.0
+
+## Familia has default database
+Familia.logical_database
+#=> nil
+
+## Can set database number
+Familia.logical_database(2)
+Familia.logical_database
+#=> 2
+
+## Familia has default prefix
+Familia.prefix
+#=> nil
+
+## Can set custom prefix
+Familia.prefix('app')
+Familia.prefix
+#=> "app"
+
+## default_suffix method returns suffix
+Familia.default_suffix
+#=> :data
+
+## Setting values with nil preserves current value
+current_default_expiration = Familia.default_expiration
+Familia.default_expiration(nil)
+Familia.default_expiration
+#=> 3600.0
+
+## Setting delim with nil preserves current value
+current_delim = Familia.delim
+Familia.delim(nil)
+Familia.delim
+#=> "|"
+
+# Cleanup - restore defaults
+Familia.delim(':')
+Familia.suffix(:object)
+Familia.default_expiration(0)
+Familia.logical_database(nil)
+Familia.prefix(nil)

data/try/core/tools_try.rb

@@ -0,0 +1,54 @@
+require_relative '../helpers/test_helpers'
+
+# Test Familia::Tools - key migration and utility functions
+group "Familia::Tools"
+
+try "move_keys across Redis instances" do
+  source_redis = Redis.new(db: 10)
+  dest_redis = Redis.new(db: 11)
+
+  # Setup test data
+  source_redis.set("test:key1", "value1")
+  source_redis.set("test:key2", "value2")
+
+  # Move keys
+  moved = Familia::Tools.move_keys(source_redis, dest_redis, "test:*")
+
+  moved == 2 &&
+    dest_redis.get("test:key1") == "value1" &&
+    !source_redis.exists?("test:key1")
+ensure
+  source_redis&.flushdb
+  dest_redis&.flushdb
+end
+
+try "rename with transformation block" do
+  redis = Familia.redis
+  redis.set("old:key1", "value1")
+  redis.set("old:key2", "value2")
+
+  renamed = Familia::Tools.rename(redis, "old:*") { |key| key.gsub("old:", "new:") }
+
+  renamed == 2 &&
+    redis.get("new:key1") == "value1" &&
+    !redis.exists?("old:key1")
+ensure
+  redis&.del("old:key1", "old:key2", "new:key1", "new:key2")
+end
+
+try "get_any retrieves values regardless of type" do
+  redis = Familia.redis
+  redis.set("string_key", "string_value")
+  redis.hset("hash_key", "field", "hash_value")
+  redis.lpush("list_key", "list_value")
+
+  string_val = Familia::Tools.get_any(redis, "string_key")
+  hash_val = Familia::Tools.get_any(redis, "hash_key")
+  list_val = Familia::Tools.get_any(redis, "list_key")
+
+  string_val == "string_value" &&
+    hash_val.is_a?(Hash) &&
+    list_val.is_a?(Array)
+ensure
+  redis&.del("string_key", "hash_key", "list_key")
+end

data/try/core/utils_try.rb

@@ -0,0 +1,189 @@
+# try/core/utils_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+# Test Familia utility methods and helpers
+
+##
+## ID Generation
+##
+
+## Familia.generate_id
+Familia.respond_to?(:generate_id)
+#=> true
+
+## Can generate a default base-36 ID
+id = Familia.generate_id
+[id.class, id.length > 10, id.match?(/^[a-z0-9]+$/)]
+#=> [String, true, true]
+
+## Generated IDs are unique
+[Familia.generate_id == Familia.generate_id]
+#=> [false]
+
+## Can generate an ID with a custom base (hex)
+hex_id = Familia.generate_id(16)
+[hex_id.class, hex_id.length == 64, hex_id.match?(/^[a-f0-9]+$/)]
+#=> [String, true, true]
+
+## Familia.generate_trace_id
+Familia.respond_to?(:generate_trace_id)
+#=> true
+
+## Can generate a default base-36 trace ID
+trace_id = Familia.generate_trace_id
+[trace_id.class, trace_id.length > 5, trace_id.length < 20]
+#=> [String, true, true]
+
+## Can generate a trace ID with a custom base (hex)
+hex_trace_id = Familia.generate_trace_id(16)
+[hex_trace_id.class, hex_trace_id.length == 16]
+#=> [String, true]
+
+## Familia.generate_hex_id
+Familia.respond_to?(:generate_hex_id)
+#=> true
+
+## Can generate a 256-bit hex ID
+hex_id = Familia.generate_hex_id
+[hex_id.class, hex_id.length == 64, hex_id.match?(/^[a-f0-9]+$/)]
+#=> [String, true, true]
+
+## Familia.generate_hex_trace_id
+Familia.respond_to?(:generate_hex_trace_id)
+#=> true
+
+## Can generate a 64-bit hex trace ID
+hex_trace_id = Familia.generate_hex_trace_id
+[hex_trace_id.class, hex_trace_id.length == 16, hex_trace_id.match?(/^[a-f0-9]+$/)]
+#=> [String, true, true]
+
+
+##
+## ID Shortening
+##
+
+## Familia.shorten_to_external_id
+Familia.respond_to?(:shorten_to_external_id)
+#=> true
+
+## Can shorten hex ID to external ID (128 bits)
+hex_id = Familia.generate_hex_id
+external_id = Familia.shorten_to_external_id(hex_id)
+[external_id.class, external_id.length < hex_id.length]
+#=> [String, true]
+
+## Can shorten hex ID to external ID with custom base (hex)
+hex_id = Familia.generate_hex_id
+hex_external_id = Familia.shorten_to_external_id(hex_id, base: 16)
+[hex_external_id.class, hex_external_id.length == 32]
+#=> [String, true]
+
+## Familia.shorten_to_trace_id
+Familia.respond_to?(:shorten_to_trace_id)
+#=> true
+
+## Can shorten hex ID to trace ID (64 bits)
+hex_id = Familia.generate_hex_id
+trace_id = Familia.shorten_to_trace_id(hex_id)
+[trace_id.class, trace_id.length < hex_id.length]
+#=> [String, true]
+
+## Can shorten hex ID to trace ID with custom base (hex)
+hex_id = Familia.generate_hex_id
+hex_trace_id = Familia.shorten_to_trace_id(hex_id, base: 16)
+[hex_trace_id.class, hex_trace_id.length == 16]
+#=> [String, true]
+
+## Shortened IDs are deterministic
+hex_id = Familia.generate_hex_id
+id1 = Familia.shorten_to_external_id(hex_id)
+id2 = Familia.shorten_to_external_id(hex_id)
+id1 == id2
+#=> true
+
+##
+## Key helpers
+##
+Familia.delim(':') # Ensure default
+
+## Can join values with delimiter
+result = Familia.join('user', '123', 'sessions')
+result
+#=> "user:123:sessions"
+
+## Can join with custom delimiter
+original_delim = Familia.delim
+Familia.delim('|')
+result = Familia.join('a', 'b', 'c')
+[result, Familia.delim]
+#=> ["a|b|c", "|"]
+
+## Can split values with custom delimiter
+parts = Familia.split('a|b|c')
+parts
+#=> ["a", "b", "c"]
+
+## Resets delimiter for remaining tests
+Familia.delim(':')
+#=> ":"
+
+## Can split with default delimiter after reset
+parts = Familia.split('user:123:data')
+parts
+#=> ["user", "123", "data"]
+
+## Can create dbkey with default delimiter
+key = Familia.dbkey('v1', 'customer', 'email')
+key
+#=> "v1:customer:email"
+
+##
+## Other Utilities
+##
+
+## qstamp returns integer timestamp by default
+stamp = Familia.qstamp
+stamp.class
+#=> Integer
+
+## qstamp with pattern returns formatted string
+formatted = Familia.qstamp(3600, pattern: '%Y%m%d%H')
+[formatted.class, formatted.length == 10]
+#=> [String, true]
+
+## qstamp works with custom time
+test_time = Time.utc(2023, 6, 15, 14, 30, 0)
+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"]
+
+## distinguisher raises error for high-risk types with strict mode
+begin
+  Familia.distinguisher(true, strict_values: true)
+rescue Familia::HighRiskFactor => e
+  e.class
+end
+#=> Familia::HighRiskFactor
+
+## 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)
+Familia.default_expiration(0)
+Familia.logical_database(nil)
+Familia.prefix(nil)

data/try/{26_redis_bool_try.rb → datatypes/boolean_try.rb}

@@ -1,5 +1,7 @@
-require_relative '../lib/familia'
-require_relative './test_helpers'
+# try/datatypes/boolean_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
 
 Familia.debug = false
 

data/try/datatypes/datatype_base_try.rb

@@ -0,0 +1,69 @@
+# try/datatypes/base_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
+
+@limiter1 = Limiter.new :requests
+
+## Database Types are unique per instance of a Familia class
+@a = Bone.new 'atoken1', :name1
+@b = Bone.new 'atoken2', :name2
+p [@a.object_id, @b.object_id]
+p [@a.owners.parent.class, @b.owners.parent.class]
+p [@a.owners.parent.object_id, @b.owners.parent.object_id]
+p [@a.owners.dbkey, @b.owners.dbkey]
+p [@a.token, @b.token]
+p [@a.name, @b.name]
+@a.owners.dbkey.eql?(@b.owners.dbkey)
+#=> false
+
+## Database Types are frozen
+@a.owners.frozen?
+#=> true
+
+## Limiter#qstamp
+@limiter1.counter.qstamp(10.minutes, '%H:%M', 1302468980)
+##=> '20:50'
+
+## Database Types can be stored to quantized stamp suffix
+@limiter1.counter.dbkey
+##=> "v1:limiter:requests:counter:20:50"
+
+## Limiter#qstamp as a number
+@limiter2 = Limiter.new :requests
+p [@limiter1.default_expiration, @limiter2.default_expiration]
+p [@limiter1.counter.parent.default_expiration, @limiter2.counter.parent.default_expiration]
+@limiter2.counter.qstamp(10.minutes, pattern: nil, time: 1302468980)
+#=> 1302468600
+
+## Database Types can be stored to quantized numeric suffix. This
+## tryouts is disabled b/c `DataType#dbkey` takes no args
+## and relies on the `class Limiter` definition in test_helpers.rb
+## for the `:quantize` option. The quantized suffix for the Limiter
+## class is `'%H:%M'` so its dbkeys will always look like that.
+@limiter2.counter.dbkey
+##=> "v1:limiter:requests:counter:1302468600"
+
+## Increment counter
+@limiter1.counter.delete!
+@limiter1.counter.increment
+#=> 1
+
+## Check counter default_expiration
+@limiter1.counter.default_expiration
+#=> 3600.0
+
+## Check limiter default_expiration
+@limiter1.default_expiration
+#=> 1800.0
+
+## Check default_expiration for a different instance
+## (this exists to make sure options are cloned for each instance)
+@limiter3 = Limiter.new :requests
+@limiter3.counter.default_expiration
+#=> 3600.0
+
+## Check current_expiration
+sleep 1 # Database default_expirations are in seconds so we can't wait any less time than this (without mocking)
+@limiter1.counter.current_expiration
+#=> 3600-1