familia 2.0.0.pre18 → 2.0.0.pre21

data/try/unit/horreum/automatic_index_validation_try.rb

@@ -0,0 +1,255 @@
+# try/unit/horreum/automatic_index_validation_try.rb
+#
+# frozen_string_literal: true
+
+#
+# Automatic index validation tests
+# Tests that unique index validation happens automatically when adding to indexes
+#
+
+require_relative '../../support/helpers/test_helpers'
+
+# Test classes for automatic validation
+class ::AutoValidCompany < Familia::Horreum
+  feature :relationships
+
+  identifier_field :company_id
+  field :company_id
+  field :name
+end
+
+class ::AutoValidEmployee < Familia::Horreum
+  feature :relationships
+
+  identifier_field :emp_id
+  field :emp_id
+  field :badge_number
+  field :email
+
+  # Instance-scoped unique index (should auto-validate in add_to_* methods)
+  unique_index :badge_number, :badge_index, within: AutoValidCompany
+
+  # Class-level unique index (auto-validates in save)
+  unique_index :email, :email_index
+end
+
+class ::AutoValidUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  unique_index :email, :email_index
+end
+
+# Setup
+@company_id = "comp_#{rand(1000000)}"
+@company = AutoValidCompany.new(company_id: @company_id, name: 'Test Corp')
+@company.save
+
+@emp1_id = "emp_#{rand(1000000)}"
+@emp2_id = "emp_#{rand(1000000)}"
+
+# =============================================
+# 1. Automatic Validation in add_to_* Methods
+# =============================================
+
+## First employee can add badge to company index
+@emp1 = AutoValidEmployee.new(emp_id: @emp1_id, badge_number: 'BADGE123', email: 'emp1@example.com')
+@emp1.save  # Save first to establish class-level email index
+@emp1.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE123')
+#=> true
+
+## Duplicate badge is automatically rejected without manual guard call
+@emp2 = AutoValidEmployee.new(emp_id: @emp2_id, badge_number: 'BADGE123', email: 'emp2@example.com')
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('AutoValidEmployee exists in AutoValidCompany with badge_number=BADGE123')
+end
+#=> true
+
+## Badge was not added after validation failure
+@company.badge_index.get('BADGE123')
+#=> @emp1_id
+
+## Different badge number works fine
+@emp2.badge_number = 'BADGE456'
+@emp2.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE456')
+#=> true
+
+## Same employee can re-add (idempotent)
+@emp1.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.get('BADGE123')
+#=> @emp1_id
+
+## Different company allows same badge (scoped uniqueness)
+@company2_id = "comp_#{rand(1000000)}"
+@company2 = AutoValidCompany.new(company_id: @company2_id, name: 'Other Corp')
+@company2.save
+@emp3_id = "emp_#{rand(1000000)}"
+@emp3 = AutoValidEmployee.new(emp_id: @emp3_id, badge_number: 'BADGE123', email: 'emp3@example.com')
+@emp3.add_to_auto_valid_company_badge_index(@company2)
+@company2.badge_index.has_key?('BADGE123')
+#=> true
+
+## Nil badge_number handled gracefully (no validation or addition)
+@emp_nil = AutoValidEmployee.new(emp_id: "emp_nil_#{rand(1000000)}", badge_number: nil, email: 'empnil@example.com')
+@emp_nil.add_to_auto_valid_company_badge_index(@company)
+#=> nil
+
+## Nil parent handled gracefully (no validation or addition)
+@emp4 = AutoValidEmployee.new(emp_id: "emp4_#{rand(1000000)}", badge_number: 'BADGE789', email: 'emp4@example.com')
+@emp4.add_to_auto_valid_company_badge_index(nil)
+#=> nil
+
+# =============================================
+# 2. Transaction Detection in save()
+# =============================================
+
+## Normal save works outside transaction
+@user1_id = "user_#{rand(1000000)}"
+@user1 = AutoValidUser.new(user_id: @user1_id, email: 'user1@example.com')
+@user1.save
+#=> true
+
+## save() raises error when called within transaction
+@user2_id = "user_#{rand(1000000)}"
+begin
+  AutoValidUser.transaction do
+    @user2 = AutoValidUser.new(user_id: @user2_id, email: 'user2@example.com')
+    @user2.save
+  end
+  false
+rescue Familia::OperationModeError => e
+  e.message.include?('Cannot call save within a transaction')
+end
+#=> true
+
+## Object was not saved due to transaction error
+AutoValidUser.find_by_email('user2@example.com')
+#=> nil
+
+## Transaction with explicit field updates works (bypass save)
+@user3_id = "user_#{rand(1000000)}"
+@user3 = AutoValidUser.new(user_id: @user3_id, email: 'user3@example.com')
+AutoValidUser.transaction do |_tx|
+  @user3.hmset(@user3.to_h_for_storage)
+end
+@user3.exists?
+#=> true
+
+## save() works after transaction completes
+@user4_id = "user_#{rand(1000000)}"
+AutoValidUser.transaction do
+  # Do something else in transaction
+end
+@user4 = AutoValidUser.new(user_id: @user4_id, email: 'user4@example.com')
+@user4.save
+#=> true
+
+# =============================================
+# 3. Combined Automatic Validation Scenarios
+# =============================================
+
+## Employee with duplicate class-level email caught in save
+@emp5_id = "emp_#{rand(1000000)}"
+@emp5 = AutoValidEmployee.new(emp_id: @emp5_id, badge_number: 'BADGE999', email: 'emp1@example.com')
+begin
+  @emp5.save
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('AutoValidEmployee exists email=emp1@example.com')
+end
+#=> true
+
+## Employee can save with unique email
+@emp1.save
+AutoValidEmployee.find_by_email('emp1@example.com')&.emp_id
+#=> @emp1_id
+
+## After save, duplicate instance-scoped index still caught automatically
+@emp6_id = "emp_#{rand(1000000)}"
+@emp6 = AutoValidEmployee.new(emp_id: @emp6_id, badge_number: 'BADGE123', email: 'emp6@example.com')
+@emp6.save  # Class-level index is fine
+begin
+  @emp6.add_to_auto_valid_company_badge_index(@company)  # Instance-scoped duplicate
+  false
+rescue Familia::RecordExistsError => e
+  e.message.include?('badge_number=BADGE123')
+end
+#=> true
+
+# =============================================
+# 4. Error Message Quality
+# =============================================
+
+## Instance-scoped validation error includes both class names
+begin
+  @emp2.badge_number = 'BADGE123'  # Reset to duplicate
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue Familia::RecordExistsError => e
+  [e.message.include?('AutoValidEmployee'), e.message.include?('AutoValidCompany')]
+end
+#=> [true, true]
+
+## Instance-scoped validation error includes field name and value
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue Familia::RecordExistsError => e
+  [e.message.include?('badge_number'), e.message.include?('BADGE123')]
+end
+#=> [true, true]
+
+## Error type is RecordExistsError
+begin
+  @emp2.add_to_auto_valid_company_badge_index(@company)
+rescue => e
+  e.class
+end
+#=> Familia::RecordExistsError
+
+# =============================================
+# 5. Performance - No Double Validation
+# =============================================
+
+## Manual guard call before add_to_* is redundant but harmless
+@emp7_id = "emp_#{rand(1000000)}"
+@emp7 = AutoValidEmployee.new(emp_id: @emp7_id, badge_number: 'BADGE777', email: 'emp7@example.com')
+@emp7.guard_unique_auto_valid_company_badge_index!(@company)
+@emp7.add_to_auto_valid_company_badge_index(@company)
+@company.badge_index.has_key?('BADGE777')
+#=> true
+
+## Manual guard call detects duplicate
+@emp8_id = "emp_#{rand(1000000)}"
+@emp8 = AutoValidEmployee.new(emp_id: @emp8_id, badge_number: 'BADGE777', email: 'emp8@example.com')
+begin
+  @emp8.guard_unique_auto_valid_company_badge_index!(@company)  # Should fail - duplicate badge
+  false
+rescue Familia::RecordExistsError
+  true
+end
+#=> true
+
+# Teardown - clean up test objects
+[@emp1, @emp2, @emp3, @emp_nil, @emp4, @emp5, @emp6, @emp7, @emp8].compact.each do |obj|
+  obj.destroy! if obj.respond_to?(:destroy!) && obj.respond_to?(:exists?) && obj.exists?
+end
+
+[@user1, @user3, @user4].compact.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
+[AutoValidEmployee.email_index, AutoValidUser.email_index].each do |index|
+  index.delete! if index.respond_to?(:delete!) && index.respond_to?(:exists?) && index.exists?
+end

data/try/unit/horreum/base_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/base_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/base_try.rb
 
 require_relative '../../support/helpers/test_helpers'
@@ -41,7 +45,7 @@ Familia.debug = false
 
 ## Remove the key
 @hashkey.delete!
-#=> true
+#=> 1
 
 ## Horreum objects can update and save their fields (1 of 2)
 @customer.name = 'John Doe'

data/try/unit/horreum/class_methods_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/class_methods_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/class_methods_try.rb
 
 # Test Horreum class methods
@@ -16,9 +20,9 @@ module AnotherModuleName
   end
 end
 
-## create factory method with existence checking
+## create! factory method with existence checking
 TestUser
-#==> _.respond_to?(:create)
+#==> _.respond_to?(:create!)
 #==> _.respond_to?(:exists?)
 
 ## multiget method is available

data/try/unit/horreum/commands_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/commands_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/commands_try.rb
 
 # Test Horreum Valkey/Redis commands

data/try/unit/horreum/defensive_initialization_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/defensive_initialization_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/defensive_initialization_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/destroy_related_fields_cleanup_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/destroy_related_fields_cleanup_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/destroy_related_fields_cleanup_try.rb
 
 # Horreum destroy! Related Fields Cleanup Tryouts

data/try/unit/horreum/enhanced_conflict_handling_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/enhanced_conflict_handling_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/enhanced_conflict_handling_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/field_categories_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/field_categories_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/field_categories_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/field_definition_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/field_definition_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/field_definition_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/initialization_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/initialization_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/initialization_try.rb
 
 require_relative '../../support/helpers/test_helpers'
@@ -101,7 +105,7 @@ Familia.debug = false
 
 ## Clean up saved test objects
 [@customer6, @complex].map(&:delete!)
-#=> [true, true]
+#=> [1, 1]
 
 ## "Cleaning up" test objects that were never saved returns true regardless
 ## b/c it takes place in a transaction and it's the transaction's success

data/try/unit/horreum/json_type_preservation_try.rb

@@ -1,3 +1,5 @@
+# try/unit/horreum/json_type_preservation_try.rb
+#
 # frozen_string_literal: true
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/optimized_loading_try.rb

@@ -0,0 +1,156 @@
+# try/unit/horreum/optimized_loading_try.rb
+#
+# frozen_string_literal: true
+
+# Test optimized loading methods with check_exists parameter and pipelined bulk loading
+
+require_relative '../../support/helpers/test_helpers'
+
+OptimizedUser = Class.new(Familia::Horreum) do
+  identifier_field :user_id
+  field :user_id
+  field :name
+  field :email
+  field :age
+end
+
+# Setup: Create test users
+setup_user1 = OptimizedUser.new(user_id: 'opt_user_1', name: 'Alice', email: 'alice@example.com', age: 30)
+setup_user1.save
+
+setup_user2 = OptimizedUser.new(user_id: 'opt_user_2', name: 'Bob', email: 'bob@example.com', age: 25)
+setup_user2.save
+
+setup_user3 = OptimizedUser.new(user_id: 'opt_user_3', name: 'Charlie', email: 'charlie@example.com', age: 35)
+setup_user3.save
+
+## find_by_dbkey with check_exists: true (default) returns object for existing key
+found_user = OptimizedUser.find_by_dbkey(OptimizedUser.dbkey('opt_user_1'))
+found_user.name
+#=> 'Alice'
+
+## find_by_dbkey with check_exists: true (default) returns nil for non-existent key
+OptimizedUser.find_by_dbkey(OptimizedUser.dbkey('nonexistent'))
+#=> nil
+
+## find_by_dbkey with check_exists: false returns object for existing key
+found_user_fast = OptimizedUser.find_by_dbkey(OptimizedUser.dbkey('opt_user_1'), check_exists: false)
+found_user_fast.name
+#=> 'Alice'
+
+## find_by_dbkey with check_exists: false returns nil for non-existent key
+OptimizedUser.find_by_dbkey(OptimizedUser.dbkey('nonexistent'), check_exists: false)
+#=> nil
+
+## find_by_dbkey with check_exists: false correctly deserializes all fields
+fast_loaded = OptimizedUser.find_by_dbkey(OptimizedUser.dbkey('opt_user_2'), check_exists: false)
+[fast_loaded.user_id, fast_loaded.name, fast_loaded.email, fast_loaded.age]
+#=> ['opt_user_2', 'Bob', 'bob@example.com', 25]
+
+## find_by_identifier with check_exists: true (default) returns object
+OptimizedUser.find_by_identifier('opt_user_1').name
+#=> 'Alice'
+
+## find_by_identifier with check_exists: false returns object
+OptimizedUser.find_by_identifier('opt_user_1', check_exists: false).name
+#=> 'Alice'
+
+## find_by_identifier with check_exists: false returns nil for non-existent
+OptimizedUser.find_by_identifier('nonexistent', check_exists: false)
+#=> nil
+
+## find_by_id alias works with check_exists parameter
+OptimizedUser.find_by_id('opt_user_2', check_exists: false).email
+#=> 'bob@example.com'
+
+## find alias works with check_exists parameter
+OptimizedUser.find('opt_user_3', check_exists: false).age
+#=> 35
+
+## load alias works with check_exists parameter
+OptimizedUser.load('opt_user_1', check_exists: false).user_id
+#=> 'opt_user_1'
+
+## load_multi loads multiple existing objects
+users = OptimizedUser.load_multi(['opt_user_1', 'opt_user_2', 'opt_user_3'])
+users.map(&:name)
+#=> ['Alice', 'Bob', 'Charlie']
+
+## load_multi returns nils for non-existent objects in correct positions
+users_mixed = OptimizedUser.load_multi(['opt_user_1', 'nonexistent', 'opt_user_3'])
+[users_mixed[0]&.name, users_mixed[1], users_mixed[2]&.name]
+#=> ['Alice', nil, 'Charlie']
+
+## load_multi with compact filters out nils
+users_compact = OptimizedUser.load_multi(['opt_user_1', 'nonexistent', 'opt_user_2']).compact
+users_compact.map(&:name)
+#=> ['Alice', 'Bob']
+
+## load_multi preserves order of identifiers
+users_ordered = OptimizedUser.load_multi(['opt_user_3', 'opt_user_1', 'opt_user_2'])
+users_ordered.map(&:user_id)
+#=> ['opt_user_3', 'opt_user_1', 'opt_user_2']
+
+## load_multi handles empty array
+OptimizedUser.load_multi([])
+#=> []
+
+## load_multi handles all non-existent identifiers
+all_missing = OptimizedUser.load_multi(['missing1', 'missing2'])
+all_missing.compact
+#=> []
+
+## load_multi correctly deserializes all field types
+multi_loaded = OptimizedUser.load_multi(['opt_user_2']).first
+[multi_loaded.user_id, multi_loaded.name, multi_loaded.email, multi_loaded.age]
+#=> ['opt_user_2', 'Bob', 'bob@example.com', 25]
+
+## load_batch alias works
+batch_users = OptimizedUser.load_batch(['opt_user_1', 'opt_user_2'])
+batch_users.map(&:name)
+#=> ['Alice', 'Bob']
+
+## load_multi_by_keys loads by full dbkeys
+keys = [OptimizedUser.dbkey('opt_user_1'), OptimizedUser.dbkey('opt_user_2')]
+keyed_users = OptimizedUser.load_multi_by_keys(keys)
+keyed_users.map(&:name)
+#=> ['Alice', 'Bob']
+
+## load_multi_by_keys returns nil for non-existent keys
+keys_mixed = [OptimizedUser.dbkey('opt_user_1'), OptimizedUser.dbkey('nonexistent')]
+keyed_mixed = OptimizedUser.load_multi_by_keys(keys_mixed)
+[keyed_mixed[0]&.name, keyed_mixed[1]]
+#=> ['Alice', nil]
+
+## load_multi_by_keys handles empty array
+OptimizedUser.load_multi_by_keys([])
+#=> []
+
+## load_multi_by_keys handles empty/nil keys and maintains position alignment
+keys_with_empty = [OptimizedUser.dbkey('opt_user_1'), '', OptimizedUser.dbkey('opt_user_2'), nil]
+mixed_keys = OptimizedUser.load_multi_by_keys(keys_with_empty)
+[mixed_keys[0]&.name, mixed_keys[1], mixed_keys[2]&.name, mixed_keys[3]]
+#=> ['Alice', nil, 'Bob', nil]
+
+## load_multi handles nil identifiers gracefully
+users_with_nils = OptimizedUser.load_multi(['opt_user_1', nil, 'opt_user_2'])
+[users_with_nils[0]&.name, users_with_nils[1], users_with_nils[2]&.name]
+#=> ['Alice', nil, 'Bob']
+
+## load_multi handles empty string identifiers
+users_with_empty = OptimizedUser.load_multi(['opt_user_1', '', 'opt_user_2'])
+[users_with_empty[0]&.name, users_with_empty[1], users_with_empty[2]&.name]
+#=> ['Alice', nil, 'Bob']
+
+## find_by_identifier works with suffix as keyword parameter
+OptimizedUser.find_by_identifier('opt_user_1', suffix: :object)&.name
+#=> 'Alice'
+
+## find_by_identifier works with both keyword parameters
+OptimizedUser.find_by_identifier('opt_user_1', suffix: :object, check_exists: false)&.name
+#=> 'Alice'
+
+# Teardown: Clean up test data
+OptimizedUser.destroy!('opt_user_1')
+OptimizedUser.destroy!('opt_user_2')
+OptimizedUser.destroy!('opt_user_3')

data/try/unit/horreum/relations_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/relations_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/relations_try.rb
 # Test Horreum Database type relations functionality
 
@@ -92,15 +96,15 @@ prefs = @test_user.preferences
 @test_user.preferences.size
 #=> 2
 
-## Clearing a counter returns false when not set yet
+## Clearing a counter returns 0 when not set yet
 @test_product.views.clear
 @test_product.views.clear
-#=> false
+#=> 0
 
-## Clearing a counter returns true when it is set
+## Clearing a counter returns 1 when it is set
 @test_product.views.increment
 @test_product.views.clear
-#=> true
+#=> 1
 
 ## Counter Database type works
 @test_product.views.increment

data/try/unit/horreum/serialization_persistent_fields_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/serialization_persistent_fields_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/serialization_persistent_fields_try.rb
 
 require_relative '../../support/helpers/test_helpers'

data/try/unit/horreum/serialization_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/serialization_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/serialization_try.rb
 
 require_relative '../../support/helpers/test_helpers'
@@ -20,10 +24,10 @@ Familia.dbclient.set('debug:starting_save_if_not_exists_tests', Familia.now.to_s
 @new_customer.save_if_not_exists
 #=> true
 
-## save_if_not_exists raises error when customer already exists
+## save_if_not_exists! raises error when customer already exists
 @duplicate_customer = Customer.new "new-customer-#{@test_id}@test.com"
 @duplicate_customer.name = 'Duplicate Customer'
-@duplicate_customer.save_if_not_exists
+@duplicate_customer.save_if_not_exists!
 #=!> Familia::RecordExistsError
 #==> error.message.include?("Key already exists")
 

data/try/unit/horreum/settings_try.rb

@@ -1,3 +1,7 @@
+# try/unit/horreum/settings_try.rb
+#
+# frozen_string_literal: true
+
 # try/horreum/settings_try.rb
 
 # Test Horreum settings