familia 2.0.0.pre7 → 2.0.0.pre10

data/docs/guides/relationships-methods.md

@@ -0,0 +1,266 @@
+# Relationship Methods
+
+Here are the methods automatically generated for each relationship type in the new clean API:
+
+## member_of Relationships
+
+When you declare:
+```ruby
+class Domain < Familia::Horreum
+  member_of Customer, :domains
+end
+```
+
+**Generated methods on Domain instances:**
+- `add_to_customer_domains(customer)` - Add this domain to customer's domains collection
+- `remove_from_customer_domains(customer)` - Remove this domain from customer's domains collection
+- `in_customer_domains?(customer)` - Check if this domain is in customer's domains collection
+
+**Collection << operator support:**
+```ruby
+customer.domains << domain  # Clean Ruby-like syntax (equivalent to domain.add_to_customer_domains(customer))
+```
+
+The method names follow the pattern: `{action}_to_{lowercase_class_name}_{collection_name}`
+
+## tracked_in Relationships
+
+### Class-Level Tracking (class_tracked_in)
+When you declare:
+```ruby
+class Customer < Familia::Horreum
+  class_tracked_in :all_customers, score: :created_at
+end
+```
+
+**Generated class methods:**
+- `Customer.add_to_all_customers(customer)` - Add customer to class-level tracking
+- `Customer.remove_from_all_customers(customer)` - Remove customer from class-level tracking
+- `Customer.all_customers` - Access the sorted set collection directly
+
+**Automatic behavior:**
+- Objects are automatically added to class-level tracking collections when saved
+- No manual calls required for basic tracking
+
+### Relationship Tracking (tracked_in with parent class)
+When you declare:
+```ruby
+class User < Familia::Horreum
+  tracked_in Team, :active_users, score: :last_seen
+end
+```
+
+**Generated methods:**
+- Team instance methods for managing the active_users collection
+- Automatic score calculation based on the provided lambda or field
+
+## indexed_by Relationships
+
+The `indexed_by` method creates Redis hash-based indexes for O(1) field lookups with automatic management.
+
+### Class-Level Indexing (class_indexed_by)
+When you declare:
+```ruby
+class Customer < Familia::Horreum
+  class_indexed_by :email, :email_lookup
+end
+```
+
+**Generated methods:**
+- **Instance methods**: `customer.add_to_class_email_lookup`, `customer.remove_from_class_email_lookup`
+- **Class methods**: `Customer.email_lookup` (returns hash), `Customer.find_by_email(email)`
+
+**Automatic behavior:**
+- Objects are automatically added to class-level indexes when saved
+- Index updates happen transparently on field changes
+
+Redis key pattern: `customer:email_lookup`
+
+### Relationship-Scoped Indexing (indexed_by with parent:)
+When you declare:
+```ruby
+class Domain < Familia::Horreum
+  indexed_by :name, :domain_index, parent: Customer
+end
+```
+
+**Generated class methods on Customer:**
+- `Customer#find_by_name(domain_name)` - Find domain by name within this customer
+- `Customer#find_all_by_name(domain_names)` - Find multiple domains by names
+
+Redis key pattern: `domain:domain_index` (all stored at class level for consistency)
+
+### When to Use Each Context
+- **Class-level context (`class_indexed_by`)**: Use for system-wide lookups where the field value should be unique across all instances
+  - Examples: email addresses, usernames, API keys
+- **Relationship context (`parent:` parameter)**: Use for relationship-scoped lookups where the field value is unique within a specific context
+  - Examples: domain names per customer, project names per team
+
+## Complete Example
+
+From the relationships example file, you can see the new clean API in action:
+
+```ruby
+# Domain declares membership in Customer collections
+class Domain < Familia::Horreum
+  member_of Customer, :domains
+  class_tracked_in :active_domains, score: -> { status == 'active' ? Time.now.to_i : 0 }
+end
+
+class Customer < Familia::Horreum
+  class_indexed_by :email, :email_lookup
+  class_tracked_in :all_customers, score: :created_at
+end
+```
+
+**Usage with automatic behavior:**
+```ruby
+# Create and save objects (automatic indexing and tracking)
+customer = Customer.new(email: "admin@acme.com", name: "Acme Corp")
+customer.save  # Automatically added to email_lookup and all_customers
+
+domain = Domain.new(name: "acme.com", status: "active")
+domain.save    # Automatically added to active_domains
+
+# Clean relationship syntax
+customer.domains << domain  # Ruby-like collection syntax
+
+# Query relationships
+domain.in_customer_domains?(customer)         # => true
+customer.domains.member?(domain.identifier)   # => true
+
+# O(1) lookups with automatic management
+found_id = Customer.email_lookup.get("admin@acme.com")
+```
+
+## Method Naming Conventions
+
+The relationship system uses consistent naming patterns:
+- **member_of**: `{add_to|remove_from|in}_#{parent_class.downcase}_#{collection_name}`
+- **class_tracked_in**: `{add_to|remove_from}_#{collection_name}` (class methods)
+- **class_indexed_by**: `{add_to|remove_from}_class_#{index_name}` (instance methods)
+- **indexed_by with parent**: `{add_to|remove_from}_#{parent_class.downcase}_#{index_name}` (instance methods)
+
+## Key Benefits
+
+- **Automatic management**: Save operations update indexes and tracking automatically
+- **Ruby-idiomatic**: Use `<<` operator for natural collection syntax
+- **Consistent storage**: All indexes stored at class level for architectural simplicity
+- **Clean API**: Removed complex global vs parent conditionals for simpler method generation
+
+
+## Context Parameter Usage Patterns
+
+The `context` parameter in `indexed_by` is a fundamental architectural decision that determines index scope and ownership. Here are practical patterns for when to use each approach:
+
+### Global Context Pattern
+Use `class_indexed_by` when field values should be unique system-wide:
+
+```ruby
+class User < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id, :email, :username
+
+  # System-wide unique email lookup
+  class_indexed_by :email, :email_lookup
+  class_indexed_by :username, :username_lookup
+end
+
+# Usage:
+user.add_to_global_email_lookup
+found_user_id = User.email_lookup.get("john@example.com")
+```
+
+**Redis keys generated**: `global:email_lookup`, `global:username_lookup`
+
+### Parent Context Pattern
+Use `parent: SomeClass` when field values are unique within a specific parent context:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  identifier_field :custid
+  field :custid, :name
+  sorted_set :domains
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id, :name, :subdomain
+
+  # Domains are unique per customer (customer can't have duplicate domain names)
+  indexed_by :name, :domain_index, parent: Customer
+  indexed_by :subdomain, :subdomain_index, parent: Customer
+end
+
+# Usage:
+customer = Customer.new(custid: "cust_123")
+customer.find_by_name("example.com")           # Find domain within this customer
+customer.find_all_by_subdomain(["www", "api"]) # Find multiple subdomains
+```
+
+**Redis keys generated**: `customer:cust_123:domain_index`, `customer:cust_123:subdomain_index`
+
+### Mixed Pattern Example
+A real-world example showing both patterns:
+
+```ruby
+class ApiKey < Familia::Horreum
+  feature :relationships
+
+  identifier_field :key_id
+  field :key_id, :key_hash, :name, :scope
+
+  # API key hashes must be globally unique
+  class_indexed_by :key_hash, :global_key_lookup
+
+  # But key names can be reused across different customers
+  indexed_by :name, :customer_key_lookup, parent: Customer
+  indexed_by :scope, :scope_lookup, parent: Customer
+end
+
+# Usage examples:
+# Global lookup (system-wide unique)
+ApiKey.key_lookup.get("sha256:abc123...")
+
+# Scoped lookup (unique per customer)
+customer = Customer.new(custid: "cust_456")
+customer.find_by_name("production-api-key")
+customer.find_all_by_scope(["read", "write"])
+```
+
+### Migration Guide
+If you have existing code with old syntax, here's how to update it:
+
+```ruby
+# ❌ Old syntax (pre-refactoring)
+indexed_by :email_lookup, field: :email
+indexed_by :email, :email_lookup, context: :global
+tracked_in :global, :all_users, score: :created_at
+
+# ✅ New syntax - Class-level scope
+class_indexed_by :email, :email_lookup
+class_tracked_in :all_users, score: :created_at
+
+# ✅ New syntax - Relationship scope
+indexed_by :email, :customer_email_lookup, parent: Customer
+tracked_in Customer, :user_activity, score: :last_seen
+```
+
+**Key Changes**:
+1. **Class-level relationships**: Use `class_` prefix (`class_tracked_in`, `class_indexed_by`)
+2. **Relationship-scoped**: Use `parent:` parameter instead of `:global` symbol
+3. **Automatic management**: Objects automatically added to class-level collections on save
+4. **Clean syntax**: Collections support `<<` operator for Ruby-like relationship building
+5. **Simplified storage**: All indexes stored at class level (parent is conceptual only)
+
+**Behavioral Changes**:
+- Save operations now automatically update indexes and class-level tracking
+- No more manual `add_to_*` calls required for basic functionality
+- `<<` operator works naturally with all collection types
+- Method generation simplified without complex global/parent conditionals

data/examples/relationships_basic.rb

@@ -3,92 +3,100 @@
 # Basic Relationships Example
 # This example demonstrates the core features of Familia's relationships system
 
-require_relative '../lib/familia'
+require 'familia'
 
 # Configure Familia for the example
+# Note: Individual models can specify logical_database if needed
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_URI', 'redis://localhost:6379/15')
+  config.uri = 'redis://localhost:6379/'
 end
 
-puts "=== Familia Relationships Basic Example ==="
+puts '=== Familia Relationships Basic Example ==='
 puts
 
 # Define our model classes
 class Customer < Familia::Horreum
+  logical_database 15 # Use test database
   feature :relationships
 
   identifier_field :custid
-  field :custid, :name, :email, :plan
+  field :custid
+  field :name
+  field :email
+  field :plan
 
   # Define collections for tracking relationships
   set :domains           # Simple set of domain IDs
   list :projects         # Ordered list of project IDs
   sorted_set :activity   # Activity feed with timestamps
 
-  # Create indexes for fast lookups
-  indexed_by :email_lookup, field: :email
-  indexed_by :plan_lookup, field: :plan
+  # Create indexes for fast lookups (using class_ prefix for class-level)
+  class_indexed_by :email, :email_lookup # i.e. Customer.email_lookup
+  class_indexed_by :plan, :plan_lookup # i.e. Customer.plan_lookup
 
-  # Track in global collections
-  tracked_in :all_customers, type: :sorted_set, score: :created_at
-
-  def created_at
-    Time.now.to_i
-  end
+  # Track in class-level collections (using class_ prefix for class-level)
+  class_tracked_in :all_customers, score: :created_at # i.e. Customer.all_customers
 end
 
 class Domain < Familia::Horreum
+  logical_database 15 # Use test database
   feature :relationships
 
   identifier_field :domain_id
-  field :domain_id, :name, :dns_zone, :status
+  field :domain_id
+  field :name
+  field :dns_zone
+  field :status
 
   # Declare membership in customer collections
-  member_of Customer, :domains, type: :set
+  member_of Customer, :domains #, type: :set
 
-  # Track domains by status
-  tracked_in :active_domains, type: :sorted_set,
-    score: ->(domain) { domain.status == 'active' ? Time.now.to_i : 0 }
+  # Track domains by status (using class_ prefix for class-level)
+  class_tracked_in :active_domains,
+                   score: -> { status == 'active' ? Time.now.to_i : 0 }
 end
 
 class Project < Familia::Horreum
+  logical_database 15 # Use test database
   feature :relationships
 
   identifier_field :project_id
-  field :project_id, :name, :priority
+  field :project_id
+  field :name
+  field :priority
 
   # Member of customer projects list (ordered)
   member_of Customer, :projects, type: :list
 end
 
-puts "=== 1. Basic Object Creation ==="
+puts '=== 1. Basic Object Creation ==='
 
 # Create some sample objects
 customer = Customer.new(
-  custid: "cust_#{SecureRandom.hex(4)}",
-  name: "Acme Corporation",
-  email: "admin@acme.com",
-  plan: "enterprise"
+  # custid: "cust_#{SecureRandom.hex(4)}",
+  name: 'Acme Corporation',
+  email: 'admin@acme.com',
+  plan: 'enterprise'
 )
 
 domain1 = Domain.new(
-  domain_id: "dom_#{SecureRandom.hex(4)}",
-  name: "acme.com",
-  dns_zone: "acme.com.",
-  status: "active"
+  # domain_id: "dom_#{SecureRandom.hex(4)}",
+  name: 'acme.com',
+  dns_zone: 'acme.com.',
+  status: 'active'
 )
 
 domain2 = Domain.new(
-  domain_id: "dom_#{SecureRandom.hex(4)}",
-  name: "staging.acme.com",
-  dns_zone: "staging.acme.com.",
-  status: "active"
+  # domain_id: "dom_#{SecureRandom.hex(4)}",
+  name: 'staging.acme.com',
+  dns_zone: 'staging.acme.com.',
+  status: 'active'
 )
 
 project = Project.new(
-  project_id: "proj_#{SecureRandom.hex(4)}",
-  name: "Website Redesign",
-  priority: "high"
+  # project_id: "proj_#{SecureRandom.hex(4)}",
+  name: 'Website Redesign',
+  priority: 'high'
 )
 
 puts "✓ Created customer: #{customer.name} (#{customer.custid})"
@@ -96,49 +104,44 @@ puts "✓ Created domains: #{domain1.name}, #{domain2.name}"
 puts "✓ Created project: #{project.name}"
 puts
 
-puts "=== 2. Establishing Relationships ==="
-
-# Add objects to indexed lookups
-Customer.add_to_email_lookup(customer)
-Customer.add_to_plan_lookup(customer)
-puts "✓ Added customer to email and plan indexes"
+puts '=== 2. Establishing Relationships ==='
 
-# Add customer to global tracking
-Customer.add_to_all_customers(customer)
-puts "✓ Added customer to global customer tracking"
+# Save objects to automatically update indexes and class-level tracking
+customer.save  # Automatically adds to email_lookup, plan_lookup, and all_customers
+puts '✓ Customer automatically added to indexes and tracking on save'
 
-# Establish member_of relationships (bidirectional)
-domain1.add_to_customer_domains(customer.custid)
-customer.domains.add(domain1.identifier)
+# Establish member_of relationships using clean << operator syntax
+customer.domains << domain1   # Clean Ruby-like syntax
+customer.domains << domain2   # Same as domain1.add_to_customer_domains(customer)
+customer.projects << project  # Same as project.add_to_customer_projects(customer)
 
-domain2.add_to_customer_domains(customer.custid)
-customer.domains.add(domain2.identifier)
+puts '✓ Established domain ownership relationships using << operator'
+puts '✓ Established project ownership relationships using << operator'
 
-project.add_to_customer_projects(customer.custid)
-customer.projects.add(project.identifier)
+# Save domains to automatically add them to class-level tracking
+domain1.save  # Automatically adds to active_domains if status == 'active'
+domain2.save  # Automatically adds to active_domains if status == 'active'
+puts '✓ Domains automatically added to status tracking on save'
+puts
 
-puts "✓ Established domain ownership relationships"
-puts "✓ Established project ownership relationships"
+puts '=== 3. Querying Relationships ==='
 
-# Track domains in status collections
-Domain.add_to_active_domains(domain1)
-Domain.add_to_active_domains(domain2)
-puts "✓ Added domains to active tracking"
-puts
+record = Customer.get_by_email('admin@acme.com')
+puts "Email lookup: #{record&.custid || 'not found'}"
 
-puts "=== 3. Querying Relationships ==="
+Customer.get_by_plan('enterprise') # raises MoreThanOne
 
-# Test indexed lookups
-found_customer_id = Customer.email_lookup.get(customer.email)
-puts "Email lookup for #{customer.email}: #{found_customer_id}"
+results = Customer.find_by_email('admin@acme.com')
+puts "Email lookup: #{results&.size} found"
 
-enterprise_customers = Customer.plan_lookup.get("enterprise")
-puts "Enterprise customer found: #{enterprise_customers}"
+results = Customer.find_by_plan('enterprise')
+puts "Enterprise lookup: #{results&.size} found"
+puts
 
 # Test membership queries
 puts "\nDomain membership checks:"
-puts "  #{domain1.name} belongs to customer? #{domain1.in_customer_domains?(customer.custid)}"
-puts "  #{domain2.name} belongs to customer? #{domain2.in_customer_domains?(customer.custid)}"
+puts "  #{domain1.name} belongs to customer? #{domain1.in_customer_domains?(customer)}"
+puts "  #{domain2.name} belongs to customer? #{domain2.in_customer_domains?(customer)}"
 
 puts "\nCustomer collections:"
 puts "  Customer has #{customer.domains.size} domains"
@@ -147,69 +150,37 @@ puts "  Domain IDs: #{customer.domains.members}"
 puts "  Project IDs: #{customer.projects.members}"
 
 # Test tracked_in collections
-all_customers_count = Customer.all_customers.size
-puts "\nGlobal tracking:"
+all_customers_count = Customer.values.size
+puts "\nClass-level tracking:"
 puts "  Total customers in system: #{all_customers_count}"
 
 active_domains_count = Domain.active_domains.size
 puts "  Active domains in system: #{active_domains_count}"
 puts
 
-puts "=== 4. Range Queries ==="
+puts '=== 4. Range Queries ==='
 
 # Get recent customers (last 24 hours)
-yesterday = (Time.now - 24.hours).to_i
-recent_customers = Customer.all_customers.range_by_score(yesterday, '+inf')
+yesterday = (Time.now - (24 * 3600)).to_i # 24 hours ago
+recent_customers = Customer.values.rangebyscore(yesterday, '+inf')
 puts "Recent customers (last 24h): #{recent_customers.size}"
 
 # Get all active domains by score
-active_domain_scores = Domain.active_domains.range_by_score(1, '+inf', with_scores: true)
-puts "Active domains with timestamps:"
-active_domain_scores.each do |domain_id, timestamp|
-  puts "  #{domain_id}: active since #{Time.at(timestamp.to_i)}"
+active_domain_scores = Domain.active_domains.rangebyscore(1, '+inf', with_scores: true)
+puts 'Active domains with timestamps:'
+active_domain_scores.each_slice(2) do |domain_id, timestamp|
+  puts "  #{domain_id}: active since #{Time.at(timestamp.to_i)} #{timestamp.inspect}"
 end
 puts
 
-puts "=== 5. Batch Operations ==="
-
-# Create additional test data
-additional_customers = []
-3.times do |i|
-  cust = Customer.new(
-    custid: "batch_cust_#{i}",
-    name: "Customer #{i}",
-    email: "customer#{i}@example.com",
-    plan: i.even? ? "basic" : "premium"
-  )
-  additional_customers << cust
-
-  # Add to indexes and tracking
-  Customer.add_to_email_lookup(cust)
-  Customer.add_to_plan_lookup(cust)
-  Customer.add_to_all_customers(cust)
-end
-
-puts "✓ Created and indexed #{additional_customers.size} additional customers"
 
-# Query by plan
-basic_customers = Customer.plan_lookup.get("basic")
-premium_customers = Customer.plan_lookup.get("premium")
-enterprise_customers = Customer.plan_lookup.get("enterprise")
-
-puts "\nCustomer distribution by plan:"
-puts "  Basic: #{basic_customers ? 1 : 0} customers"
-puts "  Premium: #{premium_customers ? 1 : 0} customers"
-puts "  Enterprise: #{enterprise_customers ? 1 : 0} customers"
-puts
-
-puts "=== 6. Relationship Cleanup ==="
+puts '=== 6. Relationship Cleanup ==='
 
 # Remove relationships
-puts "Cleaning up relationships..."
+puts 'Cleaning up relationships...'
 
 # Remove from member_of relationships
-domain1.remove_from_customer_domains(customer.custid)
-customer.domains.remove(domain1.identifier)
+domain1.remove_from_customer_domains(customer)
 puts "✓ Removed #{domain1.name} from customer domains"
 
 # Remove from tracking collections
@@ -222,52 +193,14 @@ puts "  Customer domains: #{customer.domains.size}"
 puts "  Active domains: #{Domain.active_domains.size}"
 puts
 
-puts "=== 7. Advanced Usage - Permission Encoding ==="
-
-# Demonstrate basic score encoding for permissions
-class DocumentAccess
-  # Permission flags (powers of 2)
-  READ = 1
-  WRITE = 2
-  DELETE = 4
-  ADMIN = 8
-
-  def self.encode_permissions(timestamp, permissions)
-    "#{timestamp}.#{permissions}".to_f
-  end
-
-  def self.decode_permissions(score)
-    parts = score.to_s.split('.')
-    timestamp = parts[0].to_i
-    permissions = parts[1] ? parts[1].to_i : 0
-    [timestamp, permissions]
-  end
-end
-
-# Example permission encoding
-now = Time.now.to_i
-read_write_permissions = DocumentAccess::READ | DocumentAccess::WRITE  # 3
-admin_permissions = DocumentAccess::ADMIN  # 8
-
-encoded_score = DocumentAccess.encode_permissions(now, read_write_permissions)
-timestamp, permissions = DocumentAccess.decode_permissions(encoded_score)
-
-puts "Permission encoding example:"
-puts "  Original: timestamp=#{now}, permissions=#{read_write_permissions}"
-puts "  Encoded score: #{encoded_score}"
-puts "  Decoded: timestamp=#{timestamp}, permissions=#{permissions}"
-puts "  Has read access: #{(permissions & DocumentAccess::READ) != 0}"
-puts "  Has write access: #{(permissions & DocumentAccess::WRITE) != 0}"
-puts "  Has delete access: #{(permissions & DocumentAccess::DELETE) != 0}"
-puts
-
-puts "=== Example Complete! ==="
+puts '=== Example Complete! ==='
 puts
-puts "Key takeaways:"
-puts "• tracked_in: Use for activity feeds, leaderboards, time-series data"
-puts "• indexed_by: Use for fast O(1) lookups by field values"
-puts "• member_of: Use for bidirectional ownership/membership"
-puts "• Score encoding: Combine timestamps with metadata for rich queries"
-puts "• Batch operations: Use Redis pipelines for efficiency"
+puts 'Key takeaways:'
+puts '• class_tracked_in: Automatic class-level collections updated on save'
+puts '• class_indexed_by: Automatic class-level indexes updated on save'
+puts '• member_of: Use << operator for clean Ruby-like collection syntax'
+puts '• indexed_by with parent:: Use for relationship-scoped indexes'
+puts '• Save operations: Automatically update indexes and class-level tracking'
+puts '• << operator: Works naturally with all collection types (sets, lists, sorted sets)'
 puts
-puts "See docs/wiki/Relationships-Guide.md for comprehensive documentation"
+puts 'See docs/wiki/Relationships-Guide.md for comprehensive documentation'

data/familia.gemspec

@@ -19,10 +19,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
 
-  spec.add_dependency 'benchmark'
-  spec.add_dependency 'connection_pool'
-  spec.add_dependency 'csv'
-  spec.add_dependency 'logger'
+  spec.add_dependency 'benchmark', '~> 0.1'
+  spec.add_dependency 'connection_pool', '~> 2.4'
+  spec.add_dependency 'csv', '~> 3.1'
+  spec.add_dependency 'logger', '~> 1.6'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'