familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/horreum/core/connection.rb

@@ -2,25 +2,61 @@
 
 module Familia
   class Horreum
-    # Connection: Valkey connection management for Horreum instances
-    # Provides both instance and class-level connection methods
+    # Connection - Mixed instance and class-level methods for Valkey connection management
+    # Provides connection handling, transactions, and URI normalization for both
+    # class-level operations (e.g., Customer.dbclient) and instance-level operations
+    # (e.g., customer.dbclient)
     module Connection
       attr_reader :uri
 
-      # Returns the Database connection for the class.
+      # Normalizes various URI formats to a consistent URI object
+      # Considers the class/instance logical_database when uri is nil or Integer
+      def normalize_uri(uri)
+        case uri
+        when Integer
+          new_uri = Familia.uri.dup
+          new_uri.db = uri
+          new_uri
+        when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) }
+          URI.parse(uri)
+        when URI
+          uri
+        when nil
+          # Use logical_database if available, otherwise fall back to Familia.uri
+          if respond_to?(:logical_database) && logical_database
+            new_uri = Familia.uri.dup
+            new_uri.db = logical_database
+            new_uri
+          else
+            Familia.uri
+          end
+        else
+          raise ArgumentError, "Invalid URI type: #{uri.class.name}"
+        end
+      end
+
+      # Creates a new Database connection instance using the class/instance configuration
+      def create_dbclient(uri = nil)
+        parsed_uri = normalize_uri(uri)
+        Familia.create_dbclient(parsed_uri)
+      end
+
+      # Returns the Database connection for the class using Chain of Responsibility pattern.
       #
-      # This method retrieves the Database connection instance for the class. If no
-      # connection is set, it initializes a new connection using the provided URI
-      # or database configuration.
+      # This method uses a chain of handlers to resolve connections in priority order:
+      # 1. FiberTransactionHandler - Fiber[:familia_transaction] (active transaction)
+      # 2. DefaultConnectionHandler - Horreum model class-level @dbclient
+      # 3. GlobalFallbackHandler - Familia.dbclient(uri || logical_database) (global fallback)
       #
       # @return [Redis] the Database connection instance.
       #
-      def dbclient
-        Fiber[:familia_transaction] || @dbclient || Familia.dbclient(uri || logical_database)
+      def dbclient(uri = nil)
+        @class_connection_chain ||= build_connection_chain
+        @class_connection_chain.handle(uri)
       end
 
       def connect(*)
-        Familia.connect(*)
+        create_dbclient(*)
       end
 
       def uri=(uri)
@@ -46,27 +82,194 @@ module Familia
       #
       # @note This method works with the global Familia.transaction context when available
       #
+      # Executes a Redis transaction (MULTI/EXEC) using this object's connection context.
+      #
+      # Provides atomic execution of multiple Redis commands with automatic connection
+      # management and operation mode enforcement. Uses the object's database and
+      # connection settings. Returns a MultiResult object for consistency with global methods.
+      #
+      # @param [Proc] block The block containing Redis commands to execute atomically
+      # @yield [Redis] conn The Redis connection configured for transaction mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #   (e.g., FiberConnectionHandler or DefaultConnectionHandler that don't support transactions)
+      #
+      # @example Basic instance transaction
+      #   customer = Customer.new(custid: 'cust_123')
+      #   result = customer.transaction do |conn|
+      #     conn.hset(customer.dbkey, 'name', 'John Doe')
+      #     conn.hset(customer.dbkey, 'email', 'john@example.com')
+      #     conn.hget(customer.dbkey, 'name')
+      #   end
+      #   result.successful?    # => true
+      #   result.results        # => ["OK", "OK", "John Doe"]
+      #
+      # @example Using with object's database context
+      #   class Customer < Familia::Horreum
+      #     logical_database 5  # Use database 5
+      #     field :name
+      #     field :email
+      #   end
+      #
+      #   customer = Customer.new(custid: 'cust_456')
+      #   result = customer.transaction do |conn|
+      #     # Commands automatically execute in database 5
+      #     conn.hset(customer.dbkey, 'status', 'active')
+      #     conn.sadd('active_customers', customer.identifier)
+      #   end
+      #   result.successful?    # => true
+      #
+      # @example Reentrant behavior with global transactions
+      #   customer = Customer.new(custid: 'cust_789')
+      #
+      #   # When called within a global transaction, reuses the transaction connection
+      #   result = Familia.transaction do |global_conn|
+      #     global_conn.set('global_key', 'value')
+      #
+      #     # This reuses the same transaction connection
+      #     customer.transaction do |local_conn|
+      #       local_conn.hset(customer.dbkey, 'updated', Time.now.to_i)
+      #       'local_return_value'  # Returned directly in nested context
+      #     end
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Transaction Context:
+      #   - When called outside global transaction: Creates local MultiResult
+      #   - When called inside global transaction: Yields to existing transaction
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @see Familia.transaction For global transaction method
+      # @see MultiResult For details on the return value structure
+      # @see #batch_update For similar atomic field updates with MultiResult
       def transaction(&)
-        # If we're already in a Familia.transaction context, just yield the multi connection
-        if Fiber[:familia_transaction]
-          yield(Fiber[:familia_transaction])
-        else
-          # Otherwise, create a local transaction
-          block_result = dbclient.multi(&)
-        end
-        block_result
+        Familia::Connection::TransactionCore.execute_transaction(-> { dbclient }, &)
       end
       alias multi transaction
 
-      def pipeline(&)
-        # If we're already in a Familia.pipeline context, just yield the pipeline connection
-        if Fiber[:familia_pipeline]
-          yield(Fiber[:familia_pipeline])
-        else
-          # Otherwise, create a local transaction
-          block_result = dbclient.pipeline(&)
-        end
-        block_result
+      # Executes Redis commands in a pipeline using this object's connection context.
+      #
+      # Batches multiple Redis commands together and sends them in a single network
+      # round-trip for improved performance. Uses the object's database and connection
+      # settings. Returns a MultiResult object for consistency with global methods.
+      #
+      # @param [Proc] block The block containing Redis commands to execute in pipeline
+      # @yield [Redis] conn The Redis connection configured for pipelined mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #   (e.g., FiberConnectionHandler or CachedConnectionHandler that don't support pipelines)
+      #
+      # @example Basic instance pipeline
+      #   customer = Customer.new(custid: 'cust_123')
+      #   result = customer.pipelined do |conn|
+      #     conn.hset(customer.dbkey, 'last_login', Time.now.to_i)
+      #     conn.hincrby(customer.dbkey, 'login_count', 1)
+      #     conn.sadd('recent_logins', customer.identifier)
+      #     conn.hget(customer.dbkey, 'login_count')
+      #   end
+      #   result.successful?        # => true
+      #   result.results           # => ["OK", 15, "OK", "15"]
+      #   result.results.last      # => "15" (new login count)
+      #
+      # @example Performance optimization for object operations
+      #   user = User.new(userid: 'user_456')
+      #
+      #   # Instead of multiple round-trips:
+      #   # user.save                    # Round-trip 1
+      #   # user.tags.add('premium')     # Round-trip 2
+      #   # user.sessions.clear          # Round-trip 3
+      #
+      #   # Use pipeline for single round-trip:
+      #   result = user.pipelined do |conn|
+      #     conn.hmset(user.dbkey, user.to_h_for_storage)
+      #     conn.sadd(user.tags.dbkey, 'premium')
+      #     conn.del(user.sessions.dbkey)
+      #   end
+      #   # All operations completed in one network round-trip
+      #
+      # @example Using with object's database context
+      #   class Session < Familia::Horreum
+      #     logical_database 3  # Use database 3
+      #     field :user_id
+      #     field :expires_at
+      #   end
+      #
+      #   session = Session.new(session_id: 'sess_789')
+      #   result = session.pipelined do |conn|
+      #     # Commands automatically execute in database 3
+      #     conn.hset(session.dbkey, 'user_id', 'user_123')
+      #     conn.hset(session.dbkey, 'expires_at', 1.hour.from_now.to_i)
+      #     conn.expire(session.dbkey, 3600)
+      #   end
+      #
+      # @example Reentrant behavior with global pipelines
+      #   customer = Customer.new(custid: 'cust_abc')
+      #
+      #   # When called within a global pipeline, reuses the pipeline connection
+      #   result = Familia.pipelined do |global_conn|
+      #     global_conn.set('global_counter', 0)
+      #
+      #     # This reuses the same pipeline connection
+      #     customer.pipelined do |local_conn|
+      #       local_conn.hset(customer.dbkey, 'updated', Time.now.to_i)
+      #       Redis::Future.new  # Returns Redis::Future in nested context
+      #     end
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Pipeline Context:
+      #   - When called outside global pipeline: Creates local MultiResult
+      #   - When called inside global pipeline: Yields to existing pipeline
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @note Performance Considerations:
+      #   - Best for multiple independent operations on the same object
+      #   - Reduces network latency by batching commands
+      #   - Commands execute independently (some may succeed, others fail)
+      #
+      # @see Familia.pipelined For global pipeline method
+      # @see MultiResult For details on the return value structure
+      # @see Familia.transaction For atomic command execution
+      def pipelined(&block)
+        Familia::Connection::PipelineCore.execute_pipeline(-> { dbclient }, &block)
+      end
+      alias pipeline pipelined
+
+      private
+
+      # Builds the class-level connection chain with handlers in priority order
+      def build_connection_chain
+        # Cache handlers at class level to avoid creating new instances per model instance
+        @fiber_connection_handler ||= Familia::Connection::FiberConnectionHandler.new
+        @provider_connection_handler ||= Familia::Connection::ProviderConnectionHandler.new
+
+        # Determine the appropriate class context
+        # When called from instance: self is instance, self.class is the model class
+        # When called from class: self is the model class
+        klass = self.is_a?(Class) ? self : self.class
+
+        # Always check class first for @dbclient since instance-level connections were removed
+        @cached_connection_handler ||= Familia::Connection::CachedConnectionHandler.new(klass)
+        @create_connection_handler ||= Familia::Connection::CreateConnectionHandler.new(klass)
+
+        Familia::Connection::ResponsibilityChain.new
+          .add_handler(Familia::Connection::FiberTransactionHandler.instance)
+          .add_handler(@fiber_connection_handler)
+          .add_handler(@provider_connection_handler)
+          .add_handler(@cached_connection_handler)
+          .add_handler(@create_connection_handler)
       end
     end
   end

data/lib/familia/horreum/core/database_commands.rb

@@ -1,13 +1,13 @@
 # lib/familia/horreum/database_commands.rb
 
 module Familia
-  # InstanceMethods - Module containing instance-level methods for Familia
+  # Familia::Horreum
   #
   # This module is included in classes that include Familia, providing
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-    # Methods that call Database commands (InstanceMethods)
+    # DatabaseCommands - Instance-level methods for horreum models that call Database commands
     #
     # NOTE: There is no hgetall for Horreum. This is because Horreum
     # is a single hash in Database that we aren't meant to have be working
@@ -20,11 +20,11 @@ module Familia
         dbclient.move dbkey, logical_database
       end
 
-      # Checks if the calling object's key exists in Redis.
+      # Checks if the calling object's key exists in the database.
       #
       # @param check_size [Boolean] When true (default), also verifies the hash has a non-zero size.
       #   When false, only checks key existence regardless of content.
-      # @return [Boolean] Returns `true` if the key exists in Redis. When `check_size` is true,
+      # @return [Boolean] Returns `true` if the key exists in the database. When `check_size` is true,
       #   also requires the hash to have at least one field.
       #
       # @example Check existence with size validation (default behavior)
@@ -49,6 +49,7 @@ module Familia
         dbclient.hlen dbkey
       end
       alias size field_count
+      alias length field_count
 
       # Sets a timeout on key. After the timeout has expired, the key will
       # automatically be deleted. Returns 1 if the timeout was set, 0 if key
@@ -56,19 +57,19 @@ module Familia
       #
       def expire(default_expiration = nil)
         default_expiration ||= self.class.default_expiration
-        Familia.trace :EXPIRE, dbclient, default_expiration, caller(1..1) if Familia.debug?
+        Familia.trace :EXPIRE, nil, default_expiration if Familia.debug?
         dbclient.expire dbkey, default_expiration.to_i
       end
 
       # Retrieves the remaining time to live (TTL) for the object's dbkey.
       #
-      # This method accesses the ovjects Database client to obtain the TTL of `dbkey`.
+      # This method accesses the objects Database client to obtain the TTL of `dbkey`.
       # If debugging is enabled, it logs the TTL retrieval operation using `Familia.trace`.
       #
       # @return [Integer] The TTL of the key in seconds. Returns -1 if the key does not exist
       #   or has no associated expire time.
       def current_expiration
-        Familia.trace :CURRENT_EXPIRATION, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :CURRENT_EXPIRATION, nil, uri if Familia.debug?
         dbclient.ttl dbkey
       end
 
@@ -77,32 +78,32 @@ module Familia
       # @param field [String] The field to remove from the hash.
       # @return [Integer] The number of fields that were removed from the hash (0 or 1).
       def remove_field(field)
-        Familia.trace :HDEL, dbclient, field, caller(1..1) if Familia.debug?
+        Familia.trace :HDEL, nil, field if Familia.debug?
         dbclient.hdel dbkey, field
       end
       alias remove remove_field # deprecated
 
       def data_type
-        Familia.trace :DATATYPE, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :DATATYPE, nil, uri if Familia.debug?
         dbclient.type dbkey(suffix)
       end
 
       # For parity with DataType#hgetall
       def hgetall
-        Familia.trace :HGETALL, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :HGETALL, nil, uri if Familia.debug?
         dbclient.hgetall dbkey(suffix)
       end
       alias all hgetall
 
       def hget(field)
-        Familia.trace :HGET, dbclient, field, caller(1..1) if Familia.debug?
+        Familia.trace :HGET, nil, field if Familia.debug?
         dbclient.hget dbkey(suffix), field
       end
 
       # @return The number of fields that were added to the hash. If the
       #  field already exists, this will return 0.
       def hset(field, value)
-        Familia.trace :HSET, dbclient, field, caller(1..1) if Familia.debug?
+        Familia.trace :HSET, nil, field if Familia.debug?
         dbclient.hset dbkey, field, value
       end
 
@@ -115,18 +116,18 @@ module Familia
       # @return [Integer] 1 if the field is a new field in the hash and the value was set,
       #   0 if the field already exists in the hash and no operation was performed
       def hsetnx(field, value)
-        Familia.trace :HSETNX, dbclient, field, caller(1..1) if Familia.debug?
+        Familia.trace :HSETNX, nil, field if Familia.debug?
         dbclient.hsetnx dbkey, field, value
       end
 
       def hmset(hsh = {})
         hsh ||= to_h
-        Familia.trace :HMSET, dbclient, hsh, caller(1..1) if Familia.debug?
+        Familia.trace :HMSET, nil, hsh if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end
 
       def hkeys
-        Familia.trace :HKEYS, dbclient, 'uri', caller(1..1) if Familia.debug?
+        Familia.trace :HKEYS, nil, 'uri' if Familia.debug?
         dbclient.hkeys dbkey(suffix)
       end
 
@@ -169,14 +170,23 @@ module Familia
       end
       alias has_key? key?
 
-      # Deletes the entire dbkey
+      # Deletes the dbkey for this horreum :object.
+      #
+      # It does not delete the related fields keys. See destroy!
+      #
       # @return [Boolean] true if the key was deleted, false otherwise
       def delete!
-        Familia.trace :DELETE!, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :DELETE!, nil, uri if Familia.debug?
+
+        # Delete the main object key
         ret = dbclient.del dbkey
         ret.positive?
       end
       alias clear delete!
+
+      def echo(*args)
+        dbclient.echo "[#{self.class}] #{args.join(' ')}"
+      end
     end
   end
 end

data/lib/familia/horreum/core/serialization.rb

@@ -1,5 +1,5 @@
 # lib/familia/horreum/serialization.rb
-#
+
 module Familia
   # Familia::Horreum
   #
@@ -21,7 +21,7 @@ module Familia
     #   - nil - Valid response for certain operations
     #
     # @example Validating a command response
-    #   response = redis.set("key", "value")
+    #   response = dbclient.set("key", "value")
     #   valid = @valid_command_return_values.include?(response)
     #   # => true if response is "OK"
     #
@@ -31,7 +31,7 @@ module Familia
       attr_reader :valid_command_return_values
     end
 
-    # Serialization: Object persistence and retrieval from the DB
+    # Serialization - Instance-level methods for object persistence and retrieval
     # Handles conversion between Ruby objects and Valkey hash storage
     #
     module Serialization
@@ -61,7 +61,7 @@ module Familia
       # @see #commit_fields The underlying method that performs the field persistence
       #
       def save(update_expiration: true)
-        Familia.trace :SAVE, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :SAVE, nil, uri if Familia.debug?
 
         # No longer need to sync computed identifier with a cache field
         self.created ||= Familia.now.to_i if respond_to?(:created)
@@ -71,6 +71,9 @@ module Familia
         #
         ret = commit_fields(update_expiration: update_expiration)
 
+        # Add to class-level instances collection after successful save
+        self.class.instances.add(identifier, Familia.now) if ret && self.class.respond_to?(:instances)
+
         Familia.ld "[save] #{self.class} #{dbkey} #{ret} (update_expiration: #{update_expiration})"
 
         # Did Database accept our offering?
@@ -123,7 +126,7 @@ module Familia
         identifier_field = self.class.identifier_field
 
         Familia.ld "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
-        Familia.trace :SAVE_IF_NOT_EXISTS, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :SAVE_IF_NOT_EXISTS, nil, uri if Familia.debug?
 
         dbclient.watch(dbkey) do
           if dbclient.exists(dbkey).positive?
@@ -180,7 +183,7 @@ module Familia
 
       # Updates multiple fields atomically in a Database transaction.
       #
-      # @param fields [Hash] Field names and values to update. Special key :update_expiration
+      # @param kwargs [Hash] Field names and values to update. Special key :update_expiration
       #   controls whether to update key expiration (default: true)
       # @return [MultiResult] Transaction result
       #
@@ -194,9 +197,9 @@ module Familia
         update_expiration = kwargs.delete(:update_expiration) { true }
         fields = kwargs
 
-        Familia.trace :BATCH_UPDATE, dbclient, fields.keys, caller(1..1) if Familia.debug?
+        Familia.trace :BATCH_UPDATE, nil, fields.keys if Familia.debug?
 
-        command_return_values = transaction do |conn|
+        transaction_result = transaction do |conn|
           fields.each do |field, value|
             prepared_value = serialize_value(value)
             conn.hset dbkey, field, prepared_value
@@ -208,9 +211,8 @@ module Familia
         # Update expiration if requested and supported
         self.update_expiration(default_expiration: nil) if update_expiration && respond_to?(:update_expiration)
 
-        # Return same MultiResult format as other methods
-        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
-        MultiResult.new(summary_boolean, command_return_values)
+        # Return the MultiResult directly (transaction already returns MultiResult)
+        transaction_result
       end
 
       # Updates the object by applying multiple field values.
@@ -235,11 +237,12 @@ module Familia
         self
       end
 
-      # Permanently removes this object from the DB storage.
+      # Permanently removes this object and its related fields from the DB.
       #
-      # Deletes the object's Valkey key and all associated data. This operation
+      # Deletes the object's database key and all associated data. This operation
       # is irreversible and will permanently destroy all stored information
-      # for this object instance.
+      # for this object instance and the additional list, set, hash, string
+      # etc fields defined for this class.
       #
       # @return [void]
       #
@@ -259,8 +262,25 @@ module Familia
       # @see #delete! The underlying method that performs the key deletion
       #
       def destroy!
-        Familia.trace :DESTROY, dbclient, uri, caller(1..1) if Familia.debug?
-        delete!
+        Familia.trace :DESTROY, dbkey, uri
+
+        # Execute all deletion operations within a transaction
+        transaction do |conn|
+          # Delete the main object key
+          conn.del(dbkey)
+
+          # Delete all related fields if present
+          if self.class.relations?
+            Familia.trace :DELETE_RELATED_FIELDS!, nil,
+                          "#{self.class} has relations: #{self.class.related_fields.keys}"
+
+            self.class.related_fields.each do |name, _definition|
+              obj = send(name)
+              Familia.trace :DELETE_RELATED_FIELD, name, "Deleting related field #{name} (#{obj.dbkey})"
+              conn.del(obj.dbkey)
+            end
+          end
+        end
       end
 
       # Clears all fields by setting them to nil.
@@ -306,7 +326,7 @@ module Familia
       #   no authoritative source in Valkey storage.
       #
       def refresh!
-        Familia.trace :REFRESH, dbclient, uri, caller(1..1) if Familia.debug?
+        Familia.trace :REFRESH, nil, uri if Familia.debug?
         raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
         fields = hgetall
@@ -442,7 +462,7 @@ module Familia
       #
       # The serialization process:
       # 1. Attempts conversion using Familia.distinguisher with relaxed type checking
-      # 2. For Hash/Array types that return nil, tries custom dump_method or JSON.dump
+      # 2. For Hash/Array types that return nil, tries custom dump_method or Familia::JsonSerializer.dump
       # 3. Logs warnings when serialization fails completely
       #
       # @param val [Object] The Ruby object to serialize for Valkey storage
@@ -485,7 +505,7 @@ module Familia
       # Hash or Array types. Simple string values are returned as-is.
       #
       # @param val [String] The string value from Database to deserialize
-      # @param symbolize_keys [Boolean] Whether to symbolize hash keys (default: true for compatibility)
+      # @param symbolize [Boolean] Whether to symbolize hash keys (default: true for compatibility)
       # @return [Object] The deserialized value (Hash, Array, or original string)
       #
       def deserialize_value(val, symbolize: true)
@@ -522,7 +542,7 @@ module Familia
           field_type = self.class.field_types[field_name]
           next unless field_type&.method_name
 
-          # Set the transient field back to nil
+          # UnsortedSet the transient field back to nil
           send("#{field_type.method_name}=", nil)
           Familia.ld "[reset_transient_fields!] Reset #{field_name} to nil"
         end

data/lib/familia/horreum/core/utils.rb

@@ -7,7 +7,8 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-    # Utils - Module containing utility methods for Familia::Horreum (InstanceMethods)
+    # Utils - Instance-level utility methods for Familia::Horreum
+    # Provides identifier handling, dbkey generation, and object inspection
     #
     module Utils
       # def uri

data/lib/familia/horreum/shared/settings.rb

@@ -7,7 +7,8 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-    # Settings - Module containing settings for Familia::Horreum (InstanceMethods)
+    # Settings - Instance-level configuration methods for Horreum models
+    # Provides per-instance settings like logical_database, dump_method, load_method, suffix
     #
     module Settings
       attr_writer :dump_method, :load_method, :suffix