Skip to content

Add development-friendly class reloading support to avoid "already defined" errors #92

@delano

Description

@delano

Problem

When reloading Familia model classes during development (e.g., via load in IRB), the system throws ArgumentError for already defined methods:

irb> load 'examples/autoloader/mega_customer.rb'
# => true (first time)

irb> load 'examples/autoloader/mega_customer.rb'  
# ArgumentError: Method >>> custid <<< already defined for MegaCustomer

This makes iterative development and debugging difficult, requiring IRB restarts to test class changes.

Root Cause

  1. Familia field definitions create getter/setter methods via define_method
  2. On reload, the class constant still exists with previously defined methods
  3. FieldType#handle_method_conflict defaults to :raise strategy
  4. Ruby 3.2+ changes around class redefinition make this behavior more prominent

Proposed Solution

Add opt-in reloading support using Ruby's remove_const for clean class unloading:

1. Reloadable Feature Module (lib/familia/features/reloadable.rb)

  • Provides reload! and unload! class methods
  • Handles constant removal and file reloading
  • Tracks source file locations

2. Development Helper Utilities (lib/familia/reload_helper.rb)

  • IRB-friendly methods: Familia.reload_class(klass_or_path)
  • Class tracking and management
  • Safe constant removal patterns

3. Enhanced Examples

  • Demonstrate proper reloading workflow
  • Show feature usage in development

Usage Example

class MegaCustomer < Familia::Horreum
  include Familia::Features::Reloadable
  field :custid
  field :username
  # ...
end

# In IRB development:
MegaCustomer.reload!  # Cleanly reloads from source file
# Or using helper:
Familia.reload_class('examples/autoloader/mega_customer.rb')

Design Principles

  • Preserve intentional behavior: Keep default error-raising for production safety
  • Opt-in only: No changes to existing field definition behavior
  • Ruby 3.2+ idiomatic: Use remove_const following modern Ruby patterns
  • Development-focused: Designed for IRB/console workflows, not automatic reloading

Technical Details

See technical analysis in Serena memory class-reloading-technical-analysis for comprehensive implementation details, Ruby 3.2+ considerations, ORM pattern research, and detailed architecture specifications.

Benefits

  • Faster development iteration cycles
  • No more IRB restarts for class changes
  • Maintains production safety guarantees
  • Follows Ruby community best practices
  • Zero performance impact on production code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions