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

```bash # Add to Gemfile gem ‘familia’, ‘>= 2.0.0’

Or install directly

gem install familia ```

2. Configure Connection

```ruby # 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

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

4. Basic Operations

```ruby # Create user = User.new(email: ‘alice@example.com’, name: ‘Alice’) user.save

Find

user = User.load(‘alice@example.com’)

Update

user.name = ‘Alice Smith’ user.save

Check existence

User.exists?(‘alice@example.com’) #=> true ```

Prerequisites

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

Usage Examples

Creating and Saving Objects

ruby 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.find_by_id("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

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

Object Relationships

Familia includes a powerful relationships system for managing object associations:

```ruby class Customer < Familia::Horreum feature :relationships

identifier_field :custid field :custid, :name, :email set :domains # Collection for related objects

# Automatic indexing and tracking class_indexed_by :email, :email_lookup class_tracked_in :all_customers, score: :created_at end

class Domain < Familia::Horreum feature :relationships

identifier_field :domain_id field :domain_id, :name, :status

# Bidirectional membership member_of Customer, :domains end

Clean, Ruby-like syntax

customer = Customer.new(custid: “cust123”, email: “admin@acme.com”) customer.save # Automatically indexed and tracked

domain = Domain.new(domain_id: “dom456”, name: “acme.com”) customer.domains « domain # Clean collection syntax

Fast O(1) lookups

found_customer = Customer.find_by_email(“admin@acme.com”) ```

Advanced Features

Relationships and Associations

Familia provides three types of relationships with automatic management:

  • member_of - Bidirectional membership with clean << operator support
  • indexed_by - O(1) hash-based field lookups (class-level or relationship-scoped)
  • tracked_in - Scored collections for rankings, time-series, and analytics

All relationships support automatic indexing and tracking - objects are automatically added to class-level collections when saved, with no manual management required.

Organizing Complex Models

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

Self-Registering Features

```ruby # 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.

AI Development Assistance

This version of Familia was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:

  • Google Gemini - Refactoring, code generation, and documentation.
  • Claude Sonnet 4, Opus 4.1 - Architecture design, code generation, and documentation
  • Claude Desktop & Claude Code (Max plan) - Interactive development sessions and debugging
  • GitHub Copilot - Code completion and refactoring assistance
  • Qodo Merge Pro - Code review and quality improvements

I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows as developers.

Epilogue

For more information, visit: - Github Repository - RubyGems Page

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