familia 2.0.0.pre13 → 2.0.0.pre15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca101edcf531af301428b4b29bc83f464a84e47339a9d67f1b8a70ead828aa74
-  data.tar.gz: 56255e7fbc191f8c15b75d5cab0a990b83c3e54fe07362f1b20dbf392edca65d
+  metadata.gz: 00416beac08786c1fffd75a0c2578669c6a0d18169824ca1a23e9122018a386b
+  data.tar.gz: c38f7bfe985a7d6151abf2ce4b6d7ca32ddb97adf8d069880f7e919662937851
 SHA512:
-  metadata.gz: d92e09f275bcf262a73afe443fa5e099fff6c0836502de52d485358ec1f5d5a095878fe69ff9c4d5fcdbe26aa00c404474418cc72e9748b10d783ded2942e1b5
-  data.tar.gz: 2e22b89f457a6b188b31820e794960a5ad288c406ad7550fc47f48501489394fb891c966f7e147fe2b89b8d2eaa36b736258b75184a0aee5e5aa2aaf63ac6878
+  metadata.gz: a3d6a60c86460578567fbd6f33e96c8ae0ee2dbfc80f3ffc6f123dc6fb84c6020efd359601122e63543c0128401d235587e9770df8acbbfa1f55cb908a012e07
+  data.tar.gz: 5062f93d7494df05a6d62dade395a0522ca8ab02afd4fdc5a00ee21db08b05ace8c3227d07739ef7cdd727fa72888ea4ec415491eb60028b25166d107d574e8e

data/CHANGELOG.rst

@@ -12,6 +12,28 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre14:
+
+2.0.0.pre14 — 2025-09-08
+========================
+
+Changed
+-------
+
+- **BREAKING CHANGE**: Renamed ``Familia::Refinements::TimeUtils`` to ``Familia::Refinements::TimeLiterals`` to better reflect the module's primary purpose of enabling numeric and string values to be treated as time unit literals (e.g., ``5.minutes``, ``"30m".in_seconds``). Functionality remains the same - only the module name has changed. Users must update their refinement usage from ``using Familia::Refinements::TimeUtils`` to ``using Familia::Refinements::TimeLiterals``.
+
+Fixed
+-----
+
+- Fixed ExternalIdentifier HashKey method calls by replacing incorrect ``.del()`` calls with ``.remove_field()`` in three critical locations: extid setter (cleanup old mapping when changing value), find_by_extid (cleanup orphaned mapping when object not found), and destroy! (cleanup mapping when object is destroyed). Added comprehensive test coverage for all scenarios to prevent regression. PR #100
+
+AI Assistance
+-------------
+
+- Claude Code helped rename TimeUtils to TimeLiterals throughout the codebase, including module name, file path, all usage references, and updating existing documentation.
+- Gemini 2.5 Flash wrote the inline docs for TimeLiterals based on a discussion re: naming rationale.
+- Claude Code fixed the ExternalIdentifier HashKey method bug, replacing incorrect ``.del()`` calls with proper ``.remove_field()`` calls, and implemented test coverage for the affected scenarios.
+
 .. _changelog-2.0.0.pre13:
 
 2.0.0.pre13 — 2025-09-07
@@ -20,13 +42,13 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 Added
 -----
 
-- **Feature-specific autoloading**: Features can now automatically discover and load extension files from your project directories. When you include a feature like ``safe_dump``, Familia searches for configuration files using conventional patterns like ``{model_name}/{feature_name}_*.rb``, enabling clean separation between core model definitions and feature-specific configurations.
+- **Feature Autoloading System**: Features can now automatically discover and load extension files from your project directories. When you include a feature like ``safe_dump``, Familia searches for configuration files using conventional patterns like ``{model_name}/{feature_name}_*.rb``, enabling clean separation between core model definitions and feature-specific configurations. See ``docs/migrating/v2.0.0-pre13.md`` for migration details.
 
-- **Consolidated autoloader architecture**: Introduced ``Familia::Autoloader`` as a shared utility for consistent file loading patterns across the framework, supporting both general-purpose and feature-specific autoloading scenarios.
+- **Consolidated autoloader architecture**: Introduced ``Familia::Features::Autoloader`` as a shared utility for consistent file loading patterns across the framework, supporting both general-purpose and feature-specific autoloading scenarios.
 
 - Added ``PER_MONTH`` constant (2,629,746 seconds = 30.437 days) derived from Gregorian year for consistent month calculations.
 - Added ``months``, ``month``, and ``in_months`` conversion methods to Numeric refinement.
-- Added month unit mappings (``'mo'``, ``'month'``, ``'months'``) to TimeUtils ``UNIT_METHODS`` hash.
+- Added month unit mappings (``'mo'``, ``'month'``, ``'months'``) to TimeLiterals ``UNIT_METHODS`` hash.
 
 - **Error Handling**: Added ``NotSupportedError`` for invalid serialization mode combinations in encryption subsystem. PR #97
 
@@ -34,7 +56,7 @@ Changed
 -------
 
 - Refactored time and numeric extensions from global monkey patches to proper Ruby refinements for better encapsulation and reduced global namespace pollution
-- Updated all internal classes to use refinements via ``using Familia::Refinements::TimeUtils`` statements
+- Updated all internal classes to use refinements via ``using Familia::Refinements::TimeLiterals`` statements
 - Added centralized ``RefinedContext`` module in test helpers to support refinement testing in tryouts files
 
 - Updated ``PER_YEAR`` constant to use Gregorian year (31,556,952 seconds = 365.2425 days) for calendar consistency.
@@ -49,7 +71,7 @@ Fixed
 - Fixed byte conversion logic in ``to_bytes`` method to correctly handle exact 1024-byte boundaries (``size >= 1024`` instead of ``size > 1024``)
 - Resolved refinement testing issues in tryouts by implementing ``eval``-based code execution within refined contexts
 
-- Fixed TimeUtils refinement ``months_old`` and ``years_old`` methods returning incorrect values (raw seconds instead of months/years). The underlying ``age_in`` method now properly handles ``:months`` and ``:years`` units. Issue #94.
+- Fixed TimeLiterals refinement ``months_old`` and ``years_old`` methods returning incorrect values (raw seconds instead of months/years). The underlying ``age_in`` method now properly handles ``:months`` and ``:years`` units. Issue #94.
 - Fixed calendar consistency issue where ``12.months != 1.year`` by updating ``PER_YEAR`` to use Gregorian year (365.2425 days) and defining ``PER_MONTH`` as ``PER_YEAR / 12``.
 
 Security
@@ -72,7 +94,7 @@ AI Assistance
 
 - Significant AI assistance in architectural design and implementation of the feature-specific autoloading system, including pattern matching logic, Ruby introspection methods, and comprehensive debugging of edge cases and thread safety considerations.
 
-- Claude Code assisted with implementing the fix for broken ``months_old`` and ``years_old`` methods in the TimeUtils refinement, including analysis, implementation, testing, and documentation.
+- Claude Code assisted with implementing the fix for broken ``months_old`` and ``years_old`` methods in the TimeLiterals refinement, including analysis, implementation, testing, and documentation.
 
 - Performance optimization research and OJ gem integration strategy, including compatibility analysis and testing approach for seamless stdlib JSON replacement. PR #97
 
@@ -161,7 +183,7 @@ Added
    with ancestry chain traversal for model-specific feature
    registration. This enables better organization, standardized naming,
    and automatic loading of project-specific features via the new
-   ``Familia::Autoloader`` module.
+   ``Familia::Features::Autoloader`` module.
 -  **Improved SafeDump DSL**: Replaced the internal
    ``@safe_dump_fields`` implementation with a cleaner, more robust DSL
    using ``safe_dump_field`` and ``safe_dump_fields`` methods.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre13)
+    familia (2.0.0.pre15)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)

data/README.md

@@ -170,7 +170,26 @@ All relationships support automatic indexing and tracking - objects are automati
 
 ## Organizing Complex Models
 
-For large applications, you can organize model complexity using custom features:
+For large applications, you can organize model complexity using custom features and the Feature Autoloading System:
+
+### Feature Autoloading System
+
+Familia automatically discovers and loads feature-specific configuration files, enabling clean separation between core model definitions and feature configurations:
+
+```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  # password excluded for security
+end
+```
+
+Extension files follow the pattern: `{model_name}/{feature_name}_*.rb`
 
 ### Self-Registering Features
 
@@ -201,7 +220,7 @@ class Customer < Familia::Horreum
 end
 ```
 
-This keeps complex models organized while maintaining Familia's clean, declarative style.
+These approaches keep complex models organized while maintaining Familia's clean, declarative style. For detailed migration information, see the [migration guides](docs/migrating/).
 
 ## AI Development Assistance
 

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

@@ -44,7 +44,7 @@ end
 
 The `post_inclusion_autoload` system works in **two phases**:
 
-### Phase 1: Feature System Hook
+### Feature System Hook
 
 In `lib/familia/features.rb`, after including the feature module:
 
@@ -61,29 +61,6 @@ def feature(feature_name, **options)
 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
@@ -199,17 +176,10 @@ The `post_inclusion_autoload` system provides a clean, automatic, and safe way t
 
 ## Implementation Details
 
-### Autoloadable Module
+### Autoloader
 
-Features that support autoloading include the `Familia::Features::Autoloadable` module:
+Looks for features files in models/features.rb, models/features/, models/model_name/features.rb, models/model_name/features/
 
-```ruby
-module Familia::Features::SafeDump
-  include Familia::Features::Autoloadable  # ← Enables autoloading
-
-  # Feature implementation...
-end
-```
 
 ### Anonymous Class Handling
 

data/docs/guides/time-utilities.md

@@ -4,10 +4,10 @@ Familia provides a comprehensive time utilities refinement that adds convenient
 
 ## Overview
 
-The `Familia::Refinements::TimeUtils` module extends Ruby's built-in classes with intuitive time manipulation methods:
+The `Familia::Refinements::TimeLiterals` module extends Ruby's built-in classes with intuitive time manipulation methods:
 
 ```ruby
-using Familia::Refinements::TimeUtils
+using Familia::Refinements::TimeLiterals
 
 2.hours        #=> 7200 (seconds)
 "30m".in_seconds  #=> 1800
@@ -40,7 +40,7 @@ This prevents subtle bugs where `12.months` and `1.year` would differ by ~5.8 ho
 ### Converting Numbers to Time Units
 
 ```ruby
-using Familia::Refinements::TimeUtils
+using Familia::Refinements::TimeLiterals
 
 # Singular and plural forms work identically
 1.second   #=> 1
@@ -140,7 +140,7 @@ timestamp.within?(1.hour)       #=> false
 ### Cache Expiration
 
 ```ruby
-using Familia::Refinements::TimeUtils
+using Familia::Refinements::TimeLiterals
 
 class CacheEntry < Familia::Horreum
   field :data

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

@@ -124,7 +124,7 @@ end
 
 class Customer < Familia::Horreum
   module Features
-    include Familia::Autoloader
+    include Familia::Features::Autoloader
     # Automatically discovers and loads all *.rb files from customer/features/
   end
 end
@@ -210,7 +210,7 @@ If you have project-specific features, set up auto-loading:
 module YourProject
   class ModelName < Familia::Horreum
     module Features
-      include Familia::Autoloader
+      include Familia::Features::Autoloader
     end
   end
 end

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

@@ -1,320 +1,86 @@
 # Migrating Guide: v2.0.0-pre13
 
-This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects through automatic discovery and loading of feature-specific configuration files.
+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-Specific Autoloading System
+## Feature Autoloading System
 
-### Overview
+### What Changed
 
-The new autoloading system allows features to automatically discover and load extension files from your project directories. When you include a feature in your model, Familia now searches for configuration files using conventional patterns, enabling clean separation between core model definitions and feature-specific configurations.
+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 Usage
+### Basic Migration
 
-#### Before (Manual Configuration)
+#### Before
 ```ruby
 # app/models/user.rb
 class User < Familia::Horreum
   field :name, :email, :password
 
   feature :safe_dump
-  # All configuration had to be done in the same file
-  safe_dump_fields :name, :email  # password excluded for security
+  safe_dump_fields :name, :email  # Configuration mixed with model
 end
 ```
 
-#### After (Automatic Discovery)
+#### After
 ```ruby
 # app/models/user.rb - Clean model definition
 class User < Familia::Horreum
   field :name, :email, :password
-  feature :safe_dump  # ← Triggers autoloading
+  feature :safe_dump  # Configuration auto-loaded
 end
 
-# app/models/user/safe_dump_extensions.rb - Automatically loaded
+# app/models/user/safe_dump_extensions.rb - Automatically discovered
 class User
-  safe_dump_fields :name, :email  # password excluded for security
+  safe_dump_fields :name, :email
 end
 ```
 
-### File Naming Conventions
-
-The autoloading system follows these patterns for discovering extension files:
+### File Naming Convention
 
-#### Pattern: `{model_name}/{feature_name}_*.rb`
+Extension files follow the pattern: `{model_name}/{feature_name}_*.rb`
 
-**Example Structures:**
 ```
 app/models/
-├── user.rb                              # Main model
+├── user.rb
 ├── user/
-│   ├── safe_dump_extensions.rb          # SafeDump configuration
-│   ├── safe_dump_custom.rb              # Additional SafeDump setup
-│   └── relationships_config.rb          # Relationships configuration
-├── product.rb                           # Another model
-└── product/
-    ├── safe_dump_fields.rb              # Product's SafeDump config
-    └── expiration_settings.rb           # Expiration configuration
-```
-
-#### Supported Patterns
-- `safe_dump_extensions.rb`
-- `safe_dump_*.rb` (any filename starting with the feature name)
-- `expiration_config.rb`
-- `relationships_setup.rb`
-
-### Advanced Configuration Examples
-
-#### Complex SafeDump Setup
-```ruby
-# app/models/customer.rb
-class Customer < Familia::Horreum
-  field :first_name, :last_name, :email, :phone
-  field :credit_card_number, :ssn, :internal_notes
-
-  feature :safe_dump
-end
-
-# app/models/customer/safe_dump_configuration.rb
-class Customer
-  # Define which fields are safe for API responses
-  safe_dump_fields :first_name, :last_name, :email
-
-  # Custom serialization for specific fields
-  def safe_dump_email
-    email&.downcase
-  end
-
-  # Computed fields for API
-  def safe_dump_full_name
-    "#{first_name} #{last_name}".strip
-  end
-end
-```
-
-#### Multi-Feature Organization
-```ruby
-# app/models/session.rb
-class Session < Familia::Horreum
-  field :user_id, :token, :ip_address, :user_agent
-
-  feature :safe_dump
-  feature :expiration
-end
-
-# app/models/session/safe_dump_api.rb
-class Session
-  safe_dump_fields :user_id, :ip_address
-  # token excluded for security
-end
-
-# app/models/session/expiration_policy.rb
-class Session
-  # Sessions expire after 24 hours
-  def self.default_ttl
-    24 * 60 * 60
-  end
-
-  # Cascade expiration to related data
-  cascade_expiration_to :user_sessions
-end
-```
-
-### Consolidated Autoloader Architecture
-
-#### Familia::Autoloader
-
-The new `Familia::Autoloader` class provides a shared utility for consistent file loading patterns across the framework:
-
-```ruby
-# Internal usage example (you typically won't call this directly)
-autoloader = Familia::Autoloader.new(
-  base_class: User,
-  feature_name: :safe_dump,
-  search_patterns: ['user/safe_dump_*.rb']
-)
-
-# Discovers and loads matching files
-autoloader.discover_and_load_extensions
-```
-
-#### Autoloading Strategies
-
-The autoloader supports multiple discovery strategies:
-
-1. **Directory-based**: Search in conventional directories
-2. **Pattern-based**: Use glob patterns for flexible matching
-3. **Explicit paths**: Load specific files when found
-
-### How Autoloading Works
-
-#### Discovery Process
-
-1. **Feature Activation**: When `feature :safe_dump` is called
-2. **Path Resolution**: Autoloader determines search paths based on model location
-3. **Pattern Matching**: Searches for files matching `{model_name}/{feature_name}_*.rb`
-4. **File Loading**: Loads discovered files in alphabetical order
-5. **Extension Application**: Feature-specific methods become available
-
-#### Search Locations
-
-The autoloader searches in these locations (in order):
-
-```ruby
-# If your model is in app/models/user.rb, it searches:
-[
-  'app/models/user/',           # Same directory as model
-  'lib/user/',                  # Lib directory
-  'config/models/user/',        # Config directory
-  './user/'                     # Current directory
-]
+│   ├── safe_dump_extensions.rb    # SafeDump configuration
+│   └── expiration_config.rb       # Expiration settings
 ```
 
 ### Migration Steps
 
-#### 1. Reorganize Existing Models
-
-Move feature-specific configuration to separate files:
-
-```bash
-# Create directories for feature configurations
-mkdir -p app/models/user
-mkdir -p app/models/product
-mkdir -p app/models/order
-
-# Move configurations
-# From app/models/user.rb, extract safe_dump configuration to:
-# app/models/user/safe_dump_extensions.rb
-```
-
-#### 2. Update Model Files
+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
 
-Clean up your main model files:
+### Debugging
 
+Enable debug output to troubleshoot autoloading:
 ```ruby
-# Before: Everything in one file
-class User < Familia::Horreum
-  field :name, :email, :password, :role
-
-  feature :safe_dump
-  safe_dump_fields :name, :email
-
-  feature :expiration
-  def self.default_ttl
-    86400
-  end
-end
-
-# After: Clean separation
-class User < Familia::Horreum
-  field :name, :email, :password, :role
-
-  feature :safe_dump    # Configuration auto-loaded
-  feature :expiration   # Configuration auto-loaded
-end
-```
-
-#### 3. Create Extension Files
-
-Set up your feature-specific configurations:
-
-```ruby
-# app/models/user/safe_dump_extensions.rb
-class User
-  safe_dump_fields :name, :email
-  # password and role excluded for security
-end
-
-# app/models/user/expiration_config.rb
-class User
-  def self.default_ttl
-    86400  # 24 hours
-  end
-end
+ENV['FAMILIA_DEBUG'] = '1'  # Shows discovered and loaded files
 ```
 
-### Benefits of the New System
+Common issues:
+- Files must follow `{feature_name}_*.rb` naming pattern
+- Extension files should reopen the same class as your model
 
-#### Code Organization
-- **Separation of Concerns**: Feature logic separated from core model definition
-- **Maintainability**: Easier to find and modify feature-specific code
-- **Readability**: Core models are cleaner and more focused
+## Architecture
 
-#### Team Development
-- **Reduced Conflicts**: Multiple developers can work on different features without merge conflicts
-- **Feature Ownership**: Clear boundaries for feature-specific code
-- **Testing**: Easier to test features in isolation
+The Feature Autoloading System consists of two key components:
 
-#### Scalability
-- **Large Models**: Complex models remain manageable
-- **Feature Growth**: New features can be added without bloating main model files
-- **Refactoring**: Easier to extract and reorganize feature code
+### 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
 
-### Debugging Autoloading
-
-#### Enable Debug Output
-
-```ruby
-# In your application initialization
-ENV['FAMILIA_DEBUG'] = '1'
+### 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
 
-# Or programmatically
-Familia::Features::Autoloadable.debug = true
-```
-
-#### Debug Output Example
-```
-[Familia::Autoloader] Searching for User safe_dump extensions...
-[Familia::Autoloader] Found: app/models/user/safe_dump_extensions.rb
-[Familia::Autoloader] Loading: app/models/user/safe_dump_extensions.rb
-[Familia::Autoloader] SafeDump extension loaded successfully for User
-```
-
-#### Troubleshooting
-
-**Common Issues:**
-
-1. **File Not Found**: Ensure file naming follows the `{feature_name}_*.rb` pattern
-2. **Load Order**: Files are loaded alphabetically; prefix with numbers if order matters
-3. **Class Scope**: Extension files should reopen the same class as your model
-
-**Validation:**
-```ruby
-# Check if autoloading worked
-User.respond_to?(:safe_dump_field_names)  # => true
-User.safe_dump_field_names                # => [:name, :email]
-```
-
-### Backward Compatibility
-
-The autoloading system is fully backward compatible:
-
-- **Existing Models**: Continue to work without changes
-- **Manual Configuration**: Still supported alongside autoloading
-- **Gradual Migration**: You can migrate models one at a time
-
-### Performance Considerations
-
-- **Load Time**: Files are loaded once during feature activation
-- **Memory Usage**: No additional memory overhead after loading
-- **Caching**: Discovered files are cached to avoid repeated filesystem scans
-
-### Testing Your Migration
-
-```ruby
-# Test that autoloading is working
-class TestUser < Familia::Horreum
-  field :name, :email
-  feature :safe_dump
-end
-
-# Verify extension methods are available
-puts TestUser.respond_to?(:safe_dump_field_names)
-puts TestUser.safe_dump_field_names.inspect
-
-# Test instance methods
-user = TestUser.new(name: "John", email: "john@example.com")
-puts user.safe_dump.inspect
-```
+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
 

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

@@ -0,0 +1,37 @@
+# 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/examples/safe_dump.rb

@@ -273,7 +273,7 @@ puts "LegacyModel fields after set_safe_dump_fields: #{LegacyModel.safe_dump_fie
 puts
 puts '=== Cleaning up test data ==='
 [User, Product, Order, Address, Customer, LegacyModel].each do |klass|
-  klass.redis.del(klass.redis.keys("#{klass.name.downcase}:*"))
+  klass.dbclient.del(klass.dbclient.keys("#{klass.name.downcase}:*"))
 rescue StandardError => e
   puts "Error cleaning #{klass}: #{e.message}"
 end

data/lib/familia/base.rb

@@ -15,7 +15,7 @@ module Familia
   #
   module Base
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     @features_available = nil
     @feature_definitions = nil

data/lib/familia/data_type.rb

@@ -16,7 +16,7 @@ module Familia
     include Familia::Base
     extend Familia::Features
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     @registered_types = {}
     @valid_options = %i[class parent default_expiration default logical_database dbkey dbclient suffix prefix]