familia 2.0.0.pre13 → 2.0.0.pre14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca101edcf531af301428b4b29bc83f464a84e47339a9d67f1b8a70ead828aa74
-  data.tar.gz: 56255e7fbc191f8c15b75d5cab0a990b83c3e54fe07362f1b20dbf392edca65d
+  metadata.gz: 21e0d1d581a958fbf3492579039d9190764a83fb4add2a47fe3eb23d2d27ef2b
+  data.tar.gz: 9cda237209e910633ddcb9a7605cecb291eb66825de05aacd3bc6522168d220b
 SHA512:
-  metadata.gz: d92e09f275bcf262a73afe443fa5e099fff6c0836502de52d485358ec1f5d5a095878fe69ff9c4d5fcdbe26aa00c404474418cc72e9748b10d783ded2942e1b5
-  data.tar.gz: 2e22b89f457a6b188b31820e794960a5ad288c406ad7550fc47f48501489394fb891c966f7e147fe2b89b8d2eaa36b736258b75184a0aee5e5aa2aaf63ac6878
+  metadata.gz: 65cda30c3f3f96c0315c03f200dff37b507474d9a6367c6ce03b899450fd041403263ce6a5bfdb318bc90120c59234190e07548e576a522f92bcb4718dba6a55
+  data.tar.gz: 7a14a093a0fd83bce0e1fd08be41b98c4c418352d1d4210937cc3473f29264e1bf3dae2b671dee18c89b75faeb3a8e38b93ebf55632bba696da8653eb91b4eb3

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.
 
 - 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
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre13)
+    familia (2.0.0.pre14)
       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/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-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::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]

data/lib/familia/features/expiration.rb

@@ -149,7 +149,7 @@ module Familia
     module Expiration
       @default_expiration = nil
 
-      using Familia::Refinements::TimeUtils
+      using Familia::Refinements::TimeLiterals
 
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?

data/lib/familia/features/external_identifier.rb

@@ -99,7 +99,7 @@ module Familia
             klass.define_method :"#{method_name}=" do |value|
               # Remove old mapping if extid is changing
               old_value = instance_variable_get(:"@#{field_name}")
-              self.class.extid_lookup.del(old_value) if old_value && old_value != value && respond_to?(:identifier)
+              self.class.extid_lookup.remove_field(old_value) if old_value && old_value != value
 
               # Set the new value
               instance_variable_set(:"@#{field_name}", value)
@@ -153,7 +153,7 @@ module Familia
           find_by_id(primary_id)
         rescue Familia::NotFound
           # If the object was deleted but mapping wasn't cleaned up
-          extid_lookup.del(extid)
+          extid_lookup.remove_field(extid)
           nil
         end
       end
@@ -236,7 +236,7 @@ module Familia
       def destroy!
         # Clean up extid mapping when object is destroyed
         current_extid = instance_variable_get(:@extid)
-        self.class.extid_lookup.del(current_extid) if current_extid
+        self.class.extid_lookup.remove_field(current_extid) if current_extid
 
         super if defined?(super)
       end

data/lib/familia/features/quantization.rb

@@ -246,7 +246,7 @@ module Familia
     #
     module Quantization
 
-      using Familia::Refinements::TimeUtils
+      using Familia::Refinements::TimeLiterals
 
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?

data/lib/familia/field_type.rb

@@ -29,7 +29,7 @@ module Familia
   class FieldType
     attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Initialize a new field type
     #

data/lib/familia/horreum.rb

@@ -31,7 +31,7 @@ module Familia
     include Familia::Horreum::Core
     include Familia::Horreum::Settings
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Singleton Class Context
     #

data/lib/familia/refinements/{time_utils.rb → time_literals.rb}

@@ -1,10 +1,41 @@
-# lib/familia/refinements/time_utils.rb
+# lib/familia/refinements/time_literals.rb
 
 module Familia
   module Refinements
 
-    # Familia::Refinements::TimeUtils
-    module TimeUtils
+    # Familia::Refinements::TimeLiterals
+    #
+    # This module provides a set of refinements for `Numeric` and `String` to
+    # enable readable and expressive time duration and timestamp manipulation.
+    #
+    # The name "TimeLiterals" reflects its core purpose: to allow us to treat
+    # numeric values directly as "literals" of time units (e.g., `5.minutes`,
+    # `1.day`). It extends this concept to include conversions between these
+    # literal time quantities, parsing string representations of time
+    # durations, and performing common timestamp-based calculations
+    # in an intuitive manner.
+    #
+    # @example Expressing durations
+    #   5.minutes.ago           #=> A Time object 5 minutes in the past
+    #   1.day.from_now          #=> A Time object 1 day in the future
+    #   (2.5).hours             #=> 9000.0 (seconds)
+    #
+    # @example Converting between units
+    #   3600.in_hours           #=> 1.0
+    #   86400.in_days           #=> 1.0
+    #
+    # @example Parsing string durations
+    #   "30m".in_seconds        #=> 1800.0
+    #   "2.5h".in_seconds       #=> 9000.0
+    #
+    # @example Timestamp calculations
+    #   timestamp = 2.days.ago.to_i
+    #   timestamp.days_old      #=> ~2.0
+    #   timestamp.older_than?(1.day) #=> true
+    #
+    # @note `to_bytes` also lives here until we find it a better home!
+    #
+    module TimeLiterals
       # Time unit constants
       PER_MICROSECOND = 0.000001
       PER_MILLISECOND = 0.001
@@ -65,7 +96,7 @@ module Familia
         alias_method :month,       :months
         alias_method :year,        :years
 
-        # Fun aliases
+        # Shortest aliases
         alias_method :ms, :milliseconds
         alias_method :μs, :microseconds
 

data/lib/familia/refinements.rb

@@ -2,4 +2,4 @@
 
 require_relative 'refinements/logger_trace'
 require_relative 'refinements/snake_case'
-require_relative 'refinements/time_utils'
+require_relative 'refinements/time_literals'

data/lib/familia/utils.rb

@@ -6,7 +6,7 @@ module Familia
   #
   module Utils
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Joins array elements with Familia delimiter
     # @param val [Array] elements to join

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre13'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre14'.freeze unless defined?(Familia::VERSION)
 end

data/try/core/extensions_try.rb

@@ -1,7 +1,7 @@
 require_relative '../helpers/test_helpers'
 
 module RefinedContext
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   # This helper evaluates code within the refined context using eval.
   # This works because eval executes the code as if it were written

data/try/core/time_utils_try.rb

@@ -1,7 +1,7 @@
 require_relative '../helpers/test_helpers'
 
 module RefinedContext
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   def self.eval_in_refined_context(code)
     eval(code)
@@ -12,7 +12,7 @@ module RefinedContext
   end
 end
 
-# Test TimeUtils refinement
+# Test TimeLiterals refinement
 
 ## Numeric#months - convert number to months in seconds
 result = RefinedContext.eval_in_refined_context("1.month")
@@ -34,7 +34,7 @@ RefinedContext.instance_eval_in_refined_context("2629746.in_months")
 #=> 1.0
 
 ## Numeric#in_years - convert seconds to years
-result = RefinedContext.eval_in_refined_context("#{Familia::Refinements::TimeUtils::PER_YEAR}.in_years")
+result = RefinedContext.eval_in_refined_context("#{Familia::Refinements::TimeLiterals::PER_YEAR}.in_years")
 result.round(1)
 #=> 1.0
 
@@ -52,75 +52,75 @@ result.round(0)
 #=> 31556952.0
 
 ## Numeric#age_in - calculate age in months from timestamp (approximately 1 month ago)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_MONTH
 result = RefinedContext.eval_in_refined_context("#{timestamp}.age_in(:months)")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## Numeric#age_in - calculate age in years from timestamp (approximately 1 year ago)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_YEAR
 result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.age_in(:years)")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## Numeric#months_old - convenience method for age_in(:months)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_MONTH
 result = RefinedContext.eval_in_refined_context("#{timestamp}.months_old")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## Numeric#years_old - convenience method for age_in(:years)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_YEAR
 result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.years_old")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## Numeric#months_old - should NOT return seconds (the original bug)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_MONTH
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_MONTH
 result = RefinedContext.eval_in_refined_context("#{timestamp}.months_old")
 result.between?(0.9, 1.1)  # Should be ~1 month, not millions of seconds
 #=> true
 
 ## Numeric#years_old - should NOT return seconds (the original bug)
-timestamp = Time.now.to_f - Familia::Refinements::TimeUtils::PER_YEAR
+timestamp = Time.now.to_f - Familia::Refinements::TimeLiterals::PER_YEAR
 result = RefinedContext.instance_eval_in_refined_context("#{timestamp}.years_old")
 result.between?(0.9, 1.1)  # Should be ~1 year, not millions of seconds
 #=> true
 
 ## age_in with from_time parameter - months
-past_time = Time.now - (2 * Familia::Refinements::TimeUtils::PER_MONTH)  # 2 months ago
-from_time = Time.now - Familia::Refinements::TimeUtils::PER_MONTH  # 1 month ago
+past_time = Time.now - (2 * Familia::Refinements::TimeLiterals::PER_MONTH)  # 2 months ago
+from_time = Time.now - Familia::Refinements::TimeLiterals::PER_MONTH  # 1 month ago
 result = RefinedContext.eval_in_refined_context("#{past_time.to_f}.age_in(:months, #{from_time.to_f})")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## age_in with from_time parameter - years
-past_time = Time.now - (2 * Familia::Refinements::TimeUtils::PER_YEAR)  # 2 years ago
-from_time = Time.now - Familia::Refinements::TimeUtils::PER_YEAR  # 1 year ago
+past_time = Time.now - (2 * Familia::Refinements::TimeLiterals::PER_YEAR)  # 2 years ago
+from_time = Time.now - Familia::Refinements::TimeLiterals::PER_YEAR  # 1 year ago
 result = RefinedContext.instance_eval_in_refined_context("#{past_time.to_f}.age_in(:years, #{from_time.to_f})")
 (result - 1.0).abs < 0.01
 #=> true
 
 ## Verify month constant is approximately correct (30.437 days)
 expected_seconds_per_month = 30.437 * 24 * 60 * 60
-Familia::Refinements::TimeUtils::PER_MONTH.round(0)
+Familia::Refinements::TimeLiterals::PER_MONTH.round(0)
 #=> 2629746.0
 
 ## Verify year constant (365.2425 days - Gregorian year)
 expected_seconds_per_year = 365.2425 * 24 * 60 * 60
-Familia::Refinements::TimeUtils::PER_YEAR.round(0)
+Familia::Refinements::TimeLiterals::PER_YEAR.round(0)
 #=> 31556952.0
 
 ## UNIT_METHODS contains months mapping
-Familia::Refinements::TimeUtils::UNIT_METHODS['months']
+Familia::Refinements::TimeLiterals::UNIT_METHODS['months']
 #=> :months
 
 ## UNIT_METHODS contains mo mapping
-Familia::Refinements::TimeUtils::UNIT_METHODS['mo']
+Familia::Refinements::TimeLiterals::UNIT_METHODS['mo']
 #=> :months
 
 ## UNIT_METHODS contains month mapping
-Familia::Refinements::TimeUtils::UNIT_METHODS['month']
+Familia::Refinements::TimeLiterals::UNIT_METHODS['month']
 #=> :months
 
 ## Calendar consistency - 12 months equals 1 year (fix for inconsistency issue)

data/try/features/external_identifier/external_identifier_try.rb

@@ -198,3 +198,29 @@ ExternalIdTest.extid_lookup[@test_obj.extid]
 
 # Cleanup test objects
 @test_obj.destroy! rescue nil
+
+## Test 1: Changing extid value (should work after bug fix)
+bug_test_obj = ExternalIdTest.new(id: 'bug_test', name: 'Bug Test Object')
+bug_test_obj.save
+bug_test_obj.extid = 'new_extid_value'
+bug_test_obj.extid
+#=> "new_extid_value"
+
+## Test 2: find_by_extid with deleted object (should work after bug fix)
+delete_test_obj = ExternalIdTest.new(id: 'delete_test', name: 'Delete Test')
+delete_test_obj.save
+test_extid = delete_test_obj.extid
+# Delete the object directly from Redis to simulate cleanup scenario
+ExternalIdTest.dbclient.del(delete_test_obj.dbkey)
+# Now try to find by extid - this should clean up mapping and return nil
+ExternalIdTest.find_by_extid(test_extid)
+#=> nil
+
+## Test 3: destroy! method (should work after bug fix)
+destroy_test_obj = ExternalIdTest.new(id: 'destroy_test', name: 'Destroy Test')
+destroy_test_obj.save
+destroy_extid = destroy_test_obj.extid
+destroy_test_obj.destroy!
+# Verify mapping was cleaned up
+ExternalIdTest.extid_lookup.key?(destroy_extid)
+#=> false

data/try/helpers/test_helpers.rb

@@ -12,7 +12,7 @@ Familia.enable_database_logging = true
 Familia.enable_database_counter = true
 
 class Bone < Familia::Horreum
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   identifier_field :token
   field     :token
@@ -42,7 +42,7 @@ end
 
 class Customer < Familia::Horreum
 
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   logical_database 15 # Use something other than the default DB
   default_expiration 5.years
@@ -106,7 +106,7 @@ end
 @c.custid = 'd@example.com'
 
 class Session < Familia::Horreum
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   logical_database 14 # don't use Onetime's default DB
   default_expiration 180.minutes
@@ -130,7 +130,7 @@ end
 @s = Session.new
 
 class CustomDomain < Familia::Horreum
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   feature :expiration
 
@@ -161,7 +161,7 @@ end
 @d.custid = @c.custid
 
 class Limiter < Familia::Horreum
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   feature :expiration
   feature :quantization
@@ -243,7 +243,7 @@ end
 
 # Helper module for testing refinements in tryouts
 module RefinedContext
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   def self.eval_in_refined_context(code)
     eval(code)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre13
+  version: 2.0.0.pre14
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -180,6 +180,7 @@ files:
 - docs/migrating/v2.0.0-pre11.md
 - docs/migrating/v2.0.0-pre12.md
 - docs/migrating/v2.0.0-pre13.md
+- docs/migrating/v2.0.0-pre14.md
 - docs/migrating/v2.0.0-pre5.md
 - docs/migrating/v2.0.0-pre6.md
 - docs/migrating/v2.0.0-pre7.md
@@ -255,7 +256,7 @@ files:
 - lib/familia/refinements.rb
 - lib/familia/refinements/logger_trace.rb
 - lib/familia/refinements/snake_case.rb
-- lib/familia/refinements/time_utils.rb
+- lib/familia/refinements/time_literals.rb
 - lib/familia/secure_identifier.rb
 - lib/familia/settings.rb
 - lib/familia/utils.rb