familia 2.0.0.pre16 → 2.0.0.pre18

data/lib/familia/base.rb

@@ -17,8 +17,6 @@ module Familia
 
     @features_available = nil
     @feature_definitions = nil
-    @dump_method = :to_json
-    @load_method = :from_json
 
     def self.included(base)
       # Ensure the including class gets its own feature registry
@@ -31,14 +29,15 @@ module Familia
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
 
-      def add_feature(klass, feature_name, depends_on: [])
+      def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}
         Familia.trace :ADD_FEATURE, klass, feature_name if Familia.debug?
 
         # Create field definition object
         feature_def = FeatureDefinition.new(
           name: feature_name,
-          depends_on: depends_on
+          depends_on: depends_on,
+          field_group: field_group
         )
 
         # Track field definitions after defining field methods
@@ -112,14 +111,15 @@ module Familia
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
 
-      def add_feature(klass, feature_name, depends_on: [])
+      def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}
         Familia.trace :ADD_FEATURE, klass, feature_name if Familia.debug?
 
         # Create field definition object
         feature_def = FeatureDefinition.new(
           name: feature_name,
-          depends_on: depends_on
+          depends_on: depends_on,
+          field_group: field_group
         )
 
         # Track field definitions after defining field methods

data/lib/familia/connection/middleware.rb

@@ -1,6 +1,6 @@
 # lib/familia/connection/middleware.rb
 
-require_relative '../../middleware/database_middleware'
+require_relative '../../middleware/database_logger'
 
 module Familia
   module Connection
@@ -19,13 +19,13 @@ module Familia
       # Increments the middleware version, invalidating all cached connections
       def increment_middleware_version!
         @middleware_version += 1
-        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}" if Familia.debug?
+        Familia.trace :MIDDLEWARE_VERSION, nil, "Incremented to #{@middleware_version}"
       end
 
       # Sets a versioned fiber-local connection
-      def set_fiber_connection(connection)
+      def fiber_connection=(connection)
         Fiber[:familia_connection] = [connection, middleware_version]
-        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}" if Familia.debug?
+        Familia.trace :FIBER_CONNECTION, nil, "Set with version #{middleware_version}"
       end
 
       # Clears the fiber-local connection
@@ -50,24 +50,78 @@ module Familia
         increment_middleware_version! if value
       end
 
+      # Reconnects with fresh middleware registration
+      #
+      # This method is useful when middleware needs to be applied to connection pools
+      # that were created before middleware was enabled. It:
+      #
+      # 1. Clears the middleware registration flag to allow re-registration
+      # 2. Re-runs the middleware registration logic
+      # 3. Clears connection chain to force rebuild
+      # 4. Increments middleware version to invalidate cached connections
+      # 5. Clears fiber-local connections
+      #
+      # The next connection request will use the updated middleware configuration.
+      # Existing connection pools will naturally create new connections with middleware
+      # as old connections are cycled out.
+      #
+      # @note If no middleware is enabled, this method safely clears connection state
+      #       but won't register any middleware until it's enabled.
+      #
+      # @example Enable middleware and reconnect
+      #   Familia.enable_database_logging = true
+      #   Familia.reconnect!
+      #
+      # @example In test suites
+      #   # Test file A creates pools
+      #   Familia.connection_provider = ->(uri) { pool.with { |c| c } }
+      #
+      #   # Test file B enables middleware
+      #   Familia.enable_database_logging = true
+      #   Familia.reconnect!  # Force new connections with middleware
+      #
+      def reconnect!
+        # Allow middleware to be re-registered
+        @middleware_registered = false
+        register_middleware_once
+
+        # Clear connection chain to force rebuild
+        @connection_chain = nil
+
+        # Increment version to invalidate all cached connections
+        increment_middleware_version!
+
+        # Clear fiber-local connections
+        clear_fiber_connection!
+
+        Familia.trace :RECONNECT, nil, 'Connection chain cleared, will rebuild with current middleware on next use'
+      end
+
       private
 
       # Registers middleware once globally, regardless of when clients are created.
       # This prevents duplicate middleware registration and ensures all clients get middleware.
       def register_middleware_once
+        # Skip if already registered
         return if @middleware_registered
 
+        # Check if any middleware is enabled
+        return unless Familia.enable_database_logging || Familia.enable_database_counter
+
         if Familia.enable_database_logging
           DatabaseLogger.logger = Familia.logger
           RedisClient.register(DatabaseLogger)
+          Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseLogger'
         end
 
         if Familia.enable_database_counter
           # NOTE: This middleware uses AtomicFixnum from concurrent-ruby which is
           # less contentious than Mutex-based counters. Safe for production.
           RedisClient.register(DatabaseCommandCounter)
+          Familia.trace :MIDDLEWARE_REGISTERED, nil, 'Registered DatabaseCommandCounter'
         end
 
+        # Set flag after successful registration
         @middleware_registered = true
       end
     end

data/lib/familia/connection.rb

@@ -42,7 +42,7 @@ module Familia
       @connection_chain = nil # Force rebuild of chain
     end
 
-    # Sets the default URI for Database connections.
+# Sets the default URI for Database connections.
     #
     # NOTE: uri is not a property of the Settings module b/c it's not
     # configured in class defintions like default_expiration or logical DB index.

data/lib/familia/data_type/class_methods.rb

@@ -0,0 +1,63 @@
+# lib/familia/data_type/definition.rb
+
+module Familia
+  class DataType
+    # ClassMethods - Class-level DSL methods for defining DataType behavior
+    #
+    # This module is extended into classes that inherit from Familia::DataType,
+    # providing class methods for type registration, configuration, and inheritance.
+    #
+    # Key features:
+    # * Type registration system for creating DataType subclasses
+    # * Database and connection configuration
+    # * Inheritance hooks for propagating settings
+    # * Option validation and filtering
+    #
+    module ClassMethods
+      attr_accessor :parent, :suffix, :prefix, :uri
+      attr_writer :logical_database
+
+      # To be called inside every class that inherits DataType
+      # +methname+ is the term used for the class and instance methods
+      # that are created for the given +klass+ (e.g. set, list, etc)
+      def register(klass, methname)
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}" if Familia.debug?
+
+        @registered_types[methname] = klass
+      end
+
+      # Get the registered type class from a given method name
+      # +methname+ is the method name used to register the class (e.g. :set, :list, etc)
+      # Returns the registered class or nil if not found
+      def registered_type(methname)
+        @registered_types[methname]
+      end
+
+      def logical_database(val = nil)
+        @logical_database = val unless val.nil?
+        @logical_database || parent&.logical_database
+      end
+
+      def uri(val = nil)
+        @uri = val unless val.nil?
+        @uri || (parent ? parent.uri : Familia.uri)
+      end
+
+      def inherited(obj)
+        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type" if Familia.debug?
+        obj.logical_database = logical_database
+        obj.default_expiration = default_expiration # method added via Features::Expiration
+        obj.uri = uri
+        super
+      end
+
+      def valid_keys_only(opts)
+        opts.slice(*DataType.valid_options)
+      end
+
+      def relations?
+        @has_related_fields ||= false
+      end
+    end
+  end
+end

data/lib/familia/data_type/connection.rb

@@ -0,0 +1,83 @@
+# lib/familia/data_type/connection.rb
+
+module Familia
+  class DataType
+    # Connection - Instance-level connection and key generation methods
+    #
+    # This module provides instance methods for database connection resolution
+    # and Redis key generation for DataType objects.
+    #
+    # Key features:
+    # * Database connection resolution with Chain of Responsibility pattern
+    # * Redis key generation based on parent context
+    # * Direct database access for advanced operations
+    #
+    module Connection
+      # TODO: Replace with Chain of Responsibility pattern
+      def dbclient
+        return Fiber[:familia_transaction] if Fiber[:familia_transaction]
+        return @dbclient if @dbclient
+
+        # Delegate to parent if present, otherwise fall back to Familia
+        parent ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+      end
+
+      # Produces the full dbkey for this object.
+      #
+      # @return [String] The full dbkey.
+      #
+      # This method determines the appropriate dbkey based on the context of the DataType object:
+      #
+      # 1. If a hardcoded key is set in the options, it returns that key.
+      # 2. For instance-level DataType objects, it uses the parent instance's dbkey method.
+      # 3. For class-level DataType objects, it uses the parent class's dbkey method.
+      # 4. For standalone DataType objects, it uses the keystring as the full dbkey.
+      #
+      # For class-level DataType objects (parent_class? == true):
+      # - The suffix is optional and used to differentiate between different types of objects.
+      # - If no suffix is provided, the class's default suffix is used (via the self.suffix method).
+      # - If a nil suffix is explicitly passed, it won't appear in the resulting dbkey.
+      # - Passing nil as the suffix is how class-level DataType objects are created without
+      #   the global default 'object' suffix.
+      #
+      # @example Instance-level DataType
+      #   user_instance.some_datatype.dbkey  # => "user:123:some_datatype"
+      #
+      # @example Class-level DataType
+      #   User.some_datatype.dbkey  # => "user:some_datatype"
+      #
+      # @example Standalone DataType
+      #   DataType.new("mykey").dbkey  # => "mykey"
+      #
+      # @example Class-level DataType with explicit nil suffix
+      #   User.dbkey("123", nil)  # => "user:123"
+      #
+      def dbkey
+        # Return the hardcoded key if it's set. This is useful for
+        # support legacy keys that aren't derived in the same way.
+        return opts[:dbkey] if opts[:dbkey]
+
+        if parent_instance?
+          # This is an instance-level datatype object so the parent instance's
+          # dbkey method is defined in Familia::Horreum::InstanceMethods.
+          parent.dbkey(keystring)
+        elsif parent_class?
+          # This is a class-level datatype object so the parent class' dbkey
+          # method is defined in Familia::Horreum::DefinitionMethods.
+          parent.dbkey(keystring, nil)
+        else
+          # This is a standalone DataType object where it's keystring
+          # is the full database key (dbkey).
+          keystring
+        end
+      end
+
+      # Provides a structured way to "gear down" to run db commands that are
+      # not implemented in our DataType classes since we intentionally don't
+      # have a method_missing method.
+      def direct_access
+        yield(dbclient, dbkey)
+      end
+    end
+  end
+end

data/lib/familia/data_type/{commands.rb → database_commands.rb}

@@ -1,10 +1,10 @@
-# lib/familia/data_type/commands.rb
+# lib/familia/data_type/database_commands.rb
 
 module Familia
   class DataType
     # Must be included in all DataType classes to provide Valkey/Redis
     # commands. The class must have a dbkey method.
-    module Commands
+    module DatabaseCommands
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end

data/lib/familia/data_type/serialization.rb

@@ -11,9 +11,9 @@ module Familia
       # @return [String, nil] The serialized representation of the value, or nil
       #   if serialization fails.
       #
-      # @note When a class option is specified, it uses that class's
-      #   serialization method. Otherwise, it relies on Familia.distinguisher for
-      #   serialization.
+      # @note When a class option is specified, it uses Familia.identifier_extractor
+      #   to extract the identifier from objects. Otherwise, it extracts identifiers
+      #   from Familia::Base instances or class names.
       #
       # @example With a class option
       #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
@@ -31,13 +31,13 @@ module Familia
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
         if opts[:class]
-          prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
+          prepared = Familia.identifier_extractor(opts[:class])
           Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
         end
 
         if prepared.nil?
           # Enforce strict values when no class option is specified
-          prepared = Familia.distinguisher(val, strict_values: true)
+          prepared = Familia.identifier_extractor(val)
           Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
         end
 

data/lib/familia/data_type/settings.rb

@@ -0,0 +1,96 @@
+# lib/familia/data_type/settings.rb
+
+module Familia
+  class DataType
+    # Settings - Instance-level configuration and introspection methods
+    #
+    # This module provides instance methods for accessing and managing
+    # DataType object configuration, parent relationships, and serialization.
+    #
+    # Key features:
+    # * Parent object relationship management
+    # * URI and database configuration
+    # * Serialization method delegation
+    # * Type introspection
+    #
+    module Settings
+      attr_reader :keystring, :opts, :logical_database
+      attr_reader :uri
+
+      alias url uri
+
+      def class?
+        !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
+      end
+
+      def parent_instance?
+        parent&.is_a?(Horreum::ParentDefinition)
+      end
+
+      def parent_class?
+        parent.is_a?(Class) && parent.ancestors.include?(Familia::Horreum)
+      end
+
+      def parent?
+        parent_class? || parent_instance?
+      end
+
+      def parent
+        # Return cached ParentDefinition if available
+        return @parent if @parent
+
+        # Return class-level parent if no instance parent
+        return self.class.parent unless @parent_ref
+
+        # Create ParentDefinition dynamically from stored reference.
+        # This ensures we get the current identifier value (available after initialization)
+        # rather than a stale nil value from initialization time. Cannot cache due to frozen object.
+        Horreum::ParentDefinition.from_parent(@parent_ref)
+      end
+
+      def parent=(value)
+        case value
+        when Horreum::ParentDefinition
+          @parent = value
+        when nil
+          @parent = nil
+          @parent_ref = nil
+        else
+          # Store parent instance reference for lazy ParentDefinition creation.
+          # During initialization, the parent's identifier may not be available yet,
+          # so we defer ParentDefinition creation until first access for memory efficiency.
+          # Note: @parent_ref is not cleared after use because DataType objects are frozen.
+          @parent_ref = value
+          @parent = nil  # Will be created dynamically in parent method
+        end
+      end
+
+      def uri
+        # Return explicit instance URI if set
+        return @uri if @uri
+
+        # If we have a parent with logical_database, build URI with that database
+        if parent && parent.respond_to?(:logical_database) && parent.logical_database
+          new_uri = (self.class.uri || Familia.uri).dup
+          new_uri.db = parent.logical_database
+          new_uri
+        else
+          # Fall back to class-level URI or global Familia.uri
+          self.class.uri || Familia.uri
+        end
+      end
+
+      def uri=(value)
+        @uri = value
+      end
+
+      def dump_method
+        self.class.dump_method
+      end
+
+      def load_method
+        self.class.load_method
+      end
+    end
+  end
+end

data/lib/familia/data_type/types/hashkey.rb

@@ -95,7 +95,8 @@ module Familia
     def remove_field(field)
       dbclient.hdel dbkey, field.to_s
     end
-    alias remove remove_field # deprecated
+    alias remove remove_field
+    alias remove_element remove_field
 
     def increment(field, by = 1)
       dbclient.hincrby(dbkey, field.to_s, by).to_i

data/lib/familia/data_type/types/sorted_set.rb

@@ -46,17 +46,81 @@ module Familia
       add val, score
     end
 
-    def add(val, score = nil)
-      # TODO: Support some or all of the ZADD options.
-      # XX: Only update existing elements. Don't add new ones.
-      # NX: Only add new elements. Don't update existing ones.
-      # LT: Only update if new score < current score. Doesn't prevent adding.
-      # GT: Only update if new score > current score. Doesn't prevent adding.
-      # CH: Return total changed elements (new + updated) instead of just new.
-      # INCR: Acts like ZINCRBY. Only one score-element pair allowed.
-      # Note: GT, LT and NX options are mutually exclusive.
+    # Adds an element to the sorted set with an optional score and ZADD options.
+    #
+    # This method supports Redis ZADD options for conditional adds and updates:
+    # - **NX**: Only add new elements (don't update existing)
+    # - **XX**: Only update existing elements (don't add new)
+    # - **GT**: Only update if new score > current score
+    # - **LT**: Only update if new score < current score
+    # - **CH**: Return changed count (new + updated) instead of just new count
+    #
+    # @param val [Object] The value to add to the sorted set
+    # @param score [Numeric, nil] The score for ranking (defaults to current timestamp)
+    # @param nx [Boolean] Only add new elements, don't update existing (default: false)
+    # @param xx [Boolean] Only update existing elements, don't add new (default: false)
+    # @param gt [Boolean] Only update if new score > current score (default: false)
+    # @param lt [Boolean] Only update if new score < current score (default: false)
+    # @param ch [Boolean] Return changed count instead of added count (default: false)
+    #
+    # @return [Boolean] Returns the return value from the redis gem's ZADD
+    #   command. Returns true if element was added or changed (with CH option),
+    #   false if element score was updated without change tracking or no
+    #   operation occurred due to option constraints (NX, XX, GT, LT).
+    #
+    # @raise [ArgumentError] If mutually exclusive options are specified together
+    #   (NX+XX, GT+LT, NX+GT, NX+LT)
+    #
+    # @example Add new element with timestamp
+    #   metrics.add('pageview', Time.now.to_f)  #=> true
+    #
+    # @example Preserve original timestamp on subsequent saves
+    #   index.add(email, Time.now.to_f, nx: true)  #=> true
+    #   index.add(email, Time.now.to_f, nx: true)  #=> false (unchanged)
+    #
+    # @example Update timestamp only for existing entries
+    #   index.add(email, Time.now.to_f, xx: true)  #=> false (if doesn't exist)
+    #
+    # @example Only update if new score is higher (leaderboard)
+    #   scores.add(player, 1000, gt: true)  #=> true (new entry)
+    #   scores.add(player, 1500, gt: true)  #=> false (updated)
+    #   scores.add(player, 1200, gt: true)  #=> false (not updated, score lower)
+    #
+    # @example Track total changes for analytics
+    #   changed = metrics.add(user, score, ch: true)  #=> true (new or updated)
+    #
+    # @example Combined options: only update existing, only if score increases
+    #   index.add(key, new_score, xx: true, gt: true)
+    #
+    # @note GT and LT options do NOT prevent adding new elements, they only
+    #   affect update behavior for existing elements.
+    #
+    # @note Default behavior (no options) adds new elements and updates existing
+    #   ones unconditionally, matching standard Redis ZADD semantics.
+    #
+    # @note INCR option is not supported. Use the increment method for ZINCRBY operations.
+    #
+    def add(val, score = nil, nx: false, xx: false, gt: false, lt: false, ch: false)
       score ||= Familia.now
-      ret = dbclient.zadd dbkey, score, serialize_value(val)
+
+      # Validate mutual exclusivity
+      validate_zadd_options!(nx: nx, xx: xx, gt: gt, lt: lt)
+
+      # Build options hash for redis gem
+      opts = {}
+      opts[:nx] = true if nx
+      opts[:xx] = true if xx
+      opts[:gt] = true if gt
+      opts[:lt] = true if lt
+      opts[:ch] = true if ch
+
+      # Pass options to ZADD
+      ret = if opts.empty?
+        dbclient.zadd(dbkey, score, serialize_value(val))
+      else
+        dbclient.zadd(dbkey, score, serialize_value(val), **opts)
+      end
+
       update_expiration
       ret
     end
@@ -242,6 +306,45 @@ module Familia
       at(-1)
     end
 
+
+    private
+
+    # Validates that mutually exclusive ZADD options are not specified together.
+    #
+    # @param nx [Boolean] NX option flag
+    # @param xx [Boolean] XX option flag
+    # @param gt [Boolean] GT option flag
+    # @param lt [Boolean] LT option flag
+    #
+    # @raise [ArgumentError] If mutually exclusive options are specified
+    #
+    # @note Valid combinations: XX+GT, XX+LT
+    # @note Invalid combinations: NX+XX, GT+LT, NX+GT, NX+LT
+    #
+    def validate_zadd_options!(nx:, xx:, gt:, lt:)
+      # NX and XX are mutually exclusive
+      if nx && xx
+        raise ArgumentError, "ZADD options NX and XX are mutually exclusive"
+      end
+
+      # GT and LT are mutually exclusive
+      if gt && lt
+        raise ArgumentError, "ZADD options GT and LT are mutually exclusive"
+      end
+
+      # NX is mutually exclusive with GT
+      if nx && gt
+        raise ArgumentError, "ZADD options NX and GT are mutually exclusive"
+      end
+
+      # NX is mutually exclusive with LT
+      if nx && lt
+        raise ArgumentError, "ZADD options NX and LT are mutually exclusive"
+      end
+
+      # Note: XX + GT and XX + LT are valid combinations
+    end
+
     Familia::DataType.register self, :sorted_set
     Familia::DataType.register self, :zset
   end

data/lib/familia/data_type/types/stringkey.rb

@@ -114,10 +114,6 @@ module Familia
       ret.positive?
     end
 
-    def nil?
-      value.nil?
-    end
-
     Familia::DataType.register self, :string
     Familia::DataType.register self, :stringkey
   end