familia 2.0.0.pre5 → 2.0.0.pre7

data/lib/familia/horreum/{definition_methods.rb → subclass/definition.rb}

@@ -1,29 +1,38 @@
-# lib/familia/horreum/definition_methods.rb
+# lib/familia/horreum/subclass/definition.rb
 
 require_relative 'related_fields_management'
+require_relative '../shared/settings'
 
 module Familia
-  VALID_STRATEGIES = %i[raise skip warn overwrite].freeze
+  VALID_STRATEGIES = %i[raise skip ignore warn overwrite].freeze
 
   # Familia::Horreum
   #
   class Horreum
     # Class-level instance variables
     # These are set up as nil initially and populated later
-    @dbclient = nil # TODO
-    @identifier_field = nil
-    @default_expiration = nil
+    #
+    # Connection and database settings
+    @dbclient = nil
     @logical_database = nil
     @uri = nil
-    @suffix = nil
+
+    # Database Key generation settings
     @prefix = nil
-    @fields = nil # []
-    @class_related_fields = nil # {}
-    @related_fields = nil # {}
+    @identifier_field = nil
+    @suffix = nil
+
+    # Fields and relationships
+    @fields = nil
+    @class_related_fields = nil
+    @related_fields = nil
+    @default_expiration = nil
+
+    # Serialization settings
     @dump_method = nil
     @load_method = nil
 
-    # DefinitionMethods: Provides class-level functionality for Horreum
+    # DefinitionMethods: Provides class-level functionality for Horreum subclasses
     #
     # This module is extended into classes that include Familia::Horreum,
     # providing methods for Database operations and object management.
@@ -35,7 +44,7 @@ module Familia
     #
     module DefinitionMethods
       include Familia::Settings
-      include Familia::Horreum::RelatedFieldsManagement
+      include Familia::Horreum::RelatedFieldsManagement # Provides DataType field methods
 
       # Sets or retrieves the unique identifier field for the class.
       #
@@ -86,12 +95,12 @@ module Familia
       #   - Others, depending on features available
       #
       def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
-        # Use field type system internally for consistency
-        require_relative '../field_type'
+        # Use field type system for consistency
+        require_relative '../../field_type'
 
         # Create appropriate field type based on category
         field_type = if category == :transient
-                       require_relative '../features/transient_fields/transient_field_type'
+                       require_relative '../../features/transient_fields/transient_field_type'
                        TransientFieldType.new(name, as: as, fast_method: false, on_conflict: on_conflict)
                      else
                        # For regular fields and other categories, create custom field type with category override
@@ -160,7 +169,7 @@ module Familia
         @related_fields
       end
 
-      def has_relations?
+      def relations?
         @has_relations ||= false
       end
 
@@ -232,7 +241,7 @@ module Familia
       # @param options [Hash] Field options
       #
       def transient_field(name, **)
-        require_relative '../features/transient_fields/transient_field_type'
+        require_relative '../../features/transient_fields/transient_field_type'
         field_type = TransientFieldType.new(name, **, fast_method: false)
         register_field_type(field_type)
       end
@@ -261,7 +270,7 @@ module Familia
           WARNING
         when :raise
           raise ArgumentError, "Method >>> #{method_name} <<< already defined for #{self}"
-        when :skip
+        when :skip, :ignore
           # Do nothing, skip silently
         end
       end
@@ -279,19 +288,26 @@ module Familia
         end
       end
 
-      # Defines a fast attribute method with a bang (!) suffix for a given
-      # attribute name. Fast attribute methods are used to immediately read or
-      # write attribute values from/to the database. Calling a fast attribute
-      # method has no effect on any of the object's other attributes and does
-      # not trigger a call to update the object's expiration time.
+      # Fast attribute accessor method for immediate DB persistence.
+      #
+      # @param field_name [Symbol, String] the name of the horreum model attribute
+      # @param method_name [Symbol, String] the name of the regular accessor method
+      # @param fast_method_name [Symbol, String] the name of the fast method (must end with '!')
+      # @param on_conflict [Symbol] conflict resolution strategy for method name conflicts
       #
-      # @param [Symbol, String] name the name of the attribute for which the
-      #   fast method is defined.
-      # @return [Object] the current value of the attribute when called without
-      #   arguments.
-      # @raise [ArgumentError] if more than one argument is provided.
-      # @raise [RuntimeError] if an exception occurs during the execution of the
-      #   method.
+      # @return [void]
+      #
+      # @raise [ArgumentError] if fast_method_name doesn't end with '!'
+      #
+      # @note Generated method behavior:
+      #   - Without args: Retrieves current value from Redis
+      #   - With value: Sets and immediately persists to Redis
+      #   - Returns boolean indicating success for writes
+      #   - Bypasses object-level caching and expiration updates
+      #
+      # @example
+      #   # Creates a method like: username!(value = nil)
+      #   define_fast_writer_method(:username, :username, :username!, :raise)
       #
       def define_fast_writer_method(field_name, method_name, fast_method_name, on_conflict)
         raise ArgumentError, 'Must end with !' unless fast_method_name.to_s.end_with?('!')

data/lib/familia/horreum/{management_methods.rb → subclass/management.rb}

@@ -1,4 +1,4 @@
-# lib/familia/horreum/management_methods.rb
+# lib/familia/horreum/subclass/management.rb
 
 require_relative 'related_fields_management'
 
@@ -15,7 +15,7 @@ module Familia
     # * Provides utility methods for working with Database objects
     #
     module ManagementMethods
-      include Familia::Horreum::RelatedFieldsManagement
+      include Familia::Horreum::RelatedFieldsManagement # Provides DataType query methods
 
       # Creates and persists a new instance of the class.
       #
@@ -55,9 +55,7 @@ module Familia
       #
       def create(*, **)
         fobj = new(*, **)
-        raise Familia::Problem, "#{self} already exists: #{fobj.dbkey}" if fobj.exists?
-
-        fobj.save
+        fobj.save_if_not_exists
         fobj
       end
 
@@ -172,8 +170,8 @@ module Familia
       #   User.exists?(123)  # Returns true if user:123:object exists in Redis
       #
       def exists?(identifier, suffix = nil)
+        raise NoIdentifier, "Empty identifier" if identifier.to_s.empty?
         suffix ||= self.suffix
-        return false if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
@@ -234,9 +232,11 @@ module Familia
       # distinction b/c passing in an explicitly nil is how DataType objects
       # at the class level are created without the global default 'object'
       # suffix. See DataType#dbkey "parent_class?" for more details.
+      #
       def dbkey(identifier, suffix = self.suffix)
-        # Familia.ld "[.dbkey] #{identifier} for #{self} (suffix:#{suffix})"
-        raise NoIdentifier, self if identifier.to_s.empty?
+        if identifier.to_s.empty?
+          raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
+        end
 
         identifier &&= identifier.to_s
         Familia.dbkey(prefix, identifier, suffix)
@@ -255,6 +255,7 @@ module Familia
       # Returns the number of dbkeys matching the given filter pattern
       # @param filter [String] dbkey pattern to match (default: '*')
       # @return [Integer] Number of matching keys
+      #
       def matching_keys_count(filter = '*')
         dbclient.keys(dbkey(filter)).compact.size
       end

data/lib/familia/horreum/{related_fields_management.rb → subclass/related_fields_management.rb}

@@ -15,7 +15,7 @@ module Familia
     #
     # Usage:
     #   Include this module in classes that need DataType management
-    #   Call setup_relations_accessors to initialize the feature
+    #   Call setup_related_fields_accessors to initialize the feature
     #
     module RelatedFieldsManagement
       # A practical flag to indicate that a Horreum member has relations,
@@ -23,17 +23,22 @@ module Familia
       @has_relations = nil
 
       def self.included(base)
-        base.extend(ClassMethods)
-        base.setup_relations_accessors
+        base.extend(RelatedFieldsAccessors)
+        base.setup_related_fields_accessors
       end
 
-      module ClassMethods
+      module RelatedFieldsAccessors
         # Sets up all DataType related methods
-        # This method is the core of the metaprogramming logic
+        # This method generates the following for each registered DataType:
         #
-        def setup_relations_accessors
+        # Instance methods: set(), list(), hashkey(), sorted_set(), etc.
+        # Query methods: set?(), list?(), hashkey?(), sorted_set?(), etc.
+        # Collection methods: sets(), lists(), hashkeys(), sorted_sets(), etc.
+        # Class methods: class_set(), class_list(), etc.
+        #
+        def setup_related_fields_accessors
           Familia::DataType.registered_types.each_pair do |kind, klass|
-            Familia.ld "[registered_types] #{kind} => #{klass}"
+            Familia.trace :registered_types, kind, klass, caller(1..1) if Familia.debug?
 
             # Dynamically define instance-level relation methods
             #
@@ -86,11 +91,11 @@ module Familia
           end
         end
       end
-      # End of ClassMethods module
+      # End of RelatedFieldsAccessors module
 
       # Creates an instance-level relation
       def attach_instance_related_field(name, klass, opts)
-        Familia.ld "[#{self}##{name}] Attaching instance-level #{klass} #{opts}"
+        Familia.trace :attach_instance, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
 
         name = name.to_s.to_sym
@@ -115,7 +120,7 @@ module Familia
 
       # Creates a class-level relation
       def attach_class_related_field(name, klass, opts)
-        Familia.ld "[#{self}.#{name}] Attaching class-level #{klass} #{opts}"
+        Familia.trace :attach_class_related_field, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
         name = name.to_s.to_sym

data/lib/familia/horreum.rb

@@ -1,5 +1,10 @@
 # lib/familia/horreum.rb
 
+require_relative 'horreum/subclass/definition'
+require_relative 'horreum/subclass/management'
+require_relative 'horreum/shared/settings'
+require_relative 'horreum/core'
+
 module Familia
   #
   # Horreum: A module for managing Redis-based object storage and relationships
@@ -23,6 +28,8 @@ module Familia
   #
   class Horreum
     include Familia::Base
+    include Familia::Horreum::Core
+    include Familia::Horreum::Settings
 
     # Singleton Class Context
     #
@@ -62,13 +69,14 @@ module Familia
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
-        member.extend(DefinitionMethods)
-        member.extend(ManagementMethods)
-        member.extend(Connection)
-        member.extend(Features)
 
-        # Tracks all the classes/modules that include Familia. It's
-        # 10pm, do you know where you Familia members are?
+        # 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
+
+        # Track all classes that inherit from Horreum
         Familia.members << member
         super
       end
@@ -84,7 +92,7 @@ module Familia
     #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
-      Familia.ld "[Horreum] Initializing #{self.class}"
+      Familia.trace :INITIALIZE, dbclient, "Initializing #{self.class}", caller(1..1) if Familia.debug?
       initialize_relatives
 
       # No longer auto-create a key field - the identifier method will
@@ -123,7 +131,7 @@ module Familia
       elsif args.any?
         initialize_with_positional_args(*args)
       else
-        Familia.ld "[Horreum] #{self.class} initialized with no arguments"
+      Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
         # Default values are intentionally NOT set here to:
         # - Maintain Database memory efficiency (only store non-nil values)
         # - Avoid conflicts with nil-skipping serialization logic
@@ -158,7 +166,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.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
+        Familia.trace :INITIALIZE_RELATIVES, dbclient, "#{name} => #{klass} #{opts.keys}", caller(1..1) if Familia.debug?
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
         # automatically. This is what determines the dbkey for DataType
@@ -310,11 +318,3 @@ module Familia
     end
   end
 end
-
-require_relative 'horreum/definition_methods'
-require_relative 'horreum/management_methods'
-require_relative 'horreum/database_commands'
-require_relative 'horreum/connection'
-require_relative 'horreum/serialization'
-require_relative 'horreum/settings'
-require_relative 'horreum/utils'

data/lib/familia/validation/command_recorder.rb

@@ -0,0 +1,336 @@
+# lib/familia/validation/command_recorder.rb
+
+require 'concurrent-ruby'
+
+module Familia
+  module Validation
+    # Enhanced command recorder that captures Redis commands with full context
+    # for validation purposes. Extends the existing DatabaseLogger functionality
+    # to provide detailed command tracking including transaction boundaries.
+    #
+    # @example Basic usage
+    #   CommandRecorder.start_recording
+    #   # ... perform Redis operations
+    #   commands = CommandRecorder.stop_recording
+    #   puts commands.map(&:to_s)
+    #
+    # @example Transaction recording
+    #   CommandRecorder.start_recording
+    #   Familia.transaction do |conn|
+    #     conn.hset("key", "field", "value")
+    #     conn.incr("counter")
+    #   end
+    #   commands = CommandRecorder.stop_recording
+    #   commands.transaction_blocks.length #=> 1
+    #   commands.transaction_blocks.first.commands.length #=> 2
+    #
+    module CommandRecorder
+      extend self
+
+      # Thread-safe recording state
+      @recording_state = Concurrent::ThreadLocalVar.new { false }
+      @recorded_commands = Concurrent::ThreadLocalVar.new { CommandSequence.new }
+      @transaction_stack = Concurrent::ThreadLocalVar.new { [] }
+      @pipeline_stack = Concurrent::ThreadLocalVar.new { [] }
+
+      # Represents a single Redis command with full context
+      class RecordedCommand
+        attr_reader :command, :args, :result, :timestamp, :duration_us, :context, :command_type
+
+        def initialize(command:, args:, result:, timestamp:, duration_us:, context: {})
+          @command = command.to_s.upcase
+          @args = args.dup.freeze
+          @result = result
+          @timestamp = timestamp
+          @duration_us = duration_us
+          @context = context.dup.freeze
+          @command_type = determine_command_type
+        end
+
+        def to_s
+          args_str = @args.map(&:inspect).join(', ')
+          "#{@command}(#{args_str})"
+        end
+
+        def to_h
+          {
+            command: @command,
+            args: @args,
+            result: @result,
+            timestamp: @timestamp,
+            duration_us: @duration_us,
+            context: @context,
+            command_type: @command_type
+          }
+        end
+
+        def transaction_command?
+          %w[MULTI EXEC DISCARD].include?(@command)
+        end
+
+        def pipeline_command?
+          @context[:pipeline] == true
+        end
+
+        def atomic_command?
+          @context[:transaction] == true
+        end
+
+        private
+
+        def determine_command_type
+          case @command
+          when 'MULTI', 'EXEC', 'DISCARD'
+            :transaction_control
+          when 'PIPELINE'
+            :pipeline_control
+          when /^H(GET|SET|DEL|EXISTS|KEYS|LEN|MGET|MSET)/
+            :hash
+          when /^(L|R)(PUSH|POP|LEN|RANGE|INDEX|SET|REM)/
+            :list
+          when /^S(ADD|REM|MEMBERS|CARD|ISMEMBER|DIFF|INTER|UNION)/
+            :set
+          when /^Z(ADD|REM|RANGE|SCORE|CARD|COUNT|RANK|INCR)/
+            :sorted_set
+          when /^(GET|SET|DEL|EXISTS|EXPIRE|TTL|TYPE|INCR|DECR)/
+            :string
+          else
+            :other
+          end
+        end
+      end
+
+      # Represents a sequence of Redis commands with transaction boundaries
+      class CommandSequence
+        attr_reader :commands, :transaction_blocks, :pipeline_blocks
+
+        def initialize
+          @commands = []
+          @transaction_blocks = []
+          @pipeline_blocks = []
+        end
+
+        def add_command(recorded_command)
+          @commands << recorded_command
+        end
+
+        def start_transaction(context = {})
+          @transaction_blocks << TransactionBlock.new(context)
+        end
+
+        def end_transaction
+          return unless current_transaction
+
+          current_transaction.finalize(@commands)
+        end
+
+        def start_pipeline(context = {})
+          @pipeline_blocks << PipelineBlock.new(context)
+        end
+
+        def end_pipeline
+          return unless current_pipeline
+
+          current_pipeline.finalize(@commands)
+        end
+
+        def current_transaction
+          @transaction_blocks.last
+        end
+
+        def current_pipeline
+          @pipeline_blocks.last
+        end
+
+        def command_count
+          @commands.length
+        end
+
+        def transaction_count
+          @transaction_blocks.length
+        end
+
+        def pipeline_count
+          @pipeline_blocks.length
+        end
+
+        def to_a
+          @commands
+        end
+
+        def clear
+          @commands.clear
+          @transaction_blocks.clear
+          @pipeline_blocks.clear
+        end
+      end
+
+      # Represents a transaction block (MULTI/EXEC)
+      class TransactionBlock
+        attr_reader :start_index, :end_index, :commands, :context, :started_at
+
+        def initialize(context = {})
+          @context = context
+          @started_at = Time.now
+          @start_index = nil
+          @end_index = nil
+          @commands = []
+        end
+
+        def finalize(all_commands)
+          # Find MULTI and EXEC commands
+          multi_index = all_commands.rindex { |cmd| cmd.command == 'MULTI' }
+          exec_index = all_commands.rindex { |cmd| cmd.command == 'EXEC' }
+
+          return unless multi_index && exec_index && exec_index > multi_index
+
+          @start_index = multi_index
+          @end_index = exec_index
+          @commands = all_commands[(multi_index + 1)...exec_index]
+        end
+
+        def valid?
+          @start_index && @end_index && @commands.any?
+        end
+
+        def command_count
+          @commands.length
+        end
+      end
+
+      # Represents a pipeline block
+      class PipelineBlock
+        attr_reader :commands, :context, :started_at
+
+        def initialize(context = {})
+          @context = context
+          @started_at = Time.now
+          @commands = []
+        end
+
+        def finalize(all_commands)
+          # Pipeline commands are those executed within pipeline context
+          @commands = all_commands.select(&:pipeline_command?)
+        end
+
+        def command_count
+          @commands.length
+        end
+      end
+
+      # Start recording Redis commands for the current thread
+      def start_recording
+        @recording_state.value = true
+        @recorded_commands.value = CommandSequence.new
+        @transaction_stack.value = []
+        @pipeline_stack.value = []
+      end
+
+      # Stop recording and return the recorded command sequence
+      def stop_recording
+        @recording_state.value = false
+        sequence = @recorded_commands.value
+        @recorded_commands.value = CommandSequence.new
+        sequence
+      end
+
+      # Check if currently recording
+      def recording?
+        @recording_state.value == true
+      end
+
+      # Record a Redis command with full context
+      def record_command(command:, args:, result:, timestamp:, duration_us:, context: {})
+        return unless recording?
+
+        # Enhance context with transaction/pipeline state
+        enhanced_context = context.merge(
+          transaction: in_transaction?,
+          pipeline: in_pipeline?,
+          transaction_depth: transaction_depth,
+          pipeline_depth: pipeline_depth
+        )
+
+        recorded_cmd = RecordedCommand.new(
+          command: command,
+          args: args,
+          result: result,
+          timestamp: timestamp,
+          duration_us: duration_us,
+          context: enhanced_context
+        )
+
+        sequence = @recorded_commands.value
+        sequence.add_command(recorded_cmd)
+
+        # Handle transaction boundaries
+        case recorded_cmd.command
+        when 'MULTI'
+          sequence.start_transaction(enhanced_context)
+          @transaction_stack.value.push(Time.now)
+        when 'EXEC', 'DISCARD'
+          sequence.end_transaction if sequence.current_transaction
+          @transaction_stack.value.pop
+        end
+      end
+
+      # Check if we're currently in a transaction
+      def in_transaction?
+        @transaction_stack.value.any?
+      end
+
+      # Check if we're currently in a pipeline
+      def in_pipeline?
+        @pipeline_stack.value.any?
+      end
+
+      # Get current transaction nesting depth
+      def transaction_depth
+        @transaction_stack.value.length
+      end
+
+      # Get current pipeline nesting depth
+      def pipeline_depth
+        @pipeline_stack.value.length
+      end
+
+      # Get the current command sequence (for inspection during recording)
+      def current_sequence
+        @recorded_commands.value
+      end
+
+      # Clear all recorded data
+      def clear
+        @recorded_commands.value.clear
+      end
+
+      # Enhanced middleware that integrates with DatabaseLogger
+      module Middleware
+        def self.call(command, config)
+          return yield unless CommandRecorder.recording?
+
+          timestamp = Time.now
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+
+          result = yield
+
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start_time
+
+          CommandRecorder.record_command(
+            command: command[0],
+            args: command[1..-1],
+            result: result,
+            timestamp: timestamp,
+            duration_us: duration,
+            context: {
+              config: config,
+              thread_id: Thread.current.object_id
+            }
+          )
+
+          result
+        end
+      end
+    end
+  end
+end