familia 2.0.0.pre22 → 2.0.0.pre23

data/examples/through_relationships.rb

@@ -0,0 +1,275 @@
+#!/usr/bin/env ruby
+# examples/through_relationships.rb
+#
+# frozen_string_literal: true
+
+# Through Relationships Example
+# Demonstrates the :through option for participates_in, which creates
+# intermediate join models with additional attributes (roles, metadata, etc.)
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'familia'
+
+# Configure Familia for the example
+# Use port 2525 (Familia test database) or set REDIS_URL
+Familia.configure do |config|
+  config.uri = ENV.fetch('REDIS_URL', 'redis://localhost:2525/')
+end
+
+puts '=== Familia Through Relationships Example ==='
+puts
+puts 'The :through option creates join models between participants and targets,'
+puts 'similar to has_many :through in ActiveRecord but for Redis.'
+puts
+
+# ============================================================================
+# MODEL DEFINITIONS
+# ============================================================================
+
+# The through model MUST use feature :object_identifier
+# This enables deterministic key generation for the join record
+class Membership < Familia::Horreum
+  logical_database 15
+  feature :object_identifier  # REQUIRED for through models
+  feature :relationships
+
+  identifier_field :objid
+
+  # Foreign keys (auto-set by through operations)
+  field :organization_objid
+  field :user_objid
+
+  # Additional attributes - this is why we use :through!
+  field :role           # 'owner', 'admin', 'member'
+  field :permissions    # JSON or comma-separated list
+  field :invited_by     # Who invited this user
+  field :invited_at     # When they were invited
+  field :joined_at      # When they accepted
+  field :updated_at     # Auto-set for cache invalidation
+end
+
+class Organization < Familia::Horreum
+  logical_database 15
+  feature :object_identifier
+  feature :relationships
+
+  identifier_field :objid  # Use objid as identifier (auto-generated)
+  field :name
+  field :plan
+end
+
+class User < Familia::Horreum
+  logical_database 15
+  feature :object_identifier
+  feature :relationships
+
+  identifier_field :objid  # Use objid as identifier (auto-generated)
+  field :email
+  field :name
+
+  # Declare participation WITH a through model
+  # This creates Membership records when adding users to organizations
+  participates_in Organization, :members,
+                  score: -> { Familia.now.to_f },
+                  through: :Membership
+end
+
+puts '=== 1. Model Setup ==='
+puts
+puts 'Through model (Membership) requirements:'
+puts '  • feature :object_identifier - enables deterministic keys'
+puts '  • Fields for foreign keys: organization_objid, user_objid'
+puts '  • Additional fields: role, permissions, invited_by, etc.'
+puts
+puts 'Participant (User) declaration:'
+puts '  participates_in Organization, :members,'
+puts '                  score: -> { Familia.now.to_f },'
+puts '                  through: :Membership'
+puts
+
+# ============================================================================
+# CREATING OBJECTS
+# ============================================================================
+
+puts '=== 2. Creating Objects ==='
+
+org = Organization.new(name: 'Acme Corp', plan: 'enterprise')
+org.save
+puts "Created organization: #{org.name} (#{org.objid})"
+
+alice = User.new(email: 'alice@acme.com', name: 'Alice')
+alice.save
+puts "Created user: #{alice.name} (#{alice.objid})"
+
+bob = User.new(email: 'bob@acme.com', name: 'Bob')
+bob.save
+puts "Created user: #{bob.name} (#{bob.objid})"
+
+charlie = User.new(email: 'charlie@acme.com', name: 'Charlie')
+charlie.save
+puts "Created user: #{charlie.name} (#{charlie.objid})"
+puts
+
+# ============================================================================
+# ADDING MEMBERS WITH THROUGH ATTRIBUTES
+# ============================================================================
+
+puts '=== 3. Adding Members with Roles ==='
+puts
+
+# Add Alice as owner - through_attrs sets Membership fields
+membership_alice = org.add_members_instance(alice, through_attrs: {
+                                              role: 'owner',
+  permissions: 'all',
+  joined_at: Familia.now.to_f,
+                                            })
+
+puts "Added #{alice.name} as #{membership_alice.role}"
+puts "  Membership objid: #{membership_alice.objid}"
+puts "  Membership class: #{membership_alice.class.name}"
+puts
+
+# Add Bob as admin
+membership_bob = org.add_members_instance(bob, through_attrs: {
+                                            role: 'admin',
+  permissions: 'read,write,invite',
+  invited_by: alice.objid,
+  invited_at: Familia.now.to_f,
+  joined_at: Familia.now.to_f,
+                                          })
+
+puts "Added #{bob.name} as #{membership_bob.role}"
+puts "  Invited by: #{membership_bob.invited_by}"
+puts
+
+# Add Charlie as member
+membership_charlie = org.add_members_instance(charlie, through_attrs: {
+                                                role: 'member',
+  permissions: 'read',
+  invited_by: bob.objid,
+  invited_at: Familia.now.to_f,
+  joined_at: Familia.now.to_f,
+                                              })
+
+puts "Added #{charlie.name} as #{membership_charlie.role}"
+puts
+
+# ============================================================================
+# QUERYING MEMBERSHIPS
+# ============================================================================
+
+puts '=== 4. Querying Memberships ==='
+puts
+
+# Check organization members
+puts "Organization #{org.name} has #{org.members.size} members:"
+org.members.members.each do |user_id|
+  puts "  - #{user_id}"
+end
+puts
+
+# Check if user is member
+puts "Is Alice a member? #{alice.in_organization_members?(org)}"
+puts "Is Bob a member? #{bob.in_organization_members?(org)}"
+puts
+
+# Load and inspect through model directly
+# Key format: {target_prefix}:{target_objid}:{participant_prefix}:{participant_objid}:{through_prefix}
+membership_key = "organization:#{org.objid}:user:#{alice.objid}:membership"
+loaded_membership = Membership.load(membership_key)
+
+puts 'Direct membership lookup for Alice:'
+puts "  Key: #{membership_key}"
+puts "  Role: #{loaded_membership.role}"
+puts "  Permissions: #{loaded_membership.permissions}"
+puts "  Updated at: #{Time.at(loaded_membership.updated_at.to_f)}"
+puts
+
+# ============================================================================
+# UPDATING MEMBERSHIP ATTRIBUTES
+# ============================================================================
+
+puts '=== 5. Updating Membership (Idempotent) ==='
+puts
+
+# Re-adding with different attrs updates the existing membership
+puts "Promoting #{charlie.name} from member to admin..."
+
+updated_membership = org.add_members_instance(charlie, through_attrs: {
+                                                role: 'admin',
+  permissions: 'read,write',
+                                              })
+
+puts "  New role: #{updated_membership.role}"
+puts "  Same objid? #{updated_membership.objid == membership_charlie.objid}"
+puts '  (Idempotent: updates existing, no duplicates)'
+puts
+
+# ============================================================================
+# REMOVING MEMBERS
+# ============================================================================
+
+puts '=== 6. Removing Members ==='
+puts
+
+puts "Removing #{charlie.name} from organization..."
+org.remove_members_instance(charlie)
+
+# Verify removal
+puts "  Is Charlie still a member? #{charlie.in_organization_members?(org)}"
+
+# Through model is also destroyed
+removed_key = "organization:#{org.objid}:user:#{charlie.objid}:membership"
+removed_membership = Membership.load(removed_key)
+puts "  Membership record exists? #{removed_membership&.exists? || false}"
+puts
+
+# ============================================================================
+# BACKWARD COMPATIBILITY
+# ============================================================================
+
+puts '=== 7. Backward Compatibility ==='
+puts
+
+# Define a relationship WITHOUT :through
+class Project < Familia::Horreum
+  logical_database 15
+  feature :object_identifier
+  feature :relationships
+  identifier_field :objid
+  field :name
+end
+
+class Task < Familia::Horreum
+  logical_database 15
+  feature :object_identifier
+  feature :relationships
+  identifier_field :objid
+  field :title
+  # No :through - works exactly as before
+  participates_in Project, :tasks, score: -> { Familia.now.to_f }
+end
+
+project = Project.new(name: 'Website Redesign')
+project.save
+
+task = Task.new(title: 'Design mockups')
+task.save
+
+# Without :through, returns the target (not a through model)
+result = project.add_tasks_instance(task)
+puts "Without :through, add returns: #{result.class.name}"
+puts '  (Returns the target, not a through model)'
+puts
+
+# ============================================================================
+# CLEANUP
+# ============================================================================
+
+puts '=== 8. Cleanup ==='
+
+[org, alice, bob, charlie, project, task].each do |obj|
+  obj.destroy! if obj&.exists?
+end
+puts 'Cleaned up all test objects'
+puts

data/lib/familia/features/relationships/README.md

@@ -12,7 +12,7 @@
 
 **participates_in** - Collection membership ("this object belongs in that collection")
 ```ruby
-participates_in Organization, :members, score: :joined_at, bidirectional: true
+participates_in Organization, :members, score: :joined_at, generate_participant_methods: true
 # Creates: org.members, org.add_member(), customer.add_to_organization_members()
 ```
 

data/lib/familia/features/relationships/participation/participant_methods.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../collection_operations'
+require_relative 'through_model_operations'
 
 module Familia
   module Features
@@ -33,6 +34,9 @@ module Familia
         module Builder
           extend CollectionOperations
 
+          # Include ThroughModelOperations for through model lifecycle
+          extend Participation::ThroughModelOperations
+
           # Build all participant methods for a participation relationship
           #
           # @param participant_class [Class] The class receiving these methods (e.g., Domain)
@@ -40,8 +44,9 @@ module Familia
           # @param collection_name [Symbol] Name of the collection (e.g., :domains)
           # @param type [Symbol] Collection type (:sorted_set, :set, :list)
           # @param as [Symbol, nil] Optional custom name for relationship methods (e.g., :employees)
+          # @param through [Symbol, Class, nil] Through model class for join table pattern
           #
-          def self.build(participant_class, target_class, collection_name, type, as)
+          def self.build(participant_class, target_class, collection_name, type, as, through = nil, method_prefix = nil)
             # Determine target name based on participation context:
             # - Instance-level: target_class is a Class object (e.g., Team) → use config_name ("project_team")
             # - Class-level: target_class is the string 'class' (from class_participates_in) → use as-is
@@ -55,8 +60,8 @@ module Familia
 
             # Core participant methods
             build_membership_check(participant_class, target_name, collection_name, type)
-            build_add_to_target(participant_class, target_name, collection_name, type)
-            build_remove_from_target(participant_class, target_name, collection_name, type)
+            build_add_to_target(participant_class, target_name, collection_name, type, through)
+            build_remove_from_target(participant_class, target_name, collection_name, type, through)
 
             # Type-specific methods
             case type
@@ -73,18 +78,23 @@ module Familia
             # - Class-level collections are accessed directly on the class (User.all_users)
             return if target_class.is_a?(String)  # 'class' indicates class-level participation
 
-            # If `as` is specified, create a custom method for just this collection
-            # Otherwise, add to the default pluralized method that unions all collections
+            # Priority for method naming:
+            # 1. `as:` - most specific, applies to just this collection
+            # 2. `method_prefix:` - applies to all collections for this target class
+            # 3. Default - uses target_class.config_name
             if as
               # Custom method for just this specific collection
               build_reverse_collection_methods(participant_class, target_class, as, [collection_name])
+            elsif method_prefix
+              # Custom prefix for all methods related to this target class
+              build_reverse_collection_methods(participant_class, target_class, method_prefix, nil)
             else
               # Default pluralized method - will include ALL collections for this target
               build_reverse_collection_methods(participant_class, target_class, nil, nil)
             end
           end
 
-          # Generate reverse collection methods on participant class for bidirectional access
+          # Generate reverse collection methods on participant class for symmetric access
           #
           # Creates methods like:
           # - user.team_instances (returns Array of Team instances)
@@ -186,11 +196,11 @@ module Familia
           end
 
           # Build method to add self to target's collection
-          # Creates: domain.add_to_customer_domains(customer, score)
-          def self.build_add_to_target(participant_class, target_name, collection_name, type)
+          # Creates: domain.add_to_customer_domains(customer, score, through_attrs: {})
+          def self.build_add_to_target(participant_class, target_name, collection_name, type, through = nil)
             method_name = "add_to_#{target_name}_#{collection_name}"
 
-            participant_class.define_method(method_name) do |target_instance, score = nil|
+            participant_class.define_method(method_name) do |target_instance, score = nil, through_attrs: {}|
               return unless target_instance&.identifier
 
               # Use Horreum's DataType accessor instead of manual creation
@@ -201,6 +211,9 @@ module Familia
                 score = calculate_participation_score(target_instance.class, collection_name)
               end
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection add and reverse index tracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               target_instance.transaction do |_tx|
@@ -217,12 +230,34 @@ module Familia
                 # Track participation for efficient cleanup using DataType method (SADD)
                 track_participation_in(collection.dbkey) if respond_to?(:track_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model operations intentionally happen AFTER
+              # the transaction block closes. This is a deliberate design decision because:
+              #
+              # 1. ThroughModelOperations.find_or_create performs load operations that would
+              #    return Redis::Future objects inside a transaction, breaking the flow
+              # 2. The core participation (collection add + tracking) is atomic within the tx
+              # 3. Through model creation is logically separate - if it fails, the participation
+              #    itself succeeded and can be cleaned up or retried independently
+              #
+              # If Familia's transaction handling changes in the future, revisit this boundary.
+              through_model = if through_class
+                Participation::ThroughModelOperations.find_or_create(
+                  through_class: through_class,
+                  target: target_instance,
+                  participant: self,
+                  attrs: through_attrs
+                )
+              end
+
+              # Return through model if using :through, otherwise self for backward compat
+              through_model || self
             end
           end
 
           # Build method to remove self from target's collection
           # Creates: domain.remove_from_customer_domains(customer)
-          def self.build_remove_from_target(participant_class, target_name, collection_name, type)
+          def self.build_remove_from_target(participant_class, target_name, collection_name, type, through = nil)
             method_name = "remove_from_#{target_name}_#{collection_name}"
 
             participant_class.define_method(method_name) do |target_instance|
@@ -231,6 +266,9 @@ module Familia
               # Use Horreum's DataType accessor instead of manual creation
               collection = target_instance.send(collection_name)
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection remove and reverse index untracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               target_instance.transaction do |_tx|
@@ -240,6 +278,17 @@ module Familia
                 # Remove from participation tracking using DataType method (SREM)
                 untrack_participation_in(collection.dbkey) if respond_to?(:untrack_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model destruction intentionally happens AFTER
+              # the transaction block. See build_add_to_target for detailed rationale.
+              # The core removal is atomic; through model cleanup is a separate operation.
+              if through_class
+                Participation::ThroughModelOperations.find_and_destroy(
+                  through_class: through_class,
+                  target: target_instance,
+                  participant: self
+                )
+              end
             end
           end
 

data/lib/familia/features/relationships/participation/target_methods.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../collection_operations'
+require_relative 'through_model_operations'
 
 module Familia
   module Features
@@ -30,18 +31,22 @@ module Familia
         module Builder
           extend CollectionOperations
 
+          # Include ThroughModelOperations for through model lifecycle
+          extend Participation::ThroughModelOperations
+
           # Build all target methods for a participation relationship
           # @param target_class [Class] The class receiving these methods (e.g., Customer)
           # @param collection_name [Symbol] Name of the collection (e.g., :domains)
           # @param type [Symbol] Collection type (:sorted_set, :set, :list)
-          def self.build(target_class, collection_name, type)
+          # @param through [Symbol, Class, nil] Through model class for join table pattern
+          def self.build(target_class, collection_name, type, through = nil)
             # FIRST: Ensure the DataType field is defined on the target class
             TargetMethods::Builder.ensure_collection_field(target_class, collection_name, type)
 
             # Core target methods
             build_collection_getter(target_class, collection_name, type)
-            build_add_item(target_class, collection_name, type)
-            build_remove_item(target_class, collection_name, type)
+            build_add_item(target_class, collection_name, type, through)
+            build_remove_item(target_class, collection_name, type, through)
             build_bulk_add(target_class, collection_name, type)
 
             # Type-specific methods
@@ -74,11 +79,11 @@ module Familia
           end
 
           # Build method to add an item to the collection
-          # Creates: customer.add_domains_instance(domain, score)
-          def self.build_add_item(target_class, collection_name, type)
+          # Creates: customer.add_domains_instance(domain, score, through_attrs: {})
+          def self.build_add_item(target_class, collection_name, type, through = nil)
             method_name = "add_#{collection_name}_instance"
 
-            target_class.define_method(method_name) do |item, score = nil|
+            target_class.define_method(method_name) do |item, score = nil, through_attrs: {}|
               collection = send(collection_name)
 
               # Calculate score if needed and not provided
@@ -86,6 +91,9 @@ module Familia
                 score = item.calculate_participation_score(self.class, collection_name)
               end
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection add and reverse index tracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               transaction do |_tx|
@@ -102,17 +110,42 @@ module Familia
                 # Track participation in reverse index using DataType method (SADD)
                 item.track_participation_in(collection.dbkey) if item.respond_to?(:track_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model operations intentionally happen AFTER
+              # the transaction block closes. This is a deliberate design decision because:
+              #
+              # 1. ThroughModelOperations.find_or_create performs load operations that would
+              #    return Redis::Future objects inside a transaction, breaking the flow
+              # 2. The core participation (collection add + tracking) is atomic within the tx
+              # 3. Through model creation is logically separate - if it fails, the participation
+              #    itself succeeded and can be cleaned up or retried independently
+              #
+              # If Familia's transaction handling changes in the future, revisit this boundary.
+              through_model = if through_class
+                Participation::ThroughModelOperations.find_or_create(
+                  through_class: through_class,
+                  target: self,
+                  participant: item,
+                  attrs: through_attrs
+                )
+              end
+
+              # Return through model if using :through, otherwise self for backward compat
+              through_model || self
             end
           end
 
           # Build method to remove an item from the collection
           # Creates: customer.remove_domains_instance(domain)
-          def self.build_remove_item(target_class, collection_name, type)
+          def self.build_remove_item(target_class, collection_name, type, through = nil)
             method_name = "remove_#{collection_name}_instance"
 
             target_class.define_method(method_name) do |item|
               collection = send(collection_name)
 
+              # Resolve through class if specified
+              through_class = through ? Familia.resolve_class(through) : nil
+
               # Use transaction for atomicity between collection remove and reverse index untracking
               # All operations use Horreum's DataType methods (not direct Redis calls)
               transaction do |_tx|
@@ -122,6 +155,17 @@ module Familia
                 # Remove from participation tracking using DataType method (SREM)
                 item.untrack_participation_in(collection.dbkey) if item.respond_to?(:untrack_participation_in)
               end
+
+              # TRANSACTION BOUNDARY: Through model destruction intentionally happens AFTER
+              # the transaction block. See build_add_item for detailed rationale.
+              # The core removal is atomic; through model cleanup is a separate operation.
+              if through_class
+                Participation::ThroughModelOperations.find_and_destroy(
+                  through_class: through_class,
+                  target: self,
+                  participant: item
+                )
+              end
             end
           end