Merge pull request #37 from delano/delano/20240826-fast-attribute

Enhancements for Redis access and instance relations

Author: delano

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (1.0.0.pre.rc6)
+    familia (1.0.0.pre.rc7)
       redis (>= 4.8.1, < 6.0)
       uri-redis (~> 1.3)
 

README.md

@@ -1,4 +1,4 @@
-# Familia - 1.0.0-rc6 (August 2024)
+# Familia - 1.0.0-rc7 (August 2024)
 
 **Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) for Redis.**
 

VERSION.yml

@@ -2,4 +2,4 @@
 :MAJOR: 1
 :MINOR: 0
 :PATCH: 0
-:PRE: rc6
+:PRE: rc7

lib/familia/horreum.rb

@@ -142,9 +142,11 @@ def initialize_relatives
         #
         opts[:parent] = self # unless opts.key(:parent)
 
+        suffix_override = opts.fetch(:suffix, name)
+
         # Instantiate the RedisType object and below we store it in
         # an instance variable.
-        redis_type = klass.new name, opts
+        redis_type = klass.new suffix_override, opts
 
         # Freezes the redis_type, making it immutable.
         # This ensures the object's state remains consistent and prevents any modifications,

lib/familia/horreum/class_methods.rb

@@ -74,38 +74,90 @@ def field(name)
         fields << name
         attr_accessor name
 
-        # Every field gets a fast writer method for immediately persisting
-        fast_writer! name
+        # Every field gets a fast attribute method for immediately persisting
+        fast_attribute! name
       end
 
-      # Defines a writer method with a bang (!) suffix for a given attribute name.
+      # Defines a fast attribute method with a bang (!) suffix for a given
+      # attribute name. Fast attribute methods are used to immediately read or
+      # write attribute values from/to Redis. Calling a fast attribute method
+      # has no effect on any of the object's other attributes and does not
+      # trigger a call to update the object's expiration time.
       #
       # The dynamically defined method performs the following:
-      # - Checks if the correct number of arguments is provided (exactly one).
+      # - 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.
+      # - Checks if the correct number of arguments is provided (zero or one).
       # - Converts the provided value to a format suitable for Redis storage.
-      # - Uses the existing accessor method to set the attribute value.
-      # - Persists the value to Redis immediately using the hset command.
-      # - Includes custom error handling to raise an ArgumentError if the wrong number of arguments is given.
-      # - Raises a custom error message if an exception occurs during the execution of the method.
-      #
-      # @param [Symbol, String] name the name of the attribute for which the writer method is defined.
-      # @raise [ArgumentError] if the wrong number of arguments is provided.
-      # @raise [RuntimeError] if an exception occurs during the execution of the method.
-      #
-      def fast_writer!(name)
+      # - Uses the existing accessor method to set the attribute value when
+      #   writing.
+      # - Persists the value to Redis immediately using the hset command when
+      #   writing.
+      # - Includes custom error handling to raise an ArgumentError if the wrong
+      #   number of arguments is given.
+      # - Raises a custom error message if an exception occurs during the
+      #   execution of the method.
+      #
+      # @param [Symbol, String] name the name of the attribute for which the
+      #   fast method is defined.
+      # @return [Object] the current value of the attribute when called without
+      #   arguments.
+      # @raise [ArgumentError] if more than one argument is provided.
+      # @raise [RuntimeError] if an exception occurs during the execution of the
+      #   method.
+      #
+      def fast_attribute!(name = nil)
+        # Fast attribute accessor method for the '#{name}' attribute.
+        # This method provides immediate read and write access to the attribute
+        # in Redis.
+        #
+        # When called without arguments, it retrieves the current value of the
+        # attribute from Redis.
+        # When called with an argument, it immediately persists the new value to
+        # Redis.
+        #
+        # @overload #{name}!
+        #   Retrieves the current value of the attribute from Redis.
+        #   @return [Object] the current value of the attribute.
+        #
+        # @overload #{name}!(value)
+        #   Sets and immediately persists the new value of the attribute to
+        #   Redis.
+        #   @param value [Object] the new value to set for the attribute.
+        #   @return [Object] the newly set value.
+        #
+        # @raise [ArgumentError] if more than one argument is provided.
+        # @raise [RuntimeError] if an exception occurs during the execution of
+        #   the method.
+        #
+        # @note This method bypasses any object-level caching and interacts
+        #   directly with Redis. It does not trigger updates to other attributes
+        #   or the object's expiration time.
+        #
+        # @example
+        #
+        #      def #{name}!(*args)
+        #        # Method implementation
+        #      end
+        #
         define_method :"#{name}!" do |*args|
           # Check if the correct number of arguments is provided (exactly one).
-          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)" if args.size != 1
+          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0 or 1)" if args.size > 1
 
           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.
+          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?
 
             # Convert the provided value to a format suitable for Redis storage.
             prepared = to_redis(val)
-            Familia.ld "[.fast_writer!] #{name} val: #{val.class} prepared: #{prepared.class}"
+            Familia.ld "[.fast_attribute!] #{name} val: #{val.class} prepared: #{prepared.class}"
 
             # Use the existing accessor method to set the attribute value.
             send :"#{name}=", val

lib/familia/redistype.rb

@@ -16,7 +16,7 @@ class RedisType
     extend Familia::Features
 
     @registered_types = {}
-    @valid_options = %i[class parent ttl default db key redis]
+    @valid_options = %i[class parent ttl default db key redis suffix]
     @db = nil
 
     feature :expiration

try/27_redis_horreum_try.rb

@@ -47,12 +47,12 @@
 @customer.save
 #=> true
 
-## Horreum object fields have a fast writer method (1 of 2)
+## Horreum object fields have a fast attribute method (1 of 2)
 Familia.trace :LOAD, @customer.redis, @customer.redisuri, caller if Familia.debug?
 @customer.name! 'Jane Doe'
 #=> 0
 
-## Horreum object fields have a fast writer method (2 of 2)
+## Horreum object fields have a fast attribute method (2 of 2)
 @customer.refresh!
 @customer.name
 #=> "Jane Doe"