familia 1.0.0.pre.rc1 → 1.0.0.pre.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcefc7fe4a1a64cc584d629612f752ecb1eca753ab39245217f017a03b71075e
-  data.tar.gz: 8a2d0313578fe9acf743537efaee95e8167eabab98474a2a821222696641b567
+  metadata.gz: b4f3c02cad65603669b086ec26f31512004e939da510fec97fcc3803f132e5f5
+  data.tar.gz: cdd710ea75ff3c6ce3ccb88caef97226ee9fb549435fce605433621a8583f06d
 SHA512:
-  metadata.gz: 3f5e8755442f3766515caf445e78888fa26a1b66910bd04228d2fee24988ffa1b380ea5aeedde02a5c545e74d58fee5e273801e7c3f5cc18e873093f383da42a
-  data.tar.gz: 39d8c525f39c123982a150dc62e1cfd302b602086068ea7e694061bc889ab040e1765af5177e23fb9db5b408e2f4ec6f0b5d4ddf165d6ead6dce929a927a61d1
+  metadata.gz: '058e49695798298238523d571a4d21b47234874b47af018fdb085d22a430fa8db2ca725cb3103e0c8eee309b000eea7598cc4e9aed00373191d393af8d4ab27d'
+  data.tar.gz: 9ff11c6c341d540e69ddb9d0518b67c9463b2248899b6f74a94a92b609140ed064e303e3559a455847727d5f7581aa41fccce5fdaac5effb5d74a30202e75721

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: rc2

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
 
@@ -54,6 +53,19 @@ module Familia
       def field(name)
         fields << name
         attr_accessor name
+
+        # Every field gets a fast writer method for immediately persisting
+        fast_writer! name
+      end
+
+      # @return The return value from redis client for hset command
+      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
+        end
       end
 
       # Returns the list of field names defined for the class in the order
@@ -81,11 +93,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 +152,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 +188,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 +237,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 +287,6 @@ module Familia
         @load_method || :from_json # Familia.load_method
       end
     end
+    # End of ClassMethods module
   end
 end

data/lib/familia/horreum/commands.rb

@@ -36,13 +36,60 @@ module Familia
         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 hincrby(field, increment)
+        redis.hincrby rediskey(suffix), field, increment
+      end
+
+      def hincrbyfloat(field, increment)
+        redis.hincrbyfloat rediskey(suffix), field, increment
+      end
+
+      def hlen
+        redis.hlen rediskey(suffix)
+      end
+
+      def hstrlen(field)
+        redis.hstrlen rediskey(suffix), field
       end
 
       def delete!

data/lib/familia/horreum/serialization.rb

@@ -10,6 +10,12 @@ module Familia
 
     # Methods that call load and dump (InstanceMethods)
     #
+    # Note on refresh methods:
+    # In this class, refresh! is the primary method that performs the Redis
+    # query and state update. The non-bang refresh method is provided as a
+    # convenience for method chaining, but still performs the same destructive
+    # update as refresh!. This deviates from common Ruby conventions to better
+    # fit the specific needs of this system.
     module Serialization
       #include Familia::RedisType::Serialization
 
@@ -38,8 +44,9 @@ module Familia
         Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
 
         # Update timestamp fields
+        self.key ||= self.identifier
         self.updated = Familia.now.to_i
-        self.created = Familia.now.to_i unless self.created
+        self.created ||= Familia.now.to_i
 
         # Thr return value of commit_fields is an array of strings: ["OK"].
         ret = commit_fields # e.g. ["OK"]
@@ -64,12 +71,39 @@ 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.
+      #
+      # @note This is a destructive operation that will overwrite any unsaved
+      #   changes.
+      # @return The list of field names that were updated.
+      def refresh!
+        Familia.trace :REFRESH, redis, redisuri, caller(1..1) if Familia.debug?
+        fields = hgetall
+        Familia.ld "[refresh!] #{self.class} #{rediskey} #{fields.keys}"
+        optimistic_refresh(**fields)
+      end
+
+      # Refreshes the object's state and returns self to allow method chaining.
+      # This method calls refresh! internally, performing the actual Redis
+      # query and state update.
+      #
+      # @note While this method allows chaining, it still performs a
+      #   destructive update like refresh!.
+      # @return [self] Returns the object itself after refreshing, allowing
+      #   method chaining.
+      def refresh
+        refresh!
+        self
+      end
+
       def to_h
         # Use self.class.fields to efficiently generate a hash
         # of all the fields for this object
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
-          prepared = val.to_s
+          prepared = to_redis(val)
           Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
           hsh[field] = prepared
           hsh
@@ -79,13 +113,14 @@ module Familia
       def to_a
         self.class.fields.map do |field|
           val = send(field)
-          Familia.ld " [to_a] field: #{field} val: #{val}"
-          to_redis(val)
+          prepared = to_redis(val)
+          Familia.ld " [to_a] field: #{field} val: #{val.class} prepared: #{prepared.class}"
+          prepared
         end
       end
 
-      # The to_redis method in Familia::Redistype and Familia::Horreum serve similar purposes
-      # but have some key differences in their implementation:
+      # The to_redis method in Familia::Redistype and Familia::Horreum serve
+      # similar purposes but have some key differences in their implementation:
       #
       # Similarities:
       # - Both methods aim to serialize various data types for Redis storage
@@ -97,16 +132,19 @@ module Familia
       # - Familia::Horreum had more explicit type checking and conversion
       # - Familia::Redistype includes more extensive debug tracing
       #
-      # The centralized Familia.distinguisher method accommodates both approaches by:
-      # 1. Handling a wide range of data types, including those from both implementations
+      # The centralized Familia.distinguisher method accommodates both approaches
+      # by:
+      # 1. Handling a wide range of data types, including those from both
+      #    implementations
       # 2. Providing a 'strict_values' option for flexible type handling
       # 3. Supporting custom serialization through a dump_method
       # 4. Including debug tracing similar to Familia::Redistype
       #
-      # By using Familia.distinguisher, we achieve more consistent behavior across
-      # different parts of the library while maintaining the flexibility to handle
-      # various data types and custom serialization needs. This centralization
-      # also makes it easier to extend or modify serialization behavior in the future.
+      # By using Familia.distinguisher, we achieve more consistent behavior
+      # across different parts of the library while maintaining the flexibility
+      # to handle various data types and custom serialization needs. This
+      # centralization also makes it easier to extend or modify serialization
+      # behavior in the future.
       #
       def to_redis(val)
         prepared = Familia.distinguisher(val, false)
@@ -115,7 +153,10 @@ module Familia
           prepared = val.send(dump_method)
         end
 
-        Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}" if prepared.nil?
+        if prepared.nil?
+          Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}"
+        end
+
         prepared
       end
 
@@ -127,6 +168,7 @@ module Familia
         expire ttl.to_i
       end
     end
+    # End of Serialization module
 
     include Serialization # these become Horreum instance methods
   end
@@ -134,21 +176,18 @@ end
 
 __END__
 
-
-
-# From RedisHash
-def save
-  hsh = { :key => identifier }
-  ret = commit_fields hsh
-  ret == "OK"
-end
-
-def update_fields hsh={}
-  check_identifier!
-  hsh[:updated] = OT.now.to_i
-  hsh[:created] = OT.now.to_i unless has_key?(:created)
-  ret = update hsh  # update is defined in HashKey
-  ## NOTE: caching here like this only works if hsh has all keys
-  #self.cache.replace hsh
-  ret
+# Consider adding a retry mechanism for the refresh operation
+# if it fails to fetch the expected data:
+def refresh_with_retry(max_attempts = 3)
+  attempts = 0
+  base = 2
+  while attempts < max_attempts
+    refresh!
+    return if name == "Jane Doe" # Or whatever condition indicates a successful refresh
+    attempts += 1
+
+    sleep_time = 0.1 * (base ** attempts)
+    sleep(sleep_time) # Exponential backoff
+  end
+  raise "Failed to refresh after #{max_attempts} attempts"
 end

data/lib/familia/horreum/utils.rb

@@ -27,9 +27,10 @@ module Familia
       # Whether this is a Horreum or RedisType object, the value is taken
       # from the `identifier` method).
       #
-      def rediskey(suffix = self.suffix, ignored = nil)
+      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
       end
 

data/lib/familia/horreum.rb

@@ -94,6 +94,15 @@ module Familia
         # end
       end
 
+      # Automatically add a 'key' field if it's not already defined
+      # This ensures that every object has a unique identifier
+      unless self.class.fields.include?(:key)
+        # Define the 'key' field for this class
+        # This approach allows flexibility in how identifiers are generated
+        # while ensuring each object has a consistent way to be referenced
+        self.class.field :key # , default: -> { identifier }
+      end
+
       # Implementing classes can define an init method to do any
       # additional initialization. Notice that this is called
       # after the fields are set.
@@ -145,23 +154,64 @@ module Familia
       end
     end
 
+    # Initializes the object with positional arguments.
+    # Maps each argument to a corresponding field in the order they are defined.
+    #
+    # @param args [Array] List of values to be assigned to fields
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
     def initialize_with_positional_args(*args)
-      self.class.fields.zip(args).each do |field, value|
-        send(:"#{field}=", value) if value
+      Familia.trace :INITIALIZE_ARGS, redis, args, caller(1..1) if Familia.debug?
+      self.class.fields.zip(args).filter_map do |field, value|
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
       end
     end
     private :initialize_with_positional_args
 
-    def initialize_with_keyword_args(**kwargs)
-      self.class.fields.each do |field|
+    # Initializes the object with keyword arguments.
+    # Assigns values to fields based on the provided hash of field names and values.
+    # Handles both symbol and string keys to accommodate different sources of data.
+    #
+    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_keyword_args(**fields)
+      Familia.trace :INITIALIZE_KWARGS, redis, fields.keys, caller(1..1) if Familia.debug?
+      self.class.fields.filter_map do |field|
         # Redis will give us field names as strings back, but internally
-        # we use symbols. So we do both.
-        value = kwargs[field.to_sym] || kwargs[field.to_s]
-        send(:"#{field}=", value) if value
+        # we use symbols. So we check for both.
+        value = fields[field.to_sym] || fields[field.to_s]
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
       end
     end
     private :initialize_with_keyword_args
 
+    # A thin wrapper around the private initialize method that accepts a field
+    # hash and refreshes the existing object.
+    #
+    # This method is part of horreum.rb rather than serialization.rb because it
+    # operates solely on the provided values and doesn't query Redis or other
+    # external sources. That's why it's called "optimistic" refresh: it assumes
+    # the provided values are correct and updates the object accordingly.
+    #
+    # @see #refresh!
+    #
+    # @param fields [Hash] A hash of field names and their new values to update
+    #   the object with.
+    # @return [Array] The list of field names that were updated.
+    def optimistic_refresh(**fields)
+      Familia.ld "[optimistic_refresh] #{self.class} #{rediskey} #{fields.keys}"
+      initialize_with_keyword_args(**fields)
+    end
+
     # Determines the unique identifier for the instance
     # This method is used to generate Redis keys for the object
     def identifier
@@ -183,7 +233,7 @@ module Familia
                   end
 
       # If the unique_id is nil, raise an error
-      raise Problem, "Identifier is nil for #{self}" if unique_id.nil?
+      raise Problem, "Identifier is nil for #{self.class}" if unique_id.nil?
       raise Problem, 'Identifier is empty' if unique_id.empty?
 
       unique_id

data/lib/familia/logging.rb

@@ -3,23 +3,6 @@
 require 'pathname'
 require 'logger'
 
-module LoggerTraceRefinement
-  # Set to same value as Logger::DEBUG since 0 is the floor
-  # without either more invasive changes to the Logger class
-  # or a CustomLogger class that inherits from Logger.
-  TRACE = 2 unless defined?(TRACE)
-  refine Logger do
-
-    def trace(progname = nil, &block)
-      Thread.current[:severity_letter] = 'T'
-      add(LoggerTraceRefinement::TRACE, nil, progname, &block)
-    ensure
-      Thread.current[:severity_letter] = nil
-    end
-
-  end
-end
-
 module Familia
   @logger = Logger.new($stdout)
   @logger.progname = name
@@ -38,7 +21,7 @@ module Familia
     # variable `severity_letter` is arbitrary and could be anything.
     severity_letter = Thread.current[:severity_letter] || severity_letter
 
-    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  <#{relative_path}:#{line}>\n"
+    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  [#{relative_path}:#{line}]\n"
   end
 
   # The Logging module provides a set of methods and constants for logging messages
@@ -120,7 +103,7 @@ module Familia
     attr_reader :logger
 
     # Gives our logger the ability to use our trace method.
-    #using LoggerTraceRefinement if Familia.debug
+    using LoggerTraceRefinement if LoggerTraceRefinement::ENABLED
 
     def info(*msg)
       @logger.info(*msg)
@@ -156,14 +139,14 @@ module Familia
     # @return [nil]
     #
     def trace(label, redis_instance, ident, context = nil)
-      return unless Familia.debug? && ENV.key?('FAMILIA_TRACE')
+      return unless LoggerTraceRefinement::ENABLED
       instance_id = redis_instance&.id
       codeline = if context
                    context = [context].flatten
                    context.reject! { |line| line =~ %r{lib/familia} }
                    context.first
                  end
-      @logger.debug format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
+      @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
 
   end

data/lib/familia/redistype.rb

@@ -61,10 +61,10 @@ module Familia
       end
     end
 
-    attr_reader :name, :parent, :opts
+    attr_reader :keystring, :parent, :opts
     attr_writer :dump_method, :load_method
 
-    # +name+: If parent is set, this will be used as the suffix
+    # +keystring+: If parent is set, this will be used as the suffix
     # for rediskey. Otherwise this becomes the value of the key.
     # If this is an Array, the elements will be joined.
     #
@@ -92,10 +92,10 @@ module Familia
     #
     # Uses the redis connection of the parent or the value of
     # opts[:redis] or Familia.redis (in that order).
-    def initialize(name, opts = {})
+    def initialize(keystring, opts = {})
       #Familia.ld " [initializing] #{self.class} #{opts}"
-      @name = name
-      @name = @name.join(Familia.delim) if @name.is_a?(Array)
+      @keystring = keystring
+      @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
 
       # Remove all keys from the opts that are not in the allowed list
       @opts = opts || {}
@@ -112,7 +112,7 @@ module Familia
 
     # Produces the full redis key for this object.
     def rediskey
-      Familia.ld "[rediskey] #{name} for #{self.class} (#{opts})"
+      Familia.ld "[rediskey] #{keystring} for #{self.class} (#{opts})"
 
       # Return the hardcoded key if it's set. This is useful for
       # support legacy keys that aren't derived in the same way.
@@ -121,15 +121,15 @@ module Familia
       if parent_instance?
         # This is an instance-level redistype object so the parent instance's
         # rediskey method is defined in Familia::Horreum::InstanceMethods.
-        parent.rediskey(name)
+        parent.rediskey(keystring)
       elsif parent_class?
         # This is a class-level redistype object so the parent class' rediskey
         # method is defined in Familia::Horreum::ClassMethods.
-        parent.rediskey(name, nil)
+        parent.rediskey(keystring, nil)
       else
-        # This is a standalone RedisType object where it's name
+        # This is a standalone RedisType object where it's keystring
         # is the full key.
-        name
+        keystring
       end
     end
 

data/lib/familia/refinements.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'logger'
+
+# Controls whether tracing is enabled via an environment variable
+FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
+
+# FlexibleHashAccess
+#
+# This module provides a refinement for the Hash class to allow flexible access
+# to hash keys using either strings or symbols interchangeably for reading values.
+#
+# Note: This refinement only affects reading from the hash. Writing to the hash
+# maintains the original key type.
+#
+# @example Using the refinement
+#   using FlexibleHashAccess
+#
+#   h = { name: "Alice", "age" => 30 }
+#   h[:name]   # => "Alice"
+#   h["name"]  # => "Alice"
+#   h[:age]    # => 30
+#   h["age"]   # => 30
+#
+#   h["job"] = "Developer"
+#   h[:job]    # => "Developer"
+#   h["job"]   # => "Developer"
+#
+#   h[:salary] = 75000
+#   h[:salary] # => 75000
+#   h["salary"] # => nil (original key type is preserved)
+#
+module FlexibleHashAccess
+  refine Hash do
+    ##
+    # Retrieves a value from the hash using either a string or symbol key.
+    #
+    # @param key [String, Symbol] The key to look up
+    # @return [Object, nil] The value associated with the key, or nil if not found
+    def [](key)
+      super(key.to_s) || super(key.to_sym)
+    end
+  end
+end
+
+# LoggerTraceRefinement
+#
+# This module adds a 'trace' log level to the Ruby Logger class.
+# It is enabled when the FAMILIA_TRACE environment variable is set to
+# '1', 'true', or 'yes' (case-insensitive).
+#
+# @example Enabling trace logging
+#   # Set environment variable
+#   ENV['FAMILIA_TRACE'] = 'true'
+#
+#   # In your Ruby code
+#   require 'logger'
+#   using LoggerTraceRefinement
+#
+#   logger = Logger.new(STDOUT)
+#   logger.trace("This is a trace message")
+#
+module LoggerTraceRefinement
+  # Indicates whether trace logging is enabled
+  ENABLED = %w[1 true yes].include?(FAMILIA_TRACE)
+
+  # The numeric level for trace logging (same as DEBUG)
+  TRACE = 0 unless defined?(TRACE)
+
+  refine Logger do
+    ##
+    # Logs a message at the TRACE level.
+    #
+    # @param progname [String] The program name to include in the log message
+    # @yield A block that evaluates to the message to log
+    # @return [true] Always returns true
+    #
+    # @example Logging a trace message
+    #   logger.trace("MyApp") { "Detailed trace information" }
+    def trace(progname = nil, &block)
+      Thread.current[:severity_letter] = 'T'
+      add(LoggerTraceRefinement::TRACE, nil, progname, &block)
+    ensure
+      Thread.current[:severity_letter] = nil
+    end
+  end
+end

data/lib/familia/types/hashkey.rb

@@ -53,13 +53,12 @@ module Familia
       multi_from_redis(*el)
     end
 
-    def all
+    def hgetall
       # TODO: Use from_redis. Also name `all` is confusing with
       # Onetime::Customer.all which returns all customers.
       redis.hgetall rediskey
     end
-    alias to_hash all
-    alias clone all
+    alias all hgetall
 
     def has_key?(field)
       redis.hexists rediskey, field

data/lib/familia/utils.rb

@@ -64,8 +64,8 @@ module Familia
       Time.at(rounded).utc.strftime(pattern)
     end
 
-    def generate_sha_hash(elements)
-      concatenated_string = Familia.join(elements)
+    def generate_sha_hash(*elements)
+      concatenated_string = Familia.join(*elements)
       DIGEST_CLASS.hexdigest(concatenated_string)
     end
 
@@ -113,10 +113,6 @@ module Familia
           Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
           value_to_distinguish.identifier
 
-        elsif dump_method && value_to_distinguish.respond_to?(dump_method)
-          Familia.trace :TOREDIS_DISTINGUISHER, redis, "#{value_to_distinguish.class}##{dump_method}", caller(1..1) if Familia.debug?
-          value_to_distinguish.send(dump_method)
-
         else
           Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
           raise Familia::HighRiskFactor, value_to_distinguish if strict_values

data/lib/familia.rb

@@ -5,6 +5,7 @@ require 'redis'
 require 'uri/redis'
 
 require_relative 'familia/core_ext'
+require_relative 'familia/refinements'
 require_relative 'familia/errors'
 require_relative 'familia/version'
 

data/try/27_redis_horreum_try.rb

@@ -38,3 +38,56 @@ Familia.debug = true
 ## Remove the key
 @hashkey.clear
 #=> 1
+
+## Horreum objects can update and save their fields (1 of 2)
+@customer.name = 'John Doe'
+#=> "John Doe"
+
+## Horreum objects can update and save their fields (2 of 2)
+@customer.save
+#=> true
+
+## Horreum object fields have a fast writer 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)
+@customer.refresh!
+@customer.name
+#=> "Jane Doe"
+
+## Unsaved changes are lost when an object reloads
+@customer.name = 'John Doe'
+@customer.refresh!
+@customer.name
+#=> "Jane Doe"
+
+## Horreum objects can be destroyed
+@customer.destroy!
+#=> true
+
+## All horrerum objects have a key field
+@customer.key
+#=> @identifier
+
+## Even ones that didn't define it
+@cd = CustomDomain.new "www.example.com", "@identifier"
+@cd.key
+#=> nil
+
+## We can call #identifier directly if we want to "lasy load" the unique identifier
+@cd.identifier
+#=> "7565befd"
+
+## The #key field will still be nil
+@cd.key
+#=> nil
+
+## But once we save
+@cd.save
+#=> true
+
+## The key will be set
+@cd.key
+#=> "7565befd"

data/try/test_helpers.rb

@@ -70,6 +70,7 @@ class Customer < Familia::Horreum
   field :email
   field :role
   field :key
+  field :name
   field :passphrase_encryption
   field :passphrase
   field :verified
@@ -154,6 +155,7 @@ class CustomDomain < Familia::Horreum
   field :trd
   field :tld
   field :sld
+  # No :key field (so we can test hte behaviour in Horreum#initialize)
   field :txt_validation_host
   field :txt_validation_value
   field :status
@@ -167,7 +169,11 @@ class CustomDomain < Familia::Horreum
   # the customer ID. This is used to ensure that the same domain can't be
   # added twice by the same customer while avoiding collisions between customers.
   def derive_id
-    Familia.generate_sha_hash(:display_domain, :custid).slice(0, 8)
+    elements = [
+      display_domain,
+      custid
+    ]
+    Familia.generate_sha_hash(*elements).slice(0, 8)
   end
 end
 @d = CustomDomain.new
@@ -178,6 +184,8 @@ class Limiter < Familia::Horreum
 
   identifier :name
   field :name
+  # No :key field (so we can test hte behaviour in Horreum#initialize)
+
   string :counter, :ttl => 1.hour, :quantize => [10.minutes, '%H:%M', 1302468980]
 
   def identifier

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc1
+  version: 1.0.0.pre.rc2
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-15 00:00:00.000000000 Z
+date: 2024-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -97,6 +97,7 @@ files:
 - lib/familia/redistype.rb
 - lib/familia/redistype/commands.rb
 - lib/familia/redistype/serialization.rb
+- lib/familia/refinements.rb
 - lib/familia/settings.rb
 - lib/familia/types/hashkey.rb
 - lib/familia/types/list.rb
@@ -141,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: An ORM for Redis in Ruby.