familia 1.2.0 → 2.0.0.pre.pre

data/lib/familia/horreum.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+# lib/familia/horreum.rb
 
 module Familia
   #
@@ -6,8 +6,8 @@ module Familia
   #
   # Key features:
   # * Provides instance-level access to a single hash in Redis
-  # * Includes Familia for class/module level access to Redis types and operations
-  # * Uses 'hashkey' to define a Redis hash referred to as "object"
+  # * Includes Familia for class/module level access to Database types and operations
+  # * Uses 'hashkey' to define a Database hash referred to as "object"
   # * Applies a default expiry (5 years) to all keys
   #
   # Metaprogramming:
@@ -55,13 +55,15 @@ module Familia
     #
     class << self
       attr_accessor :parent
-      attr_writer :redis, :dump_method, :load_method
+      # TODO: Where are we calling dbclient= from now with connection pool?
+      attr_writer :dbclient, :dump_method, :load_method
       attr_reader :has_relations
 
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
         member.extend(ClassMethods)
+        member.extend(Connection)
         member.extend(Features)
 
         # Tracks all the classes/modules that include Familia. It's
@@ -84,17 +86,8 @@ module Familia
       Familia.ld "[Horreum] Initializing #{self.class}"
       initialize_relatives
 
-      # Automatically add a 'key' field if it's not already defined. This ensures
-      # that every object horreum class has a unique identifier field. Ideally
-      # this logic would live somewhere else b/c we only need to call it once
-      # per class definition. Here it gets called every time an instance is
-      # instantiated.
-      unless self.class.fields.include?(:key)
-        # Define the 'key' field for this class
-        # This approach allows flexibility in how identifiers are generated
-        # while ensuring each object has a consistent way to be referenced
-        self.class.field :key
-      end
+      # No longer auto-create a key field - the identifier method will
+      # directly use the field specified by identifier_field
 
       # Detect if first argument is a hash (legacy support)
       if args.size == 1 && args.first.is_a?(Hash) && kwargs.empty?
@@ -131,7 +124,7 @@ module Familia
       else
         Familia.ld "[Horreum] #{self.class} initialized with no arguments"
         # Default values are intentionally NOT set here to:
-        # - Maintain Redis memory efficiency (only store non-nil values)
+        # - Maintain Database memory efficiency (only store non-nil values)
         # - Avoid conflicts with nil-skipping serialization logic
         # - Preserve consistent exists? behavior (empty vs default-filled objects)
         # - Keep initialization lightweight for unused fields
@@ -143,50 +136,49 @@ module Familia
       init if respond_to?(:init)
     end
 
-    # Sets up related Redis objects for the instance
+    # Sets up related Database objects for the instance
     # This method is crucial for establishing Redis-based relationships
     #
     # This needs to be called in the initialize method.
     #
     def initialize_relatives
-      # Generate instances of each RedisType. These need to be
+      # 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.
       #
       # i.e.
-      #     familia_object.rediskey              == v1:bone:INDEXVALUE:object
-      #     familia_object.redis_type.rediskey == v1:bone:INDEXVALUE:name
+      #     familia_object.dbkey              == v1:bone:INDEXVALUE:object
+      #     familia_object.related_object.dbkey == v1:bone:INDEXVALUE:name
       #
-      # See RedisType.install_redis_type
-      self.class.redis_types.each_pair do |name, redis_type_definition|
-        klass = redis_type_definition.klass
-        opts = redis_type_definition.opts
+      self.class.related_fields.each_pair do |name, datatype_definition|
+        klass = datatype_definition.klass
+        opts = datatype_definition.opts
         Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
-        # automatically. This is what determines the rediskey for RedisType
-        # instance and which redis connection.
+        # automatically. This is what determines the dbkey for DataType
+        # instance and which database connection.
         #
-        #   e.g. If the parent's rediskey is `customer:customer_id:object`
-        #     then the rediskey for this RedisType instance will be
+        #   e.g. If the parent's dbkey is `customer:customer_id:object`
+        #     then the dbkey for this DataType instance will be
         #     `customer:customer_id:name`.
         #
         opts[:parent] = self # unless opts.key(:parent)
 
         suffix_override = opts.fetch(:suffix, name)
 
-        # Instantiate the RedisType object and below we store it in
+        # Instantiate the DataType object and below we store it in
         # an instance variable.
-        redis_type = klass.new suffix_override, opts
+        related_object = klass.new suffix_override, opts
 
-        # Freezes the redis_type, making it immutable.
+        # Freezes the related_object, making it immutable.
         # This ensures the object's state remains consistent and prevents any modifications,
         # safeguarding its integrity and making it thread-safe.
         # Any attempts to change the object after this will raise a FrozenError.
-        redis_type.freeze
+        related_object.freeze
 
         # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
-        instance_variable_set :"@#{name}", redis_type
+        instance_variable_set :"@#{name}", related_object
       end
     end
 
@@ -198,7 +190,7 @@ module Familia
     #   (i.e., had non-nil values assigned)
     # @private
     def initialize_with_positional_args(*args)
-      Familia.trace :INITIALIZE_ARGS, redis, args, caller(1..1) if Familia.debug?
+      Familia.trace :INITIALIZE_ARGS, dbclient, args, caller(1..1) if Familia.debug?
       self.class.fields.zip(args).filter_map do |field, value|
         if value
           send(:"#{field}=", value)
@@ -217,9 +209,9 @@ module Familia
     #   (i.e., had non-nil values assigned)
     # @private
     def initialize_with_keyword_args(**fields)
-      Familia.trace :INITIALIZE_KWARGS, redis, fields.keys, caller(1..1) if Familia.debug?
+      Familia.trace :INITIALIZE_KWARGS, dbclient, fields.keys, caller(1..1) if Familia.debug?
       self.class.fields.filter_map do |field|
-        # Redis will give us field names as strings back, but internally
+        # Database will give us field names as strings back, but internally
         # we use symbols. So we check for both.
         value = fields[field.to_sym] || fields[field.to_s]
         if value
@@ -230,8 +222,8 @@ module Familia
     end
     private :initialize_with_keyword_args
 
-    def initialize_with_keyword_args_from_redis(**fields)
-      # Deserialize Redis string values back to their original types
+    def initialize_with_keyword_args_deserialize_value(**fields)
+      # Deserialize Database string values back to their original types
       deserialized_fields = fields.transform_values { |value| deserialize_value(value) }
       initialize_with_keyword_args(**deserialized_fields)
     end
@@ -240,7 +232,7 @@ module Familia
     # hash and refreshes the existing object.
     #
     # This method is part of horreum.rb rather than serialization.rb because it
-    # operates solely on the provided values and doesn't query Redis or other
+    # operates solely on the provided values and doesn't query Database or other
     # external sources. That's why it's called "optimistic" refresh: it assumes
     # the provided values are correct and updates the object accordingly.
     #
@@ -250,54 +242,71 @@ module Familia
     #   the object with.
     # @return [Array] The list of field names that were updated.
     def optimistic_refresh(**fields)
-      Familia.ld "[optimistic_refresh] #{self.class} #{rediskey} #{fields.keys}"
-      initialize_with_keyword_args_from_redis(**fields)
+      Familia.ld "[optimistic_refresh] #{self.class} #{dbkey} #{fields.keys}"
+      initialize_with_keyword_args_deserialize_value(**fields)
     end
 
     # Determines the unique identifier for the instance
-    # This method is used to generate Redis keys for the object
+    # This method is used to generate dbkeys for the object
+    # Returns nil for unsaved objects (following standard ORM patterns)
     def identifier
-      definition = self.class.identifier # e.g.
-      # When definition is a symbol or string, assume it's an instance method
-      # to call on the object to get the unique identifier. When it's a callable
-      # object, call it with the object as the argument. When it's an array,
-      # call each method in turn and join the results. When it's nil, raise
-      # an error
+      definition = self.class.identifier_field
+      return nil if definition.nil?
+
+      # Call the identifier field or proc (validation already done at class definition time)
       unique_id = case definition
                   when Symbol, String
                     send(definition)
                   when Proc
                     definition.call(self)
-                  when Array
-                    Familia.join(definition.map { |method| send(method) })
-                  else
-                    raise Problem, "Invalid identifier definition: #{definition.inspect}"
                   end
 
-      # If the unique_id is nil, raise an error
-      raise Problem, "Identifier is nil for #{self.class} #{rediskey}" if unique_id.nil?
-      raise Problem, 'Identifier is empty' if unique_id.empty?
+      # Return nil for unpopulated identifiers (like unsaved ActiveRecord objects)
+      # Only raise errors when the identifier is actually needed for Redis operations
+      return nil if unique_id.nil? || unique_id.to_s.empty?
 
       unique_id
     end
 
+    attr_writer :dbclient
+
+    # Summon the mystical Database connection from the depths of instance or class.
+    #
+    # This method is like a magical divining rod, always pointing to the nearest
+    # source of Database goodness. It first checks if we have a personal Redis
+    # connection (@dbclient), and if not, it borrows the class's connection.
+    #
+    # @return [Redis] A shimmering Database connection, ready for your bidding.
+    #
+    # @example Finding your Database way
+    #   puts object.dbclient
+    #   # => #<Redis client v5.4.1 for redis://localhost:6379/0>
+    #
+    def dbclient
+      conn = Fiber[:familia_transaction] || @dbclient || self.class.dbclient
+      # conn.select(self.class.logical_database)
+      conn
+    end
+
+    def generate_id
+      @objid ||= Familia.generate_id # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+
     # The principle is: **If Familia objects have `to_s`, then they should work
-    # everywhere strings are expected**, including as Redis hash field names.
+    # everywhere strings are expected**, including as Database hash field names.
     def to_s
       # Enable polymorphic string usage for Familia objects
       # This allows passing Familia objects directly where strings are expected
       # without requiring explicit .identifier calls
+      return super if identifier.to_s.empty?
       identifier.to_s
-    rescue => e
-      # Fallback for cases where identifier might fail
-      Familia.ld "[#{self.class}#to_s] Failed to get identifier: #{e.message}"
-      "#<#{self.class}:0x#{object_id.to_s(16)}>"
     end
   end
 end
 
 require_relative 'horreum/class_methods'
 require_relative 'horreum/commands'
+require_relative 'horreum/connection'
 require_relative 'horreum/serialization'
 require_relative 'horreum/settings'
 require_relative 'horreum/utils'

data/lib/familia/logging.rb

@@ -1,4 +1,4 @@
-# rubocop:disable all
+# lib/familia/logging.rb
 
 require 'pathname'
 require 'logger'
@@ -126,7 +126,7 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param redis_instance [Redis, Redis::Future, nil] The Redis instance or
+    # @param dbclient [Redis, Redis::Future, nil] The Database instance or
     #   Future being used.
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
@@ -134,31 +134,31 @@ module Familia
     #   obtained from `caller` or `caller.first`. Default is nil.
     #
     # @example
-    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller(1..1) if
+    #   Familia.trace :LOAD, Familia.dbclient(uri), objkey, caller(1..1) if
     #   Familia.debug?
     #
     # @return [nil]
     #
     # @note This method only executes if LoggerTraceRefinement::ENABLED is true.
-    # @note The redis_instance can be a Redis object, Redis::Future (used in
-    #   pipelined and multi blocks), or nil (when the redis connection isn't
+    # @note The dbclient can be a Database object, Redis::Future (used in
+    #   pipelined and multi blocks), or nil (when the database connection isn't
     #   relevant).
     #
-    def trace(label, redis_instance, ident, context = nil)
+    def trace(label, dbclient, ident, context = nil)
       return unless LoggerTraceRefinement::ENABLED
 
-      # Usually redis_instance is a Redis object, but it could be
+      # Usually dbclient is a Database object, but it could be
       # a Redis::Future which is what is used inside of pipelined
       # and multi blocks. In some contexts it's nil where the
-      # redis connection isn't relevant.
-      instance_id = if redis_instance
-        case redis_instance
+      # database connection isn't relevant.
+      instance_id = if dbclient
+        case dbclient
         when Redis
-          redis_instance.id.respond_to?(:to_s) ? redis_instance.id.to_s : redis_instance.class.name
+          dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
         when Redis::Future
           "Redis::Future"
         else
-          redis_instance.class.name
+        dbclient.class.name
         end
       end
 

data/lib/familia/multi_result.rb

@@ -0,0 +1,72 @@
+# lib/familia/multi_result.rb
+
+# The magical MultiResult, keeper of Redis's deepest secrets!
+#
+# 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.
+#
+# @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.
+#
+# @example Summoning a MultiResult from the void
+#   result = MultiResult.new(true, ["OK", "OK"])
+#
+# @example Divining the success of your Database ritual
+#   if result.successful?
+#     puts "Huzzah! The Database spirits smile upon you!"
+#   else
+#     puts "Alas! The Database gremlins have conspired against us!"
+#   end
+#
+# @example Peering into the raw essence of results
+#   result.results.each_with_index do |value, index|
+#     puts "Command #{index + 1} whispered back: #{value}"
+#   end
+#
+class MultiResult
+  # @return [Boolean] true if all commands in the transaction succeeded,
+  #   false otherwise
+  attr_reader :success
+
+  # @return [Array<String>] The raw return values from the Database commands
+  attr_reader :results
+
+  # Creates a new MultiResult instance.
+  #
+  # @param success [Boolean] Whether all commands succeeded
+  # @param results [Array<String>] The raw results from Database commands
+  def initialize(success, results)
+    @success = success
+    @results = results
+  end
+
+  # Returns a tuple representing the result of the transaction.
+  #
+  # @return [Array] A tuple containing the success status and the raw results.
+  #   The success status is a boolean indicating if all commands succeeded.
+  #   The raw results is an array of return values from the Database commands.
+  #
+  # @example
+  #   [true, ["OK", true, 1]]
+  #
+  def tuple
+    [successful?, results]
+  end
+  alias to_a tuple
+
+  def to_h
+    { success: successful?, results: results }
+  end
+
+  # Convenient method to check if the commit was successful.
+  #
+  # @return [Boolean] true if all commands succeeded, false otherwise
+  def successful?
+    @success
+  end
+  alias success? successful?
+end

data/lib/familia/refinements.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+# lib/familia/refinements.rb
 
 require 'pathname'
 require 'logger'
@@ -6,44 +6,6 @@ require 'logger'
 # Controls whether tracing is enabled via an environment variable
 FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
 
-# FlexibleHashAccess
-#
-# This module provides a refinement for the Hash class to allow flexible access
-# to hash keys using either strings or symbols interchangeably for reading values.
-#
-# Note: This refinement only affects reading from the hash. Writing to the hash
-# maintains the original key type.
-#
-# @example Using the refinement
-#   using FlexibleHashAccess
-#
-#   h = { name: "Alice", "age" => 30 }
-#   h[:name]   # => "Alice"
-#   h["name"]  # => "Alice"
-#   h[:age]    # => 30
-#   h["age"]   # => 30
-#
-#   h["job"] = "Developer"
-#   h[:job]    # => "Developer"
-#   h["job"]   # => "Developer"
-#
-#   h[:salary] = 75000
-#   h[:salary] # => 75000
-#   h["salary"] # => nil (original key type is preserved)
-#
-module FlexibleHashAccess
-  refine Hash do
-    ##
-    # Retrieves a value from the hash using either a string or symbol key.
-    #
-    # @param key [String, Symbol] The key to look up
-    # @return [Object, nil] The value associated with the key, or nil if not found
-    def [](key)
-      super(key.to_s) || super(key.to_sym)
-    end
-  end
-end
-
 # LoggerTraceRefinement
 #
 # This module adds a 'trace' log level to the Ruby Logger class.
@@ -62,11 +24,12 @@ end
 #   logger.trace("This is a trace message")
 #
 module LoggerTraceRefinement
-  # Indicates whether trace logging is enabled
-  ENABLED = %w[1 true yes].include?(FAMILIA_TRACE)
-
-  # The numeric level for trace logging (same as DEBUG)
-  TRACE = 0 unless defined?(TRACE)
+  unless defined?(ENABLED)
+    # Indicates whether trace logging is enabled
+    ENABLED = %w[1 true yes].include?(FAMILIA_TRACE).freeze
+    # The numeric level for trace logging (same as DEBUG)
+    TRACE = 0
+  end
 
   refine Logger do
     ##

data/lib/familia/settings.rb

@@ -1,16 +1,16 @@
-# rubocop:disable all
+# lib/familia/settings.rb
 
 module Familia
 
   @delim = ':'
   @prefix = nil
   @suffix = :object
-  @ttl = 0 # see update_expiration. Zero is skip. nil is an exception.
-  @db = nil
+  @default_expiration = 0 # see update_expiration. Zero is skip. nil is an exception.
+  @logical_database = nil
 
   module Settings
 
-    attr_writer :delim, :suffix, :ttl, :db, :prefix
+    attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix
 
     def delim(val = nil)
       @delim = val if val
@@ -27,14 +27,15 @@ module Familia
       @suffix
     end
 
-    def ttl(v = nil)
-      @ttl = v unless v.nil?
-      @ttl
+    def default_expiration(v = nil)
+      @default_expiration = v unless v.nil?
+      @default_expiration
     end
 
-    def db(v = nil)
-      @db = v unless v.nil?
-      @db
+    def logical_database(v = nil)
+      Familia.trace :DB, dbclient, "#{@logical_database} #{v}", caller(1..1) if Familia.debug?
+      @logical_database = v unless v.nil?
+      @logical_database
     end
 
     # We define this do-nothing method because it reads better
@@ -44,5 +45,4 @@ module Familia
     end
 
   end
-
 end