familia 1.0.0.pre.rc3 → 1.0.0.pre.rc4

data/lib/familia/horreum/class_methods.rb

@@ -95,15 +95,13 @@ module Familia
       def fast_writer!(name)
         define_method :"#{name}!" do |*args|
           # Check if the correct number of arguments is provided (exactly one).
-          if args.size != 1
-            raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)"
-          end
+          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 if Familia.debug?
+            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)
@@ -146,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
@@ -161,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 = '*')
@@ -184,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)
@@ -201,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
 
@@ -230,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
@@ -251,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
@@ -265,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,
@@ -273,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,8 +19,8 @@ module Familia
     module Commands
 
       def exists?
-        ret = redis.exists rediskey
-        ret.positive? # differs from redis API but I think it's okay bc `exists?` is a predicate method.
+        # 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.
@@ -28,10 +28,12 @@ module Familia
       #
       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
 
@@ -41,15 +43,18 @@ module Familia
       # @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
 
@@ -61,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
 

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

data/lib/familia/horreum/serialization.rb

@@ -113,19 +113,23 @@ module Familia
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
         # Did Redis accept our offering?
-        ret.uniq.all? { |value| value == "OK" }
+        ret.uniq.all? { |value| ["OK", true].include?(value) }
       end
 
       # Apply a smattering of fields to this object like fairy dust.
       #
-      # @param fields [Hash] A magical bag of named attributes to sprinkle onto this instance.
-      #   Each key-value pair is like a tiny spell, ready to enchant our object's properties.
+      # @param fields [Hash] A magical bag of named attributes to sprinkle onto
+      #   this instance. Each key-value pair is like a tiny spell, ready to
+      #   enchant our object's properties.
       #
-      # @return [self] Returns the newly bejeweled instance, now sparkling with fresh attributes.
+      # @return [self] Returns the newly bejeweled instance, now sparkling with
+      #   fresh attributes.
       #
       # @example Giving your object a makeover
-      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys named Jackie")
-      #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire", @loves="little boys named Jackie">
+      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys
+      #   named Jackie")
+      #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire",
+      #   @loves="little boys named Jackie">
       #
       def apply_fields(**fields)
         fields.each do |field, value|
@@ -140,10 +144,12 @@ module Familia
       # This method performs a sacred ritual, sending our cherished attributes
       # on a journey through the ethernet to find their resting place in Redis.
       #
-      # @return [Array<String>] A mystical array of strings, cryptic messages from the Redis gods.
+      # @return [Array<String>] A mystical array of strings, cryptic messages
+      #   from the Redis gods.
       #
-      # @note Be warned, young programmer! This method dabbles in the arcane art of transactions.
-      #   Side effects may include data persistence and a slight tingling sensation.
+      # @note Be warned, young programmer! This method dabbles in the arcane
+      #   art of transactions. Side effects may include data persistence and a
+      #   slight tingling sensation.
       #
       # @example Offering your changes to the Redis deities
       #   unicorn.name = "Charlie"
@@ -155,6 +161,10 @@ module Familia
         Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
         transaction do |conn|
           hmset
+
+          # Only classes that have the expiration ferature enabled will
+          # actually set an expiration time on their keys. Otherwise
+          # this will be a no-op.
           update_expiration
         end
       end
@@ -183,7 +193,6 @@ module Familia
         delete!
       end
 
-
       # Refreshes the object's state by querying Redis and overwriting the
       # current field values. This method performs a destructive update on the
       # object, regardless of unsaved changes.
@@ -217,7 +226,8 @@ module Familia
       # into a more plebeian hash. But fear not, for in this form, it can slip through
       # the cracks of the universe (or at least, into Redis) with ease.
       #
-      # @return [Hash] A glittering hash, each key a field name, each value a Redis-ready treasure.
+      # @return [Hash] A glittering hash, each key a field name, each value a
+      #   Redis-ready treasure.
       #
       # @example Turning your dragon into a hash
       #   dragon.to_h
@@ -247,7 +257,8 @@ module Familia
       #   unicorn.to_a
       #   # => ["Charlie", "magnificent", 5]
       #
-      # @note Each value is carefully disguised in its Redis costume before joining the parade.
+      # @note Each value is carefully disguised in its Redis costume
+      # before joining the parade.
       #
       def to_a
         self.class.fields.map do |field|
@@ -299,36 +310,6 @@ module Familia
         prepared
       end
 
-      # Set an expiration date for our data, like a "best before" sticker for Redis!
-      #
-      # This method gives our data a lifespan in Redis. It's like telling Redis,
-      # "Hey, this data is fresh now, but it might get stale after a while!"
-      #
-      # @param ttl [Integer, nil] The Time To Live in seconds. If nil, we'll check
-      #   our options for a default expiration time.
-      #
-      # @return [Boolean] true if the expiration was set successfully, false otherwise.
-      #   It's like asking Redis, "Did you stick that expiration label on properly?"
-      #
-      # @example Making your pet rock data mortal
-      #   rocky.update_expiration(86400) # Dwayne will live in Redis for one day
-      #
-      # @note If the TTL is zero, we assume our data wants to live forever.
-      #   Immortality in Redis! Who wouldn't want that?
-      #
-      def update_expiration(ttl = nil)
-        ttl ||= opts[:ttl]
-        ttl = ttl.to_i
-
-        return if ttl.zero?
-
-        Familia.ld "Setting expiration for #{rediskey} to #{ttl} seconds"
-
-        # EXPIRE command returns 1 if the timeout was set, 0 if key does not
-        # exist or the timeout could not be set.
-        expire(ttl).positive?
-      end
-
     end
     # End of Serialization module
 

data/lib/familia/horreum/settings.rb

@@ -29,14 +29,6 @@ module Familia
         }
       end
 
-      def ttl=(v)
-        @ttl = v.to_i
-      end
-
-      def ttl
-        @ttl || self.class.ttl
-      end
-
       def db=(v)
         @db = v.to_i
       end

data/lib/familia/horreum/utils.rb

@@ -28,7 +28,6 @@ module Familia
       # from the `identifier` method).
       #
       def rediskey(suffix = nil, ignored = nil)
-        Familia.ld "[#rediskey] #{identifier} for #{self.class}"
         raise Familia::NoIdentifier, "No identifier for #{self.class}" if identifier.to_s.empty?
         suffix ||= self.suffix # use the instance method to get the default suffix
         self.class.rediskey identifier, suffix

data/lib/familia/horreum.rb

@@ -56,7 +56,7 @@ module Familia
     class << self
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
-        Familia.trace :INHERITED, nil, "Inherited by #{member}", caller if Familia.debug?
+        Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
         member.extend(ClassMethods)
         member.extend(Features)
 

data/lib/familia/logging.rb

@@ -126,26 +126,48 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param redis_instance [Object] The Redis instance being used.
+    # @param redis_instance [Redis, Redis::Future, nil] The Redis instance or
+    #   Future being used.
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
     # @param context [Array<String>, String, nil] The calling context, typically
     #   obtained from `caller` or `caller.first`. Default is nil.
     #
     # @example
-    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller if Familia.debug?
-    #
+    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller(1..1) if
+    #   Familia.debug?
     #
     # @return [nil]
     #
+    # @note This method only executes if LoggerTraceRefinement::ENABLED is true.
+    # @note The redis_instance can be a Redis object, Redis::Future (used in
+    #   pipelined and multi blocks), or nil (when the redis connection isn't
+    #   relevant).
+    #
     def trace(label, redis_instance, ident, context = nil)
       return unless LoggerTraceRefinement::ENABLED
-      instance_id = redis_instance&.id
+
+      # Usually redis_instance is a Redis object, but it could be
+      # a Redis::Future which is what is used inside of pipelined
+      # and multi blocks. In some contexts it's nil where the
+      # redis connection isn't relevant.
+      instance_id = if redis_instance
+        case redis_instance
+        when Redis
+          redis_instance.id.respond_to?(:to_s) ? redis_instance.id.to_s : redis_instance.class.name
+        when Redis::Future
+          "Redis::Future"
+        else
+          redis_instance.class.name
+        end
+      end
+
       codeline = if context
                    context = [context].flatten
                    context.reject! { |line| line =~ %r{lib/familia} }
                    context.first
                  end
+
       @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end