Merge pull request #27 from delano/26-rc3-feedback-collection-and-issue-resolution-for-rc4-prep

Naming and Documentation Improvements, and Minor Functional Adjustments

Author: delano

README.md

@@ -1,84 +1,234 @@
-# Familia - 1.0.0-rc2 (August 2024)
+# Familia - 1.0.0-rc4 (August 2024)
 
-**Organize and store ruby objects in Redis. A Ruby ORM for Redis.**
+**Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) 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.
+Familia provides a flexible and feature-rich way to interact with Redis using Ruby objects. It's designed to make working with Redis as natural as working with Ruby classes, while offering advanced features for complex data management.
 
 ## Installation
 
+
 Get it in one of the following ways:
 
-* In your Gemfile: `gem 'familia', '>= 1.0.0-rc2'`
-* Install it by hand: `gem install familia`
+* In your Gemfile: `gem 'familia', '>= 1.0.0-rc4'`
+* Install it by hand: `gem install familia --pre`
 * Or for development: `git clone [email protected]:delano/familia.git`
 
-## Basic Example
+
+## Core Concepts and Features
+
+### 1. Defining Horreum Classes
+
+Familia uses the concept of "Horreum" classes to represent Redis-backed objects:
 
 ```ruby
 class Flower < Familia::Horreum
-  identifier :generate_id
-  field   :token
-  field   :name
-  list    :owners
-  set     :tags
-  zset    :metrics
+  identifier :token
+  field :name
+  list :owners
+  set :tags
+  zset :metrics
   hashkey :props
-  string  :counter
+  string :counter
+end
+```
+
+### 2. Flexible Identifiers
+
+You can define identifiers in various ways:
+
+```ruby
+class User < Familia::Horreum
+  identifier :email
+  # or
+  identifier -> (user) { "user:#{user.email}" }
+  # or
+  identifier [:type, :email]
+
+  field :email
+  field :type
+end
+```
+
+### 3. Redis Data Types
+
+Familia supports various Redis data types:
+
+```ruby
+class Product < Familia::Horreum
+  string :name
+  list :categories
+  set :tags
+  zset :ratings
+  hashkey :attributes
+end
+```
+
+### 4. Class-level Redis Types
+
+You can also define Redis types at the class level:
+
+```ruby
+class Customer < Familia::Horreum
+  class_sorted_set :values, key: 'project:customers'
+  class_hashkey :projects
+  class_list :customers, suffix: []
+  class_string :message
+end
+```
+
+### 5. Automatic Expiration
+
+Use the expiration feature to set TTL for objects:
+
+```ruby
+class Session < Familia::Horreum
+  feature :expiration
+  ttl 180.minutes
+end
+```
+
+### 6. Safe Dumping for APIs
+
+Control which fields are exposed when serializing objects:
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump
+
+  @safe_dump_fields = [
+    :id,
+    :username,
+    {full_name: ->(user) { "#{user.first_name} #{user.last_name}" }}
+  ]
+end
+```
+
+### 7. Quantization for Time-based Data
+
+Use quantization for time-based metrics:
+
+```ruby
+class DailyMetric < Familia::Horreum
+  feature :quantization
+  string :counter, ttl: 1.day, quantize: [10.minutes, '%H:%M']
 end
 ```
 
-## What Familia::Horreum Can Do
+### 8. Custom Methods and Logic
 
-Familia::Horreum provides a powerful abstraction layer over Redis, allowing you to:
+Add custom methods to your Horreum classes:
 
-1. **Define Redis-backed Ruby Classes**: As shown in the example, you can easily define classes that map to Redis structures.
+```ruby
+class User < Familia::Horreum
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+
+  def active?
+    status == 'active'
+  end
+end
+```
 
-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
+### 9. Custom Methods and Logic
 
-3. **Custom Identifiers**: Use the `identifier` method to specify how objects are uniquely identified in Redis.
+You can add custom methods to your Horreum classes:
 
-4. **Automatic Serialization**: Familia handles the serialization and deserialization of your objects to and from Redis.
+```ruby
+class Customer < Familia::Horreum
+  def active?
+    verified && !reset_requested
+  end
+end
 
-5. **Redis Commands as Ruby Methods**: Interact with Redis using familiar Ruby syntax instead of raw Redis commands.
+class Session < Familia::Horreum
+  def external_identifier
+    elements = [ipaddress || 'UNKNOWNIP', custid || 'anon']
+    @external_identifier ||= Familia.generate_sha_hash(elements)
+  end
+end
+```
+### 10. Open-ended Serialization
 
-6. **TTL Support**: Set expiration times for your objects in Redis.
+```ruby
+class ComplexObject < Familia::Horreum
+  def to_redis
+    custom_serialization_method
+  end
+
+  def self.from_redis(data)
+    custom_deserialization_method(data)
+  end
+end
+```
 
-7. **Flexible Configuration**: Configure Redis connection details, serialization methods, and more.
+### 11. Transactional Operations
+
+```ruby
+user.transaction do |conn|
+  conn.set("user:#{user.id}:status", "active")
+  conn.zadd("active_users", Time.now.to_i, user.id)
+end
+```
 
-## 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 Examples
 
-## Usage Example
+### Creating and Saving Objects
 
 ```ruby
-# Create a new Flower
-rose = Flower.new
-rose.name = "Red Rose"
-rose.tags << "romantic" << "red"
-rose.owners.push("Alice", "Bob")
+flower = Flower.create(name: "Red Rose", token: "rrose")
+flower.owners.push("Alice", "Bob")
+flower.tags.add("romantic")
+flower.metrics.increment("views", 1)
+flower.props[:color] = "red"
+flower.save
+```
+
+### Retrieving and Updating Objects
+
+```ruby
+rose = Flower.from_identifier("rrose")
+rose.name = "Pink Rose"
 rose.save
+```
+
+### Using Safe Dump
+
+```ruby
+user = User.create(username: "rosedog", first_name: "Rose", last_name: "Dog")
+user.safe_dump
+# => {id: "user:rosedog", username: "rosedog", full_name: "Rose Dog"}
+```
+
+### Working with Time-based Data
+
+```ruby
+metric = DailyMetric.new
+metric.counter.increment  # Increments the counter for the current hour
+```
+
+### Bulk Operations
 
-# Retrieve a Flower
-retrieved_rose = Flower.get(rose.identifier)
-puts retrieved_rose.name  # => "Red Rose"
-puts retrieved_rose.tags.members  # => ["romantic", "red"]
+```ruby
+Flower.multiget("rrose", "tulip", "daisy")
+```
+
+### Transactional Operations
+
+```ruby
+user.transaction do |conn|
+  conn.set("user:#{user.id}:status", "active")
+  conn.zadd("active_users", Time.now.to_i, user.id)
+end
 ```
 
-## More Information
+## Conclusion
 
-* [Github](https://github.com/delano/familia)
-* [Rubygems](https://rubygems.org/gems/familia)
+Familia provides a powerful and flexible way to work with Redis in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
 
-## Contributing
+For more information, visit:
+- [Github Repository](https://github.com/delano/familia)
+- [RubyGems Page](https://rubygems.org/gems/familia)
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Feel free to submit a Pull Request.

VERSION.yml

@@ -2,4 +2,4 @@
 :MAJOR: 1
 :MINOR: 0
 :PATCH: 0
-:PRE: rc2
+:PRE: rc4

lib/familia/base.rb

@@ -24,10 +24,38 @@ class << self
 
       def add_feature(klass, methname)
         @features ||= {}
-        Familia.ld "[#{self}] Adding feature #{klass} as #{methname}"
+        Familia.ld "[#{self}] Adding feature #{klass} as #{methname.inspect}"
 
         features[methname] = klass
       end
     end
+
+    # Yo, this class is like that one friend who never checks expiration dates.
+    # It's living life on the edge, data-style!
+    #
+    # @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.
+    #
+    # @return [nil] Always returns nil. It's consistent in its laziness!
+    #
+    # @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 method is a no-op. It's like shouting into the void, but less echo-y.
+    #
+    def update_expiration(_ = nil)
+      Familia.info "[update_expiration] Skipped for #{rediskey}. #{self.class} data is immortal!"
+      nil
+    end
+
+    def generate_id
+      @key ||= Familia.generate_id
+      @key
+    end
+
+    def uuid
+      @uuid ||= SecureRandom.uuid
+      @uuid
+    end
   end
 end

lib/familia/features.rb

@@ -2,17 +2,14 @@
 
 module Familia
 
-  @features_enabled = nil
-
   module Features
 
+    @features_enabled = nil
     attr_reader :features_enabled
 
     def feature(val = nil)
       @features_enabled ||= []
 
-      Familia.ld "[Familia::Settings] feature: #{val.inspect}"
-
       # If there's a value provied check that it's a valid feature
       if val
         val = val.to_sym
@@ -24,6 +21,8 @@ def feature(val = nil)
           return
         end
 
+        Familia.trace :FEATURE, nil, "#{self} includes #{val.inspect}", caller(1..1) if Familia.debug?
+
         klass = Familia::Base.features[val]
 
         # Extend the Familia::Base subclass (e.g. Customer) with the feature module
@@ -48,4 +47,6 @@ def feature(val = nil)
 
 end
 
+require_relative 'features/expiration'
+require_relative 'features/quantization'
 require_relative 'features/safe_dump'