familia 2.0.0.pre26 → 2.0.0

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

@@ -1,241 +0,0 @@
-# Migrating Guide: v2.0.0-pre22
-
-This version introduces significant performance optimizations for Redis operations, completes the bidirectional relationships feature, and improves flexibility for external identifiers.
-
-## Major Features
-
-### Bidirectional Relationship Methods
-
-**What's New:**
-
-The `participates_in` declarations now generate reverse collection methods with the `_instances` suffix, providing symmetric access to relationships from both directions.
-
-**Generated Methods:**
-```ruby
-class User < Familia::Horreum
-  participates_in Team, :members
-  participates_in Organization, :employees
-end
-
-# New reverse collection methods:
-user.team_instances         # => [team1, team2]
-user.team_ids               # => ["team_123", "team_456"]
-user.team?                  # => true/false
-user.team_count             # => 2
-
-user.organization_instances # => [org1]
-user.organization_ids       # => ["org_789"]
-```
-
-**Custom Names:**
-```ruby
-class User < Familia::Horreum
-  participates_in Organization, :contractors, as: :clients
-end
-
-user.clients_instances      # Instead of organization_instances
-user.clients_ids            # Instead of organization_ids
-```
-
-**Migration:**
-
-No changes required for existing code. The new methods are additive and don't affect existing `participates_in` functionality.
-
-### Pipelined Bulk Loading
-
-**What's New:**
-
-New `load_multi` methods provide up to 2× performance improvement for bulk object loading by using Redis pipelining.
-
-**Before (N×2 commands):**
-```ruby
-users = ids.map { |id| User.find_by_id(id) }
-# For 14 objects: 28 Redis commands (14 EXISTS + 14 HGETALL)
-```
-
-**After (1 round trip):**
-```ruby
-users = User.load_multi(ids)
-# For 14 objects: 1 pipelined batch with 14 HGETALL commands
-```
-
-**Additional Methods:**
-```ruby
-# Load by full dbkeys
-users = User.load_multi_by_keys(['user:123:object', 'user:456:object'])
-
-# Filter out nils for missing objects
-existing_only = User.load_multi(ids).compact
-```
-
-### Optional EXISTS Check Optimization
-
-**What's New:**
-
-The `find_by_id` and related methods now support skipping the EXISTS check for 50% reduction in Redis commands.
-
-```ruby
-# Default behavior (unchanged, 2 commands)
-user = User.find_by_id(123)
-
-# Optimized mode (1 command)
-user = User.find_by_id(123, check_exists: false)
-```
-
-**When to Use:**
-- Performance-critical paths
-- Bulk operations with known-to-exist keys
-- High-throughput APIs
-- Loading from sorted set results
-
-## Enhanced Features
-
-### Flexible External Identifier Format
-
-**What's New:**
-
-The `external_identifier` feature now supports custom format templates.
-
-**Examples:**
-```ruby
-# Default format (unchanged)
-class User < Familia::Horreum
-  feature :external_identifier
-end
-user.extid  # => "ext_abc123def456"
-
-# Custom prefix
-class Customer < Familia::Horreum
-  feature :external_identifier, format: 'cust_%{id}'
-end
-customer.extid  # => "cust_abc123def456"
-
-# Different separator
-class APIKey < Familia::Horreum
-  feature :external_identifier, format: 'api-%{id}'
-end
-key.extid  # => "api-abc123def456"
-```
-
-### Atomic Index Rebuilding
-
-**What's New:**
-
-Auto-generated rebuild methods for all unique and multi indexes with zero downtime.
-
-**Examples:**
-
-```ruby
-# Class-level unique index
-User.rebuild_email_lookup
-
-# Instance-scoped unique index
-company.rebuild_badge_index
-
-# With progress tracking
-User.rebuild_email_lookup(batch_size: 100) do |progress|
-  puts "#{progress[:completed]}/#{progress[:total]}"
-end
-```
-
-When to Use:
-- After data migrations or bulk imports
-- Recovering from index corruption
-- Adding indexes to existing data
-
-Migration:
-
-Run rebuild methods once after upgrade to ensure index consistency. No code changes required—methods are auto-generated from existing
-unique_index and multi_index declarations.
-
-
-## Bug Fixes
-
-### Symbol/String Target Classes in participates_in
-
-**What Was Fixed:**
-
-Fixed multiple bugs when using Symbol or String class names in `participates_in`:
-
-```ruby
-class Domain < Familia::Horreum
-  # All forms now work correctly:
-  participates_in Customer, :domains     # Class object
-  participates_in :Customer, :domains    # Symbol (was broken)
-  participates_in 'Customer', :domains   # String (was broken)
-end
-```
-
-**Errors Fixed:**
-- `NoMethodError: private method 'member_by_config_name'`
-- `NoMethodError: undefined method 'familia_name' for Symbol`
-- `NoMethodError: undefined method 'config_name' for Symbol`
-- Confusing nil errors for unloaded classes
-
-**New Behavior:**
-
-When a target class can't be resolved, you now get a helpful error:
-```
-Target class 'Customer' could not be resolved.
-Possible causes:
-1. The class hasn't been loaded yet (load order issue)
-2. The class name is misspelled
-3. The class doesn't inherit from Familia::Horreum
-
-Registered Familia classes: ["User", "Team", "Organization"]
-```
-
-## Performance Recommendations
-
-### Use Bulk Loading for Collections
-
-```ruby
-# ❌ Avoid N+1 queries
-team.members.to_a.map { |id| User.find_by_id(id) }
-
-# ✅ Use bulk loading
-User.load_multi(team.members.to_a)
-```
-
-### Skip EXISTS Checks When Safe
-
-```ruby
-# When loading from sorted sets (keys guaranteed to exist)
-task_ids = project.tasks.range(0, 9)
-tasks = Task.load_multi(task_ids)  # Or use check_exists: false
-
-# For known-existing keys
-user = User.find_by_id(session[:user_id], check_exists: false)
-```
-
-### Leverage Reverse Collection Methods
-
-```ruby
-# ❌ Manual parsing of participations
-team_keys = user.participations.members.select { |k| k.start_with?("team:") }
-team_ids = team_keys.map { |k| k.split(':')[1] }
-teams = Team.load_multi(team_ids)
-
-# ✅ Use generated methods
-teams = user.team_instances
-```
-
-## Backwards Compatibility
-
-All changes in this version are backwards compatible:
-
-- New methods are additive and don't affect existing APIs
-- Default behaviors remain unchanged
-- Symbol/String fixes don't require code changes
-
-## Recommended Actions
-
-1. **Adopt bulk loading** for performance-critical paths
-2. **Use reverse collection methods** to simplify relationship queries
-3. **Consider check_exists: false** for guaranteed-existing keys
-4. **Update external_identifier formats** if custom prefixes are needed
-
-## See Also
-
-- [Relationships Guide](../guides/feature-relationships.md)
-- [Performance Optimization Guide](../guides/optimized-loading.md)

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

@@ -1,131 +0,0 @@
-# Migrating Guide: Security Features (v2.0.0-pre5)
-
-This guide covers adopting the security enhancements introduced in v2.0.0-pre5.
-
-## Security Feature Adoption
-
-### 1. Configure Encryption Keys
-
-Before using encrypted fields, configure encryption keys:
-
-```ruby
-Familia.configure do |config|
-  config.encryption_keys = {
-    v1: 'your-32-byte-base64-encoded-key==',
-    v2: 'newer-32-byte-base64-encoded-key=='
-  }
-  config.current_key_version = :v2
-end
-```
-
-**Key Management:**
-- Use secure key storage (environment variables, key management services)
-- Rotate keys regularly by adding new versions
-- Never remove old key versions while data exists
-
-### 2. Identify Sensitive Fields
-
-Mark fields that contain sensitive data:
-
-**For Encryption:**
-```ruby
-class Vault < Familia::Horreum
-  feature :encrypted_fields
-
-  field :name                    # Plaintext
-  encrypted_field :secret_key    # Encrypted at rest
-  encrypted_field :api_token     # Transparent access
-end
-```
-
-**For Transient Fields:**
-```ruby
-class User < Familia::Horreum
-  feature :transient_fields
-
-  field :email                   # Persisted
-  transient_field :password      # Never persisted
-  transient_field :session_token # Runtime only
-end
-```
-
-### 3. Update Serialization Code
-
-Handle `ConcealedString` in serialization:
-
-**Before:**
-```ruby
-def to_json
-  { name: name, password: password }.to_json
-end
-```
-
-**After:**
-```ruby
-def to_json
-  # ConcealedString automatically excluded from serialization
-  { name: name }.to_json  # password field omitted if transient
-end
-```
-
-**Manual ConcealedString Handling:**
-```ruby
-# Access original value when needed
-password.reveal  # Returns actual string value
-password.cleared?  # Returns true if cleared from memory
-```
-
-### 4. Implement Key Rotation Procedures
-
-**Rotation Process:**
-1. Add new key version to configuration
-2. Update `current_key_version`
-3. Re-encrypt existing data using `re_encrypt_fields!`
-4. Verify migration completion
-5. Remove old keys after migration complete
-
-**Example Rotation Script:**
-```ruby
-# Step 1: Add new key version
-Familia.configure do |config|
-  config.encryption_keys = {
-    v2: ENV['OLD_ENCRYPTION_KEY'],
-    v3: ENV['NEW_ENCRYPTION_KEY']
-  }
-  config.current_key_version = :v3
-end
-
-# Step 2: Validate configuration
-Familia::Encryption.validate_configuration!
-
-# Step 3: Re-encrypt existing records
-Vault.all.each do |vault|
-  vault.re_encrypt_fields!  # Re-encrypts with current key
-  vault.save
-end
-
-# Step 4: Verify migration
-Vault.all.each do |vault|
-  status = vault.encrypted_fields_status
-  puts "Vault #{vault.identifier}: #{status}"
-end
-
-# Step 5: Remove old key (after verification)
-Familia.config.encryption_keys.delete(:v2)
-```
-
-## Security Best Practices
-
-- **Environment Variables:** Store keys in environment variables, not code
-- **Key Rotation:** Rotate encryption keys regularly (quarterly/annually)
-- **Field Selection:** Only encrypt fields that truly need protection
-- **Memory Clearing:** Use transient fields for temporary sensitive data
-- **Logging:** Verify ConcealedString prevents accidental logging
-- **Configuration Validation:** Use `validate_configuration!` before production
-- **Monitoring:** Use `encrypted_fields_status` to track encryption state
-
-## Next Steps
-
-After implementing security features:
-1. Review [Architecture Migration](v2.0.0-pre6.md) for persistence improvements
-2. Explore [Relationships Migration](v2.0.0-pre7.md) for the relationship system

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

@@ -1,154 +0,0 @@
-# Migrating Guide: Architecture Improvements (v2.0.0-pre6)
-
-This guide covers the architecture enhancements and new persistence methods in v2.0.0-pre6.
-
-## Architecture Improvements
-
-### 1. Enhanced Persistence Operations
-
-**New `save_if_not_exists` Method:**
-```ruby
-user = User.new(email: 'user@example.com')
-
-# Only save if the user doesn't already exist
-if user.save_if_not_exists
-  puts "User created successfully"
-else
-  puts "User already exists"
-end
-```
-
-**Atomic Persistence with Transactions:**
-```ruby
-user.transaction do |conn|
-  conn.set(user.key, user.serialize)
-  conn.sadd("all_users", user.identifier)
-  conn.expire(user.key, user.ttl) if user.ttl
-end
-```
-
-### 2. Modular Class Structure
-
-The Horreum class structure was reorganized for better maintainability:
-
-**Core Modules:**
-- `Familia::Horreum::Core` - Essential functionality
-- `Familia::Horreum::ClassMethods` - Class-level methods
-- `Familia::Horreum::Serialization` - Object serialization
-- `Familia::Horreum::Commands` - Valkey/Redis command wrappers
-
-**Feature System Improvements:**
-- Dependency management between features
-- Cleaner feature activation
-- Better error handling for missing dependencies
-
-### 3. Enhanced Error Handling
-
-**New Exception Types:**
-```ruby
-begin
-  user.save!
-rescue Familia::PersistenceError => e
-  puts "Failed to save: #{e.message}"
-rescue Familia::ValidationError => e
-  puts "Validation failed: #{e.message}"
-end
-```
-
-**Improved Data Consistency:**
-- Automatic retry for transient Valkey/Redis connection issues
-- Better handling of concurrent modifications
-- Enhanced validation before persistence operations
-
-## Migration Steps
-
-### 1. Update Error Handling
-
-**Before (v2.0.0-pre5):**
-```ruby
-begin
-  user.save
-rescue => e
-  puts "Something went wrong: #{e}"
-end
-```
-
-**After (v2.0.0-pre6):**
-```ruby
-begin
-  user.save
-rescue Familia::PersistenceError => e
-  puts "Persistence failed: #{e.message}"
-  # Handle specific persistence issues
-rescue Familia::ValidationError => e
-  puts "Invalid data: #{e.message}"
-  # Handle validation failures
-end
-```
-
-### 2. Adopt Conditional Persistence
-
-Replace existence checks with atomic operations:
-
-**Before:**
-```ruby
-user = User.new(email: email)
-unless User.exists?(email)
-  user.save
-end
-```
-
-**After:**
-```ruby
-user = User.new(email: email)
-user.save_if_not_exists
-```
-
-### 3. Leverage Transaction Support
-
-For complex operations, use transactions:
-
-```ruby
-# Before - Multiple separate operations
-user.save
-user.tags.add(tag)
-user.scores.add(score, timestamp)
-
-# After - Atomic transaction
-user.transaction do |conn|
-  conn.set(user.key, user.serialize)
-  conn.sadd(user.tags.key, tag)
-  conn.zadd(user.scores.key, timestamp, score)
-end
-```
-
-## Performance Improvements
-
-### Connection Management
-- Improved connection pooling with better resource utilization
-- Reduced connection overhead through intelligent connection reuse
-- Enhanced concurrent operation support
-
-### Feature System
-- Lazy feature loading reduces memory footprint
-- Optimized method dispatch for feature methods
-- Better dependency resolution
-
-## Breaking Changes
-
-### Method Signatures
-- Some internal methods changed signatures for better consistency
-- Error handling improved with specific exception types
-- Transaction block interface standardized
-
-### Feature Dependencies
-- Features now explicitly declare dependencies
-- Better error messages for missing feature requirements
-- Automatic dependency resolution where possible
-
-## Next Steps
-
-After completing architecture migration:
-1. Explore [Relationships Migration](v2.0.0-pre7.md) for the comprehensive relationship system
-2. Review updated documentation for architectural patterns
-3. Consider adopting new persistence patterns in your application