familia 2.0.0.pre24 → 2.0.0.pre25

data/try/features/relationships/class_level_multi_index_auto_try.rb

@@ -0,0 +1,318 @@
+# try/features/relationships/class_level_multi_index_auto_try.rb
+#
+# frozen_string_literal: true
+
+# Tests for class-level multi_index auto-indexing and helper methods
+#
+# This file tests:
+# 1. Auto-indexing on save - objects should automatically be added to class-level indexes
+# 2. Index updates when field values change
+# 3. Helper methods (update_all_indexes, remove_from_all_indexes, current_indexings)
+#
+# Auto-indexing for class-level indexes (within: :class) should work similarly
+# to unique_index (within: nil), calling add_to_class_* methods on save.
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test class for auto-indexing with class-level multi_index
+class ::AutoIndexCustomer < Familia::Horreum
+  feature :relationships
+  include Familia::Features::Relationships::Indexing
+
+  identifier_field :custid
+  field :custid
+  field :name
+  field :status
+  field :tier
+
+  # Class-level multi_index (within: :class is default)
+  multi_index :status, :status_index
+
+  # Explicit within: :class for second index
+  multi_index :tier, :tier_index, within: :class
+
+  # Track instances for rebuild testing
+  class_sorted_set :instances, class: self, reference: true
+end
+
+# Clean up stale data from previous runs
+%w[active pending inactive premium standard basic].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.tier_index_for(value).dbkey)
+end
+# Clean up any stale customer objects
+%w[auto_001 auto_002 auto_003 auto_004 auto_nil auto_empty auto_ws].each do |custid|
+  existing = AutoIndexCustomer.find_by_identifier(custid, check_exists: false)
+  existing&.delete! if existing&.exists?
+end
+
+# =============================================
+# 1. Auto-Indexing on Save Tests
+# =============================================
+
+## New object saved - auto-indexed in status_index
+@auto1 = AutoIndexCustomer.new(custid: 'auto_001', name: 'AutoAlice', status: 'active', tier: 'premium')
+@auto1.save
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> true
+
+## Auto-indexing works for tier_index too (explicit within: :class)
+AutoIndexCustomer.tier_index_for('premium').members.include?('auto_001')
+#=> true
+
+## Second object saved - joins same status index
+@auto2 = AutoIndexCustomer.new(custid: 'auto_002', name: 'AutoBob', status: 'active', tier: 'standard')
+@auto2.save
+AutoIndexCustomer.status_index_for('active').members.sort
+#=> ["auto_001", "auto_002"]
+
+## Different tier index is separate
+AutoIndexCustomer.tier_index_for('standard').members
+#=> ["auto_002"]
+
+## Object with different status creates new index entry
+@auto3 = AutoIndexCustomer.new(custid: 'auto_003', name: 'AutoCharlie', status: 'pending', tier: 'basic')
+@auto3.save
+AutoIndexCustomer.status_index_for('pending').members
+#=> ["auto_003"]
+
+## Active status index unchanged by new pending customer
+AutoIndexCustomer.status_index_for('active').size
+#=> 2
+
+# =============================================
+# 2. Query After Auto-Indexing
+# =============================================
+
+## find_all_by_status returns auto-indexed customers
+active_customers = AutoIndexCustomer.find_all_by_status('active')
+active_customers.map(&:custid).sort
+#=> ["auto_001", "auto_002"]
+
+## sample_from_status works with auto-indexed data
+sample = AutoIndexCustomer.sample_from_status('active', 1)
+['auto_001', 'auto_002'].include?(sample.first&.custid)
+#=> true
+
+## find_all_by_tier returns correct customers
+premium_customers = AutoIndexCustomer.find_all_by_tier('premium')
+premium_customers.map(&:custid)
+#=> ["auto_001"]
+
+# =============================================
+# 3. Field Change and Index Update
+# =============================================
+
+## Change status field and save - verify old index is NOT automatically updated
+# Note: auto_update_class_indexes calls add_to_class_*, which is idempotent
+# but does NOT remove from old index. Manual update is needed for field changes.
+@old_status = @auto1.status
+@auto1.status = 'inactive'
+@auto1.save
+
+# After save, customer is added to new index
+AutoIndexCustomer.status_index_for('inactive').members.include?('auto_001')
+#=> true
+
+## Old index still contains the entry (save doesn't auto-remove from old)
+# This is expected behavior - save is idempotent add, not update
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> true
+
+## Use update_in_class_status_index to properly move between indexes
+@auto1.update_in_class_status_index(@old_status)
+AutoIndexCustomer.status_index_for('active').members.include?('auto_001')
+#=> false
+
+## Customer now only in inactive index
+AutoIndexCustomer.status_index_for('inactive').members
+#=> ["auto_001"]
+
+# =============================================
+# 4. Helper Methods - update_all_indexes
+# =============================================
+
+## update_all_indexes method exists
+@auto2.respond_to?(:update_all_indexes)
+#=> true
+
+## update_all_indexes updates both status and tier indexes
+@old_values = { status: @auto2.status, tier: @auto2.tier }
+@auto2.status = 'pending'
+@auto2.tier = 'premium'
+@auto2.update_all_indexes(@old_values)
+
+# Check status index updated
+AutoIndexCustomer.status_index_for('active').members.include?('auto_002')
+#=> false
+
+## New status index contains customer
+AutoIndexCustomer.status_index_for('pending').members.include?('auto_002')
+#=> true
+
+## Old tier index no longer contains customer
+AutoIndexCustomer.tier_index_for('standard').members.include?('auto_002')
+#=> false
+
+## New tier index contains customer
+AutoIndexCustomer.tier_index_for('premium').members.include?('auto_002')
+#=> true
+
+# =============================================
+# 5. Helper Methods - remove_from_all_indexes
+# =============================================
+
+## remove_from_all_indexes method exists
+@auto3.respond_to?(:remove_from_all_indexes)
+#=> true
+
+## Verify customer is in indexes before removal
+[
+  AutoIndexCustomer.status_index_for('pending').members.include?('auto_003'),
+  AutoIndexCustomer.tier_index_for('basic').members.include?('auto_003')
+]
+#=> [true, true]
+
+## remove_from_all_indexes removes from all class-level indexes
+@auto3.remove_from_all_indexes
+[
+  AutoIndexCustomer.status_index_for('pending').members.include?('auto_003'),
+  AutoIndexCustomer.tier_index_for('basic').members.include?('auto_003')
+]
+#=> [false, false]
+
+# =============================================
+# 6. Helper Methods - current_indexings
+# =============================================
+
+## current_indexings method exists
+@auto1.respond_to?(:current_indexings)
+#=> true
+
+## Re-add auto1 to indexes for testing current_indexings
+@auto1.add_to_class_status_index
+@auto1.add_to_class_tier_index
+@indexings = @auto1.current_indexings
+@indexings.length
+#=> 2
+
+## current_indexings returns correct info for status_index
+@status_indexing = @indexings.find { |i| i[:index_name] == :status_index }
+[@status_indexing[:field], @status_indexing[:cardinality], @status_indexing[:type]]
+#=> [:status, :multi, "multi_index"]
+
+## current_indexings returns correct info for tier_index
+@tier_indexing = @indexings.find { |i| i[:index_name] == :tier_index }
+[@tier_indexing[:field], @tier_indexing[:cardinality], @tier_indexing[:type]]
+#=> [:tier, :multi, "multi_index"]
+
+## current_indexings shows scope_class for class-level indexes
+@status_indexing[:scope_class]
+#=> "class"
+
+# =============================================
+# 7. Helper Methods - indexed_in?
+# =============================================
+
+## indexed_in? method exists
+@auto1.respond_to?(:indexed_in?)
+#=> true
+
+## indexed_in? returns true for indexes where customer is present
+@auto1.indexed_in?(:status_index)
+#=> true
+
+## indexed_in? returns true for tier_index too
+@auto1.indexed_in?(:tier_index)
+#=> true
+
+## indexed_in? returns false for non-existent index
+@auto1.indexed_in?(:nonexistent_index)
+#=> false
+
+## After removal, indexed_in? returns false
+@auto1.remove_from_class_status_index
+@auto1.indexed_in?(:status_index)
+#=> false
+
+# =============================================
+# 8. Delete and Index Cleanup
+# =============================================
+
+## Create a new customer for delete testing
+@auto4 = AutoIndexCustomer.new(custid: 'auto_004', name: 'AutoDiana', status: 'active', tier: 'standard')
+@auto4.save
+AutoIndexCustomer.status_index_for('active').members.include?('auto_004')
+#=> true
+
+## Delete does NOT automatically remove from indexes (by design)
+# Applications should call remove_from_all_indexes before delete if needed
+@auto4.delete!
+AutoIndexCustomer.status_index_for('active').members.include?('auto_004')
+#=> true
+
+## Manual cleanup required after delete
+# Note: This tests that stale entries exist until explicitly cleaned
+# The find_by methods handle stale entries gracefully
+stale_customer = AutoIndexCustomer.find_by_identifier('auto_004')
+stale_customer
+#=> nil
+
+# =============================================
+# 9. Edge Cases
+# =============================================
+
+## Nil field value - should not be indexed
+@auto_nil = AutoIndexCustomer.new(custid: 'auto_nil', name: 'NilStatus', status: nil, tier: 'basic')
+@auto_nil.save
+# Should not create an entry in the nil index (empty string key)
+AutoIndexCustomer.status_index_for('').members.include?('auto_nil')
+#=> false
+
+## Empty string field value - should not be indexed
+@auto_empty = AutoIndexCustomer.new(custid: 'auto_empty', name: 'EmptyStatus', status: '', tier: 'basic')
+@auto_empty.save
+AutoIndexCustomer.status_index_for('').members.include?('auto_empty')
+#=> false
+
+## Whitespace-only field value - should not be indexed
+@auto_ws = AutoIndexCustomer.new(custid: 'auto_ws', name: 'WSStatus', status: '   ', tier: 'basic')
+@auto_ws.save
+AutoIndexCustomer.status_index_for('   ').members.include?('auto_ws')
+#=> false
+
+# =============================================
+# 10. Idempotent Save Behavior
+# =============================================
+
+## Saving same object multiple times doesn't duplicate index entries
+@auto2.save
+@auto2.save
+@auto2.save
+# Should still only have one entry
+AutoIndexCustomer.status_index_for(@auto2.status).members.count { |m| m == 'auto_002' }
+#=> 1
+
+## UnsortedSet inherently prevents duplicates
+AutoIndexCustomer.status_index_for('pending').size
+#=> 1
+
+# Teardown
+# Clean up test objects
+[@auto1, @auto2, @auto3, @auto_nil, @auto_empty, @auto_ws].compact.each do |obj|
+  obj.delete! if obj.respond_to?(:exists?) && obj.exists?
+end
+
+# Clean up index keys
+%w[active pending inactive premium standard basic].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.tier_index_for(value).dbkey)
+end
+
+# Clean up edge case indexes
+['', '   '].each do |value|
+  AutoIndexCustomer.dbclient.del(AutoIndexCustomer.status_index_for(value).dbkey)
+end
+
+# Clean up instances collection
+AutoIndexCustomer.instances.clear if AutoIndexCustomer.respond_to?(:instances)

data/try/features/relationships/class_level_multi_index_rebuild_try.rb

@@ -0,0 +1,393 @@
+# try/features/relationships/class_level_multi_index_rebuild_try.rb
+#
+# frozen_string_literal: true
+
+# Tests for class-level multi_index rebuild functionality
+# This feature allows rebuilding of multi-value indexes at the class level.
+#
+# The rebuild method:
+# - Enumerates all instances via class_sorted_set :instances
+# - Clears existing index sets using SCAN
+# - Rebuilds indexes from current field values
+# - Supports progress callbacks for monitoring
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test class with class-level multi_index and instances collection
+class ::RebuildCustomer < Familia::Horreum
+  feature :relationships
+  include Familia::Features::Relationships::Indexing
+
+  identifier_field :custid
+  field :custid
+  field :name
+  field :tier  # premium, standard, free
+
+  class_sorted_set :instances, reference: true  # Required for rebuild
+
+  multi_index :tier, :tier_index
+end
+
+# Test class without instances collection (for prerequisite testing)
+class ::RebuildCustomerNoInstances < Familia::Horreum
+  feature :relationships
+  include Familia::Features::Relationships::Indexing
+
+  identifier_field :custid
+  field :custid
+  field :tier
+
+  multi_index :tier, :tier_index
+end
+
+# Clean up any stale data from previous runs
+%w[premium standard free vip obsolete].each do |tier|
+  RebuildCustomer.dbclient.del(RebuildCustomer.tier_index_for(tier).dbkey)
+end
+RebuildCustomer.instances.clear
+
+# Setup - create test customers with various tiers
+@cust1 = RebuildCustomer.new(custid: 'rc_001', name: 'Alice', tier: 'premium')
+@cust1.save
+@cust2 = RebuildCustomer.new(custid: 'rc_002', name: 'Bob', tier: 'standard')
+@cust2.save
+@cust3 = RebuildCustomer.new(custid: 'rc_003', name: 'Charlie', tier: 'premium')
+@cust3.save
+@cust4 = RebuildCustomer.new(custid: 'rc_004', name: 'Diana', tier: 'free')
+@cust4.save
+@cust5 = RebuildCustomer.new(custid: 'rc_005', name: 'Eve', tier: 'standard')
+@cust5.save
+
+# Register instances
+RebuildCustomer.instances.add(@cust1.identifier)
+RebuildCustomer.instances.add(@cust2.identifier)
+RebuildCustomer.instances.add(@cust3.identifier)
+RebuildCustomer.instances.add(@cust4.identifier)
+RebuildCustomer.instances.add(@cust5.identifier)
+
+# Manually add to indexes for initial state
+@cust1.add_to_class_tier_index
+@cust2.add_to_class_tier_index
+@cust3.add_to_class_tier_index
+@cust4.add_to_class_tier_index
+@cust5.add_to_class_tier_index
+
+# =============================================
+# 1. Rebuild Method Existence
+# =============================================
+
+## Rebuild method is generated on the class
+RebuildCustomer.respond_to?(:rebuild_tier_index)
+#=> true
+
+## Rebuild method accepts optional batch_size parameter
+RebuildCustomer.method(:rebuild_tier_index).parameters.any? { |type, name| name == :batch_size }
+#=> true
+
+# =============================================
+# 2. Basic Rebuild Functionality
+# =============================================
+
+## Verify initial index state before clearing
+RebuildCustomer.tier_index_for('premium').size
+#=> 2
+
+## Clear indexes to simulate corruption or need for rebuild
+%w[premium standard free].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+RebuildCustomer.tier_index_for('premium').size
+#=> 0
+
+## Rebuild returns count of processed objects
+count = RebuildCustomer.rebuild_tier_index
+count
+#=> 5
+
+## Premium tier has correct count after rebuild
+RebuildCustomer.tier_index_for('premium').size
+#=> 2
+
+## Standard tier has correct count after rebuild
+RebuildCustomer.tier_index_for('standard').size
+#=> 2
+
+## Free tier has correct count after rebuild
+RebuildCustomer.tier_index_for('free').size
+#=> 1
+
+## Find all by tier works after rebuild
+premiums = RebuildCustomer.find_all_by_tier('premium')
+premiums.map(&:custid).sort
+#=> ["rc_001", "rc_003"]
+
+## All tiers are correctly populated
+standards = RebuildCustomer.find_all_by_tier('standard')
+standards.map(&:custid).sort
+#=> ["rc_002", "rc_005"]
+
+## Free tier query returns correct customer
+frees = RebuildCustomer.find_all_by_tier('free')
+frees.map(&:custid)
+#=> ["rc_004"]
+
+# =============================================
+# 3. Rebuild with Progress Callback
+# =============================================
+
+## Clear indexes for progress test
+%w[premium standard free].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+
+## Rebuild accepts progress block and store updates in instance variable
+@progress_updates = []
+count = RebuildCustomer.rebuild_tier_index { |progress| @progress_updates << progress.dup }
+count
+#=> 5
+
+## Progress callback receives updates
+@progress_updates.size > 0
+#=> true
+
+## Progress updates include loading phase and store in instance variable
+@loading_updates = @progress_updates.select { |p| p[:phase] == :loading }
+@loading_updates.any?
+#=> true
+
+## Progress updates include clearing phase
+@clearing_updates = @progress_updates.select { |p| p[:phase] == :clearing }
+@clearing_updates.any?
+#=> true
+
+## Progress updates include rebuilding phase and store in instance variable
+@rebuilding_updates = @progress_updates.select { |p| p[:phase] == :rebuilding }
+@rebuilding_updates.any?
+#=> true
+
+## Loading phase includes total count
+@loading_updates.last[:total]
+#=> 5
+
+## Rebuilding phase shows completion
+@rebuilding_updates.last[:current]
+#=> 5
+
+## Rebuilding phase total matches expected
+@rebuilding_updates.last[:total]
+#=> 5
+
+# =============================================
+# 4. Rebuild with Empty Instances Collection
+# =============================================
+
+## Class with empty instances has rebuild method
+RebuildCustomerNoInstances.respond_to?(:rebuild_tier_index)
+#=> true
+
+## Class with empty instances returns 0 on rebuild (no objects to process)
+result = RebuildCustomerNoInstances.rebuild_tier_index
+result
+#=> 0
+
+# =============================================
+# 5. Rebuild with Multiple Field Values
+# =============================================
+
+## Clear indexes before field value update test
+%w[premium standard free vip].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+
+## Update customer tier values to VIP and save
+@cust1.tier = 'vip'
+@cust1.save
+@cust3.tier = 'vip'
+@cust3.save
+true
+#=> true
+
+## Verify the tier change persisted by reloading
+reloaded = RebuildCustomer.find_by_identifier(@cust1.identifier)
+reloaded.tier
+#=> "vip"
+
+## Rebuild reflects updated field values
+count = RebuildCustomer.rebuild_tier_index
+count
+#=> 5
+
+## VIP tier has correct count after tier changes
+RebuildCustomer.tier_index_for('vip').size
+#=> 2
+
+## Premium tier is empty after customers moved to VIP
+RebuildCustomer.tier_index_for('premium').size
+#=> 0
+
+## Find all VIP customers works correctly
+vips = RebuildCustomer.find_all_by_tier('vip')
+vips.map(&:custid).sort
+#=> ["rc_001", "rc_003"]
+
+## Other tiers remain correct after partial update
+RebuildCustomer.tier_index_for('standard').size
+#=> 2
+
+## Free tier remains correct
+RebuildCustomer.tier_index_for('free').size
+#=> 1
+
+# =============================================
+# 6. Rebuild with Orphaned Index Cleanup
+# =============================================
+
+## Create orphaned index entry (stale data from a tier that no longer exists)
+RebuildCustomer.tier_index_for('obsolete').add('rc_001')
+RebuildCustomer.tier_index_for('obsolete').size
+#=> 1
+
+## Rebuild cleans up orphaned indexes via SCAN
+RebuildCustomer.rebuild_tier_index
+RebuildCustomer.tier_index_for('obsolete').size
+#=> 0
+
+## Valid indexes still exist after cleanup
+RebuildCustomer.tier_index_for('vip').size
+#=> 2
+
+# =============================================
+# 7. Rebuild with nil/empty Field Values
+# =============================================
+
+## Create customer with nil tier
+@cust_nil = RebuildCustomer.new(custid: 'rc_nil', name: 'NilTier', tier: nil)
+@cust_nil.save
+RebuildCustomer.instances.add(@cust_nil.identifier)
+true
+#=> true
+
+## Create customer with empty tier
+@cust_empty = RebuildCustomer.new(custid: 'rc_empty', name: 'EmptyTier', tier: '')
+@cust_empty.save
+RebuildCustomer.instances.add(@cust_empty.identifier)
+true
+#=> true
+
+## Verify instances count is now 7
+RebuildCustomer.instances.size
+#=> 7
+
+## Clear and rebuild
+%w[vip standard free].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+
+## Rebuild processes all instances (including nil/empty)
+count = RebuildCustomer.rebuild_tier_index
+count
+#=> 7
+
+## Only valid tiers are indexed (nil/empty skipped)
+total_indexed = RebuildCustomer.tier_index_for('vip').size +
+                RebuildCustomer.tier_index_for('standard').size +
+                RebuildCustomer.tier_index_for('free').size
+total_indexed
+#=> 5
+
+## Nil tier index is empty
+RebuildCustomer.tier_index_for('').size
+#=> 0
+
+# =============================================
+# 8. Rebuild with Stale Instance References
+# =============================================
+
+## Add stale reference to instances collection
+RebuildCustomer.instances.add('stale_customer_id')
+RebuildCustomer.instances.size
+#=> 8
+
+## Rebuild handles stale references gracefully (loads 7 real objects, stale ID filtered out)
+count = RebuildCustomer.rebuild_tier_index
+count
+#=> 7
+
+## Index remains consistent despite stale reference (only 5 valid objects with tiers)
+RebuildCustomer.tier_index_for('vip').size
+#=> 2
+
+# =============================================
+# 9. Multiple Consecutive Rebuilds
+# =============================================
+
+## First rebuild (7 loadable objects from 8 instances)
+count1 = RebuildCustomer.rebuild_tier_index
+count1
+#=> 7
+
+## Second rebuild
+count2 = RebuildCustomer.rebuild_tier_index
+count2
+#=> 7
+
+## Third rebuild
+count3 = RebuildCustomer.rebuild_tier_index
+count3
+#=> 7
+
+## Index remains consistent after multiple rebuilds
+RebuildCustomer.tier_index_for('vip').size
+#=> 2
+
+## All expected VIP customers still findable
+vips = RebuildCustomer.find_all_by_tier('vip')
+vips.map(&:custid).sort
+#=> ["rc_001", "rc_003"]
+
+# =============================================
+# 10. Rebuild with batch_size Parameter
+# =============================================
+
+## Clear indexes
+%w[vip standard free].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+
+## Rebuild with small batch size (7 loadable objects from 8 instances)
+count = RebuildCustomer.rebuild_tier_index(batch_size: 1)
+count
+#=> 7
+
+## Index works correctly with small batch size
+RebuildCustomer.tier_index_for('vip').size
+#=> 2
+
+## Clear and rebuild with large batch size
+%w[vip standard free].each do |tier|
+  RebuildCustomer.tier_index_for(tier).clear
+end
+
+## Rebuild with large batch size (7 loadable objects from 8 instances)
+count = RebuildCustomer.rebuild_tier_index(batch_size: 1000)
+count
+#=> 7
+
+## Index works correctly with large batch size
+RebuildCustomer.find_all_by_tier('standard').map(&:custid).sort
+#=> ["rc_002", "rc_005"]
+
+# Teardown
+@cust1&.delete!
+@cust2&.delete!
+@cust3&.delete!
+@cust4&.delete!
+@cust5&.delete!
+@cust_nil&.delete!
+@cust_empty&.delete!
+
+# Clean up index keys
+%w[premium standard free vip obsolete].each do |tier|
+  RebuildCustomer.dbclient.del(RebuildCustomer.tier_index_for(tier).dbkey)
+end
+RebuildCustomer.instances.clear