familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/horreum.rb

@@ -7,25 +7,41 @@ require_relative 'horreum/core'
 
 module Familia
   #
-  # Horreum: A module for managing Redis-based object storage and relationships
+  # Horreum: A Valkey/Redis-backed ORM base class providing field definitions and DataType relationships
   #
-  # Key features:
-  # * Provides instance-level access to a single hash in Redis
-  # * 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
+  # Familia::Horreum serves as the foundation for creating Ruby objects that are persisted
+  # to and retrieved from Valkey/Redis. It provides a comprehensive field system, DataType
+  # relationships, and automated key generation for seamless object-relational mapping.
   #
-  # Metaprogramming:
-  # * The class << self block defines class-level behavior
-  # * The `inherited` method extends ClassMethods to subclasses like
-  #  `MyModel` in the example below
+  # Core Features:
+  # * Field definition system with automatic getter/setter/fast writer generation
+  # * DataType relationships (sets, lists, hashes, sorted sets, counters, locks)
+  # * Flexible identifier strategies (symbols, procs, arrays)
+  # * Automatic Redis key generation and management
+  # * Feature system for modular functionality (expiration, safe_dump, relationships)
+  # * Thread-safe DataType instances with automatic freezing
+  # * Multiple initialization patterns for different use cases
+  #
+  # Architecture:
+  # * Inheriting classes automatically extend definition and management methods
+  # * Instance-level DataTypes are created per object with unique Redis keys
+  # * Class-level DataTypes are shared across all instances
+  # * All objects tracked in Familia.members for reloading and introspection
   #
   # Usage:
-  #   class MyModel < Familia::Horreum
+  #   class User < Familia::Horreum
+  #     identifier_field :email
   #     field :name
-  #     field :email
+  #     field :created_at
+  #     set :tags
+  #     list :activity_log
+  #     feature :expiration
   #   end
   #
+  #   user = User.new(email: "john@example.com", name: "John")
+  #   user.tags << "premium"
+  #   user.save
+  #
   class Horreum
     include Familia::Base
     include Familia::Horreum::Core
@@ -33,68 +49,136 @@ module Familia
 
     using Familia::Refinements::TimeLiterals
 
-    # Singleton Class Context
-    #
-    # The code within this block operates on the singleton class (also known as
-    # eigenclass or metaclass) of the current class. This means:
+    # Class-Level Inheritance and Extension Management
     #
-    # 1. Methods defined here become class methods, not instance methods.
-    # 2. Constants and variables set here belong to the class, not instances.
-    # 3. This is the place to define class-level behavior and properties.
+    # This singleton class block defines the metaclass behavior that governs how
+    # Familia::Horreum subclasses are configured and extended when they inherit.
     #
-    # Use this context for:
-    # * Defining class methods
-    # * Setting class-level configurations
-    # * Creating factory methods
-    # * Establishing relationships with other classes
+    # Key Responsibilities:
+    # * Automatically extend subclasses with essential functionality modules
+    # * Register new classes in Familia.members for tracking and reloading
+    # * Provide class-level attribute accessors for configuration
+    # * Establish the inheritance chain that enables the Horreum ORM pattern
     #
-    # Example:
-    #   class MyClass
-    #     class << self
-    #       def class_method
-    #         puts "This is a class method"
-    #       end
-    #     end
-    #   end
+    # When a class inherits from Horreum, the inherited() hook automatically:
+    # * Extends DefinitionMethods (field, identifier_field, dbkey definitions)
+    # * Extends ManagementMethods (create, find, destroy operations)
+    # * Extends Connection (database client and connection management)
+    # * Extends Features (feature loading and configuration)
+    # * Registers the class in Familia.members for introspection
     #
-    #   MyClass.class_method  # => "This is a class method"
-    #
-    # Note: Changes made here affect the class itself and all future instances,
-    # but not existing instances of the class.
+    # Class-Level Attributes:
+    # * @parent - Parent object reference for nested relationships
+    # * @dbclient - Database connection override for this class
+    # * @dump_method/@load_method - Serialization method configuration
+    # * @has_related_fields - Flag indicating if DataType relationships are defined
     #
     class << self
       attr_accessor :parent
       # TODO: Where are we calling dbclient= from now with connection pool?
       attr_writer :dbclient, :dump_method, :load_method
-      attr_reader :has_relations
+      attr_reader :has_related_fields
 
       # 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?
+        Familia.trace :HORREUM, nil, "Welcome #{member} to the family" if Familia.debug?
 
         # Class-level functionality extensions:
         member.extend(Familia::Horreum::DefinitionMethods)    # field(), identifier_field(), dbkey()
         member.extend(Familia::Horreum::ManagementMethods)    # create(), find(), destroy!()
         member.extend(Familia::Horreum::Connection)           # dbclient, connection management
-        member.extend(Familia::Features)             # feature() method for optional modules
+        member.extend(Familia::Features) # feature() method for optional modules
+
+        # Copy parent class configuration to child class
+        # This implements conventional ORM inheritance behavior where child classes
+        # automatically inherit all parent configuration without manual copying
+        parent_class = member.superclass
+        if parent_class.respond_to?(:identifier_field) && parent_class != Familia::Horreum
+          # Copy essential configuration instance variables from parent
+          if parent_class.identifier_field
+            member.instance_variable_set(:@identifier_field, parent_class.identifier_field)
+          end
+
+          # Copy field system configuration
+          member.instance_variable_set(:@fields, parent_class.fields.dup) if parent_class.fields&.any?
+
+          if parent_class.respond_to?(:field_types) && parent_class.field_types&.any?
+            # Copy field_types hash (FieldType instances are frozen/immutable and can be safely shared)
+            copied_field_types = parent_class.field_types.dup
+            member.instance_variable_set(:@field_types, copied_field_types)
+            # Re-install field methods on the child class using proper method name detection
+            parent_class.field_types.each_value do |field_type|
+              # Collect all method names that field_type.install will create
+              methods_to_check = [
+                field_type.method_name,
+                (field_type.method_name ? :"#{field_type.method_name}=" : nil),
+                field_type.fast_method_name,
+              ].compact
+
+              # Only install if none of the methods already exist
+              methods_exist = methods_to_check.any? do |method_name|
+                member.method_defined?(method_name) || member.private_method_defined?(method_name)
+              end
+
+              field_type.install(member) unless methods_exist
+            end
+          end
+
+          # Copy features configuration
+          if parent_class.respond_to?(:features_enabled) && parent_class.features_enabled&.any?
+            member.instance_variable_set(:@features_enabled, parent_class.features_enabled.dup)
+          end
+
+          # Copy other configuration using consistent instance variable access
+          if (prefix = parent_class.instance_variable_get(:@prefix))
+            member.instance_variable_set(:@prefix, prefix)
+          end
+          if (suffix = parent_class.instance_variable_get(:@suffix))
+            member.instance_variable_set(:@suffix, suffix)
+          end
+          if (logical_db = parent_class.instance_variable_get(:@logical_database))
+            member.instance_variable_set(:@logical_database, logical_db)
+          end
+          if (default_exp = parent_class.instance_variable_get(:@default_expiration))
+            member.instance_variable_set(:@default_expiration, default_exp)
+          end
+
+          # Copy DataType relationships
+          if parent_class.class_related_fields&.any?
+            member.instance_variable_set(:@class_related_fields, parent_class.class_related_fields.dup)
+          end
+          if parent_class.related_fields&.any?
+            member.instance_variable_set(:@related_fields, parent_class.related_fields.dup)
+          end
+          if parent_class.instance_variable_get(:@has_related_fields)
+            member.instance_variable_set(:@has_related_fields,
+                                         parent_class.instance_variable_get(:@has_related_fields))
+          end
+        end
 
         # Track all classes that inherit from Horreum
         Familia.members << member
+
+        # Set up automatic instance tracking using built-in class_sorted_set
+        member.class_sorted_set :instances
+
         super
       end
     end
 
+    attr_writer :dbclient
+
     # Instance initialization
-    # This method sets up the object's state, including Redis-related data.
+    # This method sets up the object's state, including Valkey/Redis-related data.
     #
     # Usage:
     #
-    #   Session.new("abc123", "user456")                   # positional (brittle)
-    #   Session.new(sessid: "abc123", custid: "user456")   # hash (robust)
-    #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
+    #   `Session.new("abc123", "user456")`                   # positional (brittle)
+    #   `Session.new(sessid: "abc123", custid: "user456")`   # hash (robust)
+    #   `Session.new({sessid: "abc123", custid: "user456"})` # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
-      Familia.trace :INITIALIZE, dbclient, "Initializing #{self.class}", caller(1..1) if Familia.debug?
+      Familia.trace :INITIALIZE, nil, "Initializing #{self.class}" if Familia.debug?
       initialize_relatives
 
       # No longer auto-create a key field - the identifier method will
@@ -108,15 +192,16 @@ module Familia
 
       # Initialize object with arguments using one of four strategies:
       #
-      # 1. **Identifier** (Recommended for lookups): A single argument is treated as the identifier.
-      #    Example: Customer.new("cust_123")
-      #    - Robust and convenient for creating objects from an ID.
+      # 1. **Identifier** (Recommended for lookups): A single argument is
+      #     treated as the identifier. Robust and convenient for creating
+      #     objects from an ID. e.g. `Customer.new("cust_123")`
       #
-      # 2. **Keyword Arguments** (Recommended for creation): Order-independent field assignment
-      #    Example: Customer.new(name: "John", email: "john@example.com")
+      # 2. **Keyword Arguments** (Recommended for creation): Order-independent
+      #     field assignment
+      #    e.g. Customer.new(name: "John", email: "john@example.com")
       #
       # 3. **Positional Arguments** (Legacy): Field assignment by definition order
-      #    Example: Customer.new("cust_123", "John", "john@example.com")
+      #    e.g. Customer.new("cust_123", "John", "john@example.com")
       #
       # 4. **No Arguments**: Object created with all fields as nil
       #
@@ -127,8 +212,8 @@ module Familia
         initialize_with_keyword_args(**kwargs)
       elsif args.any?
         initialize_with_positional_args(*args)
-      else
-        Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
+      elsif Familia.debug?
+        Familia.trace :INITIALIZE, nil, "#{self.class} initialized with no arguments"
         # Default values are intentionally NOT set here
       end
 
@@ -143,7 +228,7 @@ module Familia
     end
 
     # Sets up related Database objects for the instance
-    # This method is crucial for establishing Redis-based relationships
+    # This method is crucial for establishing Valkey/Redis-based relationships
     #
     # This needs to be called in the initialize method.
     #
@@ -159,7 +244,7 @@ module Familia
       self.class.related_fields.each_pair do |name, data_type_definition|
         klass = data_type_definition.klass
         opts = data_type_definition.opts
-        Familia.trace :INITIALIZE_RELATIVES, dbclient, "#{name} => #{klass} #{opts.keys}", caller(1..1) if Familia.debug?
+        Familia.trace :INITIALIZE_RELATIVES, nil, "#{name} => #{klass} #{opts.keys}" if Familia.debug?
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
         # automatically. This is what determines the dbkey for DataType
@@ -169,7 +254,8 @@ module Familia
         #     then the dbkey for this DataType instance will be
         #     `customer:customer_id:name`.
         #
-        opts[:parent] = self # unless opts.key(:parent)
+        # Store reference to the instance for lazy ParentDefinition creation
+        opts[:parent] = self
 
         suffix_override = opts.fetch(:suffix, name)
 
@@ -188,48 +274,6 @@ module Familia
       end
     end
 
-    # Initializes the object with positional arguments.
-    # Maps each argument to a corresponding field in the order they are defined.
-    #
-    # @param args [Array] List of values to be assigned to fields
-    # @return [Array<Symbol>] List of field names that were successfully updated
-    #   (i.e., had non-nil values assigned)
-    # @private
-    def initialize_with_positional_args(*args)
-      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)
-          field.to_sym
-        end
-      end
-    end
-    private :initialize_with_positional_args
-
-    # Initializes the object with keyword arguments.
-    # Assigns values to fields based on the provided hash of field names and values.
-    # Handles both symbol and string keys to accommodate different sources of data.
-    #
-    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
-    # @return [Array<Symbol>] List of field names that were successfully updated
-    #   (i.e., had non-nil values assigned)
-    # @private
-    def initialize_with_keyword_args(**fields)
-      Familia.trace :INITIALIZE_KWARGS, dbclient, fields.keys, caller(1..1) if Familia.debug?
-      self.class.fields.filter_map do |field|
-        # 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
-          # Use the mapped method name, not the field name
-          method_name = self.class.field_method_map[field] || field
-          send(:"#{method_name}=", value)
-          field.to_sym
-        end
-      end
-    end
-    private :initialize_with_keyword_args
-
     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) }
@@ -270,33 +314,26 @@ module Familia
                   end
 
       # Return nil for unpopulated identifiers (like unsaved ActiveRecord objects)
-      # Only raise errors when the identifier is actually needed for Redis operations
+      # Only raise errors when the identifier is actually needed for db 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.
+    # Returns the Database connection for the instance using Chain of Responsibility pattern.
     #
-    # @return [Redis] A shimmering Database connection, ready for your bidding.
+    # This method uses a chain of handlers to resolve connections in priority order:
+    # 1. FiberTransactionHandler - Fiber[:familia_transaction] (active transaction)
+    # 2. CachedConnectionHandler - Accesses self.dbclient
+    # 3. CachedConnectionHandler - Accesses self.class.dbclient
+    # 4. GlobalFallbackHandler - Familia.dbclient(uri || logical_database) (global fallback)
     #
-    # @example Finding your Database way
-    #   puts object.dbclient
-    #   # => #<Redis client v5.4.1 for redis://localhost:6379/0>
+    # @return [Redis] the Database connection instance.
     #
-    def dbclient
-      Fiber[:familia_transaction] || @dbclient || self.class.dbclient
-      # conn.select(self.class.logical_database)
-    end
+
 
     def generate_id
-      @objid ||= Familia.generate_id # rubocop:disable Naming/MemoizedInstanceVariableName
+      @objid ||= Familia.generate_id
     end
 
     # The principle is: **If Familia objects have `to_s`, then they should work
@@ -309,5 +346,50 @@ module Familia
 
       identifier.to_s
     end
+
+    private
+
+    # Initializes the object with positional arguments.
+    # Maps each argument to a corresponding field in the order they are defined.
+    #
+    # @param args [Array] List of values to be assigned to fields
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_positional_args(*args)
+      Familia.trace :INITIALIZE_ARGS, nil, args if Familia.debug?
+      self.class.fields.zip(args).filter_map do |field, value|
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
+      end
+    end
+
+    # Initializes the object with keyword arguments.
+    # Assigns values to fields based on the provided hash of field names and values.
+    # Handles both symbol and string keys to accommodate different sources of data.
+    #
+    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_keyword_args(**fields)
+      Familia.trace :INITIALIZE_KWARGS, nil, fields.keys if Familia.debug?
+      self.class.fields.filter_map do |field|
+        # 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
+          # Use the mapped method name, not the field name
+          method_name = self.class.field_method_map[field] || field
+          send(:"#{method_name}=", value)
+          field.to_sym
+        end
+      end
+    end
+
+    # Builds the instance-level connection chain with handlers in priority order
+
   end
 end

data/lib/familia/json_serializer.rb

@@ -13,7 +13,6 @@ module Familia
   #   parsed = Familia::JsonSerializer.parse(json, symbolize_names: true)
   #
   module JsonSerializer
-
     class << self
       # Parse JSON string into Ruby objects
       #

data/lib/familia/logging.rb

@@ -10,6 +10,7 @@ module Familia
     severity_letter = severity[0] # Get the first letter of the severity
     pid = Process.pid
     thread_id = Thread.current.object_id
+    fiber_id = Fiber.current.object_id
     full_path, line = caller(5..5).first.split(':')[0..1]
     parent_path = Pathname.new(full_path).ascend.find { |p| p.basename.to_s == 'familia' }
     relative_path = full_path.sub(parent_path.to_s, 'familia')
@@ -19,9 +20,9 @@ module Familia
     # the default. The thread local variable is set in the trace
     # method in the Familia::Refinements::LoggerTrace module. The name of the
     # variable `severity_letter` is arbitrary and could be anything.
-    severity_letter = Thread.current[:severity_letter] || severity_letter
+    severity_letter = Fiber[:severity_letter] || severity_letter
 
-    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  [#{relative_path}:#{line}]\n"
+    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}/#{fiber_id}: #{msg}  [#{relative_path}:#{line}]\n"
   end
 
   # The Logging module provides a set of methods and constants for logging messages
@@ -103,9 +104,7 @@ module Familia
     attr_reader :logger
 
     # Gives our logger the ability to use our trace method.
-    if Familia::Refinements::LoggerTrace::ENABLED
-      using Familia::Refinements::LoggerTrace
-    end
+    using Familia::Refinements::LoggerTrace if Familia::Refinements::LoggerTrace::ENABLED
 
     def info(*msg)
       @logger.info(*msg)
@@ -129,16 +128,12 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param dbclient [Redis, Redis::Future, nil] The Database instance or
-    #   Future being used.
+    # @param instance_id
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
-    # @param context [Array<String>, String, nil] The calling context, typically
-    #   obtained from `caller` or `caller.first`. Default is nil.
+    # @param extra_context [Array<String>, String, nil] Any extra details to include.
     #
-    # @example
-    #   Familia.trace :LOAD, Familia.dbclient(uri), objkey, caller(1..1) if
-    #   Familia.debug?
+    # @example Familia.trace :LOAD, Familia.dbclient(uri), objkey if Familia.debug?
     #
     # @return [nil]
     #
@@ -147,110 +142,12 @@ module Familia
     #   pipelined and multi blocks), or nil (when the database connection isn't
     #   relevant).
     #
-    def trace(label, dbclient, ident, context = nil)
+    def trace(label, instance_id = nil, ident = nil, extra_context = nil)
       return unless Familia::Refinements::LoggerTrace::ENABLED
 
-      # 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
-      # database connection isn't relevant.
-      instance_id = if dbclient
-                      case dbclient
-                      when Redis
-                        dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
-                      when Redis::Future
-                        'Redis::Future'
-                      else
-                        dbclient.class.name
-                      end
-                    end
-
-      codeline = if context
-                   context = [context].flatten
-                   context.reject! { |line| line =~ %r{lib/familia} }
-                   context.first
-                 end
-
-      @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
+      # Let the other values show nothing when nil, but make it known for the focused value
+      ident_str = (ident.nil? ? '<nil>' : ident).to_s
+      @logger.trace format('[%s] %s -> %s <-%s', label, instance_id, ident_str, extra_context)
     end
   end
 end
-
-
-__END__
-
-
-### Example 1: Basic Logging
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 2: Setting Log Level
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.level = Logger::WARN
-
-logger.debug("This is a debug message") # Will not be logged
-logger.info("This is an info message")  # Will not be logged
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 3: Customizing Log Format
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.formatter = proc do |severity, datetime, progname, msg|
-  "#{datetime}: #{severity} - #{msg}\n"
-end
-
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 4: Logging with a Program Name
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.progname = 'Familia'
-
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 5: Logging with a Block
-```ruby
-require 'logger'
-
-# Calling any of the methods above with a block
-#   (affects only the one entry).
-#   Doing so can have two benefits:
-#
-#   - Context: the block can evaluate the entire program context
-#     and create a context-dependent message.
-#   - Performance: the block is not evaluated unless the log level
-#     permits the entry actually to be written:
-#
-#       logger.error { my_slow_message_generator }
-#
-#     Contrast this with the string form, where the string is
-#     always evaluated, regardless of the log level:
-#
-#       logger.error("#{my_slow_message_generator}")
-logger = Logger.new($stdout)
-
-logger.info { "This is an info message" }
-logger.warn { "This is a warning message" }
-logger.error { "This is an error message" }
-```