familia 2.0.0.pre8 → 2.0.0.pre12

data/examples/relationships_basic.rb

@@ -1,273 +0,0 @@
-#!/usr/bin/env ruby
-
-# Basic Relationships Example
-# This example demonstrates the core features of Familia's relationships system
-
-require_relative '../lib/familia'
-
-# Configure Familia for the example
-Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_URI', 'redis://localhost:6379/15')
-end
-
-puts "=== Familia Relationships Basic Example ==="
-puts
-
-# Define our model classes
-class Customer < Familia::Horreum
-  feature :relationships
-
-  identifier_field :custid
-  field :custid, :name, :email, :plan
-
-  # Define collections for tracking relationships
-  set :domains           # Simple set of domain IDs
-  list :projects         # Ordered list of project IDs
-  sorted_set :activity   # Activity feed with timestamps
-
-  # Create indexes for fast lookups
-  indexed_by :email_lookup, field: :email
-  indexed_by :plan_lookup, field: :plan
-
-  # Track in global collections
-  tracked_in :all_customers, type: :sorted_set, score: :created_at
-
-  def created_at
-    Time.now.to_i
-  end
-end
-
-class Domain < Familia::Horreum
-  feature :relationships
-
-  identifier_field :domain_id
-  field :domain_id, :name, :dns_zone, :status
-
-  # Declare membership in customer collections
-  member_of Customer, :domains, type: :set
-
-  # Track domains by status
-  tracked_in :active_domains, type: :sorted_set,
-    score: ->(domain) { domain.status == 'active' ? Time.now.to_i : 0 }
-end
-
-class Project < Familia::Horreum
-  feature :relationships
-
-  identifier_field :project_id
-  field :project_id, :name, :priority
-
-  # Member of customer projects list (ordered)
-  member_of Customer, :projects, type: :list
-end
-
-puts "=== 1. Basic Object Creation ==="
-
-# Create some sample objects
-customer = Customer.new(
-  custid: "cust_#{SecureRandom.hex(4)}",
-  name: "Acme Corporation",
-  email: "admin@acme.com",
-  plan: "enterprise"
-)
-
-domain1 = Domain.new(
-  domain_id: "dom_#{SecureRandom.hex(4)}",
-  name: "acme.com",
-  dns_zone: "acme.com.",
-  status: "active"
-)
-
-domain2 = Domain.new(
-  domain_id: "dom_#{SecureRandom.hex(4)}",
-  name: "staging.acme.com",
-  dns_zone: "staging.acme.com.",
-  status: "active"
-)
-
-project = Project.new(
-  project_id: "proj_#{SecureRandom.hex(4)}",
-  name: "Website Redesign",
-  priority: "high"
-)
-
-puts "✓ Created customer: #{customer.name} (#{customer.custid})"
-puts "✓ Created domains: #{domain1.name}, #{domain2.name}"
-puts "✓ Created project: #{project.name}"
-puts
-
-puts "=== 2. Establishing Relationships ==="
-
-# Add objects to indexed lookups
-Customer.add_to_email_lookup(customer)
-Customer.add_to_plan_lookup(customer)
-puts "✓ Added customer to email and plan indexes"
-
-# Add customer to global tracking
-Customer.add_to_all_customers(customer)
-puts "✓ Added customer to global customer tracking"
-
-# Establish member_of relationships (bidirectional)
-domain1.add_to_customer_domains(customer.custid)
-customer.domains.add(domain1.identifier)
-
-domain2.add_to_customer_domains(customer.custid)
-customer.domains.add(domain2.identifier)
-
-project.add_to_customer_projects(customer.custid)
-customer.projects.add(project.identifier)
-
-puts "✓ Established domain ownership relationships"
-puts "✓ Established project ownership relationships"
-
-# Track domains in status collections
-Domain.add_to_active_domains(domain1)
-Domain.add_to_active_domains(domain2)
-puts "✓ Added domains to active tracking"
-puts
-
-puts "=== 3. Querying Relationships ==="
-
-# Test indexed lookups
-found_customer_id = Customer.email_lookup.get(customer.email)
-puts "Email lookup for #{customer.email}: #{found_customer_id}"
-
-enterprise_customers = Customer.plan_lookup.get("enterprise")
-puts "Enterprise customer found: #{enterprise_customers}"
-
-# Test membership queries
-puts "\nDomain membership checks:"
-puts "  #{domain1.name} belongs to customer? #{domain1.in_customer_domains?(customer.custid)}"
-puts "  #{domain2.name} belongs to customer? #{domain2.in_customer_domains?(customer.custid)}"
-
-puts "\nCustomer collections:"
-puts "  Customer has #{customer.domains.size} domains"
-puts "  Customer has #{customer.projects.size} projects"
-puts "  Domain IDs: #{customer.domains.members}"
-puts "  Project IDs: #{customer.projects.members}"
-
-# Test tracked_in collections
-all_customers_count = Customer.all_customers.size
-puts "\nGlobal tracking:"
-puts "  Total customers in system: #{all_customers_count}"
-
-active_domains_count = Domain.active_domains.size
-puts "  Active domains in system: #{active_domains_count}"
-puts
-
-puts "=== 4. Range Queries ==="
-
-# Get recent customers (last 24 hours)
-yesterday = (Time.now - 24.hours).to_i
-recent_customers = Customer.all_customers.range_by_score(yesterday, '+inf')
-puts "Recent customers (last 24h): #{recent_customers.size}"
-
-# Get all active domains by score
-active_domain_scores = Domain.active_domains.range_by_score(1, '+inf', with_scores: true)
-puts "Active domains with timestamps:"
-active_domain_scores.each do |domain_id, timestamp|
-  puts "  #{domain_id}: active since #{Time.at(timestamp.to_i)}"
-end
-puts
-
-puts "=== 5. Batch Operations ==="
-
-# Create additional test data
-additional_customers = []
-3.times do |i|
-  cust = Customer.new(
-    custid: "batch_cust_#{i}",
-    name: "Customer #{i}",
-    email: "customer#{i}@example.com",
-    plan: i.even? ? "basic" : "premium"
-  )
-  additional_customers << cust
-
-  # Add to indexes and tracking
-  Customer.add_to_email_lookup(cust)
-  Customer.add_to_plan_lookup(cust)
-  Customer.add_to_all_customers(cust)
-end
-
-puts "✓ Created and indexed #{additional_customers.size} additional customers"
-
-# Query by plan
-basic_customers = Customer.plan_lookup.get("basic")
-premium_customers = Customer.plan_lookup.get("premium")
-enterprise_customers = Customer.plan_lookup.get("enterprise")
-
-puts "\nCustomer distribution by plan:"
-puts "  Basic: #{basic_customers ? 1 : 0} customers"
-puts "  Premium: #{premium_customers ? 1 : 0} customers"
-puts "  Enterprise: #{enterprise_customers ? 1 : 0} customers"
-puts
-
-puts "=== 6. Relationship Cleanup ==="
-
-# Remove relationships
-puts "Cleaning up relationships..."
-
-# Remove from member_of relationships
-domain1.remove_from_customer_domains(customer.custid)
-customer.domains.remove(domain1.identifier)
-puts "✓ Removed #{domain1.name} from customer domains"
-
-# Remove from tracking collections
-Domain.active_domains.remove(domain2.identifier)
-puts "✓ Removed #{domain2.name} from active domains"
-
-# Verify cleanup
-puts "\nAfter cleanup:"
-puts "  Customer domains: #{customer.domains.size}"
-puts "  Active domains: #{Domain.active_domains.size}"
-puts
-
-puts "=== 7. Advanced Usage - Permission Encoding ==="
-
-# Demonstrate basic score encoding for permissions
-class DocumentAccess
-  # Permission flags (powers of 2)
-  READ = 1
-  WRITE = 2
-  DELETE = 4
-  ADMIN = 8
-
-  def self.encode_permissions(timestamp, permissions)
-    "#{timestamp}.#{permissions}".to_f
-  end
-
-  def self.decode_permissions(score)
-    parts = score.to_s.split('.')
-    timestamp = parts[0].to_i
-    permissions = parts[1] ? parts[1].to_i : 0
-    [timestamp, permissions]
-  end
-end
-
-# Example permission encoding
-now = Time.now.to_i
-read_write_permissions = DocumentAccess::READ | DocumentAccess::WRITE  # 3
-admin_permissions = DocumentAccess::ADMIN  # 8
-
-encoded_score = DocumentAccess.encode_permissions(now, read_write_permissions)
-timestamp, permissions = DocumentAccess.decode_permissions(encoded_score)
-
-puts "Permission encoding example:"
-puts "  Original: timestamp=#{now}, permissions=#{read_write_permissions}"
-puts "  Encoded score: #{encoded_score}"
-puts "  Decoded: timestamp=#{timestamp}, permissions=#{permissions}"
-puts "  Has read access: #{(permissions & DocumentAccess::READ) != 0}"
-puts "  Has write access: #{(permissions & DocumentAccess::WRITE) != 0}"
-puts "  Has delete access: #{(permissions & DocumentAccess::DELETE) != 0}"
-puts
-
-puts "=== Example Complete! ==="
-puts
-puts "Key takeaways:"
-puts "• tracked_in: Use for activity feeds, leaderboards, time-series data"
-puts "• indexed_by: Use for fast O(1) lookups by field values"
-puts "• member_of: Use for bidirectional ownership/membership"
-puts "• Score encoding: Combine timestamps with metadata for rich queries"
-puts "• Batch operations: Use Redis pipelines for efficiency"
-puts
-puts "See docs/wiki/Relationships-Guide.md for comprehensive documentation"

data/lib/familia/features/external_identifiers/external_identifier_field_type.rb

@@ -1,120 +0,0 @@
-# lib/familia/features/external_identifiers/external_identifier_field_type.rb
-
-require 'familia/field_type'
-
-module Familia
-  module Features
-    module ExternalIdentifiers
-      # ExternalIdentifierFieldType - Fields that generate deterministic external identifiers
-      #
-      # External identifier fields generate shorter, public-facing identifiers that are
-      # deterministically derived from object identifiers. These IDs are safe for use
-      # in URLs, APIs, and other external contexts where shorter IDs are preferred.
-      #
-      # Key characteristics:
-      # - Deterministic generation from objid ensures consistency
-      # - Shorter than objid (128-bit vs 256-bit) for external use
-      # - Base-36 encoding for URL-safe identifiers
-      # - 'ext_' prefix for clear identification as external IDs
-      # - Lazy generation preserves values from initialization
-      #
-      # @example Using external identifier fields
-      #   class User < Familia::Horreum
-      #     feature :object_identifiers
-      #     feature :external_identifiers
-      #     field :email
-      #   end
-      #
-      #   user = User.new(email: 'user@example.com')
-      #   user.objid  # => "01234567-89ab-7def-8000-123456789abc"
-      #   user.extid  # => "ext_abc123def456ghi789" (deterministic from objid)
-      #
-      #   # Same objid always produces same extid
-      #   user2 = User.new(objid: user.objid, email: 'user@example.com')
-      #   user2.extid  # => "ext_abc123def456ghi789" (identical to user.extid)
-      #
-      class ExternalIdentifierFieldType < FieldType
-        # Override getter to provide lazy generation from objid
-        #
-        # Generates the external identifier deterministically from the object's
-        # objid. This ensures consistency - the same objid will always produce
-        # the same extid. Only generates when objid is available.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_getter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, method_name) do
-            klass.define_method method_name do
-              # Check if we already have a value (from initialization or previous generation)
-              existing_value = instance_variable_get(:"@#{field_name}")
-              return existing_value unless existing_value.nil?
-
-              # Generate external identifier from objid if available
-              generated_extid = generate_external_identifier
-              return unless generated_extid
-
-              instance_variable_set(:"@#{field_name}", generated_extid)
-
-              # Update mapping if we have an identifier
-              if respond_to?(:identifier) && identifier
-                self.class.extid_lookup[generated_extid] = identifier
-              end
-
-              generated_extid
-            end
-          end
-        end
-
-        # Override setter to preserve values during initialization
-        #
-        # This ensures that values passed during object initialization
-        # (e.g., when loading from Redis) are preserved and not overwritten
-        # by the lazy generation logic.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_setter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, :"#{method_name}=") do
-            klass.define_method :"#{method_name}=" do |value|
-              # Remove old mapping if extid is changing
-              old_value = instance_variable_get(:"@#{field_name}")
-              if old_value && old_value != value && respond_to?(:identifier)
-                self.class.extid_lookup.del(old_value)
-              end
-
-              # Set the new value
-              instance_variable_set(:"@#{field_name}", value)
-
-              # Update mapping if we have both extid and identifier
-              if value && respond_to?(:identifier) && identifier
-                self.class.extid_lookup[value] = identifier
-              end
-            end
-          end
-        end
-
-        # External identifier fields are persisted to database
-        #
-        # @return [Boolean] true - external identifiers are always persisted
-        #
-        def persistent?
-          true
-        end
-
-        # Category for external identifier fields
-        #
-        # @return [Symbol] :external_identifier
-        #
-        def category
-          :external_identifier
-        end
-      end
-    end
-  end
-end

data/lib/familia/features/external_identifiers.rb

@@ -1,111 +0,0 @@
-# lib/familia/features/external_identifiers.rb
-
-require_relative 'external_identifiers/external_identifier_field_type'
-
-module Familia
-  module Features
-
-    # Familia::Features::ExternalIdentifiers
-    #
-    module ExternalIdentifiers
-      def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
-
-        # Ensure default prefix is set in feature options
-        base.add_feature_options(:external_identifiers, prefix: 'ext')
-
-        # Add class-level mapping for extid -> id lookups
-        base.class_hashkey :extid_lookup
-
-        # Register the extid field using our custom field type
-        base.register_field_type(
-          ExternalIdentifiers::ExternalIdentifierFieldType.new(:extid, as: :extid, fast_method: false)
-        )
-      end
-
-      # ExternalIdentifiers::ClassMethods
-      #
-      module ClassMethods
-        def generate_extid(objid = nil)
-          unless features_enabled.include?(:object_identifiers)
-            raise Familia::Problem,
-                  'ExternalIdentifiers requires ObjectIdentifiers feature'
-          end
-          return nil if objid.to_s.empty?
-
-          objid_hex = objid.to_s.delete('-')
-          external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
-          prefix = feature_options(:external_identifiers)[:prefix] || 'ext'
-          "#{prefix}_#{external_part}"
-        end
-
-        # Find an object by its external identifier
-        #
-        # @param extid [String] The external identifier to search for
-        # @return [Object, nil] The object if found, nil otherwise
-        #
-        def find_by_extid(extid)
-          return nil if extid.to_s.empty?
-
-          if Familia.debug?
-            reference = caller(1..1).first
-            Familia.trace :FIND_BY_EXTID, Familia.dbclient, extid, reference
-          end
-
-          # Look up the primary ID from the external ID mapping
-          primary_id = extid_lookup[extid]
-          return nil if primary_id.nil?
-
-          # Find the object by its primary ID
-          find_by_id(primary_id)
-        rescue Familia::NotFound
-          # If the object was deleted but mapping wasn't cleaned up
-          extid_lookup.del(extid)
-          nil
-        end
-      end
-
-      # Generate external identifier deterministically from objid
-      def generate_external_identifier
-        return nil unless respond_to?(:objid)
-
-        current_objid = objid
-        return nil if current_objid.nil? || current_objid.to_s.empty?
-
-        # Convert objid to hex string for processing
-        objid_hex = current_objid.delete('-') # Remove UUID hyphens if present
-
-        # Generate deterministic external ID using SecureIdentifier
-        external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
-
-        # Get prefix from feature options, default to "ext"
-        options = self.class.feature_options(:external_identifiers)
-        prefix = options[:prefix] || 'ext'
-
-        "#{prefix}_#{external_part}"
-      end
-
-      def external_identifier
-        extid
-      end
-
-      def init
-        super if defined?(super)
-        # External IDs are generated from objid, so no additional setup needed
-      end
-
-      def destroy!
-        # Clean up extid mapping when object is destroyed
-        current_extid = instance_variable_get(:@extid)
-        if current_extid
-          self.class.extid_lookup.del(current_extid)
-        end
-
-        super if defined?(super)
-      end
-
-      Familia::Base.add_feature self, :external_identifiers, depends_on: [:object_identifiers]
-    end
-  end
-end

data/lib/familia/features/object_identifiers/object_identifier_field_type.rb

@@ -1,91 +0,0 @@
-# lib/familia/features/object_identifiers/object_identifier_field_type.rb
-
-require 'familia/field_type'
-
-module Familia
-  module Features
-    module ObjectIdentifiers
-      # ObjectIdentifierFieldType - Fields that generate unique object identifiers
-      #
-      # Object identifier fields automatically generate unique identifiers when first
-      # accessed if not already set. The generation strategy is configurable via
-      # feature options. These fields preserve any values set during initialization
-      # to ensure data integrity when loading existing objects from Redis.
-      #
-      # @example Using object identifier fields
-      #   class User < Familia::Horreum
-      #     feature :object_identifiers, generator: :uuid_v7
-      #   end
-      #
-      #   user = User.new
-      #   user.objid  # Generates UUID v7 on first access
-      #
-      #   # Loading existing object preserves ID
-      #   user2 = User.new(objid: "existing-uuid")
-      #   user2.objid  # Returns "existing-uuid", not regenerated
-      #
-      class ObjectIdentifierFieldType < FieldType
-        # Override getter to provide lazy generation with configured strategy
-        #
-        # Generates the identifier using the configured strategy if not already set.
-        # This preserves any values set during initialization while providing
-        # automatic generation for new objects.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_getter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, method_name) do
-            klass.define_method method_name do
-              # Check if we already have a value (from initialization or previous generation)
-              existing_value = instance_variable_get(:"@#{field_name}")
-              return existing_value unless existing_value.nil?
-
-              # Generate new identifier using configured strategy
-              generated_id = generate_object_identifier
-              instance_variable_set(:"@#{field_name}", generated_id)
-              generated_id
-            end
-          end
-        end
-
-        # Override setter to preserve values during initialization
-        #
-        # This ensures that values passed during object initialization
-        # (e.g., when loading from Redis) are preserved and not overwritten
-        # by the lazy generation logic.
-        #
-        # @param klass [Class] The class to define the method on
-        #
-        def define_setter(klass)
-          field_name = @name
-          method_name = @method_name
-
-          handle_method_conflict(klass, :"#{method_name}=") do
-            klass.define_method :"#{method_name}=" do |value|
-              instance_variable_set(:"@#{field_name}", value)
-            end
-          end
-        end
-
-        # Object identifier fields are persisted to database
-        #
-        # @return [Boolean] true - object identifiers are always persisted
-        #
-        def persistent?
-          true
-        end
-
-        # Category for object identifier fields
-        #
-        # @return [Symbol] :object_identifier
-        #
-        def category
-          :object_identifier
-        end
-      end
-    end
-  end
-end