familia

Familia - 2.0

Organize and store Ruby objects in Valkey/Redis. A powerful Ruby ORM (of sorts) for Valkey/Redis.

Familia provides a flexible and feature-rich way to interact with Valkey using Ruby objects. It's designed to make working with Valkey as natural as working with Ruby classes, while offering advanced features for complex data management.

Quick Start

1. Installation

# Add to Gemfile
gem 'familia', '>= 2.0.0'

# Or install directly
gem install familia

2. Configure Connection

# config/initializers/familia.rb (Rails)
# or at the top of your script

require 'familia'

# Basic configuration
Familia.uri = 'redis://localhost:6379/0'

# Or with authentication
Familia.uri = 'redis://user:password@localhost:6379/0'

3. Create Your First Model

class User < Familia::Horreum
  identifier_field :email
  field :email
  field :name
  field :created_at
end

4. Basic Operations

# Create
user = User.new(email: '[e-mail]', name: 'Alice')
user.save

# Find
user = User.load('[e-mail]')

# Update
user.name = 'Alice Smith'
user.save

# Check existence
User.exists?('[e-mail]')  #=> true

Prerequisites

• Ruby: 3.4+ (3.4+ recommended)
• Valkey/Redis: 6.0+
• Gems: redis (automatically installed)

Usage Examples

Creating and Saving Objects

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

rose = Flower.find_by_id("rrose")
rose.name = "Pink Rose"
rose.save

Using Safe Dump

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

metric = DailyMetric.new
metric.counter.increment  # Increments the counter for the current hour

Bulk Operations

Flower.multiget("rrose", "tulip", "daisy")

Transactional Operations

user.transaction do |conn|
  conn.set("user:#{user.id}:status", "active")
  conn.zadd("active_users", Time.now.to_i, user.id)
end

Organizing Complex Models

For large applications, you can organize model complexity using custom features:

Self-Registering Features

# app/features/customer_management.rb
module MyApp::Features::CustomerManagement
  Familia::Base.add_feature(self, :customer_management)

  def self.included(base)
    base.extend(ClassMethods)
  end

  module ClassMethods
    def create_with_validation(attrs)
      # Complex creation logic
    end
  end

  def complex_business_method
    # Instance methods
  end
end

# models/customer.rb
class Customer < Familia::Horreum
  field :email, :name
  feature :customer_management  # Clean model definition
end

This keeps complex models organized while maintaining Familia's clean, declarative style.

Conclusion

Familia provides a powerful and flexible way to work with Valkey-compatible 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.

For more information, visit:

• Github Repository
• RubyGems Page

Contributions are welcome! Feel free to submit a Pull Request.