familia 1.2.1 → 2.0.0.pre2

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!

data/lib/familia/horreum/connection.rb

@@ -0,0 +1,82 @@
+# lib/familia/horreum/connection.rb
+
+module Familia
+  class Horreum
+
+    # Familia::Horreum::Connection
+    #
+    module Connection
+      attr_reader :uri
+
+      # Returns the Database connection for the class.
+      #
+      # This method retrieves the Database 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 Database connection instance.
+      #
+      def dbclient
+        Fiber[:familia_transaction] || @dbclient || Familia.dbclient(uri || logical_database)
+      end
+
+      def connect(*)
+        Familia.connect(*)
+      end
+
+      def uri=(uri)
+        @uri = normalize_uri(uri)
+      end
+      alias url uri
+      alias url= uri=
+
+      # Perform a sacred Database transaction ritual.
+      #
+      # This method creates a protective circle around your Database operations,
+      # ensuring they all succeed or fail together. It's like a group hug for your
+      # data operations, but with more ACID properties.
+      #
+      # @yield [conn] A block where you can perform your Database incantations.
+      # @yieldparam conn [Redis] A Database connection in multi mode.
+      #
+      # @example Performing a Database rain dance
+      #   transaction do |conn|
+      #     conn.set("weather", "rainy")
+      #     conn.set("mood", "melancholic")
+      #   end
+      #
+      # @note This method works with the global Familia.transaction context when available
+      #
+      def transaction
+        # If we're already in a Familia.transaction context, just yield the multi connection
+        if Fiber[:familia_transaction]
+          yield(Fiber[:familia_transaction])
+        else
+          # Otherwise, create a local transaction
+          block_result = dbclient.multi do |conn|
+            yield(conn)
+          end
+        end
+        block_result
+      end
+      alias multi transaction
+
+      def pipeline
+        # If we're already in a Familia.pipeline context, just yield the pipeline connection
+        if Fiber[:familia_pipeline]
+          yield(Fiber[:familia_pipeline])
+        else
+          # Otherwise, create a local transaction
+          block_result = dbclient.pipeline do |conn|
+            yield(conn)
+          end
+        end
+        block_result
+      end
+
+    end
+
+    # Include Connection module for instance methods after it's loaded
+    include Familia::Horreum::Connection
+  end
+end

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

@@ -1,21 +1,23 @@
+# lib/familia/horreum/related_fields_management.rb
+
 module Familia
   class Horreum
     #
-    # RelationsManagement: Manages Redis-type fields and relations
+    # RelatedFieldsManagement: Manages DataType fields and relations
     #
     # This module uses metaprogramming to dynamically create methods
-    # for managing different types of Redis objects (e.g., sets, lists, hashes).
+    # for managing different types of Database objects (e.g., sets, lists, hashes).
     #
     # Key metaprogramming features:
-    # * Dynamically defines methods for each Redis type (e.g., set, list, hashkey)
+    # * Dynamically defines methods for each Database type (e.g., set, list, hashkey)
     # * Creates both instance-level and class-level relation methods
     # * Provides query methods for checking relation types
     #
     # Usage:
-    #   Include this module in classes that need Redis-type management
+    #   Include this module in classes that need DataType management
     #   Call setup_relations_accessors to initialize the feature
     #
-    module RelationsManagement
+    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
@@ -26,18 +28,18 @@ module Familia
       end
 
       module ClassMethods
-        # Sets up all Redis-type related methods
+        # Sets up all DataType related methods
         # This method is the core of the metaprogramming logic
         #
         def setup_relations_accessors
-          Familia::RedisType.registered_types.each_pair do |kind, klass|
+          Familia::DataType.registered_types.each_pair do |kind, klass|
             Familia.ld "[registered_types] #{kind} => #{klass}"
 
             # Dynamically define instance-level relation methods
             #
             # Once defined, these methods can be used at the instance-level of a
             # Familia member to define *instance-level* relations to any of the
-            # RedisType types (e.g. set, list, hash, etc).
+            # DataType types (e.g. set, list, hash, etc).
             #
             define_method :"#{kind}" do |*args|
               name, opts = *args
@@ -45,15 +47,15 @@ module Familia
               # As log as we have at least one relation, we can set this flag.
               @has_relations = true
 
-              attach_instance_redis_object_relation name, klass, opts
+              attach_instance_related_field name, klass, opts
             end
             define_method :"#{kind}?" do |name|
-              obj = redis_types[name.to_s.to_sym]
+              obj = related_fields[name.to_s.to_sym]
               !obj.nil? && klass == obj.klass
             end
             define_method :"#{kind}s" do
-              names = redis_types.keys.select { |name| send(:"#{kind}?", name) }
-              names.collect! { |name| redis_types[name] }
+              names = related_fields.keys.select { |name| send(:"#{kind}?", name) }
+              names.collect! { |name| related_fields[name] }
               names
             end
 
@@ -61,24 +63,24 @@ module Familia
             #
             # Once defined, these methods can be used at the class-level of a
             # Familia member to define *class-level relations* to any of the
-            # RedisType types (e.g. class_set, class_list, class_hash, etc).
+            # DataType types (e.g. class_set, class_list, class_hash, etc).
             #
             define_method :"class_#{kind}" do |*args|
               name, opts = *args
-              attach_class_redis_object_relation name, klass, opts
+              attach_class_related_field name, klass, opts
             end
             define_method :"class_#{kind}?" do |name|
-              obj = class_redis_types[name.to_s.to_sym]
+              obj = class_related_fields[name.to_s.to_sym]
               !obj.nil? && klass == obj.klass
             end
             define_method :"class_#{kind}s" do
-              names = class_redis_types.keys.select { |name| send(:"class_#{kind}?", name) }
-              # TODO: This returns instances of the RedisType class which
+              names = class_related_fields.keys.select { |name| send(:"class_#{kind}?", name) }
+              # TODO: This returns instances of the DataType class which
               # also contain the options. This is different from the instance
-              # RedisTypes defined above which returns the Struct of name, klass, and opts.
+              # DataTypes defined above which returns the Struct of name, klass, and opts.
               # names.collect! { |name| self.send name }
               # OR NOT:
-              names.collect! { |name| class_redis_types[name] }
+              names.collect! { |name| class_related_fields[name] }
               names
             end
           end
@@ -87,17 +89,17 @@ module Familia
       # End of ClassMethods module
 
       # Creates an instance-level relation
-      def attach_instance_redis_object_relation(name, klass, opts)
+      def attach_instance_related_field(name, klass, opts)
         Familia.ld "[#{self}##{name}] Attaching instance-level #{klass} #{opts}"
         raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
 
         name = name.to_s.to_sym
         opts ||= {}
 
-        redis_types[name] = Struct.new(:name, :klass, :opts).new
-        redis_types[name].name = name
-        redis_types[name].klass = klass
-        redis_types[name].opts = 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
 
         attr_reader name
 
@@ -108,11 +110,11 @@ module Familia
           !send(name).empty?
         end
 
-        redis_types[name]
+        related_fields[name]
       end
 
       # Creates a class-level relation
-      def attach_class_redis_object_relation(name, klass, opts)
+      def attach_class_related_field(name, klass, opts)
         Familia.ld "[#{self}.#{name}] Attaching class-level #{klass} #{opts}"
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
@@ -120,10 +122,10 @@ module Familia
         opts = opts.nil? ? {} : opts.clone
         opts[:parent] = self unless opts.key?(:parent)
 
-        class_redis_types[name] = Struct.new(:name, :klass, :opts).new
-        class_redis_types[name].name = name
-        class_redis_types[name].klass = klass
-        class_redis_types[name].opts = opts
+        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
 
         # An accessor method created in the metaclass will
         # access the instance variables for this class.
@@ -136,13 +138,13 @@ module Familia
           !send(name).empty?
         end
 
-        redis_object = klass.new name, opts
-        redis_object.freeze
-        instance_variable_set(:"@#{name}", redis_object)
+        related_field = klass.new name, opts
+        related_field.freeze
+        instance_variable_set(:"@#{name}", related_field)
 
-        class_redis_types[name]
+        class_related_fields[name]
       end
     end
-    # End of RelationsManagement module
+    # End of RelatedFieldsManagement module
   end
 end