familia 1.2.1 → 2.0.0.pre.pre

data/lib/familia/horreum/class_methods.rb

@@ -1,62 +1,61 @@
-# frozen_string_literal: true
+# lib/familia/horreum/class_methods.rb
 
-require_relative 'relations_management'
+require_relative 'related_fields_management'
 
 module Familia
   class Horreum
     # Class-level instance variables
     # These are set up as nil initially and populated later
-    @redis = nil
-    @identifier = nil
-    @ttl = nil
-    @db = nil
+    @dbclient = nil # TODO
+    @identifier_field = nil
+    @default_expiration = nil
+    @logical_database = nil
     @uri = nil
     @suffix = nil
     @prefix = nil
     @fields = nil # []
-    @class_redis_types = nil # {}
-    @redis_types = nil # {}
+    @class_related_fields = nil # {}
+    @related_fields = nil # {}
     @dump_method = nil
     @load_method = nil
 
     # ClassMethods: Provides class-level functionality for Horreum
     #
     # This module is extended into classes that include Familia::Horreum,
-    # providing methods for Redis operations and object management.
+    # providing methods for Database operations and object management.
     #
     # Key features:
-    # * Includes RelationsManagement for Redis-type field handling
-    # * Defines methods for managing fields, identifiers, and Redis keys
-    # * Provides utility methods for working with Redis objects
+    # * Includes RelatedFieldsManagement for DataType field handling
+    # * Defines methods for managing fields, identifiers, and dbkeys
+    # * Provides utility methods for working with Database objects
     #
     module ClassMethods
       include Familia::Settings
-      include Familia::Horreum::RelationsManagement
-
-      # Returns the Redis connection for the class.
-      #
-      # This method retrieves the Redis connection instance for the class. If no
-      # connection is set, it initializes a new connection using the provided URI
-      # or database configuration.
-      #
-      # @return [Redis] the Redis connection instance.
-      #
-      def redis
-        @redis || Familia.redis(uri || db)
-      end
-
-      # Sets or retrieves the unique identifier for the class.
-      #
-      # This method defines or returns the unique identifier used to generate the
-      # Redis key for the object. If a value is provided, it sets the identifier;
-      # otherwise, it returns the current identifier.
-      #
-      # @param [Object] val the value to set as the identifier (optional).
-      # @return [Object] the current identifier.
-      #
-      def identifier(val = nil)
-        @identifier = val if val
-        @identifier
+      include Familia::Horreum::RelatedFieldsManagement
+
+      # Sets or retrieves the unique identifier field for the class.
+      #
+      # This method defines or returns the field or method that contains the unique
+      # identifier used to generate the dbkey for the object. If a value is provided,
+      # it sets the identifier field; otherwise, it returns the current identifier field.
+      #
+      # @param [Object] val the field name or method to set as the identifier field (optional).
+      # @return [Object] the current identifier field.
+      #
+      def identifier_field(val = nil)
+        if val
+          # Validate identifier field definition at class definition time
+          case val
+          when Symbol, String, Proc
+            @identifier_field = val
+          else
+            raise Problem, <<~ERROR
+              Invalid identifier field definition: #{val.inspect}.
+              Use a field name (Symbol/String) or Proc.
+            ERROR
+          end
+        end
+        @identifier_field
       end
 
       # Defines a field for the class and creates accessor methods.
@@ -84,12 +83,12 @@ module Familia
       # The dynamically defined method performs the following:
       # - Acts as both a reader and a writer method.
       # - When called without arguments, retrieves the current value from Redis.
-      # - When called with an argument, persists the value to Redis immediately.
+      # - When called with an argument, persists the value to Database immediately.
       # - Checks if the correct number of arguments is provided (zero or one).
-      # - Converts the provided value to a format suitable for Redis storage.
+      # - Converts the provided value to a format suitable for Database storage.
       # - Uses the existing accessor method to set the attribute value when
       #   writing.
-      # - Persists the value to Redis immediately using the hset command when
+      # - Persists the value to Database immediately using the hset command when
       #   writing.
       # - Includes custom error handling to raise an ArgumentError if the wrong
       #   number of arguments is given.
@@ -145,21 +144,21 @@ module Familia
           val = args.first
 
           # If no value is provided to this fast attribute method, make a call
-          # to redis to return the current stored value of the hash field.
+          # to the db to return the current stored value of the hash field.
           return hget name if val.nil?
 
           begin
             # Trace the operation if debugging is enabled.
-            Familia.trace :FAST_WRITER, redis, "#{name}: #{val.inspect}", caller(1..1) if Familia.debug?
+            Familia.trace :FAST_WRITER, dbclient, "#{name}: #{val.inspect}", caller(1..1) if Familia.debug?
 
-            # Convert the provided value to a format suitable for Redis storage.
+            # Convert the provided value to a format suitable for Database storage.
             prepared = serialize_value(val)
             Familia.ld "[.fast_attribute!] #{name} val: #{val.class} prepared: #{prepared.class}"
 
             # Use the existing accessor method to set the attribute value.
             send :"#{name}=", val
 
-            # Persist the value to Redis immediately using the hset command.
+            # Persist the value to Database immediately using the hset command.
             hset name, prepared
           rescue Familia::Problem => e
             # Raise a custom error message if an exception occurs during the execution of the method.
@@ -175,36 +174,24 @@ module Familia
         @fields
       end
 
-      def class_redis_types
-        @class_redis_types ||= {}
-        @class_redis_types
+      def class_related_fields
+        @class_related_fields ||= {}
+        @class_related_fields
       end
 
-      def class_redis_types?(name)
-        class_redis_types.key? name.to_s.to_sym
-      end
-
-      def redis_object?(name)
-        redis_types.key? name.to_s.to_sym
-      end
-
-      def redis_types
-        @redis_types ||= {}
-        @redis_types
+      def related_fields
+        @related_fields ||= {}
+        @related_fields
       end
 
       def has_relations?
         @has_relations ||= false
       end
 
-      def db(v = nil)
-        @db = v unless v.nil?
-        @db || parent&.db
-      end
-
-      def uri(v = nil)
-        @uri = v unless v.nil?
-        @uri || parent&.uri
+      def logical_database(v = nil)
+        Familia.trace :DB, Familia.dbclient, "#{@logical_database} #{v}", caller(1..1) if Familia.debug?
+        @logical_database = v unless v.nil?
+        @logical_database || parent&.logical_database
       end
 
       def all(suffix = nil)
@@ -217,11 +204,11 @@ module Familia
         matching_keys_count(filter) > 0
       end
 
-      # Returns the number of Redis keys matching the given filter pattern
-      # @param filter [String] Redis key pattern to match (default: '*')
+      # 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 = '*')
-        redis.keys(rediskey(filter)).compact.size
+        dbclient.keys(dbkey(filter)).compact.size
       end
       alias size matching_keys_count # For backwards compatibility
 
@@ -273,7 +260,7 @@ module Familia
       #
       def create *args, **kwargs
         fobj = new(*args, **kwargs)
-        raise Familia::Problem, "#{self} already exists: #{fobj.rediskey}" if fobj.exists?
+        raise Familia::Problem, "#{self} already exists: #{fobj.dbkey}" if fobj.exists?
 
         fobj.save
         fobj
@@ -285,17 +272,17 @@ module Familia
       end
 
       def rawmultiget(*ids)
-        ids.collect! { |objid| rediskey(objid) }
+        ids.collect! { |objid| dbkey(objid) }
         return [] if ids.compact.empty?
 
-        Familia.trace :MULTIGET, redis, "#{ids.size}: #{ids}", caller(1..1) if Familia.debug?
-        redis.mget(*ids)
+        Familia.trace :MULTIGET, dbclient, "#{ids.size}: #{ids}", caller(1..1) if Familia.debug?
+        dbclient.mget(*ids)
       end
 
-      # Retrieves and instantiates an object from Redis using the full object
+      # Retrieves and instantiates an object from Database using the full object
       # key.
       #
-      # @param objkey [String] The full Redis key for the object.
+      # @param objkey [String] The full dbkey for the object.
       # @return [Object, nil] An instance of the class if the key exists, nil
       #   otherwise.
       # @raise [ArgumentError] If the provided key is empty.
@@ -325,10 +312,10 @@ module Familia
 
         # We use a lower-level method here b/c we're working with the
         # full key and not just the identifier.
-        does_exist = redis.exists(objkey).positive?
+        does_exist = dbclient.exists(objkey).positive?
 
         Familia.ld "[.find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :FROM_KEY, redis, objkey, caller(1..1) if Familia.debug?
+        Familia.trace :FROM_KEY, dbclient, objkey, caller(1..1) 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
@@ -337,22 +324,22 @@ module Familia
         # the constructor, which will then be annoying to debug.
         return unless does_exist
 
-        obj = redis.hgetall(objkey) # horreum objects are persisted as redis hashes
-        Familia.trace :FROM_KEY2, redis, "#{objkey}: #{obj.inspect}", caller(1..1) if Familia.debug?
+        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?
 
         new(**obj)
       end
-      alias from_rediskey find_by_key # deprecated
+      alias from_dbkey find_by_key # deprecated
 
-      # Retrieves and instantiates an object from Redis using its identifier.
+      # Retrieves and instantiates an object from Database using its identifier.
       #
       # @param identifier [String, Integer] The unique identifier for the
       #   object.
-      # @param suffix [Symbol] The suffix to use in the Redis key (default:
+      # @param suffix [Symbol] The suffix to use in the dbkey (default:
       #   :object).
       # @return [Object, nil] An instance of the class if found, nil otherwise.
       #
-      # This method constructs the full Redis key using the provided identifier
+      # This method constructs the full dbkey using the provided identifier
       # and suffix, then delegates to `find_by_key` for the actual retrieval and
       # instantiation.
       #
@@ -367,10 +354,10 @@ module Familia
         suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
-        objkey = rediskey(identifier, suffix)
+        objkey = dbkey(identifier, suffix)
 
         Familia.ld "[.find_by_id] #{self} from key #{objkey})"
-        Familia.trace :FIND_BY_ID, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
+        Familia.trace :FIND_BY_ID, Familia.dbclient(uri), objkey, caller(1..1).first if Familia.debug?
         find_by_key objkey
       end
       alias find find_by_id
@@ -380,10 +367,10 @@ module Familia
       # Checks if an object with the given identifier exists in Redis.
       #
       # @param identifier [String, Integer] The unique identifier for the object.
-      # @param suffix [Symbol, nil] The suffix to use in the Redis key (default: class suffix).
+      # @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 Redis key using the provided identifier and suffix,
+      # This method constructs the full dbkey using the provided identifier and suffix,
       # then checks if the key exists in Redis.
       #
       # @example
@@ -393,24 +380,24 @@ module Familia
         suffix ||= self.suffix
         return false if identifier.to_s.empty?
 
-        objkey = rediskey identifier, suffix
+        objkey = dbkey identifier, suffix
 
-        ret = redis.exists objkey
-        Familia.trace :EXISTS, redis, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
+        ret = dbclient.exists objkey
+        Familia.trace :EXISTS, dbclient, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
 
-        ret.positive? # differs from redis API but I think it's okay bc `exists?` is a predicate method.
+        ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
       end
 
-      # Destroys an object in Redis with the given identifier.
+      # Destroys an object in Database with the given identifier.
       #
       # @param identifier [String, Integer] The unique identifier for the object to destroy.
-      # @param suffix [Symbol, nil] The suffix to use in the Redis key (default: class suffix).
+      # @param suffix [Symbol, nil] The suffix to use in the dbkey (default: class suffix).
       # @return [Boolean] true if the object was successfully destroyed, false otherwise.
       #
       # This method is part of Familia's high-level object lifecycle management. While `delete!`
-      # operates directly on Redis keys, `destroy!` operates at the object level and is used for
+      # operates directly on dbkeys, `destroy!` operates at the object level and is used for
       # ORM-style operations. Use `destroy!` when removing complete objects from the system, and
-      # `delete!` when working directly with Redis keys.
+      # `delete!` when working directly with dbkeys.
       #
       # @example
       #   User.destroy!(123)  # Removes user:123:object from Redis
@@ -419,27 +406,27 @@ module Familia
         suffix ||= self.suffix
         return false if identifier.to_s.empty?
 
-        objkey = rediskey identifier, suffix
+        objkey = dbkey identifier, suffix
 
-        ret = redis.del objkey
-        Familia.trace :DESTROY!, redis, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
+        ret = dbclient.del objkey
+        Familia.trace :DESTROY!, dbclient, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
         ret.positive?
       end
 
-      # Finds all keys in Redis matching the given suffix pattern.
+      # Finds all keys in Database matching the given suffix pattern.
       #
       # @param suffix [String] The suffix pattern to match (default: '*').
-      # @return [Array<String>] An array of matching Redis keys.
+      # @return [Array<String>] An array of matching dbkeys.
       #
-      # This method searches for all Redis keys that match the given suffix pattern.
-      # It uses the class's rediskey method to construct the search pattern.
+      # This method searches for all dbkeys that match the given suffix pattern.
+      # It uses the class's dbkey method to construct the search pattern.
       #
       # @example
       #   User.find  # Returns all keys matching user:*:object
       #   User.find('active')  # Returns all keys matching user:*:active
       #
       def find_keys(suffix = '*')
-        redis.keys(rediskey('*', suffix)) || []
+        dbclient.keys(dbkey('*', suffix)) || []
       end
 
       # +identifier+ can be a value or an Array of values used to create the index.
@@ -449,15 +436,15 @@ module Familia
       # +suffix+ If a nil value is explicitly passed in, it won't appear in the redis
       # key that's returned. If no suffix is passed in, the class' suffix is used
       # as the default (via the class method self.suffix). It's an important
-      # distinction b/c passing in an explicitly nil is how RedisType objects
+      # 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 RedisType#rediskey "parent_class?" for more details.
-      def rediskey(identifier, suffix = self.suffix)
-        # Familia.ld "[.rediskey] #{identifier} for #{self} (suffix:#{suffix})"
+      # 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?
 
         identifier &&= identifier.to_s
-        Familia.rediskey(prefix, identifier, suffix)
+        Familia.dbkey(prefix, identifier, suffix)
       end
 
       def dump_method
@@ -468,6 +455,6 @@ module Familia
         @load_method || :from_json # Familia.load_method
       end
     end
-    # End of ClassMethods module
+
   end
 end

data/lib/familia/horreum/commands.rb

@@ -1,25 +1,25 @@
-# rubocop:disable all
-#
+# lib/familia/horreum/commands.rb
+
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
   #
   # This module is included in classes that include Familia, providing
-  # instance-level functionality for Redis operations and object management.
+  # instance-level functionality for Database operations and object management.
   #
   class Horreum
 
-    # Methods that call Redis commands (InstanceMethods)
+    # Methods that call Database commands (InstanceMethods)
     #
     # NOTE: There is no hgetall for Horreum. This is because Horreum
-    # is a single hash in Redis that we aren't meant to have be working
+    # is a single hash in Database that we aren't meant to have be working
     # on in memory for more than, making changes -> committing. To
     # emphasize this, instead of "refreshing" the object with hgetall,
     # just load the object again.
     #
     module Commands
 
-      def move(db)
-        redis.move rediskey, db
+      def move(logical_database)
+        dbclient.move dbkey, logical_database
       end
 
       # Checks if the calling object's key exists in Redis.
@@ -39,7 +39,7 @@ module Familia
       # @note The default behavior maintains backward compatibility by treating empty hashes
       #   as non-existent. Use `check_size: false` for pure key existence checking.
       def exists?(check_size: true)
-        key_exists = self.class.redis.exists?(rediskey)
+        key_exists = self.class.dbclient.exists?(dbkey)
         return key_exists unless check_size
         key_exists && !size.zero?
       end
@@ -47,7 +47,7 @@ module Familia
       # Returns the number of fields in the main object hash
       # @return [Integer] number of fields
       def field_count
-        redis.hlen rediskey
+        dbclient.hlen dbkey
       end
       alias size field_count
 
@@ -55,44 +55,39 @@ module Familia
       # automatically be deleted. Returns 1 if the timeout was set, 0 if key
       # does not exist or the timeout could not be set.
       #
-      def expire(ttl = nil)
-        ttl ||= self.class.ttl
-        Familia.trace :EXPIRE, redis, ttl, caller(1..1) if Familia.debug?
-        redis.expire rediskey, ttl.to_i
+      def expire(default_expiration = nil)
+        default_expiration ||= self.class.default_expiration
+        Familia.trace :EXPIRE, dbclient, default_expiration, caller(1..1) if Familia.debug?
+        dbclient.expire dbkey, default_expiration.to_i
       end
 
-      # Retrieves the remaining time to live (TTL) for the object's Redis key.
+      # Retrieves the remaining time to live (TTL) for the object's dbkey.
       #
-      # This method accesses the ovjects Redis client to obtain the TTL of `rediskey`.
+      # This method accesses the ovjects Database client to obtain the TTL of `dbkey`.
       # If debugging is enabled, it logs the TTL retrieval operation using `Familia.trace`.
       #
       # @return [Integer] The TTL of the key in seconds. Returns -1 if the key does not exist
       #   or has no associated expire time.
-      def realttl
-        Familia.trace :REALTTL, redis, redisuri, caller(1..1) if Familia.debug?
-        redis.ttl rediskey
+      def current_expiration
+        Familia.trace :CURRENT_EXPIRATION, dbclient, uri, caller(1..1) if Familia.debug?
+        dbclient.ttl dbkey
       end
 
-      # Removes a field from the hash stored at the Redis key.
+      # Removes a field from the hash stored at the dbkey.
       #
       # @param field [String] The field to remove from the hash.
       # @return [Integer] The number of fields that were removed from the hash (0 or 1).
       def remove_field(field)
-        Familia.trace :HDEL, redis, field, caller(1..1) if Familia.debug?
-        redis.hdel rediskey, field
+        Familia.trace :HDEL, dbclient, field, caller(1..1) if Familia.debug?
+        dbclient.hdel dbkey, field
       end
       alias remove remove_field # deprecated
 
-      def redistype
-        Familia.trace :REDISTYPE, redis, redisuri, caller(1..1) if Familia.debug?
-        redis.type rediskey(suffix)
+      def datatype
+        Familia.trace :DATATYPE, dbclient, uri, caller(1..1) if Familia.debug?
+        dbclient.type dbkey(suffix)
       end
 
-      # Parity with RedisType#rename
-      def rename(newkey)
-        Familia.trace :RENAME, redis, "#{rediskey} -> #{newkey}", caller(1..1) if Familia.debug?
-        redis.rename rediskey, newkey
-      end
 
       # Retrieves the prefix for the current instance by delegating to its class.
       #
@@ -103,80 +98,80 @@ module Familia
         self.class.prefix
       end
 
-      # For parity with RedisType#hgetall
+      # For parity with DataType#hgetall
       def hgetall
-        Familia.trace :HGETALL, redis, redisuri, caller(1..1) if Familia.debug?
-        redis.hgetall rediskey(suffix)
+        Familia.trace :HGETALL, dbclient, uri, caller(1..1) if Familia.debug?
+        dbclient.hgetall dbkey(suffix)
       end
       alias all hgetall
 
       def hget(field)
-        Familia.trace :HGET, redis, field, caller(1..1) if Familia.debug?
-        redis.hget rediskey(suffix), field
+        Familia.trace :HGET, dbclient, field, caller(1..1) if Familia.debug?
+        dbclient.hget dbkey(suffix), field
       end
 
       # @return The number of fields that were added to the hash. If the
       #  field already exists, this will return 0.
       def hset(field, value)
-        Familia.trace :HSET, redis, field, caller(1..1) if Familia.debug?
-        redis.hset rediskey, field, value
+        Familia.trace :HSET, dbclient, field, caller(1..1) if Familia.debug?
+        dbclient.hset dbkey, field, value
       end
 
       def hmset(hsh={})
         hsh ||= self.to_h
-        Familia.trace :HMSET, redis, hsh, caller(1..1) if Familia.debug?
-        redis.hmset rediskey(suffix), hsh
+        Familia.trace :HMSET, dbclient, hsh, caller(1..1) if Familia.debug?
+        dbclient.hmset dbkey(suffix), hsh
       end
 
       def hkeys
-        Familia.trace :HKEYS, redis, 'redisuri', caller(1..1) if Familia.debug?
-        redis.hkeys rediskey(suffix)
+        Familia.trace :HKEYS, dbclient, 'uri', caller(1..1) if Familia.debug?
+        dbclient.hkeys dbkey(suffix)
       end
 
       def hvals
-        redis.hvals rediskey(suffix)
+        dbclient.hvals dbkey(suffix)
       end
 
       def incr(field)
-        redis.hincrby rediskey(suffix), field, 1
+        dbclient.hincrby dbkey(suffix), field, 1
       end
       alias increment incr
 
       def incrby(field, increment)
-        redis.hincrby rediskey(suffix), field, increment
+        dbclient.hincrby dbkey(suffix), field, increment
       end
       alias incrementby incrby
 
       def incrbyfloat(field, increment)
-        redis.hincrbyfloat rediskey(suffix), field, increment
+        dbclient.hincrbyfloat dbkey(suffix), field, increment
       end
       alias incrementbyfloat incrbyfloat
 
       def decrby(field, decrement)
-        redis.decrby rediskey(suffix), field, decrement
+        dbclient.decrby dbkey(suffix), field, decrement
       end
       alias decrementby decrby
 
       def decr(field)
-        redis.hdecr field
+        dbclient.hdecr field
       end
       alias decrement decr
 
       def hstrlen(field)
-        redis.hstrlen rediskey(suffix), field
+        dbclient.hstrlen dbkey(suffix), field
       end
       alias hstrlength hstrlen
 
       def key?(field)
-        redis.hexists rediskey(suffix), field
+        dbclient.hexists dbkey(suffix), field
       end
       alias has_key? key?
 
-      # Deletes the entire Redis key
+      # Deletes the entire dbkey
       # @return [Boolean] true if the key was deleted, false otherwise
       def delete!
-        Familia.trace :DELETE!, redis, redisuri, caller(1..1) if Familia.debug?
-        ret = redis.del rediskey
+        Familia.trace :DELETE!, dbclient, uri, caller(1..1) if Familia.debug?
+        ret = dbclient.del dbkey
         ret.positive?
       end
       alias clear delete!