familia 2.0.0.pre17 → 2.0.0.pre19

data/try/unit/horreum/unique_index_edge_cases_try.rb

@@ -0,0 +1,376 @@
+# Testing edge cases for unique index validation
+# lib/familia/features/relationships/indexing/unique_index_generators.rb
+# lib/familia/horreum/persistence.rb
+
+require_relative '../../../lib/familia'
+
+Familia.debug = false
+
+# ========================================
+# Setup: Define test models
+# ========================================
+
+class EdgeCaseCompany < Familia::Horreum
+  feature :relationships
+
+  identifier_field :company_id
+  field :company_id
+  field :company_name
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    # No defaults needed for this class
+    # Could add: @company_name ||= 'Unknown Company'
+  end
+end
+
+class EdgeCaseEmployee < Familia::Horreum
+  feature :relationships
+
+  identifier_field :emp_id
+  field :emp_id
+  field :email
+  field :badge_number
+  field :department
+  field :status
+
+  # Class-level unique index for email (auto-populates on save)
+  unique_index :email, :email_index
+
+  # Instance-scoped unique index for badge_number within Company
+  unique_index :badge_number, :badge_index, within: EdgeCaseCompany
+
+  # Multi-index for department (1:many) within Company
+  multi_index :department, :dept_index, within: EdgeCaseCompany
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    @status ||= 'active'  # Apply default status if not provided
+  end
+end
+
+class EdgeCaseProduct < Familia::Horreum
+  feature :relationships
+
+  identifier_field :product_id
+  field :product_id
+  field :sku
+
+  # Allow empty strings in unique index
+  unique_index :sku, :sku_index
+
+  # init receives no arguments - fields already set from new()
+  # Use ||= to apply defaults if needed
+  def init
+    # No defaults needed for this class
+  end
+end
+
+# Clear all indexes before starting
+EdgeCaseEmployee.email_index.clear
+EdgeCaseProduct.sku_index.clear
+
+# ========================================
+# Test 1: Duplicate instance-scoped index values
+# ========================================
+
+## Setup companies and employees
+@company1 = EdgeCaseCompany.new(company_id: 'c1', company_name: 'Acme Corp')
+@company2 = EdgeCaseCompany.new(company_id: 'c2', company_name: 'Tech Inc')
+@company1.save
+@company2.save
+#=> true
+
+## Create employee with badge_number in company1
+@emp1 = EdgeCaseEmployee.new(emp_id: 'e1', email: 'john@test.com', badge_number: 'B12345')
+@emp1.save  # This auto-populates email index
+@emp1.add_to_edge_case_company_badge_index(@company1)  # Manual for instance-scoped
+@company1.find_by_badge_number('B12345')&.emp_id
+#=> 'e1'
+
+## Create another employee with same badge_number - guard should detect duplicate
+@emp2 = EdgeCaseEmployee.new(emp_id: 'e2', email: 'jane@test.com', badge_number: 'B12345')
+@emp2.save  # Different email is OK
+begin
+  @emp2.guard_unique_edge_case_company_badge_index!(@company1)
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+## Same badge_number should work in different company (different scope)
+@emp2.add_to_edge_case_company_badge_index(@company2)
+@company2.find_by_badge_number('B12345')&.emp_id
+#=> 'e2'
+
+## Verify badge exists in both companies with different employees
+[@company1.find_by_badge_number('B12345')&.emp_id, @company2.find_by_badge_number('B12345')&.emp_id]
+#=> ['e1', 'e2']
+
+## Cleanup for next test
+EdgeCaseEmployee.email_index.clear
+@company1.badge_index.clear
+@company2.badge_index.clear
+#=> 1
+
+# ========================================
+# Test 2: Field updates with auto-index cleanup
+# ========================================
+
+## Create employee with email (save auto-populates index)
+@emp3 = EdgeCaseEmployee.new(emp_id: 'e3', email: 'original@test.com')
+@emp3.save
+EdgeCaseEmployee.find_by_email('original@test.com')&.emp_id
+#=> 'e3'
+
+## Update email - must manually update index (no automatic cleanup on field change)
+old_email = @emp3.email
+@emp3.email = 'updated@test.com'
+@emp3.update_in_class_email_index(old_email)  # Manual update required
+EdgeCaseEmployee.find_by_email('original@test.com')
+#=> nil
+
+## New email should resolve to employee
+EdgeCaseEmployee.find_by_email('updated@test.com')&.emp_id
+#=> 'e3'
+
+## Update instance-scoped index
+@emp3.badge_number = 'B99999'
+@emp3.add_to_edge_case_company_badge_index(@company1)
+@company1.find_by_badge_number('B99999')&.emp_id
+#=> 'e3'
+
+## Change badge and update index
+old_badge = @emp3.badge_number
+@emp3.badge_number = 'B11111'
+@emp3.update_in_edge_case_company_badge_index(@company1, old_badge)
+@company1.find_by_badge_number('B99999')
+#=> nil
+
+## New badge should work
+@company1.find_by_badge_number('B11111')&.emp_id
+#=> 'e3'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+@company1.badge_index.clear
+#=> 1
+
+# ========================================
+# Test 3: Save within explicit transactions (validation bypass)
+# ========================================
+
+## Create first employee successfully
+@emp4 = EdgeCaseEmployee.new(emp_id: 'e4', email: 'txn@test.com')
+@emp4.save
+EdgeCaseEmployee.find_by_email('txn@test.com')&.emp_id
+#=> 'e4'
+
+## Save cannot be called inside transaction - it raises OperationModeError
+@emp5 = EdgeCaseEmployee.new(emp_id: 'e5', email: 'txn@test.com')
+error_raised = false
+begin
+  EdgeCaseEmployee.transaction do |tx|
+    @emp5.save  # This will raise
+  end
+rescue Familia::OperationModeError => e
+  error_raised = e.message.include?("Cannot call save within a transaction")
+end
+error_raised
+#=> true
+
+## However, we can bypass validation by manually adding to index inside transaction
+result = EdgeCaseEmployee.transaction do |tx|
+  # Manually add without validation (dangerous!)
+  EdgeCaseEmployee.email_index['txn_bypass@test.com'] = 'e5'
+  'manual_bypass'
+end
+result.successful?
+#=> true
+
+## After transaction, the manual entry exists (no validation occurred)
+EdgeCaseEmployee.email_index['txn_bypass@test.com']
+#=> 'e5'
+
+## After transaction, the manual entry exists (no validation occurred)
+EdgeCaseEmployee.email_index['txn_bypass@test.com']
+#=> 'e5'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+#=> 1
+
+# ========================================
+# Test 4: Multiple empty string values in same index
+# ========================================
+
+## Create product with empty SKU
+@prod1 = EdgeCaseProduct.new(product_id: 'p1', sku: '')
+@prod1.save
+EdgeCaseProduct.find_by_sku('')&.product_id
+#=> 'p1'
+
+## Try to create another product with empty SKU - should fail
+@prod2 = EdgeCaseProduct.new(product_id: 'p2', sku: '')
+begin
+  @prod2.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('sku=')
+end
+#=> true
+
+## nil values should be skipped (not indexed)
+@prod3 = EdgeCaseProduct.new(product_id: 'p3', sku: nil)
+@prod3.save  # Should succeed - nil values aren't indexed
+@prod3.identifier
+#=> 'p3'
+
+## Verify nil doesn't exist in index (empty string != nil)
+EdgeCaseProduct.sku_index['']  # Empty string key
+#=> 'p1'
+
+## nil is not indexed
+EdgeCaseProduct.sku_index.keys.include?(nil)
+#=> false
+
+## Cleanup
+EdgeCaseProduct.sku_index.clear
+#=> 1
+
+# ========================================
+# Test 5: Concurrent saves with same unique value
+# ========================================
+
+## Setup fresh index
+EdgeCaseEmployee.email_index.clear
+#=> 0
+
+## Create two employees with same email (simulating race condition)
+@emp6 = EdgeCaseEmployee.new(emp_id: 'e6', email: 'race@test.com')
+@emp7 = EdgeCaseEmployee.new(emp_id: 'e7', email: 'race@test.com')
+@emp7.emp_id
+#=> 'e7'
+
+## First save succeeds
+@emp6.save
+EdgeCaseEmployee.find_by_email('race@test.com')&.emp_id
+#=> 'e6'
+
+## Second save fails due to validation
+begin
+  @emp7.save
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+## Simulate race condition: both check validation, then both write
+EdgeCaseEmployee.email_index.clear
+@emp8 = EdgeCaseEmployee.new(emp_id: 'e8', email: 'race2@test.com')
+@emp9 = EdgeCaseEmployee.new(emp_id: 'e9', email: 'race2@test.com')
+[@emp8.emp_id, @emp9.emp_id]
+#=> ['e8', 'e9']
+
+## Both pass validation check (index is empty)
+begin
+  @emp8.guard_unique_email_index!
+  @emp9.guard_unique_email_index!
+  true
+rescue
+  false
+end
+#=> true
+
+## Both write to index (last write wins in Redis)
+@emp8.add_to_class_email_index
+@emp9.add_to_class_email_index
+# Verify the index contains the identifier (orphaned entry - wastes space but harmless)
+EdgeCaseEmployee.email_index['race2@test.com']
+#=> 'e9'
+
+## find_by returns nil for orphaned index entries (object never saved)
+# This is correct behavior - orphaned entries degrade gracefully to nil
+EdgeCaseEmployee.find_by_email('race2@test.com')
+#=> nil
+
+## To properly handle concurrent saves, check existence inside transaction
+# Note: Can't read inside MULTI block, so need WATCH/MULTI pattern
+result = nil
+EdgeCaseEmployee.dbclient.watch('edge_case_employee:email_index') do
+  if EdgeCaseEmployee.email_index['race3@test.com'].nil?
+    EdgeCaseEmployee.transaction do |tx|
+      EdgeCaseEmployee.email_index['race3@test.com'] = 'e10'
+      result = 'success'
+    end
+  else
+    result = 'duplicate'
+  end
+end
+result
+#=> 'success'
+
+## Cleanup
+EdgeCaseEmployee.email_index.clear
+#=> 1
+
+# ========================================
+# Edge Case: Update with validation in compound operation
+# ========================================
+
+## Test compound index updates in transaction
+@company3 = EdgeCaseCompany.new(company_id: 'c3', company_name: 'Test Corp')
+@company3.save
+#=> true
+
+## Create employee
+@emp11 = EdgeCaseEmployee.new(emp_id: 'e11', email: 'compound@test.com', badge_number: 'B555')
+@emp11.save
+@emp11.add_to_edge_case_company_badge_index(@company3)
+@emp11.emp_id
+#=> 'e11'
+
+## Update multiple indexed fields atomically
+@emp11 = EdgeCaseEmployee.new(emp_id: 'e11', email: 'compound@test.com', badge_number: 'B555')
+@emp11.save
+@emp11.add_to_edge_case_company_badge_index(@company3)
+
+old_email = @emp11.email
+old_badge = @emp11.badge_number
+@emp11.email = 'compound_new@test.com'
+@emp11.badge_number = 'B666'
+
+# Update both indexes in single transaction
+result = EdgeCaseEmployee.transaction do |tx|
+  @emp11.update_in_class_email_index(old_email)
+  @emp11.update_in_edge_case_company_badge_index(@company3, old_badge)
+  'updated'
+end
+result.successful?
+#=> true
+
+## Verify updates succeeded
+[EdgeCaseEmployee.find_by_email('compound_new@test.com')&.emp_id, @company3.find_by_badge_number('B666')&.emp_id]
+#=> ['e11', 'e11']
+
+## Old values should be gone
+[EdgeCaseEmployee.find_by_email('compound@test.com'), @company3.find_by_badge_number('B555')]
+#=> [nil, nil]
+
+
+# Final cleanup
+EdgeCaseEmployee.email_index.clear
+if @company3&.respond_to?(:badge_index) && @company3.badge_index.respond_to?(:clear)
+  @company3.badge_index.clear
+end
+
+# Clean up test objects - check if they still exist before destroying
+[@company1, @company2, @company3].compact.each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+puts "All edge case tests completed"

data/try/unit/horreum/unique_index_guard_validation_try.rb

@@ -0,0 +1,281 @@
+# try/unit/horreum/unique_index_guard_validation_try.rb
+
+#
+# Unique index guard validation tests
+# Tests the guard_unique_*! methods for both class-level and instance-scoped indexes
+#
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test classes for unique index guard validation
+class ::GuardUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+  field :username
+
+  # Class-level unique indexes (auto-validated on save)
+  unique_index :email, :email_index
+  unique_index :username, :username_index
+end
+
+class ::GuardCompany < Familia::Horreum
+  feature :relationships
+
+  identifier_field :company_id
+  field :company_id
+  field :name
+end
+
+class ::GuardEmployee < Familia::Horreum
+  feature :relationships
+
+  identifier_field :emp_id
+  field :emp_id
+  field :badge_number
+  field :email
+
+  # Instance-scoped unique index (manually validated)
+  unique_index :badge_number, :badge_index, within: GuardCompany
+
+  # Class-level unique index (auto-validated)
+  unique_index :email, :email_index
+end
+
+# Setup
+@user_id1 = "user_#{rand(1000000)}"
+@user_id2 = "user_#{rand(1000000)}"
+@company_id = "comp_#{rand(1000000)}"
+@emp_id1 = "emp_#{rand(1000000)}"
+@emp_id2 = "emp_#{rand(1000000)}"
+
+@company = GuardCompany.new(company_id: @company_id, name: 'Test Corp')
+@company.save
+
+# =============================================
+# 1. Class-Level Unique Index Guard Methods
+# =============================================
+
+## Guard method exists for class-level unique index
+@user1 = GuardUser.new(user_id: @user_id1, email: 'test@example.com', username: 'testuser')
+@user1.respond_to?(:guard_unique_email_index!)
+#=> true
+
+## Guard passes when no conflict exists
+@user1.guard_unique_email_index!
+#=> nil
+
+## Save succeeds after guard passes
+@user1.save
+#=> true
+
+## Guard fails when duplicate email exists
+@user2 = GuardUser.new(user_id: @user_id2, email: 'test@example.com', username: 'different')
+begin
+  @user2.guard_unique_email_index!
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('GuardUser exists email=test@example.com')
+end
+#=> true
+
+## Save automatically calls guard and raises error
+begin
+  @user2.save
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+## Guard allows same identifier (updating existing record)
+@user1_copy = GuardUser.new(user_id: @user_id1, email: 'test@example.com', username: 'testuser')
+@user1_copy.guard_unique_email_index!
+#=> nil
+
+## Guard handles nil field values gracefully
+@user_nil = GuardUser.new(user_id: "user_nil_#{rand(1000000)}", email: nil, username: 'niluser')
+@user_nil.guard_unique_email_index!
+#=> nil
+
+## Guard handles empty string field values
+@user_empty1 = GuardUser.new(user_id: "user_empty1_#{rand(1000000)}", email: '', username: 'empty1')
+@user_empty1.save
+@user_empty2 = GuardUser.new(user_id: "user_empty2_#{rand(1000000)}", email: '', username: 'empty2')
+begin
+  @user_empty2.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('GuardUser exists email=')
+end
+#=> true
+
+# =============================================
+# 2. Instance-Scoped Unique Index Guard Methods
+# =============================================
+
+## Guard method exists for instance-scoped unique index
+@emp1 = GuardEmployee.new(emp_id: @emp_id1, badge_number: 'BADGE123', email: 'emp1@example.com')
+@emp1.respond_to?(:guard_unique_guard_company_badge_index!)
+#=> true
+
+## Guard method requires parent instance parameter
+@emp1.method(:guard_unique_guard_company_badge_index!).arity
+#=> 1
+
+## Guard passes when no conflict exists in parent's index
+@emp1.guard_unique_guard_company_badge_index!(@company)
+#=> nil
+
+## Can add to index after guard passes
+@emp1.add_to_guard_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE123')
+#=> true
+
+## Guard fails when duplicate badge exists in same company
+@emp2 = GuardEmployee.new(emp_id: @emp_id2, badge_number: 'BADGE123', email: 'emp2@example.com')
+begin
+  @emp2.guard_unique_guard_company_badge_index!(@company)
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('GuardEmployee exists in GuardCompany with badge_number=BADGE123')
+end
+#=> true
+
+## Guard allows same employee to re-add (idempotent)
+@emp1.guard_unique_guard_company_badge_index!(@company)
+#=> nil
+
+## Guard passes for different company (different scope)
+@company2_id = "comp_#{rand(1000000)}"
+@company2 = GuardCompany.new(company_id: @company2_id, name: 'Other Corp')
+@company2.save
+@emp2.guard_unique_guard_company_badge_index!(@company2)
+#=> nil
+
+## Can add same badge to different company
+@emp2.add_to_guard_company_badge_index(@company2)
+@company2.badge_index.has_key?('BADGE123')
+#=> true
+
+## Guard handles nil parent instance gracefully
+@emp3 = GuardEmployee.new(emp_id: "emp_#{rand(1000000)}", badge_number: 'BADGE456', email: 'emp3@example.com')
+@emp3.guard_unique_guard_company_badge_index!(nil)
+#=> nil
+
+## Guard handles nil badge_number gracefully
+@emp_nil = GuardEmployee.new(emp_id: "emp_nil_#{rand(1000000)}", badge_number: nil, email: 'empnil@example.com')
+@emp_nil.guard_unique_guard_company_badge_index!(@company)
+#=> nil
+
+# =============================================
+# 3. Mixed Class and Instance-Scoped Validation
+# =============================================
+
+## Employee has both class-level and instance-scoped indexes
+@emp4_id = "emp_#{rand(1000000)}"
+@emp4 = GuardEmployee.new(emp_id: @emp4_id, badge_number: 'BADGE789', email: 'unique@example.com')
+@emp4.class
+#=> GuardEmployee
+
+## Class-level email index auto-validates on save
+@emp4.save
+GuardEmployee.find_by_email('unique@example.com')&.emp_id
+#=> @emp4_id
+
+## Instance-scoped badge index must be manually validated and added
+@emp4.guard_unique_guard_company_badge_index!(@company)
+@emp4.add_to_guard_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE789')
+#=> true
+
+## Duplicate class-level index caught by save
+@emp5_id = "emp_#{rand(1000000)}"
+@emp5 = GuardEmployee.new(emp_id: @emp5_id, badge_number: 'BADGE999', email: 'unique@example.com')
+begin
+  @emp5.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('GuardEmployee exists email=unique@example.com')
+end
+#=> true
+
+## Duplicate instance-scoped index requires manual guard
+@emp6_id = "emp_#{rand(1000000)}"
+@emp6 = GuardEmployee.new(emp_id: @emp6_id, badge_number: 'BADGE789', email: 'emp6@example.com')
+@emp6.save  # Succeeds - no auto-validation of instance-scoped indexes
+begin
+  @emp6.guard_unique_guard_company_badge_index!(@company)
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('GuardEmployee exists in GuardCompany with badge_number=BADGE789')
+end
+#=> true
+
+# =============================================
+# 4. Guard Method Error Messages
+# =============================================
+
+## Class-level guard error includes class and field
+@user_dup = GuardUser.new(user_id: "user_dup_#{rand(1000000)}", email: 'test@example.com', username: 'dupuser')
+begin
+  @user_dup.guard_unique_email_index!
+rescue Familia::RecordExistsError => e
+  [e.message.include?('GuardUser'), e.message.include?('email=test@example.com')]
+end
+#=> [true, true]
+
+## Instance-scoped guard error includes both classes and field
+begin
+  @emp2.guard_unique_guard_company_badge_index!(@company)
+rescue Familia::RecordExistsError => e
+  [e.message.include?('GuardEmployee'), e.message.include?('GuardCompany'), e.message.include?('badge_number=BADGE123')]
+end
+#=> [true, true, true]
+
+## RecordExistsError is correct type
+begin
+  @emp2.guard_unique_guard_company_badge_index!(@company)
+rescue => e
+  e.class
+end
+#=> Familia::RecordExistsError
+
+# =============================================
+# 5. Transaction Context Behavior
+# =============================================
+
+## Guard works outside transaction
+@user_tx = GuardUser.new(user_id: "user_tx_#{rand(1000000)}", email: 'tx@example.com', username: 'txuser')
+@user_tx.guard_unique_email_index!
+#=> nil
+
+## Guard must be called outside transaction (new rule)
+unique_timestamp = Time.now.to_i
+unique_rand = rand(1000000)
+email = "tx_unique_#{unique_timestamp}_#{unique_rand}@example.com"
+@user_tx_unique = GuardUser.new(user_id: "user_tx_unique_#{unique_rand}", email: email, username: "txuser_#{unique_rand}")
+
+# Guards should be called outside transactions
+@user_tx_unique.send(:guard_unique_indexes!)
+#=> nil
+
+# Teardown - clean up test objects
+[@user1, @user2, @user_nil, @user_empty1, @user_empty2, @user_dup, @user_tx, @user_tx_unique].each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+[@emp1, @emp2, @emp3, @emp_nil, @emp4, @emp5, @emp6].each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+[@company, @company2].each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+# Clean up class-level indexes
+[GuardUser.email_index, GuardUser.username_index, GuardEmployee.email_index].each do |index|
+  index.delete! if index.respond_to?(:delete!) && index.respond_to?(:exists?) && index.exists?
+end

data/try/{refinements → unit/refinements}/dear_json_array_methods_try.rb

@@ -1,6 +1,6 @@
 # try/refinements/dear_json_array_methods_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 class TestArrayWithDearJson < Array
   include Familia::Refinements::DearJsonArrayMethods

data/try/{refinements → unit/refinements}/dear_json_hash_methods_try.rb

@@ -1,6 +1,6 @@
 # try/refinements/dear_json_hash_methods_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 class TestHashWithDearJson < Hash
   include Familia::Refinements::DearJsonHashMethods

data/try/{refinements → unit/refinements}/time_literals_numeric_methods_try.rb

@@ -1,6 +1,6 @@
 # try/refinements/time_literals_numeric_methods_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 class TestNumericWithTimeLiterals
   include Familia::Refinements::TimeLiterals::NumericMethods

data/try/{refinements → unit/refinements}/time_literals_string_methods_try.rb

@@ -1,6 +1,6 @@
 # try/refinements/time_literals_string_methods_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 class TestStringWithTimeLiterals < String
   include Familia::Refinements::TimeLiterals::StringMethods