familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/settings.rb

@@ -1,18 +1,23 @@
 # lib/familia/settings.rb
 
+# Familia
+#
 module Familia
-  @delim = ':'
+  @delim = ':'.freeze
   @prefix = nil
   @suffix = :object
   @default_expiration = 0 # see update_expiration. Zero is skip. nil is an exception.
   @logical_database = nil
   @encryption_keys = nil
   @current_key_version = nil
-  @encryption_personalization = 'FamilialMatters'
+  @encryption_personalization = 'FamilialMatters'.freeze
+  @pipeline_mode = :warn
 
+  # Familia::Settings
+  #
   module Settings
     attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix, :encryption_keys,
-                :current_key_version, :encryption_personalization
+                :current_key_version, :encryption_personalization, :transaction_mode
 
     def delim(val = nil)
       @delim = val if val
@@ -35,7 +40,7 @@ module Familia
     end
 
     def logical_database(v = nil)
-      Familia.trace :DB, dbclient, "#{@logical_database} #{v}", caller(1..1) if Familia.debug?
+      Familia.trace :DB, nil, "#{@logical_database} #{v}" if Familia.debug?
       @logical_database = v unless v.nil?
       @logical_database
     end
@@ -61,8 +66,7 @@ module Familia
     # unique per application even with identical master keys and contexts.
     # Must be 16 bytes or less (automatically padded with null bytes).
     #
-    # @example
-    #   Familia.configure do |config|
+    # @example Familia.configure do |config|
     #     config.encryption_personalization = 'MyApp1.0'
     #   end
     #
@@ -77,8 +81,80 @@ module Familia
       @encryption_personalization
     end
 
-    def config
+    # Controls transaction behavior when connection handlers don't support transactions
+    #
+    # @param val [Symbol, nil] The transaction mode or nil to get current value
+    # @return [Symbol] Current transaction mode (:strict, :warn, :permissive)
+    #
+    # Available modes:
+    # - :warn (default): Log warning and execute commands individually
+    # - :strict: Raise OperationModeError when transaction unavailable
+    # - :permissive: Silently execute commands individually
+    #
+    # @example Setting transaction mode
+    #   Familia.configure do |config|
+    #     config.transaction_mode = :warn
+    #   end
+    #
+    def transaction_mode(val = nil)
+      if val
+        unless [:strict, :warn, :permissive].include?(val)
+          raise ArgumentError, 'Transaction mode must be :strict, :warn, or :permissive'
+        end
+        @transaction_mode = val
+      end
+      @transaction_mode || :warn  # default to warn mode
+    end
+
+    # Controls pipeline behavior when connection handlers don't support pipelines
+    #
+    # @param val [Symbol, nil] The pipeline mode or nil to get current value
+    # @return [Symbol] Current pipeline mode (:strict, :warn, :permissive)
+    #
+    # Available modes:
+    # - :warn (default): Log warning and execute commands individually
+    # - :strict: Raise OperationModeError when pipeline unavailable
+    # - :permissive: Silently execute commands individually
+    #
+    # @example Setting pipeline mode
+    #   Familia.configure do |config|
+    #     config.pipeline_mode = :permissive
+    #   end
+    #
+    def pipeline_mode(val = nil)
+      if val
+        unless [:strict, :warn, :permissive].include?(val)
+          raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
+        end
+        @pipeline_mode = val
+      end
+      @pipeline_mode || :warn  # default to warn mode
+    end
+
+    def pipeline_mode=(val)
+      unless [:strict, :warn, :permissive].include?(val)
+        raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
+      end
+      @pipeline_mode = val
+    end
+
+    # Configure Familia settings
+    #
+    # @yield [Settings] self for block-based configuration
+    # @return [Settings] self for method chaining
+    #
+    # @example Block-based configuration
+    #   Familia.configure do |config|
+    #     config.redis_uri = "redis://localhost:6379/1"
+    #     config.ttl = 3600
+    #   end
+    #
+    # @example Method chaining
+    #   Familia.configure.redis_uri = "redis://localhost:6379/1"
+    def configure
+      yield self if block_given?
       self
     end
+    alias config configure
   end
 end

data/lib/familia/utils.rb

@@ -1,11 +1,9 @@
 # lib/familia/utils.rb
 
 module Familia
-
   # Family-related utility methods
   #
   module Utils
-
     using Familia::Refinements::TimeLiterals
 
     # Joins array elements with Familia delimiter
@@ -38,10 +36,10 @@ module Familia
     end
 
     # Returns current time in UTC as a float
-    # @param name [Time] time object (default: current time)
+    # @param current_time [Time] time object (default: current time)
     # @return [Float] time in seconds since epoch
-    def now(name = Time.now)
-      name.utc.to_f
+    def now(current_time = Time.now)
+      current_time.utc.to_f
     end
 
     # A quantized timestamp
@@ -51,12 +49,11 @@ module Familia
     # @param time [Integer, Float, Time, nil] A specific time to quantize (default: current time).
     # @return [Integer, String] A unix timestamp or formatted timestamp string.
     #
-    # @example
-    #   Familia.qstamp  # Returns an integer timestamp rounded to the nearest 10 minutes
+    # @example Familia.qstamp  # Returns an integer timestamp rounded to the nearest 10 minutes
     #   Familia.qstamp(1.hour)  # Uses 1 hour quantum
     #   Familia.qstamp(10.minutes, pattern: '%H:%M')  # Returns a formatted string like "12:30"
     #   Familia.qstamp(10.minutes, time: 1302468980)  # Quantizes the given Unix timestamp
-    #   Familia.qstamp(10.minutes, time: Time.now)  # Quantizes the given Time object
+    #   Familia.qstamp(10.minutes, time: Familia.now)  # Quantizes the given Time object
     #   Familia.qstamp(10.minutes, pattern: '%H:%M', time: 1302468980)  # Formats a specific time
     #
     def qstamp(quantum = 10.minutes, pattern: nil, time: nil)
@@ -72,84 +69,6 @@ module Familia
       end
     end
 
-    # This method determines the appropriate transformation to apply based on
-    # the class of the input argument.
-    #
-    # @param [Object] value_to_distinguish The value to be processed. Keep in
-    #   mind that all data is stored as a string so whatever the type
-    #   of the value, it will be converted to a string.
-    # @param [Boolean] strict_values Whether to enforce strict value handling.
-    #   Defaults to true.
-    # @return [String, nil] The processed value as a string or nil for unsupported
-    #   classes.
-    #
-    # The method uses a case statement to handle different classes:
-    # - For `Symbol`, `String`, `Integer`, and `Float` classes, it traces the
-    #   operation and converts the value to a string.
-    # - For `Familia::Horreum` class, it traces the operation and returns the
-    #   identifier of the value.
-    # - For `TrueClass`, `FalseClass`, and `NilClass`, it traces the operation and
-    #   converts the value to a string ("true", "false", or "").
-    # - For any other class, it traces the operation and returns nil.
-    #
-    # Alternative names for `value_to_distinguish` could be `input_value`, `value`,
-    # or `object`.
-    #
-    def distinguisher(value_to_distinguish, strict_values: true)
-      case value_to_distinguish
-      when ::Symbol, ::String, ::Integer, ::Float
-        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'string', caller(1..1) if Familia.debug?
-
-        # Symbols and numerics are naturally serializable to strings
-        # so it's a relatively low risk operation.
-        value_to_distinguish.to_s
-
-      when ::TrueClass, ::FalseClass, ::NilClass
-        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'true/false/nil', caller(1..1) if Familia.debug?
-
-        # TrueClass, FalseClass, and NilClass are considered high risk because their
-        # original types cannot be reliably determined from their serialized string
-        # representations. This can lead to unexpected behavior during deserialization.
-        # For instance, a TrueClass value serialized as "true" might be deserialized as
-        # a String, causing application errors. Even more problematic, a NilClass value
-        # serialized as an empty string makes it impossible to distinguish between a
-        # nil value and an empty string upon deserialization. Such scenarios can result
-        # in subtle, hard-to-diagnose bugs. To mitigate these risks, we raise an
-        # exception when encountering these types unless the strict_values option is
-        # explicitly set to false.
-        #
-        raise Familia::HighRiskFactor, value_to_distinguish if strict_values
-
-        value_to_distinguish.to_s #=> "true", "false", ""
-
-      when Familia::Base, Class
-        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'base', caller(1..1) if Familia.debug?
-
-        # When called with a class we simply transform it to its name. For
-        # instances of Familia class, we store the identifier.
-        if value_to_distinguish.is_a?(Class)
-          value_to_distinguish.name
-        else
-          value_to_distinguish.identifier
-        end
-
-      else
-        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "else1 #{strict_values}", caller(1..1) if Familia.debug?
-
-        if value_to_distinguish.class.ancestors.member?(Familia::Base)
-          Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'isabase', caller(1..1) if Familia.debug?
-
-          value_to_distinguish.identifier
-
-        else
-          Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "else2 #{strict_values}", caller(1..1) if Familia.debug?
-          raise Familia::HighRiskFactor, value_to_distinguish if strict_values
-
-          nil
-        end
-      end
-    end
-
     # Converts an absolute file path to a path relative to the current working
     # directory. This simplifies logging and error reporting by showing
     # only the relevant parts of file paths instead of lengthy absolute paths.
@@ -191,6 +110,5 @@ module Familia
     def pretty_stack(skip: 1, limit: 5)
       caller(skip..(skip + limit + 1)).first(limit).map { |frame| pretty_path(frame) }.join("\n")
     end
-
   end
 end

data/lib/familia/verifiable_identifier.rb

@@ -8,7 +8,7 @@ module Familia
   # allowing for stateless verification of an identifier's authenticity.
   module VerifiableIdentifier
     # By extending SecureIdentifier, we gain access to its instance methods
-    # (like generate_hex_id) as class methods on this module.
+    # (like generate_id) as class methods on this module.
     extend Familia::SecureIdentifier
 
     # The secret key for HMAC generation, loaded from an environment variable.
@@ -33,7 +33,7 @@ module Familia
     #        $ openssl rand -hex 32
     #        > cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d
     #
-    #     2. Set it as an environment variable in your production environment:
+    #     2. UnsortedSet it as an environment variable in your production environment:
     #        export VERIFIABLE_ID_HMAC_SECRET="cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d"
     #
     SECRET_KEY = ENV.fetch('VERIFIABLE_ID_HMAC_SECRET', 'cafef00dcafef00dcafef00dcafef00dcafef00dcafef00d')
@@ -61,8 +61,8 @@ module Familia
         # base remains as passed in keyword argument or default
       end
 
-      # Re-use generate_hex_id from the SecureIdentifier module.
-      random_hex = generate_hex_id
+      # Re-use generate_id from the SecureIdentifier module.
+      random_hex = generate_id(16)
       tag_hex = generate_tag(random_hex, scope: scope)
 
       combined_hex = random_hex + tag_hex

data/lib/familia/version.rb

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

data/lib/familia.rb

@@ -7,13 +7,14 @@ require 'connection_pool'
 
 # OJ configuration is handled internally by Familia::JsonSerializer
 
+require_relative 'multi_result'
 require_relative 'familia/refinements'
 require_relative 'familia/errors'
 require_relative 'familia/version'
 
-# Familia - A family warehouse for Redis
+# Familia - A family warehouse for Valkey/Redis
 #
-# Familia provides a way to organize and store Ruby objects in Redis.
+# Familia provides a way to organize and store Ruby objects in the database.
 # It includes various modules and classes to facilitate object-Database interactions.
 #
 # @example Basic usage
@@ -32,18 +33,31 @@ require_relative 'familia/version'
 # @see https://github.com/delano/familia
 #
 module Familia
-
   @debug = ENV['FAMILIA_DEBUG'].to_s.downcase.match?(/^(true|1)$/i).freeze
   @members = []
 
+  using Refinements::StylizeWords
+
   class << self
-    attr_accessor :debug
+    attr_accessor :debug # rubocop:disable ThreadSafety/ClassAndModuleAttributes
     attr_reader :members
 
     def included(member)
       raise Problem, "#{member} should subclass Familia::Horreum"
     end
 
+    def resolve_class(target)
+      case target
+      when Class
+        target
+      when ::String, Symbol
+        config_name = target.to_s.demodularize.snake_case
+        member_by_config_name(config_name)
+      else
+        raise ArgumentError, "Expected Class, String, or Symbol, got #{target.class}"
+      end
+    end
+
     # A convenience pattern for configuring Familia.
     #
     # @example
@@ -65,6 +79,59 @@ module Familia
     def debug?
       @debug == true
     end
+
+    # Remove a member class from the members array.
+    # Used for test cleanup to prevent anonymous classes from polluting
+    # the global registry.
+    #
+    # @param klass [Class] The class to remove from members
+    # @return [Class, nil] The removed class or nil if not found
+    def unload_member(klass)
+      Familia.ld "[unload_member] Removing #{klass} from members"
+      @members.delete(klass)
+    end
+
+    # Remove all anonymous/test classes from members array.
+    # Anonymous classes have nil names, which cause issues in member_by_config_name.
+    #
+    # @return [Array<Class>] The removed anonymous classes
+    def clear_anonymous_members
+      anonymous_classes = @members.select { |m| m.name.nil? }
+      Familia.ld "[clear_anonymous_members] Removing #{anonymous_classes.size} anonymous classes"
+      @members.reject! { |m| m.name.nil? }
+      anonymous_classes
+    end
+
+    # Check if we're in test mode by looking for test-related constants
+    # or environment variables
+    #
+    # @return [Boolean] true if running in test mode
+    def test_mode?
+      defined?(Tryouts) || ENV['FAMILIA_TEST_MODE'] == 'true'
+    end
+
+    private
+
+    # Finds a member class by its symbolized name
+    #
+    # NOTE: If you are not getting the expected results, check the load order of
+    # the models. The one your looking for may not be loaded yet. Currently
+    # models are loaded naively -- that is, they are loaded in the order
+    # they are defined in the codebase.
+    #
+    # @param config_name [Symbol, String] The symbolized name of the member class
+    # @return [Class, nil] The member class if found, nil otherwise
+    #
+    # @example
+    #   Familia.member_by_config_name(:flower) # => Flower class
+    #   Familia.member_by_config_name('flower') # => Flower class
+    #   Familia.member_by_config_name(:nonexistent) # => nil
+    #
+    def member_by_config_name(config_name)
+      Familia.ld "[member_by_config_name] #{members.map(&:config_name)} #{config_name}"
+
+      members.find { |m| m.config_name.to_s.eql?(config_name.to_s) }
+    end
   end
 
   require_relative 'familia/secure_identifier'
@@ -72,6 +139,7 @@ module Familia
   require_relative 'familia/connection'
   require_relative 'familia/settings'
   require_relative 'familia/utils'
+  require_relative 'familia/distinguisher'
   require_relative 'familia/json_serializer'
 
   extend SecureIdentifier
@@ -82,18 +150,7 @@ module Familia
 end
 
 require_relative 'familia/base'
-require_relative 'familia/features/autoloadable'
 require_relative 'familia/features'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'
 require_relative 'familia/encryption'
-
-# Ensure JSON constant is available for backward compatibility with existing code
-# This approach is safer than monkey-patching core classes globally
-begin
-  require 'json'
-rescue LoadError
-  # If json gem is not available, define a minimal JSON constant
-  # that delegates to Familia::JsonSerializer for compatibility
-  JSON = Familia::JsonSerializer
-end

data/lib/middleware/database_middleware.rb

@@ -2,7 +2,7 @@
 
 require 'concurrent-ruby'
 
-# DatabaseLogger is RedisClient middleware.
+# DatabaseLogger is Valkey/RedisClient middleware.
 #
 # This middleware addresses the need for detailed Database command logging, which
 # was removed from the redis-rb gem due to performance concerns. However, in
@@ -13,6 +13,13 @@ require 'concurrent-ruby'
 #   DatabaseLogger.logger = Logger.new(STDOUT)
 #   RedisClient.register(DatabaseLogger)
 #
+# @example Capture commands for testing
+#   commands = DatabaseLogger.capture_commands do
+#     redis.set('key', 'value')
+#     redis.get('key')
+#   end
+#   puts commands.first[:command]  # => ["SET", "key", "value"]
+#
 # @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
 #
 # @note While there were concerns about the performance impact of logging in
@@ -22,39 +29,75 @@ require 'concurrent-ruby'
 #   often outweigh the slight performance cost when enabled.
 module DatabaseLogger
   @logger = nil
+  @commands = []
 
   class << self
     # Gets/sets the logger instance used by DatabaseLogger.
     # @return [Logger, nil] The current logger instance or nil if not set.
     attr_accessor :logger
+
+    # Gets the captured commands for testing purposes.
+    # @return [Array] Array of command hashes with :command, :duration, :timestamp
+    attr_reader :commands
+
+    # Clears the captured commands array.
+    # @return [Array] Empty array
+    def clear_commands
+      @commands = []
+    end
+
+    # Captures commands in a block and returns them.
+    # This is useful for testing to see what commands were executed.
+    #
+    # @yield [] The block of code to execute while capturing commands.
+    # @return [Array] Array of captured commands with timing information.
+    #   Each command is a hash with :command, :duration, :timestamp keys.
+    #
+    # @example Test what Redis commands your code executes
+    #   commands = DatabaseLogger.capture_commands do
+    #     my_library_method()
+    #   end
+    #   assert_equal "SET", commands.first[:command][0]
+    #   assert commands.first[:duration] > 0
+    def capture_commands
+      clear_commands
+      yield
+      @commands.dup
+    end
   end
 
   # Logs the Database command and its execution time.
   #
   # This method is called for each Database command when the middleware is active.
-  # It logs the command and its execution time only if a logger is set.
+  # It always captures commands for testing and logs them if a logger is set.
   #
   # @param command [Array] The Database command and its arguments.
-  # @param _config [Hash] The configuration options for the Redis
+  # @param _config [Hash] The configuration options for the Valkey/Redis
   #   connection.
   # @return [Object] The result of the Database command execution.
   #
-  # @note The performance impact of this logging is negligible when no logger
-  #   is set, as it quickly returns control to the Database client. When a logger
-  #   is set, the minimal overhead is often offset by the valuable insights
-  #   gained during development and debugging.
+  # @note Commands are always captured with minimal overhead for testing purposes.
+  #   Logging only occurs when DatabaseLogger.logger is set.
   def call(command, _config)
-    return yield unless DatabaseLogger.logger
-
     start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
     result = yield
     duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start
-    DatabaseLogger.logger.debug("Redis: #{command.inspect} (#{duration}µs)")
+
+    # Always capture commands for testing purposes
+    DatabaseLogger.instance_variable_get(:@commands) << {
+      command: command.dup,
+      duration: duration,
+      timestamp: Time.now,
+    }
+
+    # Log if logger is set
+    DatabaseLogger.logger&.debug("Redis: #{command.inspect} (#{duration}µs)")
+
     result
   end
 end
 
-# DatabaseCommandCounter is RedisClient middleware.
+# DatabaseCommandCounter is Valkey/RedisClient middleware.
 #
 # This middleware counts the number of Database commands executed. It can be
 # useful for performance monitoring and debugging, allowing you to track
@@ -66,7 +109,6 @@ end
 #
 # @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
 #
-# rubocop:disable ThreadSafety/ClassInstanceVariable
 module DatabaseCommandCounter
   @count = Concurrent::AtomicFixnum.new(0)
 
@@ -75,11 +117,11 @@ module DatabaseCommandCounter
   # a configuration where there's a connection to each logical db, there's only
   # one when the connection is made. When using a provider of via thread local
   # it could theoretically double the number of statements executed.
-  @skip_commands = Set.new(['SELECT']).freeze
+  @skip_commands = ::Set.new(['SELECT']).freeze
 
   class << self
     # Gets the set of commands to skip counting.
-    # @return [Set] The commands that won't be counted.
+    # @return [UnsortedSet] The commands that won't be counted.
     attr_reader :skip_commands
 
     # Gets the current count of Database commands executed.

data/lib/{familia/multi_result.rb → multi_result.rb}

@@ -1,30 +1,29 @@
-# lib/familia/multi_result.rb
+# lib/multi_result.rb
 
-# The magical MultiResult, keeper of Redis's deepest secrets!
+# Represents the result of a Valkey/Redis transaction operation.
 #
-# This quirky little class wraps up the outcome of a Database "transaction"
-# (or as I like to call it, a "Database dance party") with a bow made of
-# pure Ruby delight. It knows if your commands were successful and
-# keeps the results safe in its pocket dimension.
+# This class encapsulates the outcome of a Database transaction,
+# providing access to both the success status and the individual
+# command results returned by the transaction.
 #
-# @attr_reader success [Boolean] The golden ticket! True if all your
-#   Database wishes came true in the transaction.
-# @attr_reader results [Array<String>] A mystical array of return values,
-#   each one a whisper from the Database gods.
+# @attr_reader success [Boolean] Indicates whether all commands
+#   in the transaction completed successfully.
+# @attr_reader results [Array<String>] Array of return values
+#   from the Database commands executed in the transaction.
 #
-# @example Summoning a MultiResult from the void
+# @example Creating a MultiResult instance
 #   result = MultiResult.new(true, ["OK", "OK"])
 #
-# @example Divining the success of your Database ritual
+# @example Checking transaction success
 #   if result.successful?
-#     puts "Huzzah! The Database spirits smile upon you!"
+#     puts "Transaction completed successfully"
 #   else
-#     puts "Alas! The Database gremlins have conspired against us!"
+#     puts "Transaction failed"
 #   end
 #
-# @example Peering into the raw essence of results
+# @example Accessing individual command results
 #   result.results.each_with_index do |value, index|
-#     puts "Command #{index + 1} whispered back: #{value}"
+#     puts "Command #{index + 1} returned: #{value}"
 #   end
 #
 class MultiResult
@@ -58,6 +57,13 @@ class MultiResult
   end
   alias to_a tuple
 
+  # Returns the number of results in the multi-operation.
+  #
+  # @return [Integer] The number of individual command results returned by the transaction.
+  def size
+    results.size
+  end
+
   def to_h
     { success: successful?, results: results }
   end
@@ -69,4 +75,5 @@ class MultiResult
     @success
   end
   alias success? successful?
+  alias areyouhappynow? successful?
 end

data/try/configuration/scenarios_try.rb

@@ -24,7 +24,7 @@ rescue StandardError => e
 end
 #=> false
 
-## custom Redis URI configuration doesn't always work
+## custom Valkey/Redis URI configuration doesn't always work
 begin
   # Test with custom URI
   original_uri = Familia.uri