familia 2.0.0.pre22 → 2.0.0.pre24

data/try/features/relationships/participation_commands_verification_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe 'participation_commands_verification_try' do
       field :display_domain
       field :created_at
       participates_in ReverseIndexCustomer, :domains, score: :created_at
-      participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+      participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
       class_participates_in :all_domains, score: :created_at
     end
   end

data/try/features/relationships/participation_commands_verification_try.rb

@@ -49,7 +49,7 @@ class ReverseIndexDomain < Familia::Horreum
   field :created_at
 
   participates_in ReverseIndexCustomer, :domains, score: :created_at
-  participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+  participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
   class_participates_in :all_domains, score: :created_at
 end
 

data/try/features/relationships/participation_method_prefix_try.rb

@@ -0,0 +1,133 @@
+# try/features/relationships/participation_method_prefix_try.rb
+#
+# frozen_string_literal: true
+
+require_relative '../../../lib/familia'
+
+# Test the method_prefix: option for participates_in
+# This allows shorter reverse method names for namespaced classes
+
+# Simulate a namespaced target class
+module ::Admin
+  class MethodPrefixTeam < Familia::Horreum
+    feature :relationships
+
+    identifier_field :team_id
+    field :team_id
+    field :name
+
+    sorted_set :members
+    sorted_set :admins
+
+    def init
+      @team_id ||= "team_#{SecureRandom.hex(4)}"
+    end
+  end
+end
+
+# Test class using method_prefix: option
+class ::MethodPrefixUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # Use method_prefix to get shorter method names
+  # Instead of admin_method_prefix_team_instances, we get team_instances
+  participates_in Admin::MethodPrefixTeam, :members, method_prefix: :team
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+# Test class using as: which should take precedence over method_prefix:
+class ::MethodPrefixPriorityUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # as: takes precedence over method_prefix:
+  participates_in Admin::MethodPrefixTeam, :admins, method_prefix: :team, as: :my_teams
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+# Test class without method_prefix (default behavior)
+class ::MethodPrefixDefaultUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # Default: uses config_name (method_prefix_team - demodularized, no namespace)
+  participates_in Admin::MethodPrefixTeam, :members
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+@user = MethodPrefixUser.new(email: 'alice@example.com')
+@priority_user = MethodPrefixPriorityUser.new(email: 'bob@example.com')
+@default_user = MethodPrefixDefaultUser.new(email: 'charlie@example.com')
+@team = Admin::MethodPrefixTeam.new(name: 'Engineering')
+
+## method_prefix: generates shortened method names
+# The method_prefix: :team option should generate team_* methods
+@user.respond_to?(:team_instances)
+#=> true
+
+## method_prefix: generates team_ids method
+@user.respond_to?(:team_ids)
+#=> true
+
+## method_prefix: generates team? method
+@user.respond_to?(:team?)
+#=> true
+
+## method_prefix: generates team_count method
+@user.respond_to?(:team_count)
+#=> true
+
+## method_prefix: does NOT generate verbose config_name methods
+# The verbose admin_method_prefix_team_* methods should not be created
+@user.respond_to?(:admin_method_prefix_team_instances)
+#=> false
+
+## as: takes precedence over method_prefix:
+# When both as: and method_prefix: are provided, as: wins
+@priority_user.respond_to?(:my_teams_instances)
+#=> true
+
+## as: takes precedence - method_prefix method NOT generated
+@priority_user.respond_to?(:team_instances)
+#=> false
+
+## default behavior preserved when no method_prefix
+# Without method_prefix:, the config_name is used (method_prefix_team)
+# Note: config_name uses the class name without namespace
+@default_user.respond_to?(:method_prefix_team_instances)
+#=> true
+
+## default behavior - no custom shortened method names
+# The team_instances method is not generated unless method_prefix: :team is used
+@default_user.respond_to?(:team_instances)
+#=> false
+
+## ParticipationRelationship stores method_prefix
+# The relationship metadata should include the method_prefix
+rel = MethodPrefixUser.participation_relationships.first
+rel.method_prefix
+#=> :team
+
+## ParticipationRelationship method_prefix is nil for default
+rel_default = MethodPrefixDefaultUser.participation_relationships.first
+rel_default.method_prefix
+#=> nil

data/try/features/relationships/participation_reverse_index_try.rb

@@ -28,7 +28,7 @@ class ReverseIndexDomain < Familia::Horreum
   field :created_at
 
   participates_in ReverseIndexCustomer, :domains, score: :created_at
-  participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+  participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
   class_participates_in :all_domains, score: :created_at
 end
 

data/try/features/relationships/{participation_bidirectional_try.rb → participation_reverse_methods_try.rb}

@@ -1,10 +1,10 @@
-# try/features/relationships/participation_bidirectional_try.rb
+# try/features/relationships/participation_reverse_methods_try.rb
 #
 # frozen_string_literal: true
 
 require_relative '../../../lib/familia'
 
-# Test demonstrating true bidirectional participation functionality
+# Test demonstrating reverse collection methods (generate_participant_methods: true)
 # This shows the improvement from asymmetric to symmetric relationship access
 
 # Setup test classes
@@ -51,8 +51,8 @@ class ::ProjectUser < Familia::Horreum
   field :name
   field :role
 
-  # Define bidirectional participation relationships
-  # These will auto-generate reverse collection methods with _instances suffix
+  # Define participation relationships with reverse collection methods
+  # These auto-generate methods like user.project_team_instances (when generate_participant_methods: true)
   participates_in ProjectTeam, :members          # Generates: user.project_team_instances
   participates_in ProjectTeam, :admins           # Also adds to user.project_team_instances (union)
   participates_in ProjectOrganization, :employees # Generates: user.project_organization_instances
@@ -197,13 +197,13 @@ contracting_orgs_instances.map(&:name)
 @team1.admins.to_a
 #=> [@user1.identifier]
 
-## Test bidirectional consistency - forward direction
+## Test symmetric consistency - forward direction
 team1_member_ids = @team1.members.to_a
 team1_members = ProjectUser.load_multi(team1_member_ids).compact
 team1_members.map(&:name)
 #=> ["Alice"]
 
-## Test bidirectional consistency - reverse direction
+## Test symmetric consistency - reverse direction
 user1_teams = @user1.project_team_instances
 user1_team_ids = user1_teams.map(&:identifier)
 user1_team_ids.include?(@team1.identifier)

data/try/features/relationships/participation_through_try.rb

@@ -0,0 +1,173 @@
+# try/features/relationships/participation_through_try.rb
+#
+# frozen_string_literal: true
+
+# Test through model support for participates_in relationships
+
+require_relative '../../support/helpers/test_helpers'
+
+# Define through model FIRST so it can be resolved
+class ::ThroughTestMembership < Familia::Horreum
+  feature :object_identifier
+  feature :relationships
+  identifier_field :objid
+  field :through_test_customer_objid
+  field :through_test_domain_objid
+  field :role
+  field :updated_at
+end
+
+class ::ThroughTestCustomer < Familia::Horreum
+  feature :object_identifier
+  feature :relationships
+  identifier_field :custid
+  field :custid
+  field :name
+end
+
+class ::ThroughTestDomain < Familia::Horreum
+  feature :object_identifier
+  feature :relationships
+  identifier_field :domain_id
+  field :domain_id
+  field :display_domain
+  field :created_at
+  participates_in ThroughTestCustomer, :domains, score: :created_at, through: :ThroughTestMembership
+end
+
+# Define backward compat classes in setup
+class ::BackwardCompatCustomer < Familia::Horreum
+  feature :relationships
+  identifier_field :custid
+  field :custid
+end
+
+class ::BackwardCompatDomain < Familia::Horreum
+  feature :relationships
+  identifier_field :domain_id
+  field :domain_id
+  field :created_at
+  participates_in BackwardCompatCustomer, :domains, score: :created_at
+end
+
+# Setup instance variables
+@customer = ThroughTestCustomer.new(custid: 'cust_through_123', name: 'Through Test Customer')
+@domain = ThroughTestDomain.new(domain_id: 'dom_through_456', display_domain: 'through-test.com', created_at: Familia.now.to_i)
+@customer.save
+@domain.save
+
+@compat_customer = BackwardCompatCustomer.new(custid: 'compat_cust')
+@compat_domain = BackwardCompatDomain.new(domain_id: 'compat_dom', created_at: Familia.now.to_i)
+@compat_customer.save
+@compat_domain.save
+
+## ParticipationRelationship supports through parameter
+Familia::Features::Relationships::ParticipationRelationship.members.include?(:through)
+#=> true
+
+## participates_in creates relationship with through parameter
+@rel = ThroughTestDomain.participation_relationships.first
+@rel.through
+#=> :ThroughTestMembership
+
+## Through class must have object_identifier feature
+begin
+  class ::InvalidThroughModel < Familia::Horreum
+    feature :relationships
+  end
+  class ::BadDomain < Familia::Horreum
+    feature :relationships
+    field :name
+    participates_in ThroughTestCustomer, :bad_domains, through: :InvalidThroughModel
+  end
+  false
+rescue ArgumentError => e
+  e.message.include?('must use `feature :object_identifier`')
+end
+#=> true
+
+## Adding domain creates through model automatically
+@membership1 = @customer.add_domains_instance(@domain)
+@through_key = "through_test_customer:#{@customer.objid}:through_test_domain:#{@domain.objid}:through_test_membership"
+@loaded_membership = ThroughTestMembership.load(@through_key)
+@loaded_membership&.exists?
+#=> true
+
+## Through model receives through_attrs on add
+@customer.remove_domains_instance(@domain)
+@membership2 = @customer.add_domains_instance(@domain, through_attrs: { role: 'admin' })
+@loaded_with_role = ThroughTestMembership.load(@through_key)
+@loaded_with_role.role
+#=> 'admin'
+
+## add_domains_instance returns through model when using :through
+@membership2.class.name
+#=> "ThroughTestMembership"
+
+## Returned through model can be chained
+@membership2.respond_to?(:role)
+#=> true
+
+## Returned through model has role attribute set
+@membership2.role
+#=> 'admin'
+
+## Removing domain destroys through model
+@customer.remove_domains_instance(@domain)
+@removed_check = ThroughTestMembership.load(@through_key)
+@removed_check.nil? || !@removed_check.exists?
+#=> true
+
+## Adding twice updates existing, doesn't duplicate
+@membership_v1 = @customer.add_domains_instance(@domain, through_attrs: { role: 'viewer' })
+@check_v1 = ThroughTestMembership.load(@through_key)
+@check_v1.role
+#=> 'viewer'
+
+## Second add updates the same through model
+@membership_v2 = @customer.add_domains_instance(@domain, through_attrs: { role: 'editor' })
+@check_v2 = ThroughTestMembership.load(@through_key)
+@check_v2.role
+#=> 'editor'
+
+## Only one through model exists (same objid)
+@check_v1.objid == @check_v2.objid
+#=> true
+
+## Models without :through work as before
+@compat_result = @compat_customer.add_domains_instance(@compat_domain)
+@compat_domain.in_backward_compat_customer_domains?(@compat_customer)
+#=> true
+
+## No through model created for backward compat
+@compat_rel = BackwardCompatDomain.participation_relationships.first
+@compat_rel.through.nil?
+#=> true
+
+## Backward compat returns self not through model
+@compat_result.class.name
+#=> "BackwardCompatCustomer"
+
+## Through model sets updated_at on create
+@customer.remove_domains_instance(@domain)
+@membership_with_ts = @customer.add_domains_instance(@domain, through_attrs: { role: 'owner' })
+@ts_check = ThroughTestMembership.load(@through_key)
+@ts_check.updated_at.is_a?(Float)
+#=> true
+
+## updated_at is current
+(Familia.now.to_f - @ts_check.updated_at) < 2.0
+#=> true
+
+## Through model updates updated_at on attribute change
+@old_ts = @ts_check.updated_at
+sleep 0.1
+@membership_updated = @customer.add_domains_instance(@domain, through_attrs: { role: 'admin' })
+@new_ts_check = ThroughTestMembership.load(@through_key)
+@new_ts_check.updated_at > @old_ts
+#=> true
+
+# Cleanup
+[@customer, @domain, @compat_customer, @compat_domain].each do |obj|
+  obj.destroy! if obj&.respond_to?(:destroy!) && obj.exists?
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre22
+  version: 2.0.0.pre24
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -218,6 +218,7 @@ files:
 - examples/safe_dump.rb
 - examples/sampling_demo.rb
 - examples/single_connection_transaction_confusions.rb
+- examples/through_relationships.rb
 - familia.gemspec
 - lib/familia.rb
 - lib/familia/base.rb
@@ -275,6 +276,7 @@ files:
 - lib/familia/features/relationships/participation/participant_methods.rb
 - lib/familia/features/relationships/participation/rebuild_strategies.md
 - lib/familia/features/relationships/participation/target_methods.rb
+- lib/familia/features/relationships/participation/through_model_operations.rb
 - lib/familia/features/relationships/participation_membership.rb
 - lib/familia/features/relationships/participation_relationship.rb
 - lib/familia/features/relationships/score_encoding.rb
@@ -315,6 +317,7 @@ files:
 - pr_agent.toml
 - pr_compliance_checklist.yaml
 - try/edge_cases/empty_identifiers_try.rb
+- try/edge_cases/find_by_dbkey_race_condition_try.rb
 - try/edge_cases/hash_symbolization_try.rb
 - try/edge_cases/json_serialization_try.rb
 - try/edge_cases/legacy_data_detection/deserialization_edge_cases_try.rb
@@ -361,12 +364,14 @@ files:
 - try/features/relationships/indexing_commands_verification_try.rb
 - try/features/relationships/indexing_rebuild_try.rb
 - try/features/relationships/indexing_try.rb
-- try/features/relationships/participation_bidirectional_try.rb
 - try/features/relationships/participation_commands_verification_spec.rb
 - try/features/relationships/participation_commands_verification_try.rb
+- try/features/relationships/participation_method_prefix_try.rb
 - try/features/relationships/participation_performance_improvements_try.rb
 - try/features/relationships/participation_reverse_index_try.rb
+- try/features/relationships/participation_reverse_methods_try.rb
 - try/features/relationships/participation_target_class_resolution_try.rb
+- try/features/relationships/participation_through_try.rb
 - try/features/relationships/participation_unresolved_target_try.rb
 - try/features/relationships/relationships_api_changes_try.rb
 - try/features/relationships/relationships_edge_cases_try.rb