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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5cdd5bc9ccadb7e69c324e7a2716b378fa5e5fe9938c4ed44a61b23eef99c6a
-  data.tar.gz: de5bb8d9e3b6b09906e777f9a5586eff32a5b1d3ec7c5e51a3a26dac2bd85415
+  metadata.gz: b514a58bc45692f39123cce853a679078eccd78362a78facc397a1df6d94629d
+  data.tar.gz: d29686d172bec525bee366ab54ad4e81a5903547a9a2d98c68df8ca81853c7dc
 SHA512:
-  metadata.gz: 76ffa691585dde5c45aaa17e1d02171bacb3fad0267f638b02d7c2cf0a65eaed4d0062656be2496c27ff9bd9788839a71d8475f3e14577ef607684cd179209c1
-  data.tar.gz: 96d52e17f1c3f3092d4ec39ad0fbd1455ef54a902a2f2aaa65c5531d11cdd8b53ee50ef1fa0bd967bd4fa49fd4b0693d89031bcb6decb6cc2def5cb4e1d85c9a
+  metadata.gz: cd750e1ee120eb666563e9c8c552f721926ccceaa032cd0cefcf4fad7920225ab1edc4961cf3a5a7c38d81ecab3c21b446e91a75347d51a4bc196c14f5ed94fd
+  data.tar.gz: 6c52919952e7ce8232cf1023fafe567655580a73e4d36dd0a38b8842cb618387272db6950380f71efa01797439d9542303d3addd8c94e841255923998b93589f

data/Gemfile.lock

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

data/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 git@github.com: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.

data/VERSION.yml

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

data/lib/familia/base.rb

@@ -24,10 +24,38 @@ module Familia
 
       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

data/lib/familia/features/expiration.rb

@@ -0,0 +1,90 @@
+# rubocop:disable all
+# frozen_string_literal: true
+
+
+module Familia::Features
+  #
+  module Expiration
+    @ttl = nil
+
+    module ClassMethods
+
+      attr_writer :ttl
+
+      def ttl(v = nil)
+        @ttl = v.to_f unless v.nil?
+        @ttl || parent&.ttl || Familia.ttl
+      end
+
+    end
+
+    def self.included base
+      Familia.ld "[#{base}] Loaded #{self}"
+      base.extend ClassMethods
+
+      # Optionally define ttl in the class to make
+      # sure we always have an array to work with.
+      unless base.instance_variable_defined?(:@ttl)
+        base.instance_variable_set(:@ttl, @ttl) # set above
+      end
+    end
+
+    def ttl=(v)
+      @ttl = v.to_f
+    end
+
+    def ttl
+      @ttl || self.class.ttl
+    end
+
+    # Yo, check it out! We're gonna give our Redis data an expiration date!
+    #
+    # It's like slapping a "Best Before" sticker on your favorite snack,
+    # but for data. How cool is that?
+    #
+    # @param ttl [Integer, nil] The Time To Live in seconds. Nil? No worries!
+    #   We'll dig up the default from our secret stash.
+    #
+    # @return [Boolean] Did Redis pin that expiry note successfully?
+    #   True for "Yep!", false for "Oops, butter fingers!"
+    #
+    # @example Teaching your pet rock the concept of mortality
+    #   rocky.update_expiration(86400) # Dwayne gets to party in Redis for one whole day!
+    #
+    # @note If TTL is zero, your data gets a VIP pass to the Redis eternity club.
+    #   Fancy, huh?
+    #
+    # @raise [Familia::Problem] If you try to feed it non-numbers or time-travel
+    #   (negative numbers). It's strict, but fair!
+    #
+    def update_expiration(ttl = nil)
+      ttl ||= self.ttl
+      # 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).
+      #
+      # For the same reason, we don't want to default to 0 bc there's not a
+      # good reason for the ttl to not be set in the first place. If the
+      # class doesn't have a ttl, the default comes from Familia.ttl (which
+      # is 0).
+      raise Familia::Problem, "TTL must be a number (#{ttl.class})" unless ttl.is_a?(Numeric)
+      raise Familia::Problem, "TTL must be positive (#{ttl})" unless ttl.is_a?(Numeric)
+
+      if ttl.zero?
+        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{rediskey})"
+      end
+
+      Familia.info "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
+
+      # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
+      # not exist or the timeout could not be set. Via redis-rb here, it's
+      # a bool.
+      expire(ttl)
+    end
+
+    extend ClassMethods
+
+    Familia::Base.add_feature self, :expiration
+  end
+
+end

data/lib/familia/features/quantization.rb

@@ -0,0 +1,56 @@
+# rubocop:disable all
+
+module Familia::Features
+
+  module Quantization
+
+    module ClassMethods
+      # Generates a quantized timestamp based on the given parameters.
+      #
+      # @param quantum [Integer, Array, nil] The time quantum in seconds or an array of [quantum, pattern].
+      # @param pattern [String, nil] The strftime pattern to format the timestamp.
+      # @param now [Time, nil] The current time (default: Familia.now).
+      # @return [Integer, String] A unix timestamp or formatted timestamp string.
+      #
+      # This method rounds the current time to the nearest quantum and optionally formats it
+      # according to the given pattern. It's useful for creating time-based buckets
+      # or keys with reduced granularity.
+      #
+      # @example
+      #   User.qstamp(1.hour, '%Y%m%d%H')  # Returns a string like "2023060114" for 2:30 PM
+      #   User.qstamp(10.minutes)  # Returns an integer timestamp rounded to the nearest 10 minutes
+      #   User.qstamp([1.hour, '%Y%m%d%H'])  # Same as the first example
+      #
+      # @raise [ArgumentError] If quantum is not positive
+      #
+      def qstamp(quantum = nil, pattern: nil, time: nil)
+        # Handle default values and array input
+        if quantum.is_a?(Array)
+          quantum, pattern = quantum
+        end
+        quantum ||= @opts[:quantize] || ttl || 10.minutes
+
+        # Validate quantum
+        unless quantum.is_a?(Numeric) && quantum.positive?
+          raise ArgumentError, "Quantum must be positive (#{quantum.inspect} given)"
+        end
+
+        # Call Familia.qstamp with our processed parameters
+        Familia.qstamp(quantum, pattern: pattern, time: time)
+      end
+    end
+
+    def self.included base
+      Familia.ld "[#{base}] Loaded #{self}"
+      base.extend ClassMethods
+    end
+
+    def qstamp(quantum = nil, pattern: nil, time: nil)
+      self.class.qstamp(quantum || ttl, pattern: pattern, time: time)
+    end
+
+    extend ClassMethods
+
+    Familia::Base.add_feature self, :quantization
+  end
+end

data/lib/familia/features/safe_dump.rb

@@ -102,7 +102,7 @@ module Familia::Features
     end
 
     def self.included base
-      Familia.ld "[Feature] Enabling SafeDump for #{base})"
+      Familia.ld "[#{self}] Enabled in #{base}"
       base.extend ClassMethods
 
       # Optionally define safe_dump_fields in the class to make
@@ -159,36 +159,5 @@ module Familia::Features
 
     Familia::Base.add_feature self, :safe_dump
   end
-
-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
-elsif dump_method && value_to_distunguish.respond_to?(dump_method)
-  Familia.trace :DISTINGUISHER, redis, "#{value_to_distunguish.class}##{dump_method}", caller(1..1) if Familia.debug?
-  value_to_distunguish.send(dump_method)
-else
-  if dump_method
-    msg = if dump_method.to_s.empty?
-      "No dump_method available for #{value_to_distunguish.class}"
-    else
-      "No such method: #{value_to_distunguish.class}##{dump_method}"
-    end
-    raise Familia::Problem, msg
-  else
-    Familia.trace :DISTINGUISHER, redis, "else", caller(1..1) if Familia.debug?
-    nil
-  end
-end
-
-
-if ret.nil? && dump_method && val.respond_to?(dump_method)
-  Familia.trace :TOREDIS, redis, "#{val.class}##{dump_method}", caller(1..1) if Familia.debug?
-  val.send dump_method
+  # end SafeDump
 end

data/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 @@ module Familia
           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 @@ module Familia
 
 end
 
+require_relative 'features/expiration'
+require_relative 'features/quantization'
 require_relative 'features/safe_dump'