familia 2.0.0.pre10 → 2.0.0.pre13

data/docs/guides/time-utilities.md

@@ -0,0 +1,221 @@
+# Time Utilities Guide
+
+Familia provides a comprehensive time utilities refinement that adds convenient time conversion and age calculation methods to Ruby's `Numeric` and `String` classes.
+
+## Overview
+
+The `Familia::Refinements::TimeUtils` module extends Ruby's built-in classes with intuitive time manipulation methods:
+
+```ruby
+using Familia::Refinements::TimeUtils
+
+2.hours        #=> 7200 (seconds)
+"30m".in_seconds  #=> 1800
+timestamp.days_old  #=> 5.2
+```
+
+## Time Constants
+
+Familia uses **Gregorian year** calculations for consistent time conversions:
+
+```ruby
+PER_YEAR  = 31_556_952.0  # 365.2425 days (accounts for leap years)
+PER_MONTH = 2_629_746.0   # PER_YEAR / 12 (30.437 days)
+PER_WEEK  = 604_800.0     # 7 days
+PER_DAY   = 86_400.0      # 24 hours
+```
+
+### Why Gregorian Year?
+
+The key design decision ensures **mathematical consistency**:
+
+```ruby
+12.months == 1.year  #=> true (both equal 31,556,952 seconds)
+```
+
+This prevents subtle bugs where `12.months` and `1.year` would differ by ~5.8 hours.
+
+## Basic Time Conversions
+
+### Converting Numbers to Time Units
+
+```ruby
+using Familia::Refinements::TimeUtils
+
+# Singular and plural forms work identically
+1.second   #=> 1
+30.seconds #=> 30
+5.minutes  #=> 300
+2.hours    #=> 7200
+3.days     #=> 259200
+1.week     #=> 604800
+2.months   #=> 5259492
+1.year     #=> 31556952
+```
+
+### Converting Time Units Back
+
+```ruby
+7200.in_hours     #=> 2.0
+259200.in_days    #=> 3.0
+5259492.in_months #=> 2.0
+31556952.in_years #=> 1.0
+```
+
+## String Time Parsing
+
+Parse human-readable time strings:
+
+```ruby
+"30s".in_seconds    #=> 30.0
+"5m".in_seconds     #=> 300.0
+"2h".in_seconds     #=> 7200.0
+"1d".in_seconds     #=> 86400.0
+"1w".in_seconds     #=> 604800.0
+"2mo".in_seconds    #=> 5259492.0
+"1y".in_seconds     #=> 31556952.0
+```
+
+### Supported String Formats
+
+| Unit | Abbreviations | Example |
+|------|---------------|---------|
+| Microseconds | `us`, `μs`, `microsecond`, `microseconds` | `"500us"` |
+| Milliseconds | `ms`, `millisecond`, `milliseconds` | `"250ms"` |
+| Seconds | `s`, `second`, `seconds` | `"30s"` |
+| Minutes | `m`, `minute`, `minutes` | `"15m"` |
+| Hours | `h`, `hour`, `hours` | `"2h"` |
+| Days | `d`, `day`, `days` | `"7d"` |
+| Weeks | `w`, `week`, `weeks` | `"2w"` |
+| Months | `mo`, `month`, `months` | `"6mo"` |
+| Years | `y`, `year`, `years` | `"1y"` |
+
+**Note**: Use `"mo"` for months to avoid confusion with `"m"` (minutes).
+
+## Age Calculations
+
+Calculate how old timestamps are:
+
+```ruby
+# Basic age calculation
+old_timestamp = 2.days.ago.to_i
+old_timestamp.age_in(:days)    #=> ~2.0
+old_timestamp.age_in(:hours)   #=> ~48.0
+old_timestamp.age_in(:months)  #=> ~0.066
+
+# Convenience methods
+old_timestamp.days_old     #=> ~2.0
+old_timestamp.hours_old    #=> ~48.0
+old_timestamp.minutes_old  #=> ~2880.0
+old_timestamp.weeks_old    #=> ~0.28
+old_timestamp.months_old   #=> ~0.066
+old_timestamp.years_old    #=> ~0.005
+
+# Calculate age from specific reference time
+past_timestamp = 1.week.ago.to_i
+reference_time = 3.days.ago
+past_timestamp.age_in(:days, reference_time)  #=> ~4.0
+```
+
+## Time Comparisons
+
+```ruby
+timestamp = 2.hours.ago.to_i
+
+# Check if older than duration
+timestamp.older_than?(1.hour)   #=> true
+timestamp.older_than?(3.hours)  #=> false
+
+# Check if newer than duration (future)
+future_timestamp = 1.hour.from_now.to_i
+future_timestamp.newer_than?(30.minutes)  #=> true
+
+# Check if within duration of now (past or future)
+timestamp.within?(3.hours)      #=> true
+timestamp.within?(1.hour)       #=> false
+```
+
+## Practical Examples
+
+### Cache Expiration
+
+```ruby
+using Familia::Refinements::TimeUtils
+
+class CacheEntry < Familia::Horreum
+  field :data
+  field :created_at
+
+  def expired?
+    created_at.to_i.older_than?(1.hour)
+  end
+
+  def cache_age
+    created_at.to_i.minutes_old
+  end
+end
+```
+
+### Session Management
+
+```ruby
+class UserSession < Familia::Horreum
+  field :last_active
+
+  def stale?
+    last_active.to_i.older_than?(30.minutes)
+  end
+
+  def session_duration
+    "Active for #{last_active.to_i.hours_old.round(1)} hours"
+  end
+end
+```
+
+### Data Retention
+
+```ruby
+def cleanup_old_logs
+  Log.all.select do |log|
+    log.timestamp.to_i.older_than?(30.days)
+  end.each(&:destroy)
+end
+```
+
+## Important Notes
+
+### Calendar vs. Precise Time
+
+Familia's time utilities use **average durations** suitable for:
+- Age calculations
+- Cache expiration
+- Time-based cleanup
+- General time arithmetic
+
+For **calendar-aware operations** (exact months, leap years), use Ruby's `Date`/`Time` classes:
+
+```ruby
+# For average durations (Familia)
+user_age = signup_date.to_i.months_old  #=> 6.2
+
+# For exact calendar operations (Ruby stdlib)
+exact_months = Date.today.months_since(signup_date)  #=> 6
+```
+
+### Thread Safety
+
+All time utility methods are thread-safe and work with frozen objects.
+
+## Migration from v1.x
+
+If upgrading from earlier versions:
+
+```ruby
+# Old behavior (inconsistent)
+12.months != 1.year  # Different values
+
+# New behavior (consistent)
+12.months == 1.year  # Same value: 31,556,952 seconds
+```
+
+Update any code that relied on the old 365-day year constant to expect the new Gregorian year values.

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,253 @@
+# 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
+# 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
+
+class Customer < Familia::Horreum
+  # Features now available for use
+  feature :deprecated_fields
+end
+```
+
+### After: Automatic Loading
+```ruby
+# customer/features.rb
+
+class Customer < Familia::Horreum
+  module Features
+    include Familia::Autoloader
+    # Automatically discovers and loads all *.rb files from customer/features/
+  end
+end
+
+class Customer < Familia::Horreum
+  # Features automatically loaded and available
+  feature :deprecated_fields
+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
+  class ModelName < Familia::Horreum
+    module Features
+      include Familia::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