familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/features/relationships/participation_membership.rb

@@ -0,0 +1,69 @@
+# lib/familia/features/relationships/participation_membership.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      #
+      # ParticipationMembership
+      #
+      # Represents runtime snapshot of a participant's membership in a target collection.
+      # Returned by current_participations to provide a type-safe, structured view
+      # of actual participation state.
+      #
+      # @note This represents what currently exists in Redis, not just configuration.
+      #   See ParticipationRelationship for static configuration metadata.
+      #
+      # @example
+      #   membership = user.current_participations.first
+      #   membership.target_class  # => "Team"
+      #   membership.target_id     # => "team123"
+      #   membership.collection_name  # => :members
+      #   membership.type          # => :sorted_set
+      #   membership.score         # => 1762554020.05
+      #
+      ParticipationMembership = Data.define(
+        :target_class,      # String - class name (e.g., "Customer")
+        :target_id,         # String - target instance identifier
+        :collection_name,   # Symbol - collection name (e.g., :domains)
+        :type,              # Symbol - collection type (:sorted_set, :set, :list)
+        :score,             # Float - optional, for sorted_set only
+        :decoded_score,     # Hash - optional, decoded score data
+        :position           # Integer - optional, for list only
+      ) do
+        # Check if this membership is a sorted set
+        # @return [Boolean]
+        def sorted_set?
+          type == :sorted_set
+        end
+
+        # Check if this membership is a set
+        # @return [Boolean]
+        def set?
+          type == :set
+        end
+
+        # Check if this membership is a list
+        # @return [Boolean]
+        def list?
+          type == :list
+        end
+
+        # Get the target instance (requires loading from database)
+        # @return [Familia::Horreum, nil] the loaded target instance
+        def target_instance
+          return nil unless target_class
+
+          # Resolve class from string name
+          # Only rescue NameError (class doesn't exist), not all exceptions
+          klass = Object.const_get(target_class)
+          klass.find_by_id(target_id)
+        rescue NameError
+          # Target class doesn't exist or isn't loaded
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/familia/features/relationships/participation_relationship.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/participation_relationship.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Features
@@ -10,20 +12,46 @@ module Familia
       # Used to configure code generation and runtime behavior for participates_in
       # and class_participates_in declarations.
       #
+      # @note target_class is resolved once at definition time for performance.
+      #   Use _original_target for debugging/introspection to see what was passed.
+      #
       ParticipationRelationship = Data.define(
-        :target_class,        # Class object that owns the collection
+        :_original_target,    # Original Symbol/String/Class as passed to participates_in
+        :target_class,        # Resolved Class object (e.g., User class, not :User symbol)
         :collection_name,     # Symbol name of the collection (e.g., :members, :domains)
         :score,               # Proc/Symbol/nil - score calculator for sorted sets
         :type,                # Symbol - collection type (:sorted_set, :set, :list)
-        :bidirectional, # Boolean - whether to generate reverse methods
+        :bidirectional,       # Boolean/Symbol - whether to generate reverse methods
       ) do
+        # Get a unique key for this participation relationship
+        # Useful for comparisons and hash keys
         #
-        # Get the normalized config name for the target class
+        # @return [String] unique identifier in format "TargetClass:collection_name"
+        def unique_key
+          Familia.join(target_class_base, collection_name)
+        end
+
+        # Get the base class name without namespace
+        # Handles anonymous class wrappers like "#<Class:0x123>::SymbolResolutionCustomer"
         #
-        # @return [String] The config name (e.g., "user", "perf_test_customer")
+        # @return [String] base class name (e.g., "Customer")
+        def target_class_base
+          target_class.name.split('::').last
+        end
+
+        # Check if this relationship matches the given target and collection
+        # Handles namespace-agnostic class comparison
         #
-        def target_class_config_name
-          target_class.config_name
+        # @param comparison_target [Class, String, Symbol] target to compare against
+        # @param comparison_collection [Symbol, String] collection name to compare
+        # @return [Boolean] true if both target and collection match
+        def matches?(comparison_target, comparison_collection)
+          # Normalize comparison target to base class name
+          comparison_target = comparison_target.name if comparison_target.is_a?(Class)
+          comparison_target_base = comparison_target.to_s.split('::').last
+
+          target_class_base == comparison_target_base &&
+            collection_name == comparison_collection.to_sym
         end
       end
     end

data/lib/familia/features/relationships/score_encoding.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/score_encoding.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Features

data/lib/familia/features/relationships.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require_relative 'relationships/score_encoding'
@@ -84,7 +86,7 @@ module Familia
 
       # Feature initialization
       def self.included(base)
-        Familia.ld "[#{base}] Relationships included"
+        Familia.debug "[#{base}] Relationships included"
         base.extend ModelClassMethods
         base.include ModelInstanceMethods
 
@@ -157,7 +159,7 @@ module Familia
         def create_temp_key(base_name, ttl = 300)
           timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
-          temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
+          temp_key = Familia.join('temp', base_name, timestamp, random_suffix)
 
           # UnsortedSet immediate expiry to ensure cleanup even if operation fails
           if respond_to?(:dbclient)
@@ -256,7 +258,7 @@ module Familia
         def create_temp_key(base_name, ttl = 300)
           timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
-          temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
+          temp_key = Familia.join('temp', base_name, timestamp, random_suffix)
 
           # UnsortedSet immediate expiry to ensure cleanup even if operation fails
           dbclient.expire(temp_key, ttl)

data/lib/familia/features/safe_dump.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/safe_dump.rb
+#
+# frozen_string_literal: true
 
 #
 # Class instance variables are used here for configuration. These are set

data/lib/familia/features/transient_fields/redacted_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/redacted_string.rb
+#
+# frozen_string_literal: true
 
 # RedactedString
 #

data/lib/familia/features/transient_fields/single_use_redacted_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/single_use_redacted_string.rb
+#
+# frozen_string_literal: true
 
 require_relative 'redacted_string'
 

data/lib/familia/features/transient_fields/transient_field_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/transient_field_type.rb
+#
+# frozen_string_literal: true
 
 require 'familia/field_type'
 
@@ -80,7 +82,7 @@ module Familia
     #
     def define_fast_writer(_klass)
       # No fast writer for transient fields since they're not persisted
-      Familia.ld "[TransientFieldType] Skipping fast writer for transient field: #{@name}"
+      Familia.debug "[TransientFieldType] Skipping fast writer for transient field: #{@name}"
       nil
     end
 
@@ -117,7 +119,7 @@ module Familia
     #
     def serialize(_value, _record = nil)
       # Transient fields should never be serialized
-      Familia.ld "[TransientFieldType] WARNING: serialize called on transient field #{@name}"
+      Familia.debug "[TransientFieldType] WARNING: serialize called on transient field #{@name}"
       nil
     end
 
@@ -132,7 +134,7 @@ module Familia
     #
     def deserialize(_value, _record = nil)
       # Transient fields should never be deserialized
-      Familia.ld "[TransientFieldType] WARNING: deserialize called on transient field #{@name}"
+      Familia.debug "[TransientFieldType] WARNING: deserialize called on transient field #{@name}"
       nil
     end
   end

data/lib/familia/features/transient_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields.rb
+#
+# frozen_string_literal: true
 
 require_relative 'transient_fields/redacted_string'
 require_relative 'transient_fields/transient_field_type'

data/lib/familia/features.rb

@@ -1,4 +1,6 @@
 # lib/familia/features.rb
+#
+# frozen_string_literal: true
 
 # Load the Autoloader first, then use it to load all other features
 require_relative 'features/autoloader'

data/lib/familia/field_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/field_type.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Base class for all field types in Familia
@@ -143,7 +145,8 @@ module Familia
           val = args.first
 
           # If no value provided, return current stored value
-          return hget(field_name) if val.nil?
+          # Handle Redis::Future objects during transactions
+          return hget(field_name) if val.nil? || val.is_a?(Redis::Future)
 
           begin
             # Trace the operation if debugging is enabled
@@ -151,7 +154,7 @@ module Familia
 
             # Convert value for database storage
             prepared = serialize_value(val)
-            Familia.ld "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+            Familia.debug "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
 
             # Use the setter method to update instance variable
             send(:"#{method_name}=", val) if method_name

data/lib/familia/horreum/connection.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/connection.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Horreum
@@ -6,40 +8,16 @@ module Familia
     # Provides connection handling, transactions, and URI normalization for both
     # class-level operations (e.g., Customer.dbclient) and instance-level operations
     # (e.g., customer.dbclient)
+    #
+    # Includes shared connection behavior from Familia::Connection::Behavior, providing:
+    # - URI normalization (normalize_uri)
+    # - Connection creation (create_dbclient)
+    # - Transaction method signatures
+    # - Pipeline method signatures
     module Connection
-      attr_reader :uri
-
-      # 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
+      include Familia::Connection::Behavior
 
-      # 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
+      attr_reader :uri
 
       # Returns the Database connection for the class using Chain of Responsibility pattern.
       #
@@ -48,10 +26,19 @@ module Familia
       # 2. DefaultConnectionHandler - Horreum model class-level @dbclient
       # 3. GlobalFallbackHandler - Familia.dbclient(uri || logical_database) (global fallback)
       #
+      # Thread-safe lazy initialization using double-checked locking to ensure
+      # only a single connection chain is built even under high concurrent load.
+      #
       # @return [Redis] the Database connection instance.
       #
       def dbclient(uri = nil)
-        @class_connection_chain ||= build_connection_chain
+        # Fast path: return existing chain if already initialized
+        return @class_connection_chain.handle(uri) if @class_connection_chain
+
+        # Slow path: thread-safe initialization
+        @class_connection_chain_mutex.synchronize do
+          @class_connection_chain ||= build_connection_chain
+        end
         @class_connection_chain.handle(uri)
       end
 
@@ -277,9 +264,9 @@ module Familia
         @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
+        # When called from instance: self is instance, use the model class connection
+        # When called from class: we'll use our own connection
+        klass = 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)
@@ -292,6 +279,11 @@ module Familia
           .add_handler(@cached_connection_handler)
           .add_handler(@create_connection_handler)
       end
+
+      # Thread-safe mutex initialization when module is extended
+      def self.extended(base)
+        base.instance_variable_set(:@class_connection_chain_mutex, Mutex.new)
+      end
     end
   end
 end

data/lib/familia/horreum/database_commands.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/database_commands.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::Horreum
@@ -16,6 +18,10 @@ module Familia
     # just load the object again.
     #
     module DatabaseCommands
+      # Moves the object's key to a different logical database.
+      #
+      # @param logical_database [Integer] The target database number
+      # @return [Boolean] true if the key was moved successfully
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end
@@ -40,7 +46,18 @@ module Familia
         key_exists = self.class.exists?(identifier)
         return key_exists unless check_size
 
-        key_exists && !size.zero?
+        # Handle Redis::Future in transactions - skip size check
+        if key_exists.is_a?(Redis::Future)
+          return key_exists
+        end
+
+        current_size = size
+        # Handle Redis::Future from size call too
+        if current_size.is_a?(Redis::Future)
+          return current_size
+        end
+
+        key_exists && !current_size.zero?
       end
 
       # Returns the number of fields in the main object hash
@@ -55,6 +72,8 @@ module Familia
       # automatically be deleted. Returns 1 if the timeout was set, 0 if key
       # does not exist or the timeout could not be set.
       #
+      # @param default_expiration [Integer] TTL in seconds (uses class default if nil)
+      # @return [Integer] 1 if timeout was set, 0 otherwise
       def expire(default_expiration = nil)
         default_expiration ||= self.class.default_expiration
         Familia.trace :EXPIRE, nil, default_expiration if Familia.debug?
@@ -69,7 +88,7 @@ module Familia
       # @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, nil, uri if Familia.debug?
+        Familia.trace :CURRENT_EXPIRATION, nil, self.class.uri if Familia.debug?
         dbclient.ttl dbkey
       end
 
@@ -83,24 +102,38 @@ module Familia
       end
       alias remove remove_field # deprecated
 
+      # Returns the Redis data type of the key.
+      #
+      # @return [String] The data type (e.g., 'hash', 'string', 'list')
       def data_type
-        Familia.trace :DATATYPE, nil, uri if Familia.debug?
+        Familia.trace :DATATYPE, nil, self.class.uri if Familia.debug?
         dbclient.type dbkey(suffix)
       end
 
-      # For parity with DataType#hgetall
+      # Returns all fields and values in the hash.
+      #
+      # @return [Hash] All field-value pairs in the hash
+      # @note For parity with DataType#hgetall
       def hgetall
-        Familia.trace :HGETALL, nil, uri if Familia.debug?
+        Familia.trace :HGETALL, nil, self.class.uri if Familia.debug?
         dbclient.hgetall dbkey(suffix)
       end
       alias all hgetall
 
+      # Gets the value of a hash field.
+      #
+      # @param field [String] The field name
+      # @return [String, nil] The value of the field, or nil if field doesn't exist
       def hget(field)
         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
+      # Sets the value of a hash field.
+      #
+      # @param field [String] The field name
+      # @param value [String] The value to set
+      # @return [Integer] 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, nil, field if Familia.debug?
@@ -120,51 +153,92 @@ module Familia
         dbclient.hsetnx dbkey, field, value
       end
 
+      # Sets multiple hash fields to multiple values.
+      #
+      # @param hsh [Hash] Hash of field-value pairs to set
+      # @return [String] 'OK' on success
       def hmset(hsh = {})
         hsh ||= to_h_for_storage
         Familia.trace :HMSET, nil, hsh if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end
 
+      # Returns all field names in the hash.
+      #
+      # @return [Array<String>] Array of field names
       def hkeys
-        Familia.trace :HKEYS, nil, 'uri' if Familia.debug?
+        Familia.trace :HKEYS, nil, self.class.uri if Familia.debug?
         dbclient.hkeys dbkey(suffix)
       end
 
+      # Returns all values in the hash.
+      #
+      # @return [Array<String>] Array of values
       def hvals
         dbclient.hvals dbkey(suffix)
       end
 
+      # Increments the integer value of a hash field by 1.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The value after incrementing
       def incr(field)
         dbclient.hincrby dbkey(suffix), field, 1
       end
       alias increment incr
 
+      # Increments the integer value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param increment [Integer] The increment value
+      # @return [Integer] The value after incrementing
       def incrby(field, increment)
         dbclient.hincrby dbkey(suffix), field, increment
       end
       alias incrementby incrby
 
+      # Increments the float value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param increment [Float] The increment value
+      # @return [Float] The value after incrementing
       def incrbyfloat(field, increment)
         dbclient.hincrbyfloat dbkey(suffix), field, increment
       end
       alias incrementbyfloat incrbyfloat
 
+      # Decrements the integer value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param decrement [Integer] The decrement value
+      # @return [Integer] The value after decrementing
       def decrby(field, decrement)
         dbclient.decrby dbkey(suffix), field, decrement
       end
       alias decrementby decrby
 
+      # Decrements the integer value of a hash field by 1.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The value after decrementing
       def decr(field)
         dbclient.hdecr field
       end
       alias decrement decr
 
+      # Returns the string length of the value associated with field in the hash.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The string length of the field value, or 0 if field doesn't exist
       def hstrlen(field)
         dbclient.hstrlen dbkey(suffix), field
       end
       alias hstrlength hstrlen
 
+      # Determines if a hash field exists.
+      #
+      # @param field [String] The field name
+      # @return [Boolean] true if the field exists, false otherwise
       def key?(field)
         dbclient.hexists dbkey(suffix), field
       end
@@ -176,14 +250,61 @@ module Familia
       #
       # @return [Boolean] true if the key was deleted, false otherwise
       def delete!
-        Familia.trace :DELETE!, nil, uri if Familia.debug?
+        Familia.trace :DELETE!, nil, self.class.uri if Familia.debug?
 
         # Delete the main object key
-        ret = dbclient.del dbkey
-        ret.positive?
+        dbclient.del dbkey
       end
       alias clear delete!
 
+      # Watches the key for changes during a MULTI/EXEC transaction.
+      #
+      # Decision Matrix:
+      #
+      #   | Scenario | Use | Why |
+      #   |----------|-----|-----|
+      #   | Check if exists, then create | WATCH | Must prevent duplicate creation |
+      #   | Read value, update conditionally | WATCH | Decision depends on current state |
+      #   | Compare-and-swap operations | WATCH | Need optimistic locking |
+      #   | Version-based updates | WATCH | Must detect concurrent changes |
+      #   | Batch field updates | MULTI only | No conditional logic |
+      #   | Increment + timestamp together | MULTI only | Concurrent increments OK |
+      #   | Save object atomically | MULTI only | Just need atomicity |
+      #   | Update indexes with save | MULTI only | No state checking needed |
+      #
+      # @param suffix_override [String, nil] Optional suffix override
+      # @return [String] 'OK' on success
+      def watch(...)
+        raise ArgumentError, 'Block required' unless block_given?
+
+        # Forward all arguments including the block to the watch command
+        dbclient.watch(dbkey, ...)
+
+      rescue Redis::BaseError => e
+        raise OptimisticLockError, "Redis error: #{e.message}"
+      end
+
+      # Flushes all the previously watched keys for a transaction.
+      #
+      # If a transaction completes successfully or discard is called, there's
+      # no need to manually call unwatch.
+      #
+      # NOTE: This command operates on the connection itself; not a specific key
+      #
+      # @return [String] 'OK' always, regardless of whether the key was watched or not
+      def unwatch(...) = dbclient.unwatch(...)
+
+      # Flushes all previously queued commands in a transaction and all watched keys
+      #
+      # NOTE: This command operates on the connection itself; not a specific key
+      #
+      # @return [String] 'OK' always
+      def discard(...) = dbclient.discard(...)
+
+      # Echoes a message through the Redis connection.
+      #
+      # @param args [Array] Arguments to join and echo
+      # @return [String] The echoed message
       def echo(*args)
         dbclient.echo "[#{self.class}] #{args.join(' ')}"
       end