familia 1.0.0.pre.rc7 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 518b9d319e506964416166f2d84cc05d9d4a603de80b79a2f512fa9b751c4680
-  data.tar.gz: 9f1c9737d5d141050169da6123a977921e80768f056a0da138c299ccd7716abc
+  metadata.gz: 4a664f87a493fffb0e362752c8f988c8de27d83008f3a796b66737e3d15e771d
+  data.tar.gz: cb22d85f774e40a7b656713760f2f1e31b154171620038c282ce2dbe5e88492b
 SHA512:
-  metadata.gz: 0fed4bf1187d6d9ad477504343341c1f9a5bd59d0b7c276fbb8539086ddacfd2fa2306a55f9b2b10881cdd884ad38e6a9f392f79ed822fff270d97836d681260
-  data.tar.gz: 448a16b7b71afa58a27f0dfd464d85c495ddd517bf9eba5c622fab6c7b364566595e34d71934a2b9cd67b522e4b53ad94289a8097c8d819c011ad7e3e61bd6fe
+  metadata.gz: 3942bab094053731bd0d45c47a89c7bde62d26b99339cd2fad36e5481b28f91cd3eecb17c8ef6f77e3e486858151f6d5821e973f9fb7c068431abf11634806db
+  data.tar.gz: 32933d4adbb991b3cb790f4a47134f7e428fa617b3f33d3068d98a2e795d2ee58b2654ac22fb913abdc46dd0f3459bcdfd50d71273a137d2f337c4da521e475d

data/.gitignore

@@ -8,6 +8,7 @@
 *.env
 *.log
 *.md
+!README.md
 *.txt
 !LICENSE.txt
 .ruby-version

data/.pre-commit-config.yaml

@@ -64,6 +64,6 @@ repos:
         stages: [prepare-commit-msg]
         name: Link commit to Github issue
         args:
-          - "--default=[NOJIRA]"
+          - "--default="
           - "--pattern=[a-zA-Z0-9]{0,10}-?[0-9]{1,5}"
           - "--template=[#{}]"

data/Gemfile

@@ -5,7 +5,9 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'pry-byebug', '~> 3.10.1', require: false
+  # byebug only works with MRI
+  gem 'byebug', '~> 11.0', require: false if RUBY_ENGINE == 'ruby'
+  gem 'pry-byebug', '~> 3.10.1', require: false if RUBY_ENGINE == 'ruby'
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    familia (1.0.0.pre.rc7)
+    familia (1.1.0.pre.rc1)
       redis (>= 4.8.1, < 6.0)
+      stringio (~> 3.1.1)
       uri-redis (~> 1.3)
 
 GEM
@@ -55,6 +56,7 @@ GEM
       rubocop (>= 0.90.0)
     ruby-progressbar (1.13.0)
     storable (0.10.0)
+    stringio (3.1.1)
     strscan (3.1.0)
     sysinfo (0.10.0)
       drydock (< 1.0)

data/README.md

@@ -1,4 +1,4 @@
-# Familia - 1.0.0-rc7 (August 2024)
+# Familia - 1.1.0-rc1 (November 2024)
 
 **Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) for Redis.**
 
@@ -9,7 +9,7 @@ Familia provides a flexible and feature-rich way to interact with Redis using Ru
 
 Get it in one of the following ways:
 
-* In your Gemfile: `gem 'familia', '>= 1.0.0-rc4'`
+* In your Gemfile: `gem 'familia', '>= 1.1.0-rc1'`
 * Install it by hand: `gem install familia --pre`
 * Or for development: `git clone git@github.com:delano/familia.git`
 
@@ -152,11 +152,11 @@ end
 
 ```ruby
 class ComplexObject < Familia::Horreum
-  def to_redis
+  def serialize_value
     custom_serialization_method
   end
 
-  def self.from_redis(data)
+  def self.deserialize_value(data)
     custom_deserialization_method(data)
   end
 end
@@ -188,7 +188,7 @@ flower.save
 ### Retrieving and Updating Objects
 
 ```ruby
-rose = Flower.from_identifier("rrose")
+rose = Flower.find_by_id("rrose")
 rose.name = "Pink Rose"
 rose.save
 ```

data/VERSION.yml

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

data/familia.gemspec

@@ -20,9 +20,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new('>= 2.7.8')
 
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
+  spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-redis', '~> 1.3'
 
-  # byebug only works with MRI
-  spec.add_development_dependency 'byebug', '~> 11.0' if RUBY_ENGINE == 'ruby'
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/familia/base.rb

@@ -30,21 +30,21 @@ module Familia
       end
     end
 
-    # Yo, this class is like that one friend who never checks expiration dates.
-    # It's living life on the edge, data-style!
+    # Base implementation of update_expiration that maintains API compatibility
+    # with the :expiration feature's implementation.
     #
-    # @param ttl [Integer, nil] Time To Live? More like Time To Laugh! This param
-    #   is here for compatibility, but it's as useful as a chocolate teapot.
+    # This is a no-op implementation that gets overridden by features like
+    # :expiration. It accepts an optional ttl parameter to maintain interface
+    # compatibility with the overriding implementations.
     #
-    # @return [nil] Always returns nil. It's consistent in its laziness!
+    # @param ttl [Integer, nil] Time To Live in seconds (ignored in base implementation)
+    # @return [nil] Always returns nil
     #
-    # @example Trying to teach an old dog new tricks
-    #   immortal_data.update_expiration(86400) # Nice try, but this data is here to stay!
+    # @note This is a no-op implementation. Classes that need expiration
+    #       functionality should include the :expiration feature.
     #
-    # @note This method is a no-op. It's like shouting into the void, but less echo-y.
-    #
-    def update_expiration(*)
-      Familia.info "[update_expiration] Skipped for #{rediskey}. #{self.class} data is immortal!"
+    def update_expiration(ttl: nil)
+      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{rediskey} (caller: #{caller(1..1)})"
       nil
     end
 

data/lib/familia/connection.rb

@@ -6,6 +6,7 @@ require_relative '../../lib/redis_middleware'
 module Familia
   @uri = URI.parse 'redis://127.0.0.1'
   @redis_clients = {}
+  @redis_uri_by_class = {}
 
   # The Connection module provides Redis connection management for Familia.
   # It allows easy setup and access to Redis clients across different URIs.
@@ -25,17 +26,20 @@ module Familia
     # Establishes a connection to a Redis server.
     #
     # @param uri [String, URI, nil] The URI of the Redis server to connect to.
-    #   If nil, uses the default URI.
-    # @return [Redis] The connected Redis client
+    #   If nil, uses the default URI from `@redis_uri_by_class` or `Familia.uri`.
+    # @return [Redis] The connected Redis client.
+    # @raise [ArgumentError] If no URI is specified.
     # @example
     #   Familia.connect('redis://localhost:6379')
     def connect(uri = nil)
       uri = URI.parse(uri) if uri.is_a?(String)
+      uri ||= @redis_uri_by_class[self]
       uri ||= Familia.uri
 
       raise ArgumentError, 'No URI specified' unless uri
 
       conf = uri.conf
+      @redis_uri_by_class[self] = uri.serverid
 
       if Familia.enable_redis_logging
         RedisLogger.logger = Familia.logger
@@ -49,6 +53,9 @@ module Familia
       end
 
       redis = Redis.new(conf)
+
+      # Close the existing connection if it exists
+      @redis_clients[uri.serverid].close if @redis_clients[uri.serverid]
       @redis_clients[uri.serverid] = redis
     end
 
@@ -72,6 +79,15 @@ module Familia
       @redis_clients[uri.serverid]
     end
 
+    # Retrieves the Redis client associated with the given class.
+    #
+    # @param klass [Class] The class for which to retrieve the Redis client.
+    # @return [Redis] The Redis client associated with the given class.
+    def redis_uri_by_class(klass)
+      uri = @redis_uri_by_class[klass]
+      connect(uri)
+    end
+
     # Sets the default URI for Redis connections.
     #
     # @param v [String, URI] The new default URI

data/lib/familia/errors.rb

@@ -30,4 +30,18 @@ module Familia
       "No client for #{uri.serverid}"
     end
   end
+
+  # Raised when attempting to refresh an object whose key doesn't exist in Redis
+  class KeyNotFoundError < Problem
+    attr_reader :key
+
+    def initialize(key)
+      @key = key
+      super
+    end
+
+    def message
+      "Key not found in Redis: #{key}"
+    end
+  end
 end

data/lib/familia/features/expiration.rb

@@ -49,7 +49,7 @@ module Familia::Features
     #   false otherwise.
     #
     # @example Setting an expiration of one day
-    #   object.update_expiration(86400)
+    #   object.update_expiration(ttl: 86400)
     #
     # @note If TTL is set to zero, the expiration will be removed, making the
     #   data persist indefinitely.
@@ -57,8 +57,19 @@ module Familia::Features
     # @raise [Familia::Problem] Raises an error if the TTL is not a non-negative
     #   integer.
     #
-  def update_expiration(ttl = nil)
+    def update_expiration(ttl: nil)
       ttl ||= self.ttl
+
+      if self.class.has_relations?
+        Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.redis_types.keys}"
+        self.class.redis_types.each do |name, definition|
+          next if definition.opts[:ttl].nil?
+          obj = send(name)
+          Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.rediskey}) to #{ttl}"
+          obj.update_expiration(ttl: ttl)
+        end
+      end
+
       # It's important to raise exceptions here and not just log warnings. We
       # don't want to silently fail at setting expirations and cause data
       # retention issues (e.g. not removed in a timely fashion).

data/lib/familia/features/quantization.rb

@@ -46,7 +46,7 @@ module Familia::Features
     end
 
     def qstamp(quantum = nil, pattern: nil, time: nil)
-      self.class.qstamp(quantum || ttl, pattern: pattern, time: time)
+      self.class.qstamp(quantum || self.class.ttl, pattern: pattern, time: time)
     end
 
     extend ClassMethods

data/lib/familia/horreum/class_methods.rb

@@ -33,9 +33,6 @@ module Familia
       include Familia::Settings
       include Familia::Horreum::RelationsManagement
 
-      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
@@ -156,7 +153,7 @@ module Familia
             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)
+            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.
@@ -196,6 +193,10 @@ module Familia
         @redis_types
       end
 
+      def has_relations?
+        @has_relations ||= false
+      end
+
       def db(v = nil)
         @db = v unless v.nil?
         @db || parent&.db
@@ -209,16 +210,20 @@ module Familia
       def all(suffix = nil)
         suffix ||= self.suffix
         # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| from_rediskey(k) }
+        keys(suffix).filter_map { |k| find_by_key(k) }
       end
 
       def any?(filter = '*')
-        size(filter) > 0
+        matching_keys_count(filter) > 0
       end
 
-      def size(filter = '*')
+      # Returns the number of Redis keys matching the given filter pattern
+      # @param filter [String] Redis key pattern to match (default: '*')
+      # @return [Integer] Number of matching keys
+      def matching_keys_count(filter = '*')
         redis.keys(rediskey(filter)).compact.size
       end
+      alias size matching_keys_count # For backwards compatibility
 
       def suffix(a = nil, &blk)
         @suffix = a || blk if a || !blk.nil?
@@ -312,17 +317,17 @@ module Familia
       # debugging.
       #
       # @example
-      #   User.from_rediskey("user:123")  # Returns a User instance if it exists,
+      #   User.find_by_key("user:123")  # Returns a User instance if it exists,
       #   nil otherwise
       #
-      def from_rediskey(objkey)
+      def find_by_key(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_rediskey] #{self} from key #{objkey} (exists: #{does_exist})"
+        Familia.ld "[.find_by_key] #{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
@@ -337,6 +342,7 @@ module Familia
 
         new(**obj)
       end
+      alias from_rediskey find_by_key # deprecated
 
       # Retrieves and instantiates an object from Redis using its identifier.
       #
@@ -347,7 +353,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_rediskey` for the actual retrieval and
+      # and suffix, then delegates to `find_by_key` for the actual retrieval and
       # instantiation.
       #
       # It's a higher-level method that abstracts away the key construction,
@@ -355,19 +361,21 @@ module Familia
       # identifier.
       #
       # @example
-      #   User.from_identifier(123)  # Equivalent to User.from_rediskey("user:123:object")
+      #   User.find_by_id(123)  # Equivalent to User.find_by_key("user:123:object")
       #
-      def from_identifier(identifier, suffix = nil)
+      def find_by_id(identifier, suffix = nil)
         suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
         objkey = rediskey(identifier, suffix)
 
-        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
+        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?
+        find_by_key objkey
       end
-      alias load from_identifier
+      alias find find_by_id
+      alias load find_by_id # deprecated
+      alias from_identifier find_by_id # deprecated
 
       # Checks if an object with the given identifier exists in Redis.
       #
@@ -399,8 +407,10 @@ module Familia
       # @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.
+      # 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
+      # ORM-style operations. Use `destroy!` when removing complete objects from the system, and
+      # `delete!` when working directly with Redis keys.
       #
       # @example
       #   User.destroy!(123)  # Removes user:123:object from Redis
@@ -412,7 +422,7 @@ module Familia
         objkey = rediskey identifier, suffix
 
         ret = redis.del objkey
-        Familia.trace :DELETED, redis, "#{objkey}: #{ret.inspect}", caller(1..1) if Familia.debug?
+        Familia.trace :DESTROY!, redis, "#{objkey} #{ret.inspect}", caller(1..1) if Familia.debug?
         ret.positive?
       end
 
@@ -428,7 +438,7 @@ module Familia
       #   User.find  # Returns all keys matching user:*:object
       #   User.find('active')  # Returns all keys matching user:*:active
       #
-      def find(suffix = '*')
+      def find_keys(suffix = '*')
         redis.keys(rediskey('*', suffix)) || []
       end
 

data/lib/familia/horreum/commands.rb

@@ -18,11 +18,39 @@ module Familia
     #
     module Commands
 
-      def exists?
-        # Trace output comes from the class method
-        self.class.exists? identifier, suffix
+      def move(db)
+        redis.move rediskey, db
       end
 
+      # Checks if the calling object's key exists in Redis.
+      #
+      # @param check_size [Boolean] When true (default), also verifies the hash has a non-zero size.
+      #   When false, only checks key existence regardless of content.
+      # @return [Boolean] Returns `true` if the key exists in Redis. When `check_size` is true,
+      #   also requires the hash to have at least one field.
+      #
+      # @example Check existence with size validation (default behavior)
+      #   some_object.exists?                    # => false for empty hashes
+      #   some_object.exists?(check_size: true)  # => false for empty hashes
+      #
+      # @example Check existence only
+      #   some_object.exists?(check_size: false)  # => true for empty hashes
+      #
+      # @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)
+        return key_exists unless check_size
+        key_exists && !size.zero?
+      end
+
+      # Returns the number of fields in the main object hash
+      # @return [Integer] number of fields
+      def field_count
+        redis.hlen rediskey
+      end
+      alias size field_count
+
       # 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.
@@ -33,20 +61,27 @@ module Familia
         redis.expire rediskey, ttl.to_i
       end
 
+      # Retrieves the remaining time to live (TTL) for the object's Redis key.
+      #
+      # This method accesses the ovjects Redis client to obtain the TTL of `rediskey`.
+      # 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
       end
 
-      # Deletes a field from the hash stored at the Redis key.
+      # Removes a field from the hash stored at the Redis key.
       #
-      # @param field [String] The field to delete from the hash.
+      # @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).
-      # @note This method is destructive, as indicated by the bang (!).
-      def hdel!(field)
+      def remove_field(field)
         Familia.trace :HDEL, redis, field, caller(1..1) if Familia.debug?
         redis.hdel rediskey, field
       end
+      alias remove remove_field # deprecated
 
       def redistype
         Familia.trace :REDISTYPE, redis, redisuri, caller(1..1) if Familia.debug?
@@ -59,6 +94,15 @@ module Familia
         redis.rename rediskey, newkey
       end
 
+      # Retrieves the prefix for the current instance by delegating to its class.
+      #
+      # @return [String] The prefix associated with the class of the current instance.
+      # @example
+      #   instance.prefix
+      def prefix
+        self.class.prefix
+      end
+
       # For parity with RedisType#hgetall
       def hgetall
         Familia.trace :HGETALL, redis, redisuri, caller(1..1) if Familia.debug?
@@ -78,8 +122,10 @@ module Familia
         redis.hset rediskey, field, value
       end
 
-      def hmset
-        redis.hmset rediskey(suffix), self.to_h
+      def hmset(hsh={})
+        hsh ||= self.to_h
+        Familia.trace :HMSET, redis, hsh, caller(1..1) if Familia.debug?
+        redis.hmset rediskey(suffix), hsh
       end
 
       def hkeys
@@ -116,11 +162,6 @@ module Familia
       end
       alias decrement decr
 
-      def hlen
-        redis.hlen rediskey(suffix)
-      end
-      alias hlength hlen
-
       def hstrlen(field)
         redis.hstrlen rediskey(suffix), field
       end
@@ -131,12 +172,14 @@ module Familia
       end
       alias has_key? key?
 
+      # Deletes the entire Redis key
+      # @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
         ret.positive?
       end
-      protected :delete!
+      alias clear delete!
 
     end
 

data/lib/familia/horreum/relations_management.rb

@@ -16,6 +16,10 @@ module Familia
     #   Call setup_relations_accessors to initialize the feature
     #
     module RelationsManagement
+      # 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
+
       def self.included(base)
         base.extend(ClassMethods)
         base.setup_relations_accessors
@@ -31,14 +35,17 @@ module Familia
 
             # Dynamically define instance-level relation methods
             #
-            # Once defined, these methods can be used at the class-level of a
+            # 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).
             #
             define_method :"#{kind}" do |*args|
               name, opts = *args
+
+              # 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
-              redis_types[name.to_s.to_sym]
             end
             define_method :"#{kind}?" do |name|
               obj = redis_types[name.to_s.to_sym]