familia 2.0.0.pre8 → 2.0.0.pre12

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"])
+```
+
+### Migrating 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/docs/migrating/.gitignore

@@ -0,0 +1,2 @@
+# Even all wiki markdown docs get the blues
+!*.md

data/docs/migrating/v2.0.0-pre.md

@@ -0,0 +1,84 @@
+# Migrating Guide: v1.x to v2.0.0-pre
+
+This guide covers migrating from Familia v1.x to the v2.0.0-pre foundation release.
+
+## Overview
+
+The v2.0.0-pre series represents a major modernization of Familia with:
+- Complete API redesign for clarity and consistency
+- Valkey compatibility alongside Redis support
+- Ruby 3.4+ modernization with improved thread safety
+- New connection pooling architecture
+
+## Step-by-Step Migration
+
+### 1. Update Connection Configuration
+
+**Before (v1.x):**
+```ruby
+Familia.connect('redis://localhost:6379/0')
+```
+
+**After (v2.0.0-pre):**
+```ruby
+Familia.configure do |config|
+  config.redis_uri = 'redis://localhost:6379/0'
+  config.connection_pool = true
+end
+```
+
+### 2. Migrate Identifier Declarations
+
+**Before (v1.x):**
+```ruby
+class User < Familia::Base
+  identifier :user_id
+end
+```
+
+**After (v2.0.0-pre):**
+```ruby
+class User < Familia::Horreum
+  identifier_field :user_id
+end
+```
+
+### 3. Update Feature Activations
+
+**Before (v1.x):**
+```ruby
+class User < Familia::Base
+  include Familia::Features::Expiration
+end
+```
+
+**After (v2.0.0-pre):**
+```ruby
+class User < Familia::Horreum
+  feature :expiration
+end
+```
+
+### 4. Review Method Calls
+
+Several methods were renamed for consistency:
+
+| v1.x Method | v2.0.0-pre Method | Notes |
+|-------------|------------------|-------|
+| `delete` | `destroy` | More semantic naming |
+| `exists` | `exists?` | Ruby predicate convention |
+| `dump` | `serialize` | Clearer intent |
+
+## Breaking Changes
+
+- `Familia::Base` replaced by `Familia::Horreum`
+- Connection configuration moved to block-based setup
+- Feature inclusion changed from `include` to `feature` declarations
+- Several method names updated for consistency
+
+## Next Steps
+
+After completing the foundation migration:
+1. Review [Security Feature Adoption](v2.0.0-pre5.md) for encrypted fields
+2. See [Architecture Migration](v2.0.0-pre6.md) for persistence improvements
+3. Explore [Relationships Migration](v2.0.0-pre7.md) for the new relationship system

data/docs/migrating/v2.0.0-pre11.md

@@ -0,0 +1,255 @@
+# Migrating Guide: v2.0.0-pre11
+
+This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.
+
+## Enhanced Feature System
+
+### Model-Specific Feature Registration
+
+Previously, all features were registered globally. Now you can register features specific to individual model classes, allowing for better organization and namespace management.
+
+#### Before
+```ruby
+# Global feature registration only
+module MyProjectFeature
+  # Feature implementation
+end
+Familia::Base.add_feature MyProjectFeature, :my_project_feature
+
+class Customer < Familia::Horreum
+  feature :my_project_feature
+end
+
+class Session < Familia::Horreum
+  feature :my_project_feature  # Same global feature
+end
+```
+
+#### After
+```ruby
+# Model-specific feature registration
+module CustomerSpecificFeature
+  # Feature implementation
+end
+
+# Register feature only for Customer and its subclasses
+Customer.add_feature CustomerSpecificFeature, :customer_specific
+
+class Customer < Familia::Horreum
+  feature :customer_specific  # Available via Customer's registry
+end
+
+class PremiumCustomer < Customer
+  feature :customer_specific  # Inherited via ancestry chain
+end
+
+class Session < Familia::Horreum
+  # feature :customer_specific  # Not available - would raise error
+end
+```
+
+**Benefits:**
+- Features can have the same name across different model hierarchies
+- Standardized naming: `deprecated_fields.rb` instead of `customer_deprecated_fields.rb`
+- Natural inheritance through Ruby's class hierarchy
+
+## SafeDump DSL Improvements
+
+The new DSL replaces the brittle `@safe_dump_fields` class instance variable pattern with clean, explicit methods.
+
+### Before
+```ruby
+class Customer < Familia::Horreum
+  feature :safe_dump
+
+  # Brittle - hard to move to feature modules, confusing syntax
+  @safe_dump_fields = [
+    :custid,
+    :email,
+    { active: ->(obj) { obj.active? } },
+    { display_name: ->(obj) { "#{obj.name} (#{obj.custid})" } }
+  ]
+end
+```
+
+### After
+```ruby
+class Customer < Familia::Horreum
+  feature :safe_dump
+
+  # Clean DSL - easy to understand and organize
+  safe_dump_field :custid
+  safe_dump_field :email
+  safe_dump_field :active, ->(obj) { obj.active? }
+  safe_dump_field :display_name, ->(obj) { "#{obj.name} (#{obj.custid})" }
+
+  # Or define multiple fields at once
+  safe_dump_fields :created, :updated, { status: ->(obj) { obj.role } }
+end
+```
+
+**New methods available:**
+- `safe_dump_field(name, callable = nil)` - Define a single field
+- `safe_dump_fields(*fields)` - Define multiple fields or get field names
+- `safe_dump_field_names` - Get array of field names
+- `safe_dump_field_map` - Get the internal callable map
+
+**Backward Compatibility:**
+- `set_safe_dump_fields(*fields)` - Legacy setter method (still works)
+- The old `@safe_dump_fields` pattern is no longer supported
+
+## Auto-loading Features
+
+### Before: Manual Loading
+```ruby
+# apps/api/v2/models/customer/features.rb
+
+# Manual feature loading (copied from Familia)
+features_dir = File.join(__dir__, 'features')
+if Dir.exist?(features_dir)
+  Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
+    require_relative feature_file
+  end
+end
+
+module V2
+  class Customer < Familia::Horreum
+    # Features now available for use
+    feature :deprecated_fields
+  end
+end
+```
+
+### After: Automatic Loading
+```ruby
+# apps/api/v2/models/customer/features.rb
+module V2::Customer
+  module Features
+    include Familia::Features::Autoloader
+    # Automatically discovers and loads all *.rb files from customer/features/
+  end
+end
+
+module V2
+  class Customer < Familia::Horreum
+    # Features automatically loaded and available
+    feature :deprecated_fields
+  end
+end
+```
+
+**Directory structure this enables:**
+```
+models/
+├── customer/
+│   ├── features/
+│   │   ├── deprecated_fields.rb      # Standardized names!
+│   │   ├── legacy_support.rb
+│   │   └── stripe_integration.rb
+│   └── features.rb                   # Include Autoloader here
+├── session/
+│   ├── features/
+│   │   ├── deprecated_fields.rb      # Same name, different implementation
+│   │   └── expiration_hooks.rb
+│   └── features.rb
+└── customer.rb
+```
+
+## Field Definitions in Feature Modules
+
+Feature modules can now define fields directly in their `ClassMethods` modules. When a class extends the module, the field definitions execute in the extending class's context.
+
+### Example
+```ruby
+# features/common_fields.rb
+module CommonFields
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # These field calls execute in the extending class's context
+    field :created
+    field :updated
+    field :version
+
+    def touch_updated
+      self.updated = Time.now.to_i
+    end
+  end
+
+  Familia::Base.add_feature self, :common_fields
+end
+
+# Usage
+class Customer < Familia::Horreum
+  feature :common_fields
+  # Now has :created, :updated, :version fields and touch_updated class method
+end
+```
+
+## Migration Steps
+
+### 1. Update SafeDump Usage
+Replace all `@safe_dump_fields` definitions with the new DSL:
+
+```ruby
+# Find and replace pattern:
+# Old: @safe_dump_fields = [:field1, :field2, { field3: ->(obj) { ... } }]
+# New: safe_dump_fields :field1, :field2, { field3: ->(obj) { ... } }
+
+# Or use individual field definitions for better readability:
+safe_dump_field :field1
+safe_dump_field :field2
+safe_dump_field :field3, ->(obj) { ... }
+```
+
+### 2. Set Up Auto-loading (Optional)
+If you have project-specific features, set up auto-loading:
+
+```ruby
+# Create: models/[model_name]/features.rb
+module YourProject
+  module ModelName
+    module Features
+      include Familia::Features::Autoloader
+    end
+  end
+end
+
+# Require this file before your model definitions
+require_relative 'model_name/features'
+```
+
+### 3. Organize Features by Model (Optional)
+Consider reorganizing shared feature names by model:
+
+```ruby
+# Before: features/customer_deprecated_fields.rb
+# After: models/customer/features/deprecated_fields.rb
+
+# This allows multiple models to have their own deprecated_fields.rb
+```
+
+### 4. Test Your Changes
+Run your test suite to ensure all SafeDump functionality works correctly:
+
+```ruby
+# Verify SafeDump DSL works
+model = YourModel.new(field1: 'value')
+result = model.safe_dump
+puts result.keys  # Should include your defined fields
+```
+
+## Breaking Changes
+
+1. **`@safe_dump_fields` no longer supported** - Must migrate to DSL methods
+2. **SafeDump field order** - Fields are now returned in definition order via Hash keys (Ruby 1.9+ behavior)
+
+## New Capabilities Unlocked
+
+1. **Standardized feature names** across different models
+2. **Cleaner SafeDump definitions** that can be easily moved to feature modules
+3. **Automatic feature discovery** for better project organization
+4. **Model-specific feature registries** for better namespace management
+5. **Field definitions in feature modules** for shared functionality