familia 2.0.0.pre25 → 2.0.0

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

@@ -1,95 +0,0 @@
-# Migrating Guide: v2.0.0-pre13
-
-This version introduces the Feature Autoloading System for automatic discovery and loading of feature-specific configuration files, enabling cleaner separation between core model definitions and feature configurations.
-
-## Feature Autoloading System
-
-### What Changed
-
-Features now automatically discover and load extension files from your project directories using conventional file naming patterns. This eliminates the need to configure features in your main model files.
-
-### Basic Migration
-
-#### Before
-```ruby
-# app/models/user.rb
-class User < Familia::Horreum
-  field :name, :email, :password
-
-  feature :safe_dump
-  safe_dump_fields :name, :email  # Configuration mixed with model
-end
-```
-
-#### After
-```ruby
-# app/models/user.rb - Clean model definition
-class User < Familia::Horreum
-  field :name, :email, :password
-  feature :safe_dump  # Configuration auto-loaded
-end
-
-# app/models/user/safe_dump_extensions.rb - Automatically discovered
-class User
-  safe_dump_fields :name, :email
-end
-```
-
-### File Naming Convention
-
-Extension files follow the pattern: `{model_name}/{feature_name}_*.rb`
-
-```
-app/models/
-├── user.rb
-├── user/
-│   ├── safe_dump_extensions.rb    # SafeDump configuration
-│   └── expiration_config.rb       # Expiration settings
-```
-
-### Migration Steps
-
-1. **Create extension directories**: `mkdir -p app/models/user`
-2. **Extract feature configuration** from main model files to separate extension files
-3. **Verify autoloading**: Check that feature methods are available after migration
-
-### Debugging
-
-Enable debug output to troubleshoot autoloading:
-```ruby
-ENV['FAMILIA_DEBUG'] = '1'  # Shows discovered and loaded files
-```
-
-Common issues:
-- Files must follow `{feature_name}_*.rb` naming pattern
-- Extension files should reopen the same class as your model
-
-## Architecture
-
-The Feature Autoloading System consists of two key components:
-
-### Familia::Features::Autoloader
-A utility module providing shared file loading functionality:
-- Handles Dir.glob pattern matching and file loading
-- Provides consistent debug logging across all autoloading scenarios
-- Used by both feature-specific and general-purpose autoloading
-
-### Familia::Features::Autoloadable
-A mixin for feature modules that enables post-inclusion autoloading:
-- Uses `Module.const_source_location` to find where user classes are defined
-- Discovers extension files using conventional patterns relative to the user class location
-- Integrates with the feature system's inclusion lifecycle
-
-When you call `feature :safe_dump`, the SafeDump module (which includes Autoloadable) triggers post-inclusion autoloading that searches for `user/safe_dump_*.rb` files and loads them automatically.
-
-## New Capabilities
-
-1. **Automatic Extension Discovery**: No manual require statements needed
-2. **Conventional File Organization**: Standard patterns for consistent project structure
-3. **Feature Isolation**: Clean separation between core models and feature configurations
-4. **Shared Autoloader Infrastructure**: Consistent loading behavior across all features
-5. **Debug Support**: Built-in debugging for troubleshooting autoloading issues
-
-## Breaking Changes
-
-**None** - This release is fully backward compatible. Existing models and feature configurations continue to work without modification.

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

@@ -1,37 +0,0 @@
-# Migrating Guide: v2.0.0-pre14
-
-This version renames TimeUtils to TimeLiterals for semantic clarity and fixes an ExternalIdentifier bug.
-
-## Breaking Change: TimeUtils → TimeLiterals
-
-**Migration Required:**
-
-Find and replace in your codebase:
-```bash
-# Find files to update
-grep -r "using Familia::Refinements::TimeUtils" .
-
-# Replace the import
-sed -i 's/using Familia::Refinements::TimeUtils/using Familia::Refinements::TimeLiterals/g' *.rb
-```
-
-**Before:**
-```ruby
-using Familia::Refinements::TimeUtils
-```
-
-**After:**
-```ruby
-using Familia::Refinements::TimeLiterals
-```
-
-All functionality remains identical - only the module name changed.
-
-## Bug Fix: ExternalIdentifier
-
-Fixed `NoMethodError` when using ExternalIdentifier by replacing incorrect `.del()` calls with `.remove_field()` in HashKey operations. This affected:
-- Changing external identifier values
-- Looking up objects by external ID
-- Destroying objects with external identifiers
-
-No migration needed - the fix is automatic.

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

@@ -1,58 +0,0 @@
-# Migrating Guide: v2.0.0-pre18
-
-This version completes the JSON serialization implementation by removing the string-as-is optimization and fixes encrypted field visibility in serialization.
-
-## JSON Serialization for All Types
-
-**What Changed:**
-
-All field values (including strings) are now JSON-encoded during storage for consistent type preservation.
-
-**Storage Format:**
-
-```ruby
-# Before (v2.0.0-pre14):
-HGET user:123 name
-"John Doe"                    # Plain string
-
-# After (v2.0.0-pre18):
-HGET user:123 name
-"\"John Doe\""                # JSON-encoded string
-```
-
-**Migration:**
-
-No migration needed. The deserializer automatically handles:
-- **New format**: `"\"value\""` → `"value"`
-- **Legacy format**: `"value"` → `"value"`
-
-**Why This Matters:**
-
-Prevents data corruption for edge cases:
-- Badge `"007"` stays `"007"` (not converted to integer `7`)
-- String `"true"` stays `"true"` (not converted to boolean)
-- String `"null"` stays `"null"` (not converted to `nil`)
-
-## Encrypted Field Security Fix
-
-**What Changed:**
-
-Fields defined with `category: :encrypted` now correctly exclude encrypted data from `to_h()` output.
-
-**Before:**
-```ruby
-field :secret, category: :encrypted
-user.to_h  # => {"id" => "123", "secret" => {...}}  # ❌ Exposed!
-```
-
-**After:**
-```ruby
-field :secret, category: :encrypted
-user.to_h  # => {"id" => "123"}  # ✅ Secure
-```
-
-Both `encrypted_field` and `field :name, category: :encrypted` now behave identically for security.
-
-**Migration:**
-
-No code changes needed. Review any code relying on encrypted fields appearing in `to_h()` output.

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

@@ -1,197 +0,0 @@
-# Migrating Guide: v2.0.0-pre19
-
-This version introduces significant improvements to Familia's database operations, making them more atomic, reliable, and consistent with Rails conventions. The changes include enhanced error handling, optimistic locking support, and breaking API changes.
-
-## Breaking Changes
-
-### Management.create → create!
-
-**What Changed:**
-
-The `create` class method has been renamed to `create!` to follow Rails conventions and indicate that it raises exceptions on failure.
-
-**Before:**
-```ruby
-user = User.create(email: "test@example.com")
-```
-
-**After:**
-```ruby
-user = User.create!(email: "test@example.com")
-```
-
-**Why This Matters:**
-
-- Follows Rails naming conventions where `!` methods raise exceptions
-- Makes it clear that `CreationError` will be raised if object already exists
-- Prevents silent failures in object creation
-
-### save_if_not_exists → save_if_not_exists!
-
-**What Changed:**
-
-The `save_if_not_exists` method has been renamed to `save_if_not_exists!` and now includes optimistic locking with automatic retry logic.
-
-**Before:**
-```ruby
-success = user.save_if_not_exists
-```
-
-**After:**
-```ruby
-success = user.save_if_not_exists!
-```
-
-**Behavior Changes:**
-- Now uses Redis WATCH/MULTI/EXEC for optimistic locking
-- Automatically retries up to 3 times on `OptimisticLockError`
-- Raises `RecordExistsError` if object already exists
-- More atomic and thread-safe
-
-## Enhanced Error Handling
-
-### New Error Hierarchy
-
-**What's New:**
-
-A structured error hierarchy provides better error categorization:
-
-```ruby
-Familia::Problem                    # Base class
-├── Familia::PersistenceError       # Redis/database errors
-│   ├── Familia::NonUniqueKey
-│   ├── Familia::OptimisticLockError
-│   ├── Familia::OperationModeError
-│   ├── Familia::NoConnectionAvailable
-│   ├── Familia::NotFound
-│   └── Familia::NotConnected
-└── Familia::HorreumError           # Model-related errors
-    ├── Familia::CreationError
-    ├── Familia::NoIdentifier
-    ├── Familia::FieldTypeError
-    ├── Familia::AutoloadError
-    ├── Familia::SerializerError
-    ├── Familia::UnknownFieldError
-    └── Familia::NotDistinguishableError
-```
-
-**Migration:**
-
-Update exception handling to use specific error classes:
-
-```ruby
-# Before
-rescue Familia::Problem => e
-  # Handle all errors
-
-# After - More granular handling
-rescue Familia::CreationError => e
-  # Handle creation failures specifically
-rescue Familia::OptimisticLockError => e
-  # Handle concurrent modification
-rescue Familia::PersistenceError => e
-  # Handle database-related errors
-```
-
-### New Exception Types
-
-- **`CreationError`**: Raised when object creation fails (replaces generic errors)
-- **`OptimisticLockError`**: Raised when WATCH fails due to concurrent modification
-- **`UnknownFieldError`**: Raised when referencing non-existent fields
-
-## Database Operation Improvements
-
-### Atomic Save Operations
-
-**What Changed:**
-
-The `save` method now uses a single Redis transaction for complete atomicity:
-
-```ruby
-# All operations now happen atomically:
-# 1. Save all fields (HMSET)
-# 2. Set expiration (EXPIRE)
-# 3. Update indexes
-# 4. Add to instances collection
-```
-
-**Benefits:**
-- Eliminates race conditions during save operations
-- Ensures data consistency across related operations
-- Better performance with fewer round trips
-
-### Enhanced Timestamp Precision
-
-**What Changed:**
-
-Created/updated timestamps now use float values instead of integers for higher precision:
-
-**Before:**
-```ruby
-user.created  # => 1697234567 (integer seconds)
-```
-
-**After:**
-```ruby
-user.created  # => 1697234567.123 (float with milliseconds)
-```
-
-**Migration:**
-
-No code changes needed. Existing integer timestamps continue to work.
-
-## Redis Command Enhancements
-
-### New Commands Available
-
-Added support for optimistic locking commands:
-- `watch(key)` - Watch key for changes
-- `unwatch()` - Remove all watches
-- `discard()` - Discard queued commands
-
-### Improved Command Logging
-
-Database command logging now includes:
-- Structured format for better readability
-- Pipelined operation tracking
-- Transaction boundary markers
-- Command timing information
-
-## Terminology Updates
-
-**What Changed:**
-
-Standardized on "pipelined" terminology throughout (previously mixed "pipeline"/"pipelined").
-
-**Files Affected:**
-- Method names now consistently use "pipelined"
-- Documentation updated to match Redis terminology
-- Log messages standardized
-
-**Migration:**
-
-No code changes needed - this was an internal consistency improvement.
-
-## Recommended Actions
-
-1. **Update method calls:**
-   ```ruby
-   # Replace all instances
-   Model.create(...)      → Model.create!(...)
-   obj.save_if_not_exists → obj.save_if_not_exists!
-   ```
-
-2. **Review error handling:**
-   ```ruby
-   # Consider more specific error handling
-   rescue Familia::CreationError
-   rescue Familia::OptimisticLockError
-   ```
-
-3. **Test concurrent operations:**
-   - The new optimistic locking provides better concurrency handling
-   - Verify your application handles `OptimisticLockError` appropriately
-
-4. **Review logging:**
-   - Enhanced database command logging may affect log volume
-   - Adjust log levels if needed for production environments

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)