familia 2.0.0.pre15 → 2.0.0.pre17

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

@@ -1,7 +1,6 @@
-# lib/familia/horreum/subclass/definition.rb
+# lib/familia/horreum/definition.rb
 
-require_relative 'related_fields_management'
-require_relative '../shared/settings'
+require_relative 'settings'
 
 module Familia
   VALID_STRATEGIES = %i[raise skip ignore warn overwrite].freeze
@@ -32,21 +31,103 @@ module Familia
     @dump_method = nil
     @load_method = nil
 
-    # DefinitionMethods: Provides class-level functionality for Horreum subclasses
+    # Field groups
+    @field_groups = nil
+    @current_field_group = nil
+
+    # 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
+      # Defines a field group to organize related fields.
+      #
+      # Field groups provide a way to categorize and query fields by purpose or feature.
+      # When a block is provided, fields defined within the block are automatically
+      # added to the group. Without a block, an empty group is initialized.
+      #
+      # @param name [Symbol, String] the name of the field group
+      # @yield optional block for defining fields within the group
+      # @return [Array<Symbol>] the array of field names in the group
+      #
+      # @raise [Familia::Problem] if attempting to nest field groups
+      #
+      # @example Manual field grouping
+      #   class User < Familia::Horreum
+      #     field_group :personal_info do
+      #       field :name
+      #       field :email
+      #     end
+      #   end
+      #
+      #   User.personal_info  # => [:name, :email]
+      #
+      # @example Initialize empty group
+      #   class User < Familia::Horreum
+      #     field_group :placeholder
+      #   end
+      #
+      #   User.placeholder  # => []
+      #
+      def field_group(name, &block)
+
+        # Prevent nested field groups
+        if @current_field_group
+          raise Familia::Problem,
+            "Cannot define field group :#{name} while :#{@current_field_group} is being defined. " \
+            "Nested field groups are not supported."
+        end
+
+        # Initialize group
+        field_groups[name.to_sym] ||= []
+
+        if block_given?
+          @current_field_group = name.to_sym
+          begin
+            instance_eval(&block)
+          ensure
+            @current_field_group = nil
+          end
+        else
+          Familia.ld "[field_group] Created field group :#{name} but no block given" if Familia.debug?
+        end
+
+        field_groups[name.to_sym]
+      end
+
+      # Returns the list of all field group names defined for the class.
+      #
+      # @return [Array<Symbol>] array of field group names
+      #
+      # @example
+      #   class User < Familia::Horreum
+      #     field_group :personal_info do
+      #       field :name
+      #     end
+      #     field_group :metadata do
+      #       field :created_at
+      #     end
+      #   end
+      #
+      #   User.field_groups  # => [
+      #     :personal_info => [...],
+      #     :metadata => [..]
+      #   ]
+      #
+      def field_groups
+        @field_groups ||= {}
+      end
 
       # Sets or retrieves the unique identifier field for the class.
       #
@@ -77,13 +158,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)
@@ -98,37 +179,37 @@ module Familia
       #
       def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
         # Use field type system for consistency
-        require_relative '../../field_type'
+        require_relative '../field_type'
 
         # Create appropriate field type based on category
         field_type = if category == :transient
-                       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
-                       custom_field_type = Class.new(FieldType) do
-                         define_method :category do
-                           category || :field
-                         end
-                       end
-                       custom_field_type.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
-                     end
+          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
+          custom_field_type = Class.new(FieldType) do
+            define_method :category do
+              category || :field
+            end
+          end
+          custom_field_type.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
+        end
 
         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).
       # @return [String, Symbol] the current suffix or Familia.default_suffix if none is set.
       #
-      def suffix(a = nil, &blk)
-        @suffix = a || blk if a || !blk.nil?
+      def suffix(val = nil, &blk)
+        @suffix = val || blk if val || !blk.nil?
         @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.
@@ -137,20 +218,20 @@ module Familia
       # which typically occurs with anonymous classes that haven't had their prefix
       # explicitly set.
       #
-      def prefix(a = nil)
-        @prefix = a if a
+      def prefix(val = nil)
+        @prefix = val if val
         @prefix || begin
           if name.nil?
             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?
-        @logical_database = v unless v.nil?
+      def logical_database(num = nil)
+        Familia.trace :LOGICAL_DATABASE_DEF, "instvar:#{@logical_database}", num if Familia.debug?
+        @logical_database = num unless num.nil?
         @logical_database || parent&.logical_database
       end
 
@@ -172,20 +253,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 +302,14 @@ 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
+
+        # Add to current field group if one is active
+        if @current_field_group
+          @field_groups[@current_field_group] << field_type.name
+        end
+
+        # Freeze the field_type to ensure immutability (maintains Data class heritage)
+        field_type.freeze
       end
 
       # Retrieves feature options for the current class.
@@ -303,26 +379,15 @@ module Familia
       #   end
       #
       def add_feature_options(feature_name, **options)
-  @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
+        @feature_options ||= {}
+        @feature_options[feature_name.to_sym] ||= {}
 
-  @feature_options[feature_name.to_sym]
-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
 
-      # 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'
-        field_type = TransientFieldType.new(name, **, fast_method: false)
-        register_field_type(field_type)
+        @feature_options[feature_name.to_sym]
       end
 
       private
@@ -379,8 +444,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 +459,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 +481,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 +502,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 → management.rb}

@@ -1,14 +1,12 @@
-# lib/familia/horreum/subclass/management.rb
-
-require_relative 'related_fields_management'
+# lib/familia/horreum/management.rb
 
 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 +15,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 +68,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 +108,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 +118,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 +133,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 +175,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 +219,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 +294,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 +304,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