familia 2.0.0.pre15 → 2.0.0.pre16

data/lib/familia/horreum/subclass/definition.rb

@@ -32,22 +32,22 @@ module Familia
     @dump_method = nil
     @load_method = nil
 
-    # DefinitionMethods: Provides class-level functionality for Horreum subclasses
+    # DefinitionMethods - Class-level DSL methods for defining Horreum model structure
     #
     # This module is extended into classes that include Familia::Horreum,
-    # providing methods for Database operations and object management.
+    # providing class methods for defining model structure and configuration
+    # (e.g., Customer.field :name, Customer.identifier_field :custid).
     #
     # Key features:
-    # * Includes RelatedFieldsManagement for DataType field handling
-    # * Defines methods for managing fields, identifiers, and dbkeys
-    # * Provides utility methods for working with Database objects
+    # * Defines DSL methods for field definitions (field, identifier_field)
+    # * Includes RelatedFieldsManagement for DataType field DSL (list, set, zset, etc.)
+    # * Provides class-level configuration (prefix, suffix, logical_database)
+    # * Manages field metadata and inheritance
     #
     module DefinitionMethods
       include Familia::Settings
       include Familia::Horreum::RelatedFieldsManagement # Provides DataType field methods
 
-      using Familia::Refinements::SnakeCase
-
       # Sets or retrieves the unique identifier field for the class.
       #
       # This method defines or returns the field or method that contains the unique
@@ -77,13 +77,13 @@ module Familia
       #
       # This method defines a new field for the class, creating getter and setter
       # instance methods similar to `attr_accessor`. It also generates a fast
-      # writer method for immediate persistence to Redis.
+      # writer method for immediate persistence to the database.
       #
       # @param name [Symbol, String] the name of the field to define. If a method
       #   with the same name already exists, an error is raised.
       # @param as [Symbol, String, false, nil] as the name to use for the accessor method (defaults to name).
       #   If false or nil, no accessor methods are created.
-      # @param fast_method [Symbol, false, nil] the name to use for the fast writer method (defaults to :"#{name}!").
+      # @param fast_method [Symbol, false, nil] the name to use for the fast writer method (defaults to :`"#{name}!"`).
       #   If false or nil, no fast writer method is created.
       # @param on_conflict [Symbol] conflict resolution strategy when method already exists:
       #   - :raise - raise error if method exists (default)
@@ -117,7 +117,7 @@ module Familia
         register_field_type(field_type)
       end
 
-      # Sets or retrieves the suffix for generating Redis keys.
+      # Sets or retrieves the suffix for generating Valkey/Redis keys.
       #
       # @param a [String, Symbol, nil] the suffix to set (optional).
       # @param blk [Proc] a block that returns the suffix (optional).
@@ -128,7 +128,7 @@ module Familia
         @suffix || Familia.default_suffix
       end
 
-      # Sets or retrieves the prefix for generating Redis keys.
+      # Sets or retrieves the prefix for generating Valkey/Redis keys.
       #
       # @param a [String, Symbol, nil] the prefix to set (optional).
       # @return [String, Symbol] the current prefix.
@@ -144,12 +144,12 @@ module Familia
             raise Problem, 'Cannot generate prefix for anonymous class. ' \
                            'Use `prefix` method to set explicitly.'
           end
-          name.downcase.gsub('::', Familia.delim).to_sym
+          config_name.to_sym
         end
       end
 
       def logical_database(v = nil)
-        Familia.trace :DB, Familia.dbclient, "#{@logical_database} #{v.nil?}", caller(0..2) if Familia.debug?
+        Familia.trace :LOGICAL_DATABASE_DEF, "instvar:#{@logical_database}", v if Familia.debug?
         @logical_database = v unless v.nil?
         @logical_database || parent&.logical_database
       end
@@ -172,20 +172,7 @@ module Familia
       end
 
       def relations?
-        @has_relations ||= false
-      end
-
-      # Converts the class name into a string that can be used to look up
-      # configuration values. This is particularly useful when mapping
-      # familia models with specific database numbers in the configuration.
-      #
-      # Familia::Horreum::DefinitionMethods#config_name
-      #
-      # @example V2::Session.config_name => 'session'
-      #
-      # @return [String] The underscored class name as a string
-      def config_name
-        name.snake_case
+        @has_related_fields ||= false
       end
 
       def dump_method
@@ -234,6 +221,8 @@ module Familia
         # Complete the registration after installation. If we do this beforehand
         # we can run into issues where it looks like it's already installed.
         field_types[field_type.name] = field_type
+        # Freeze the field_type to ensure immutability (maintains Data class heritage)
+        field_type.freeze
       end
 
       # Retrieves feature options for the current class.
@@ -303,21 +292,20 @@ module Familia
       #   end
       #
       def add_feature_options(feature_name, **options)
-  @feature_options ||= {}
-  @feature_options[feature_name.to_sym] ||= {}
+        @feature_options ||= {}
+        @feature_options[feature_name.to_sym] ||= {}
 
-  # Only set defaults for options that don't already exist
-  options.each do |key, value|
-    @feature_options[feature_name.to_sym][key] ||= value
-  end
+        # Only set defaults for options that don't already exist
+        options.each do |key, value|
+          @feature_options[feature_name.to_sym][key] ||= value
+        end
 
-  @feature_options[feature_name.to_sym]
-end
+        @feature_options[feature_name.to_sym]
+      end
 
       # Create and register a transient field type
       #
       # @param name [Symbol] The field name
-      # @param options [Hash] Field options
       #
       def transient_field(name, **)
         require_relative '../../features/transient_fields/transient_field_type'
@@ -379,8 +367,8 @@ end
       # @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
+      #   - Without args: Retrieves current value from Valkey/Redis
+      #   - With value: Sets and immediately persists to Valkey/Redis
       #   - Returns boolean indicating success for writes
       #   - Bypasses object-level caching and expiration updates
       #
@@ -394,20 +382,20 @@ end
         handle_method_conflict(fast_method_name, on_conflict) do
           # Fast attribute accessor method for the '#{field_name}' attribute.
           # This method provides immediate read and write access to the attribute
-          # in Redis.
+          # in the database.
           #
           # When called without arguments, it retrieves the current value of the
-          # attribute from Redis.
+          # attribute from the database.
           # When called with an argument, it immediately persists the new value to
-          # Redis.
+          # the database.
           #
           # @overload #{method_name}
-          #   Retrieves the current value of the attribute from Redis.
+          #   Retrieves the current value of the attribute from the database.
           #   @return [Object] the current value of the attribute.
           #
           # @overload #{method_name}(value)
           #   Sets and immediately persists the new value of the attribute to
-          #   Redis.
+          #   the database.
           #   @param value [Object] the new value to set for the attribute.
           #   @return [Object] the newly set value.
           #
@@ -416,7 +404,7 @@ end
           #   the method.
           #
           # @note This method bypasses any object-level caching and interacts
-          #   directly with Redis. It does not trigger updates to other attributes
+          #   directly with the database. It does not trigger updates to other attributes
           #   or the object's expiration time.
           #
           # @example
@@ -437,7 +425,7 @@ end
 
             begin
               # Trace the operation if debugging is enabled.
-              Familia.trace :FAST_WRITER, dbclient, "#{field_name}: #{val.inspect}", caller(1..1) if Familia.debug?
+              Familia.trace :FAST_WRITER, nil, "#{field_name}: #{val.inspect}" if Familia.debug?
 
               # Convert the provided value to a format suitable for Database storage.
               prepared = serialize_value(val)

data/lib/familia/horreum/subclass/management.rb

@@ -4,11 +4,11 @@ require_relative 'related_fields_management'
 
 module Familia
   class Horreum
-    # ManagementMethods: Provides class-level functionality for Horreum
-    # records.
+    # ManagementMethods - Class-level methods for Horreum model management
     #
     # This module is extended into classes that include Familia::Horreum,
-    # providing methods for Database operations and object management.
+    # providing class methods for database operations and object management
+    # (e.g., Customer.create, Customer.find_by_id)
     #
     # # Key features:
     # * Includes RelatedFieldsManagement for DataType field handling
@@ -17,11 +17,13 @@ module Familia
     module ManagementMethods
       include Familia::Horreum::RelatedFieldsManagement # Provides DataType query methods
 
+      using Familia::Refinements::StylizeWords
+
       # Creates and persists a new instance of the class.
       #
-      # @param *args [Array] Variable number of positional arguments to be passed
+      # @param args [Array] Variable number of positional arguments to be passed
       #   to the constructor.
-      # @param **kwargs [Hash] Keyword arguments to be passed to the constructor.
+      # @param kwargs [Hash] Keyword arguments to be passed to the constructor.
       # @return [Object] The newly created and persisted instance.
       # @raise [Familia::Problem] If an instance with the same identifier already
       #   exists.
@@ -68,10 +70,35 @@ module Familia
         ids.collect! { |objid| dbkey(objid) }
         return [] if ids.compact.empty?
 
-        Familia.trace :MULTIGET, dbclient, "#{ids.size}: #{ids}", caller(1..1) if Familia.debug?
+        Familia.trace :MULTIGET, nil, "#{ids.size}: #{ids}" if Familia.debug?
         dbclient.mget(*ids)
       end
 
+      # Converts the class name into a string that can be used to look up
+      # configuration values. This is particularly useful when mapping
+      # familia models with specific database numbers in the configuration.
+      #
+      # Familia::Horreum::DefinitionMethods#config_name
+      #
+      # @example V2::Session.config_name => 'session'
+      #
+      # @return [String] The underscored class name as a string
+      def config_name
+        return nil if name.nil?
+
+        name.demodularize.snake_case
+      end
+
+      # Familia::Horreum::DefinitionMethods#familia_name
+      #
+      # @example V2::Session.config_name => 'Session'
+      #
+      def familia_name
+        return nil if name.nil?
+
+        name.demodularize
+      end
+
       # Retrieves and instantiates an object from Database using the full object
       # key.
       #
@@ -83,7 +110,7 @@ module Familia
       # This method performs a two-step process to safely retrieve and
       # instantiate objects:
       #
-      # 1. It first checks if the key exists in Redis. This is crucial because:
+      # 1. It first checks if the key exists in the database. This is crucial because:
       #    - It provides a definitive answer about the object's existence.
       #    - It prevents ambiguity that could arise from `hgetall` returning an
       #      empty hash for non-existent keys, which could lead to the creation
@@ -93,7 +120,7 @@ module Familia
       #    it.
       #
       # This approach ensures that we only attempt to instantiate objects that
-      # actually exist in Redis, improving reliability and simplifying
+      # actually exist in Valkey/Redis, improving reliability and simplifying
       # debugging.
       #
       # @example
@@ -108,17 +135,17 @@ module Familia
         does_exist = dbclient.exists(objkey).positive?
 
         Familia.ld "[.find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :FROM_KEY, dbclient, objkey, caller(1..1) if Familia.debug?
+        Familia.trace :FROM_KEY, nil, objkey if Familia.debug?
 
         # This is the reason for calling exists first. We want to definitively
-        # and without any ambiguity know if the object exists in Redis. If it
+        # and without any ambiguity know if the object exists in the database. If it
         # doesn't, we return nil. If it does, we proceed to load the object.
         # Otherwise, hgetall will return an empty hash, which will be passed to
         # the constructor, which will then be annoying to debug.
         return unless does_exist
 
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
-        Familia.trace :FROM_KEY2, dbclient, "#{objkey}: #{obj.inspect}", caller(1..1) if Familia.debug?
+        Familia.trace :FROM_KEY2, nil, "#{objkey}: #{obj.inspect}" if Familia.debug?
 
         new(**obj)
       end
@@ -150,33 +177,34 @@ module Familia
         objkey = dbkey(identifier, suffix)
 
         Familia.ld "[.find_by_id] #{self} from key #{objkey})"
-        Familia.trace :FIND_BY_ID, Familia.dbclient(uri), objkey, caller(1..1).first if Familia.debug?
+        Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
         find_by_key objkey
       end
       alias find find_by_id
       alias load find_by_id # deprecated
       alias from_identifier find_by_id # deprecated
 
-      # Checks if an object with the given identifier exists in Redis.
+      # Checks if an object with the given identifier exists in the database.
       #
       # @param identifier [String, Integer] The unique identifier for the object.
       # @param suffix [Symbol, nil] The suffix to use in the dbkey (default: class suffix).
       # @return [Boolean] true if the object exists, false otherwise.
       #
       # This method constructs the full dbkey using the provided identifier and suffix,
-      # then checks if the key exists in Redis.
+      # then checks if the key exists in the database.
       #
       # @example
-      #   User.exists?(123)  # Returns true if user:123:object exists in Redis
+      #   User.exists?(123)  # Returns true if user:123:object exists in Valkey/Redis
       #
       def exists?(identifier, suffix = nil)
-        raise NoIdentifier, "Empty identifier" if identifier.to_s.empty?
+        raise NoIdentifier, 'Empty identifier' if identifier.to_s.empty?
+
         suffix ||= self.suffix
 
         objkey = dbkey identifier, suffix
 
         ret = dbclient.exists objkey
-        Familia.trace :EXISTS, dbclient, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
+        Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug?
 
         ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
       end
@@ -193,17 +221,36 @@ module Familia
       # `delete!` when working directly with dbkeys.
       #
       # @example
-      #   User.destroy!(123)  # Removes user:123:object from Redis
+      #   User.destroy!(123)  # Removes user:123:object from Valkey/Redis
       #
       def destroy!(identifier, suffix = nil)
         suffix ||= self.suffix
-        return false if identifier.to_s.empty?
+        return MultiResult.new(false, []) if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
-        ret = dbclient.del objkey
-        Familia.trace :DESTROY!, dbclient, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
-        ret.positive?
+        # Execute all deletion operations within a transaction
+        transaction do |conn|
+          # Clean up related fields first to avoid orphaned keys
+          if relations?
+            Familia.trace :DESTROY_RELATIONS!, nil, "#{self} has relations: #{related_fields.keys}" if Familia.debug?
+
+            # Create a temporary instance to access related fields.
+            # Pass identifier in constructor so init() sees it and can set dependent fields.
+            identifier_field_name = self.identifier_field
+            temp_instance = identifier_field_name ? new(identifier_field_name => identifier.to_s) : new
+
+            related_fields.each do |name, _definition|
+              obj = temp_instance.send(name)
+              Familia.trace :DESTROY_RELATION!, name, "Deleting related field #{name} (#{obj.dbkey})" if Familia.debug?
+              conn.del(obj.dbkey)
+            end
+          end
+
+          # Delete the main object key
+          ret = conn.del(objkey)
+          Familia.trace :DESTROY!, nil, "#{objkey} #{ret.inspect}" if Familia.debug?
+        end
       end
 
       # Finds all keys in Database matching the given suffix pattern.
@@ -249,7 +296,7 @@ module Familia
       end
 
       def any?(filter = '*')
-        matching_keys_count(filter) > 0
+        matching_keys_count(filter).positive?
       end
 
       # Returns the number of dbkeys matching the given filter pattern
@@ -259,7 +306,8 @@ module Familia
       def matching_keys_count(filter = '*')
         dbclient.keys(dbkey(filter)).compact.size
       end
-      alias size matching_keys_count # For backwards compatibility
+      alias size matching_keys_count
+      alias length matching_keys_count
     end
   end
 end

data/lib/familia/horreum/subclass/related_fields_management.rb

@@ -1,32 +1,99 @@
 # lib/familia/horreum/related_fields_management.rb
 
 module Familia
+
+  RelatedFieldDefinition = Data.define(:name, :klass, :opts)
+
   class Horreum
+
+    # Each related field needs some details from the parent (Horreum model)
+    # in order to generate its dbkey. We use a parent proxy pattern to store
+    # only essential parent information instead of full object reference. We
+    # need only the model class and an optional unique identifier to generate
+    # the dbkey; when the identifier is nil, we treat this as a class-level
+    # relation (e.g. model_name:related_field_name); when the identifier
+    # is not nil, we treat this as an instance-level relation
+    # (model_name:identifier:related_field_name).
+    #
+    ParentDefinition = Data.define(:model_klass, :identifier) do
+      # Factory method to create ParentDefinition from a parent instance
+      def self.from_parent(parent_instance)
+        case parent_instance
+        when Class
+          # Handle class-level relationships
+          new(parent_instance, nil)
+        else
+          # Handle instance-level relationships
+          identifier = parent_instance.respond_to?(:identifier) ? parent_instance.identifier : nil
+          new(parent_instance.class, identifier)
+        end
+      end
+
+      # Delegation methods for common operations needed by DataTypes
+      def dbclient(uri = nil)
+        model_klass.dbclient(uri)
+      end
+
+      def logical_database
+        model_klass.logical_database
+      end
+
+      def dbkey(keystring = nil)
+        if identifier
+          # Instance-level relation: model_name:identifier:keystring
+          model_klass.dbkey(identifier, keystring)
+        else
+          # Class-level relation: model_name:keystring
+          model_klass.dbkey(keystring, nil)
+        end
+      end
+
+      # Allow comparison with the original parent instance
+      def ==(other)
+        case other
+        when ParentDefinition
+          model_klass == other.model_klass && identifier == other.identifier
+        when Class
+          model_klass == other && identifier.nil?
+        else
+          # Compare with instance: check class and identifier match
+          other.is_a?(model_klass) && other.respond_to?(:identifier) && identifier == other.identifier
+        end
+      end
+      alias eql? ==
+    end
+
+    # RelatedFieldsManagement - Class-level methods for defining DataType relationships
     #
-    # RelatedFieldsManagement: Manages DataType fields and relations
+    # This module uses metaprogramming to dynamically create field definition methods
+    # that generate both class-level and instance-level accessor methods for DataTypes
+    # (e.g., list, set, zset, hashkey, string).
     #
-    # This module uses metaprogramming to dynamically create methods
-    # for managing different types of Database objects (e.g., sets, lists, hashes).
+    # When included in a class via ManagementMethods, it provides class methods like:
+    # * Customer.list :recent_orders    # defines class method for class-level list
+    # * customer.recent_orders          # creates instance method returning list instance
     #
     # Key metaprogramming features:
-    # * Dynamically defines methods for each Database type (e.g., set, list, hashkey)
-    # * Creates both instance-level and class-level relation methods
+    # * Dynamically defines DSL methods for each Database type (e.g., set, list, hashkey)
+    # * Each DSL method creates corresponding instance/class accessor methods
     # * Provides query methods for checking relation types
     #
     # Usage:
     #   Include this module in classes that need DataType management
-    #   Call setup_related_fields_accessors to initialize the feature
+    #   Call setup_related_fields_definition_methods to initialize the feature
     #
     module RelatedFieldsManagement
       # A practical flag to indicate that a Horreum member has relations,
       # not just theoretically but actually at least one list/haskey/etc.
-      @has_relations = nil
+      @has_related_fields = nil
 
       def self.included(base)
         base.extend(RelatedFieldsAccessors)
-        base.setup_related_fields_accessors
+        base.setup_related_fields_definition_methods
       end
 
+      # RelatedFieldsManagement::RelatedFieldsAccessors
+      #
       module RelatedFieldsAccessors
         # Sets up all DataType related methods
         # This method generates the following for each registered DataType:
@@ -36,9 +103,9 @@ module Familia
         # Collection methods: sets(), lists(), hashkeys(), sorted_sets(), etc.
         # Class methods: class_set(), class_list(), etc.
         #
-        def setup_related_fields_accessors
+        def setup_related_fields_definition_methods
           Familia::DataType.registered_types.each_pair do |kind, klass|
-            Familia.trace :registered_types, kind, klass, caller(1..1) if Familia.debug?
+            Familia.trace :registered_types, kind, klass if Familia.debug?
 
             # Dynamically define instance-level relation methods
             #
@@ -50,7 +117,7 @@ module Familia
               name, opts = *args
 
               # As log as we have at least one relation, we can set this flag.
-              @has_relations = true
+              @has_related_fields = true
 
               attach_instance_related_field name, klass, opts
             end
@@ -95,16 +162,13 @@ module Familia
 
       # Creates an instance-level relation
       def attach_instance_related_field(name, klass, opts)
-        Familia.trace :attach_instance, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
+        Familia.trace :attach_instance_related_field, name, klass, opts if Familia.debug?
         raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
 
         name = name.to_s.to_sym
         opts ||= {}
 
-        related_fields[name] = Struct.new(:name, :klass, :opts).new
-        related_fields[name].name = name
-        related_fields[name].klass = klass
-        related_fields[name].opts = opts
+        related_fields[name] = RelatedFieldDefinition.new(name, klass, opts)
 
         attr_reader name
 
@@ -120,17 +184,14 @@ module Familia
 
       # Creates a class-level relation
       def attach_class_related_field(name, klass, opts)
-        Familia.trace :attach_class_related_field, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
+        Familia.trace :attach_class_related_field, "#{name} #{klass}", opts if Familia.debug?
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
         name = name.to_s.to_sym
         opts = opts.nil? ? {} : opts.clone
         opts[:parent] = self unless opts.key?(:parent)
 
-        class_related_fields[name] = Struct.new(:name, :klass, :opts).new
-        class_related_fields[name].name = name
-        class_related_fields[name].klass = klass
-        class_related_fields[name].opts = opts
+        class_related_fields[name] = RelatedFieldDefinition.new(name, klass, opts)
 
         # An accessor method created in the metaclass will
         # access the instance variables for this class.