familia 2.0.0.pre12 → 2.0.0.pre13

data/docs/guides/Feature-System-Autoloading.md

@@ -0,0 +1,228 @@
+# Feature System Autoloading
+
+## Overview
+
+Familia's feature system includes an autoloading mechanism that automatically discovers and loads feature-specific extension files when features are included in your classes. This allows you to keep your main model files clean while organizing feature-specific configurations in separate files.
+
+## The Problem It Solves
+
+When you include a feature like `safe_dump` in a Familia class:
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump  # This line should trigger autoloading
+end
+```
+
+You want to be able to define the safe dump configuration in a separate file:
+
+```ruby
+# user/safe_dump_extensions.rb
+class User
+  safe_dump_fields :name, :email  # Don't dump :password
+end
+```
+
+But there's a **timing problem**: when should this extension file be loaded?
+
+## Why Standard `included` Hook Doesn't Work
+
+The original approach tried to use the standard `included` hook:
+
+```ruby
+module SafeDump
+  def self.included(base)
+    # Try to autoload here - BUT THIS IS TOO EARLY!
+    autoload_files_for(base)
+  end
+end
+```
+
+**Problem**: This happens **during** the feature inclusion process, before the feature is fully set up. The class isn't in a stable state yet.
+
+## The Solution: Post-Inclusion Hook
+
+The `post_inclusion_autoload` system works in **two phases**:
+
+### Phase 1: Feature System Hook
+
+In `lib/familia/features.rb`, after including the feature module:
+
+```ruby
+def feature(feature_name, **options)
+  # ... setup code ...
+
+  include feature_class  # Include the feature module
+
+  # NOW call the post-inclusion hook
+  if feature_class.respond_to?(:post_inclusion_autoload)
+    feature_class.post_inclusion_autoload(self, feature_name, options)
+  end
+end
+```
+
+### Phase 2: Autoloadable Implementation
+
+The `post_inclusion_autoload` method in `lib/familia/features/autoloadable.rb`:
+
+1. **Gets the source location** of the user's class file using Ruby's introspection:
+   ```ruby
+   location_info = Module.const_source_location(base.name)
+   source_location = location_info&.first  # e.g., "/path/to/models/user.rb"
+   ```
+
+2. **Calculates extension file paths** based on conventions:
+   ```ruby
+   base_dir = File.dirname(location_path)  # "/path/to/models"
+   model_name = base.name.snake_case       # "user"
+
+   # Look for files like:
+   patterns = [
+     "/path/to/models/user/safe_dump_*.rb",
+     "/path/to/models/user/features/safe_dump_*.rb",
+     "/path/to/models/features/safe_dump_*.rb"
+   ]
+   ```
+
+3. **Loads any matching files** found in those locations
+
+## Why This Timing Matters
+
+```ruby
+class User < Familia::Horreum
+  feature :safe_dump  # ← Timing is critical here
+end
+```
+
+**What happens in order:**
+
+1. `feature :safe_dump` is called
+2. Feature system includes `Familia::Features::SafeDump` module
+3. **Feature is now fully included and stable**
+4. `post_inclusion_autoload` is called
+5. Extension files are discovered and loaded
+6. `safe_dump_fields :name, :email` executes in the extension file
+
+## File Naming Conventions
+
+The autoloading system looks for files matching these patterns (in order of precedence):
+
+1. `{model_directory}/{model_name}/{feature_name}_*.rb`
+2. `{model_directory}/{model_name}/features/{feature_name}_*.rb`
+3. `{model_directory}/features/{feature_name}_*.rb`
+
+### Examples
+
+For a `User` class defined in `app/models/user.rb` with `feature :safe_dump`:
+
+```
+app/models/user/safe_dump_extensions.rb     # ← Most specific
+app/models/user/safe_dump_config.rb         # ← Also matches pattern
+app/models/user/features/safe_dump_*.rb     # ← Feature subdirectory
+app/models/features/safe_dump_*.rb          # ← Shared feature configs
+```
+
+## Complete Example
+
+### Main Model File
+
+```ruby
+# app/models/user.rb
+class User < Familia::Horreum
+  field :name
+  field :email
+  field :password
+  field :created_at
+
+  feature :safe_dump  # ← Triggers autoloading
+  feature :expiration
+end
+```
+
+### Safe Dump Extensions
+
+```ruby
+# app/models/user/safe_dump_extensions.rb
+class User
+  # Configure which fields are safe to dump in API responses
+  safe_dump_fields :name, :email, :created_at
+  # Note: :password is intentionally excluded for security
+
+  def safe_dump_display_name
+    "#{name} (#{email})"
+  end
+end
+```
+
+### Expiration Extensions
+
+```ruby
+# app/models/user/expiration_config.rb
+class User
+  # Set default TTL for user objects
+  expires_in 30.days
+
+  # Custom expiration logic
+  def should_expire?
+    !active? && last_login_at < 90.days.ago
+  end
+end
+```
+
+### Result
+
+After loading, the `User` class has:
+- `User.safe_dump_field_names` returns `[:name, :email, :created_at]`
+- `User.ttl` returns the configured expiration
+- All extension methods are available on instances
+
+## Key Benefits
+
+1. **Separation of Concerns**: Main model file focuses on core definition, extension files handle feature-specific configuration
+
+2. **Convention Over Configuration**: No manual requires, just follow naming conventions
+
+3. **Safe Timing**: Extension files load after the feature is fully set up
+
+4. **Thread Safe**: No shared state between classes
+
+5. **Discoverable**: Clear file organization makes extensions easy to find
+
+## Why It's Better Than Alternatives
+
+- **Manual requires**: Error-prone, verbose, easy to forget
+- **Configuration blocks**: Clutters the main model file
+- **Included hook**: Wrong timing, class not stable yet
+- **Class_eval strings**: Complex, hard to debug and maintain
+
+The `post_inclusion_autoload` system provides a clean, automatic, and safe way to extend feature behavior without polluting the main class definitions.
+
+## Implementation Details
+
+### Autoloadable Module
+
+Features that support autoloading include the `Familia::Features::Autoloadable` module:
+
+```ruby
+module Familia::Features::SafeDump
+  include Familia::Features::Autoloadable  # ← Enables autoloading
+
+  # Feature implementation...
+end
+```
+
+### Anonymous Class Handling
+
+The system gracefully handles edge cases:
+
+- **Anonymous classes**: Classes without names (e.g., `Class.new`) are skipped
+- **Eval contexts**: Classes defined in `eval` or irb are skipped
+- **Missing files**: No errors if extension files don't exist
+
+### Error Handling
+
+- Missing extension files are silently ignored
+- Syntax errors in extension files propagate normally
+- `NameError` during constant resolution is caught and logged
+
+This robust error handling ensures the autoloading system never breaks your application, even with unusual class definitions or missing files.

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/v2.0.0-pre11.md

@@ -102,7 +102,7 @@ end
 
 ### Before: Manual Loading
 ```ruby
-# apps/api/v2/models/customer/features.rb
+# customer/features.rb
 
 # Manual feature loading (copied from Familia)
 features_dir = File.join(__dir__, 'features')
@@ -112,29 +112,26 @@ if Dir.exist?(features_dir)
   end
 end
 
-module V2
-  class Customer < Familia::Horreum
-    # Features now available for use
-    feature :deprecated_fields
-  end
+class Customer < Familia::Horreum
+  # Features now available for use
+  feature :deprecated_fields
 end
 ```
 
 ### After: Automatic Loading
 ```ruby
-# apps/api/v2/models/customer/features.rb
-module V2::Customer
+# customer/features.rb
+
+class Customer < Familia::Horreum
   module Features
-    include Familia::Features::Autoloader
+    include Familia::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
+class Customer < Familia::Horreum
+  # Features automatically loaded and available
+  feature :deprecated_fields
 end
 ```
 
@@ -162,6 +159,7 @@ Feature modules can now define fields directly in their `ClassMethods` modules.
 ### Example
 ```ruby
 # features/common_fields.rb
+
 module CommonFields
   def self.included(base)
     base.extend ClassMethods
@@ -210,9 +208,9 @@ If you have project-specific features, set up auto-loading:
 ```ruby
 # Create: models/[model_name]/features.rb
 module YourProject
-  module ModelName
+  class ModelName < Familia::Horreum
     module Features
-      include Familia::Features::Autoloader
+      include Familia::Autoloader
     end
   end
 end