familia 1.0.0.pre.rc1 → 1.0.0.pre.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcefc7fe4a1a64cc584d629612f752ecb1eca753ab39245217f017a03b71075e
-  data.tar.gz: 8a2d0313578fe9acf743537efaee95e8167eabab98474a2a821222696641b567
+  metadata.gz: c5cdd5bc9ccadb7e69c324e7a2716b378fa5e5fe9938c4ed44a61b23eef99c6a
+  data.tar.gz: de5bb8d9e3b6b09906e777f9a5586eff32a5b1d3ec7c5e51a3a26dac2bd85415
 SHA512:
-  metadata.gz: 3f5e8755442f3766515caf445e78888fa26a1b66910bd04228d2fee24988ffa1b380ea5aeedde02a5c545e74d58fee5e273801e7c3f5cc18e873093f383da42a
-  data.tar.gz: 39d8c525f39c123982a150dc62e1cfd302b602086068ea7e694061bc889ab040e1765af5177e23fb9db5b408e2f4ec6f0b5d4ddf165d6ead6dce929a927a61d1
+  metadata.gz: 76ffa691585dde5c45aaa17e1d02171bacb3fad0267f638b02d7c2cf0a65eaed4d0062656be2496c27ff9bd9788839a71d8475f3e14577ef607684cd179209c1
+  data.tar.gz: 96d52e17f1c3f3092d4ec39ad0fbd1455ef54a902a2f2aaa65c5531d11cdd8b53ee50ef1fa0bd967bd4fa49fd4b0693d89031bcb6decb6cc2def5cb4e1d85c9a

data/Gemfile.lock

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

data/README.md

@@ -1,31 +1,84 @@
-# Familia - 1.0.0-rc1
+# Familia - 1.0.0-rc2 (August 2024)
 
 **Organize and store ruby objects in Redis. A Ruby ORM for Redis.**
 
+Familia provides a powerful and flexible way to interact with Redis using Ruby objects. It's designed to make working with Redis as natural as working with Ruby classes.
+
 ## Installation
 
 Get it in one of the following ways:
 
-* In your Gemfile: `gem 'familia', '>= 1.0.0-rc1'`
+* In your Gemfile: `gem 'familia', '>= 1.0.0-rc2'`
 * Install it by hand: `gem install familia`
 * Or for development: `git clone git@github.com:delano/familia.git`
 
 ## Basic Example
 
 ```ruby
-    class Flower < Familia::Horreum
-      identifier :generate_id
-      field   :token
-      field   :name
-      list    :owners
-      set     :tags
-      zset    :metrics
-      hashkey :props
-      string  :counter
-    end
+class Flower < Familia::Horreum
+  identifier :generate_id
+  field   :token
+  field   :name
+  list    :owners
+  set     :tags
+  zset    :metrics
+  hashkey :props
+  string  :counter
+end
+```
+
+## What Familia::Horreum Can Do
+
+Familia::Horreum provides a powerful abstraction layer over Redis, allowing you to:
+
+1. **Define Redis-backed Ruby Classes**: As shown in the example, you can easily define classes that map to Redis structures.
+
+2. **Use Various Redis Data Types**: Familia supports multiple Redis data types:
+   - `field`: For simple key-value pairs
+   - `list`: For Redis lists
+   - `set`: For Redis sets
+   - `zset`: For Redis sorted sets
+   - `hashkey`: For Redis hashes
+   - `string`: For Redis strings
+
+3. **Custom Identifiers**: Use the `identifier` method to specify how objects are uniquely identified in Redis.
+
+4. **Automatic Serialization**: Familia handles the serialization and deserialization of your objects to and from Redis.
+
+5. **Redis Commands as Ruby Methods**: Interact with Redis using familiar Ruby syntax instead of raw Redis commands.
+
+6. **TTL Support**: Set expiration times for your objects in Redis.
+
+7. **Flexible Configuration**: Configure Redis connection details, serialization methods, and more.
+
+## Advanced Features
+
+- **API Versioning**: Familia supports API versioning to help manage changes in your data model over time.
+- **Custom Serialization**: You can specify custom serialization methods for your objects.
+- **Redis URI Support**: Easily connect to Redis using URI strings.
+- **Debugging Tools**: Built-in debugging capabilities to help troubleshoot Redis interactions.
+
+## Usage Example
+
+```ruby
+# Create a new Flower
+rose = Flower.new
+rose.name = "Red Rose"
+rose.tags << "romantic" << "red"
+rose.owners.push("Alice", "Bob")
+rose.save
+
+# Retrieve a Flower
+retrieved_rose = Flower.get(rose.identifier)
+puts retrieved_rose.name  # => "Red Rose"
+puts retrieved_rose.tags.members  # => ["romantic", "red"]
 ```
 
 ## More Information
 
 * [Github](https://github.com/delano/familia)
 * [Rubygems](https://rubygems.org/gems/familia)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

data/VERSION.yml

@@ -2,4 +2,4 @@
 :MAJOR: 1
 :MINOR: 0
 :PATCH: 0
-:PRE: rc1
+:PRE: rc3

data/lib/familia/features/safe_dump.rb

@@ -12,13 +12,15 @@ module Familia::Features
   # a symbol, the method with the same name will be called on the object to
   # retrieve the value. If the field is a hash, the key is the field name and
   # the value is a lambda that will be called with the object as an argument.
-  # the hash syntax allows you to:
+  # The hash syntax allows you to:
   #   * define a field name that is different from the method name
   #   * define a field that requires some computation on-the-fly
   #   * define a field that is not a method on the object
   #
   # Example:
   #
+  #   feature :safe_dump
+  #
   #   @safe_dump_fields = [
   #     :objid,
   #     :updated,
@@ -26,11 +28,26 @@ module Familia::Features
   #     { :active => ->(obj) { obj.active? } }
   #   ]
   #
-  # Internally, all fields are normalized to the hash syntax and store in
+  # Internally, all fields are normalized to the hash syntax and stored in
   # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
   # of symbols in the order they were defined. From the example above, it would
   # return `[:objid, :updated, :created, :active]`.
   #
+  # Standalone Usage:
+  #
+  # You can also use SafeDump by including it in your model and defining the
+  # safe dump fields using the class instance variable `@safe_dump_fields`.
+  #
+  # Example:
+  #
+  #   class MyModel
+  #     include Familia::Features::SafeDump
+  #
+  #     @safe_dump_fields = [
+  #       :id, :name, { active: ->(obj) { obj.active? } }
+  #     ]
+  #   end
+  #
   module SafeDump
     @dump_method = :to_json
     @load_method = :from_json
@@ -148,6 +165,8 @@ end
 
 __END__
 
+# Some leftovers related to dump_method and load_method
+
 if value_to_distunguish.is_a?(Familia::Horreum)
   Familia.trace :DISTINGUISHER, redis, "horreum", caller(1..1) if Familia.debug?
   value_to_distunguish.identifier

data/lib/familia/horreum/class_methods.rb

@@ -8,15 +8,14 @@ module Familia
     # These are set up as nil initially and populated later
     @redis = nil
     @identifier = nil
-    @fields = nil # []
     @ttl = nil
     @db = nil
     @uri = nil
     @suffix = nil
     @prefix = nil
+    @fields = nil # []
     @class_redis_types = nil # {}
     @redis_types = nil # {}
-    @defined_fields = nil # {}
     @dump_method = nil
     @load_method = nil
 
@@ -37,23 +36,89 @@ 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
+
+        # Every field gets a fast writer method for immediately persisting
+        fast_writer! name
+      end
+
+      # 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 |*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
+
+          value = args.first
+
+          begin
+            # Trace the operation if debugging is enabled.
+            Familia.trace :FAST_WRITER, redis, "#{name}: #{value.inspect}", caller 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
 
       # Returns the list of field names defined for the class in the order
@@ -81,11 +146,6 @@ module Familia
         @redis_types
       end
 
-      def defined_fields
-        @defined_fields ||= {}
-        @defined_fields
-      end
-
       def ttl(v = nil)
         @ttl = v unless v.nil?
         @ttl || parent&.ttl
@@ -145,6 +205,34 @@ module Familia
         redis.mget(*ids)
       end
 
+      # Retrieves and instantiates an object from Redis using the full object
+      # key.
+      #
+      # @param objkey [String] The full Redis key for the object.
+      # @return [Object, nil] An instance of the class if the key exists, nil
+      #   otherwise.
+      # @raise [ArgumentError] If the provided key is empty.
+      #
+      # This method performs a two-step process to safely retrieve and
+      # instantiate objects:
+      #
+      # 1. It first checks if the key exists in Redis. This is crucial because:
+      #    - It provides a definitive answer about the object's existence.
+      #    - It prevents ambiguity that could arise from `hgetall` returning an
+      #      empty hash for non-existent keys, which could lead to the creation
+      #      of "empty" objects.
+      #
+      # 2. If the key exists, it retrieves the object's data and instantiates
+      #    it.
+      #
+      # This approach ensures that we only attempt to instantiate objects that
+      # actually exist in Redis, improving reliability and simplifying
+      # debugging.
+      #
+      # @example
+      #   User.from_key("user:123")  # Returns a User instance if it exists,
+      #   nil otherwise
+      #
       def from_key(objkey)
         raise ArgumentError, 'Empty key' if objkey.to_s.empty?
 
@@ -153,27 +241,46 @@ module Familia
         does_exist = redis.exists(objkey).positive?
 
         Familia.ld "[.from_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :LOAD, redis, objkey, caller if Familia.debug?
+        Familia.trace :FROM_KEY, redis, objkey, caller if Familia.debug?
 
-        # This is reason for calling exists first. We want to definitively and without any
-        # ambiguity know if the object exists in Redis. If it doesn't, we return nil. If
-        # it does, we proceed to load the object. Otherwise, hgetall will return an empty
-        # hash, which will be passed to the constructor, which will then be annoying to
-        # 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
+        # doesn't, we return nil. If it does, we proceed to load the object.
+        # Otherwise, hgetall will return an empty hash, which will be passed to
+        # the constructor, which will then be annoying to debug.
         return unless does_exist
 
         obj = redis.hgetall(objkey) # horreum objects are persisted as redis hashes
-        Familia.trace :HGETALL, redis, "#{objkey}: #{obj.inspect}", caller if Familia.debug?
+        Familia.trace :FROM_KEY2, redis, "#{objkey}: #{obj.inspect}", caller if Familia.debug?
 
         new(**obj)
       end
 
+      # Retrieves and instantiates an object from Redis using its identifier.
+      #
+      # @param identifier [String, Integer] The unique identifier for the
+      #   object.
+      # @param suffix [Symbol] The suffix to use in the Redis key (default:
+      #   :object).
+      # @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
+      # instantiation.
+      #
+      # It's a higher-level method that abstracts away the key construction,
+      # making it easier to retrieve objects when you only have their
+      # identifier.
+      #
+      # @example
+      #   User.from_redis(123)  # Equivalent to User.from_key("user:123:object")
+      #
       def from_redis(identifier, suffix = :object)
         return nil if identifier.to_s.empty?
 
         objkey = rediskey(identifier, suffix)
         Familia.ld "[.from_redis] #{self} from key #{objkey})"
-        Familia.trace :FROMREDIS, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
+        Familia.trace :FROM_REDIS, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
         from_key objkey
       end
 
@@ -183,10 +290,7 @@ module Familia
         objkey = rediskey identifier, suffix
 
         ret = redis.exists objkey
-        if Familia.debug?
-          Familia.trace :EXISTS, redis, "#{objkey} #{ret.inspect}",
-                        caller
-        end
+        Familia.trace :EXISTS, redis, "#{objkey} #{ret.inspect}", caller if Familia.debug?
         ret.positive?
       end
 
@@ -236,5 +340,6 @@ module Familia
         @load_method || :from_json # Familia.load_method
       end
     end
+    # End of ClassMethods module
   end
 end

data/lib/familia/horreum/commands.rb

@@ -20,9 +20,12 @@ module Familia
 
       def exists?
         ret = redis.exists rediskey
-        ret.positive?
+        ret.positive? # differs from redis API but I think it's okay bc `exists?` is a predicate method.
       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
         redis.expire rediskey, ttl.to_i
@@ -32,18 +35,94 @@ module Familia
         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)
         redis.hdel rediskey, field
       end
 
-      def redistype(suffix = nil)
+      def redistype
         redis.type rediskey(suffix)
       end
 
-      def hmset(suffix = nil)
-        suffix ||= self.class.suffix
-        redis.hmset rediskey(suffix), to_h
+      # Parity with RedisType#rename
+      def rename(newkey)
+        redis.rename rediskey, newkey
+      end
+
+      # For parity with RedisType#hgetall
+      def hgetall
+        Familia.trace :HGETALL, redis, redisuri, caller(1..1) if Familia.debug?
+        redis.hgetall rediskey(suffix)
+      end
+      alias all hgetall
+
+      def hget(field)
+        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?
+        redis.hset rediskey, field, value
+      end
+
+      def hmset
+        redis.hmset rediskey(suffix), self.to_h
+      end
+
+      def hkeys
+        Familia.trace :HKEYS, redis, 'redisuri', caller(1..1) if Familia.debug?
+        redis.hkeys rediskey(suffix)
+      end
+
+      def hvals
+        redis.hvals rediskey(suffix)
+      end
+
+      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 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?