familia 1.0.0.pre.rc2 → 1.0.0.pre.rc4

data/lib/familia/horreum/class_methods.rb

@@ -36,20 +36,40 @@ module Familia
       attr_accessor :parent
       attr_writer :redis, :dump_method, :load_method
 
+      # 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
 
-      # The object field or instance method to call to get the unique identifier
-      # for that instance. The value returned by this method will be used to
-      # generate the key for the object in Redis.
+      # 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
       end
 
-      # Define a field for the class. This will create getter and setter
-      # instance methods just like any "attr_accessor" methods.
+      # Defines a field for the class and creates accessor methods.
+      #
+      # 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.
+      #
+      # @param [Symbol, String] name the name of the field to define.
+      #
       def field(name)
         fields << name
         attr_accessor name
@@ -58,13 +78,44 @@ module Familia
         fast_writer! name
       end
 
-      # @return The return value from redis client for hset command
+      # Defines a writer method with a bang (!) suffix for a given attribute name.
+      #
+      # The dynamically defined method performs the following:
+      # - Checks if the correct number of arguments is provided (exactly 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)
-        define_method :"#{name}!" do |value|
-          prepared = to_redis(value)
-          Familia.ld "[.fast_writer!] #{name} val: #{value.class} prepared: #{prepared.class}"
-          send :"#{name}=", value # use the existing accessor
-          hset name, prepared # persist to Redis without delay
+        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
+
+          value = args.first
+
+          begin
+            # Trace the operation if debugging is enabled.
+            Familia.trace :FAST_WRITER, redis, "#{name}: #{value.inspect}", caller(1..1) if Familia.debug?
+
+            # Convert the provided value to a format suitable for Redis storage.
+            prepared = to_redis(value)
+            Familia.ld "[.fast_writer!] #{name} val: #{value.class} prepared: #{prepared.class}"
+
+            # Use the existing accessor method to set the attribute value.
+            send :"#{name}=", value
+
+            # Persist the value to Redis 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.
+            raise "#{name}! method failed: #{e.message}", e.backtrace
+          end
         end
       end
 
@@ -93,11 +144,6 @@ module Familia
         @redis_types
       end
 
-      def ttl(v = nil)
-        @ttl = v unless v.nil?
-        @ttl || parent&.ttl
-      end
-
       def db(v = nil)
         @db = v unless v.nil?
         @db || parent&.db
@@ -108,9 +154,10 @@ module Familia
         @uri || parent&.uri
       end
 
-      def all(suffix = :object)
+      def all(suffix = nil)
+        suffix ||= self.suffix
         # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| from_key(k) }
+        keys(suffix).filter_map { |k| from_rediskey(k) }
       end
 
       def any?(filter = '*')
@@ -131,12 +178,48 @@ module Familia
         @prefix || name.downcase.gsub('::', Familia.delim).to_sym
       end
 
-      def create *args
-        me = from_array(*args)
-        raise "#{self} exists: #{me.rediskey}" if me.exists?
+      # Creates and persists a new instance of the class.
+      #
+      # @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.
+      # @return [Object] The newly created and persisted instance.
+      # @raise [Familia::Problem] If an instance with the same identifier already
+      #   exists.
+      #
+      # This method serves as a factory method for creating and persisting new
+      # instances of the class. It combines object instantiation, existence
+      # checking, and persistence in a single operation.
+      #
+      # The method is flexible in accepting both positional and keyword arguments:
+      # - Positional arguments (*args) are passed directly to the constructor.
+      # - Keyword arguments (**kwargs) are passed as a hash to the constructor.
+      #
+      # After instantiation, the method checks if an object with the same
+      # identifier already exists. If it does, a Familia::Problem exception is
+      # raised to prevent overwriting existing data.
+      #
+      # Finally, the method saves the new instance returns it.
+      #
+      # @example Creating an object with keyword arguments
+      #   User.create(name: "John", age: 30)
+      #
+      # @example Creating an object with positional and keyword arguments (not recommended)
+      #   Product.create("SKU123", name: "Widget", price: 9.99)
+      #
+      # @note The behavior of this method depends on the implementation of #new,
+      #   #exists?, and #save in the class and its superclasses.
+      #
+      # @see #new
+      # @see #exists?
+      # @see #save
+      #
+      def create *args, **kwargs
+        fobj = new(*args, **kwargs)
+        raise Familia::Problem, "#{self} already exists: #{fobj.rediskey}" if fobj.exists?
 
-        me.save
-        me
+        fobj.save
+        fobj
       end
 
       def multiget(*ids)
@@ -148,7 +231,7 @@ module Familia
         ids.collect! { |objid| rediskey(objid) }
         return [] if ids.compact.empty?
 
-        Familia.trace :MULTIGET, redis, "#{ids.size}: #{ids}", caller if Familia.debug?
+        Familia.trace :MULTIGET, redis, "#{ids.size}: #{ids}", caller(1..1) if Familia.debug?
         redis.mget(*ids)
       end
 
@@ -177,18 +260,18 @@ module Familia
       # debugging.
       #
       # @example
-      #   User.from_key("user:123")  # Returns a User instance if it exists,
+      #   User.from_rediskey("user:123")  # Returns a User instance if it exists,
       #   nil otherwise
       #
-      def from_key(objkey)
+      def from_rediskey(objkey)
         raise ArgumentError, 'Empty key' if objkey.to_s.empty?
 
         # 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?
 
-        Familia.ld "[.from_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :FROM_KEY, redis, objkey, caller if Familia.debug?
+        Familia.ld "[.from_rediskey] #{self} from key #{objkey} (exists: #{does_exist})"
+        Familia.trace :FROM_KEY, redis, 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
@@ -198,7 +281,7 @@ module Familia
         return unless does_exist
 
         obj = redis.hgetall(objkey) # horreum objects are persisted as redis hashes
-        Familia.trace :FROM_KEY2, redis, "#{objkey}: #{obj.inspect}", caller if Familia.debug?
+        Familia.trace :FROM_KEY2, redis, "#{objkey}: #{obj.inspect}", caller(1..1) if Familia.debug?
 
         new(**obj)
       end
@@ -212,7 +295,7 @@ module Familia
       # @return [Object, nil] An instance of the class if found, nil otherwise.
       #
       # This method constructs the full Redis key using the provided identifier
-      # and suffix, then delegates to `from_key` for the actual retrieval and
+      # and suffix, then delegates to `from_rediskey` for the actual retrieval and
       # instantiation.
       #
       # It's a higher-level method that abstracts away the key construction,
@@ -220,59 +303,95 @@ module Familia
       # identifier.
       #
       # @example
-      #   User.from_redis(123)  # Equivalent to User.from_key("user:123:object")
+      #   User.from_identifier(123)  # Equivalent to User.from_rediskey("user:123:object")
       #
-      def from_redis(identifier, suffix = :object)
+      def from_identifier(identifier, suffix = nil)
+        suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
         objkey = rediskey(identifier, suffix)
-        Familia.ld "[.from_redis] #{self} from key #{objkey})"
-        Familia.trace :FROM_REDIS, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
-        from_key objkey
+
+        Familia.ld "[.from_identifier] #{self} from key #{objkey})"
+        Familia.trace :FROM_IDENTIFIER, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
+        from_rediskey objkey
       end
+      alias load from_identifier
 
-      def exists?(identifier, suffix = :object)
+      # 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).
+      # @return [Boolean] true if the object exists, false otherwise.
+      #
+      # This method constructs the full Redis key using the provided identifier and suffix,
+      # then checks if the key exists in Redis.
+      #
+      # @example
+      #   User.exists?(123)  # Returns true if user:123:object exists in Redis
+      #
+      def exists?(identifier, suffix = nil)
+        suffix ||= self.suffix
         return false if identifier.to_s.empty?
 
         objkey = rediskey identifier, suffix
 
         ret = redis.exists objkey
-        Familia.trace :EXISTS, redis, "#{objkey} #{ret.inspect}", caller if Familia.debug?
-        ret.positive?
+        Familia.trace :EXISTS, redis, "#{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.
       end
 
-      def destroy!(identifier, suffix = :object)
+      # Destroys an object in Redis 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).
+      # @return [Boolean] true if the object was successfully destroyed, false otherwise.
+      #
+      # This method constructs the full Redis key using the provided identifier and suffix,
+      # then removes the corresponding key from Redis.
+      #
+      # @example
+      #   User.destroy!(123)  # Removes user:123:object from Redis
+      #
+      def destroy!(identifier, suffix = nil)
+        suffix ||= self.suffix
         return false if identifier.to_s.empty?
 
         objkey = rediskey identifier, suffix
 
         ret = redis.del objkey
-        if Familia.debug?
-          Familia.trace :DELETED, redis, "#{objkey}: #{ret.inspect}",
-                        caller
-        end
+        Familia.trace :DELETED, redis, "#{objkey}: #{ret.inspect}", caller(1..1) if Familia.debug?
         ret.positive?
       end
 
+      # Finds all keys in Redis matching the given suffix pattern.
+      #
+      # @param suffix [String] The suffix pattern to match (default: '*').
+      # @return [Array<String>] An array of matching Redis keys.
+      #
+      # 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.
+      #
+      # @example
+      #   User.find  # Returns all keys matching user:*:object
+      #   User.find('active')  # Returns all keys matching user:*:active
+      #
       def find(suffix = '*')
         redis.keys(rediskey('*', suffix)) || []
       end
 
-      def qstamp(quantum = nil, pattern = nil, now = Familia.now)
-        quantum ||= ttl || 10.minutes
-        pattern ||= '%H%M'
-        rounded = now - (now % quantum)
-        Time.at(rounded).utc.strftime(pattern)
-      end
-
       # +identifier+ can be a value or an Array of values used to create the index.
       # We don't enforce a default suffix; that's left up to the instance.
       # The suffix is used to differentiate between different types of objects.
       #
-      #
-      # A nil +suffix+ will not be included in the key.
+      # +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
+      # 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})"
+        # Familia.ld "[.rediskey] #{identifier} for #{self} (suffix:#{suffix})"
         raise NoIdentifier, self if identifier.to_s.empty?
 
         identifier &&= identifier.to_s

data/lib/familia/horreum/commands.rb

@@ -19,29 +19,42 @@ module Familia
     module Commands
 
       def exists?
-        ret = redis.exists rediskey
-        ret.positive?
+        # Trace output comes from the class method
+        self.class.exists? identifier, suffix
       end
 
+      # Sets a timeout on key. After the timeout has expired, the key will 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
       end
 
       def realttl
+        Familia.trace :REALTTL, redis, redisuri, caller(1..1) if Familia.debug?
         redis.ttl rediskey
       end
 
+      # Deletes a field from the hash stored at the Redis key.
+      #
+      # @param field [String] The field to delete from the hash.
+      # @return [Integer] The number of fields that were removed from the hash (0 or 1).
+      # @note This method is destructive, as indicated by the bang (!).
       def hdel!(field)
+        Familia.trace :HDEL, redis, field, caller(1..1) if Familia.debug?
         redis.hdel rediskey, field
       end
 
       def redistype
+        Familia.trace :REDISTYPE, redis, redisuri, caller(1..1) if Familia.debug?
         redis.type rediskey(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
 
@@ -53,13 +66,14 @@ module Familia
       alias all hgetall
 
       def hget(field)
+        Familia.trace :HGET, redis, field, caller(1..1) if Familia.debug?
         redis.hget rediskey(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, redisuri, caller(1..1) if Familia.debug?
+        Familia.trace :HSET, redis, field, caller(1..1) if Familia.debug?
         redis.hset rediskey, field, value
       end
 
@@ -76,21 +90,45 @@ module Familia
         redis.hvals rediskey(suffix)
       end
 
-      def hincrby(field, increment)
+      def incr(field)
+        redis.hincrby rediskey(suffix), field, 1
+      end
+      alias increment incr
+
+      def incrby(field, increment)
         redis.hincrby rediskey(suffix), field, increment
       end
+      alias incrementby incrby
 
-      def hincrbyfloat(field, increment)
+      def incrbyfloat(field, increment)
         redis.hincrbyfloat rediskey(suffix), field, increment
       end
+      alias incrementbyfloat incrbyfloat
+
+      def decrby(field, decrement)
+        redis.decrby rediskey(suffix), field, decrement
+      end
+      alias decrementby decrby
+
+      def decr(field)
+        redis.hdecr field
+      end
+      alias decrement decr
 
       def hlen
         redis.hlen rediskey(suffix)
       end
+      alias hlength hlen
 
       def hstrlen(field)
         redis.hstrlen rediskey(suffix), field
       end
+      alias hstrlength hstrlen
+
+      def key?(field)
+        redis.hexists rediskey(suffix), field
+      end
+      alias has_key? key?
 
       def delete!
         Familia.trace :DELETE!, redis, redisuri, caller(1..1) if Familia.debug?

data/lib/familia/horreum/relations_management.rb

@@ -81,7 +81,7 @@ module Familia
 
       # Creates an instance-level relation
       def attach_instance_redis_object_relation(name, klass, opts)
-        Familia.ld "[Attaching instance-level #{name}] #{klass} => (#{self}) #{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
@@ -106,7 +106,7 @@ module Familia
 
       # Creates a class-level relation
       def attach_class_redis_object_relation(name, klass, opts)
-        Familia.ld "[#{self}] Attaching class-level #{name} #{klass} => #{opts}"
+        Familia.ld "[#{self}.#{name}] Attaching class-level #{klass} #{opts}"
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
         name = name.to_s.to_sym