familia 2.0.0.pre21 → 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/connection/operation_core.rb

@@ -87,8 +87,7 @@ module Familia
 
         # Return MultiResult format for consistency
         results = proxy.collected_results
-        summary_boolean = results.all? { |ret| !ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, results)
+        MultiResult.new(results)
       end
     end
   end

data/lib/familia/connection/pipelined_core.rb

@@ -80,9 +80,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        # Pipeline success is true if no exceptions occurred (all commands executed)
-        summary_boolean = command_return_values.none? { |ret| ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/connection/transaction_core.rb

@@ -158,8 +158,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/data_type/serialization.rb

@@ -8,46 +8,45 @@ module Familia
       # Serializes a value for storage in the database.
       #
       # @param val [Object] The value to be serialized.
-      # @param strict_values [Boolean] Whether to enforce strict value
-      #   serialization (default: true).
-      # @return [String, nil] The serialized representation of the value, or nil
-      #   if serialization fails.
+      # @return [String] The JSON-serialized representation of the value.
       #
-      # @note When a class option is specified, it uses Familia.identifier_extractor
-      #   to extract the identifier from objects. Otherwise, it extracts identifiers
-      #   from Familia::Base instances or class names.
+      # Serialization priority:
+      # 1. Familia objects (Base instances or classes) → extract identifier
+      # 2. All other values → JSON serialize for type preservation
       #
-      # @example With a class option
-      #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation across DataType and Horreum.
       #
-      # @example Without a class option
-      #   serialize_value(123) #=> "123"
-      #   serialize_value("hello") #=> "hello"
+      # @example Familia object reference
+      #   serialize_value(customer_obj) #=> "customer_123" (identifier)
       #
-      # @raise [Familia::NotDistinguishableError] If serialization fails under strict
-      #   mode.
+      # @example Primitive values (JSON encoded)
+      #   serialize_value(42)          #=> "42"
+      #   serialize_value("hello")     #=> '"hello"'
+      #   serialize_value(true)        #=> "true"
+      #   serialize_value(nil)         #=> "null"
+      #   serialize_value([1, 2, 3])   #=> "[1,2,3]"
       #
-      def serialize_value(val, strict_values: true)
-        prepared = nil
-
+      def serialize_value(val)
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
-        if opts[:class]
-          prepared = Familia.identifier_extractor(opts[:class])
-          Familia.debug "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
+        # Priority 1: Handle Familia object references - extract identifier
+        # This preserves the existing behavior for storing object references
+        if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+          prepared = val.is_a?(Class) ? val.name : val.identifier
+          Familia.debug "  Familia object: #{val.class} => #{prepared}"
+          return prepared
         end
 
-        if prepared.nil?
-          # Enforce strict values when no class option is specified
-          prepared = Familia.identifier_extractor(val)
-          Familia.debug "  from <#{val.class}> => <#{prepared.class}>"
-        end
+        # Priority 2: Everything else gets JSON serialized for type preservation
+        # This unifies behavior with Horreum fields (Issue #190)
+        prepared = Familia::JsonSerializer.dump(val)
+        Familia.debug "  JSON serialized: #{val.class} => #{prepared}"
 
         if Familia.debug?
-          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>"
+          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}> => #{prepared}<#{prepared.class}>"
         end
 
-        Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
         prepared
       end
 
@@ -81,27 +80,41 @@ module Familia
       def deserialize_values_with_nil(*values)
         Familia.debug "deserialize_values: (#{@opts}) #{values}"
         return [] if values.empty?
-        return values.flatten unless @opts[:class]
 
-        unless @opts[:class].respond_to?(load_method)
-          raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
-        end
+        # If a class option is specified, use class-based deserialization
+        if @opts[:class]
+          unless @opts[:class].respond_to?(load_method)
+            raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+          end
 
-        values.collect! do |obj|
-          next if obj.nil?
+          values.collect! do |obj|
+            next if obj.nil?
 
-          val = @opts[:class].send load_method, obj
-          Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+            val = @opts[:class].send load_method, obj
+            Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
-          val
-        rescue StandardError => e
-          Familia.info val
-          Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
-          Familia.info e.backtrace
-          nil
+            val
+          rescue StandardError => e
+            Familia.info val
+            Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
+            Familia.info e.backtrace
+            nil
+          end
+
+          return values
         end
 
-        values
+        # No class option: JSON deserialize each value for type preservation (Issue #190)
+        values.flatten.collect do |obj|
+          next if obj.nil?
+
+          begin
+            Familia::JsonSerializer.parse(obj)
+          rescue Familia::SerializerError
+            # Fallback for legacy data stored without JSON encoding
+            obj
+          end
+        end
       end
 
       # Deserializes a single value from the database.
@@ -110,13 +123,15 @@ module Familia
       # @return [Object, nil] The deserialized object, the default value if
       #   val is nil, or nil if deserialization fails.
       #
-      # @note If no class option is specified, the original value is
-      #   returned unchanged.
+      # Deserialization priority:
+      # 1. Redis::Future objects → return as-is (transaction handling)
+      # 2. nil values → return default option value
+      # 3. Class option specified → use class-based deserialization
+      # 4. No class option → JSON parse for type preservation
       #
-      # NOTE: Currently only the DataType class uses this method. Horreum
-      # fields are a newer addition and don't support the full range of
-      # deserialization options that DataType supports. It uses serialize_value
-      # for serialization since everything becomes a string in Valkey.
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation. Legacy data stored without JSON
+      # encoding is returned as-is.
       #
       def deserialize_value(val)
         # Handle Redis::Future objects during transactions first
@@ -124,10 +139,20 @@ module Familia
 
         return @opts[:default] if val.nil?
 
-        return val unless @opts[:class]
+        # If a class option is specified, use the existing class-based deserialization
+        if @opts[:class]
+          ret = deserialize_values val
+          return ret&.first # return the object or nil
+        end
 
-        ret = deserialize_values val
-        ret&.first # return the object or nil
+        # No class option: JSON deserialize for type preservation (Issue #190)
+        # This unifies behavior with Horreum fields
+        begin
+          Familia::JsonSerializer.parse(val)
+        rescue Familia::SerializerError
+          # Fallback for legacy data stored without JSON encoding
+          val
+        end
       end
     end
   end

data/lib/familia/data_type/types/sorted_set.rb

@@ -129,7 +129,7 @@ module Familia
     alias add_element add
 
     def score(val)
-      ret = dbclient.zscore dbkey, serialize_value(val, strict_values: false)
+      ret = dbclient.zscore dbkey, serialize_value(val)
       ret&.to_f
     end
     alias [] score
@@ -142,13 +142,13 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = dbclient.zrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = dbclient.zrevrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrevrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
@@ -269,7 +269,7 @@ module Familia
     end
 
     def increment(val, by = 1)
-      dbclient.zincrby(dbkey, by, val).to_i
+      dbclient.zincrby(dbkey, by, serialize_value(val)).to_i
     end
     alias incr increment
     alias incrby increment
@@ -285,12 +285,7 @@ module Familia
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
       Familia.trace :REMOVE_ELEMENT, nil, "#{value}<#{value.class}>" if Familia.debug?
-      # We use `strict_values: false` here to allow for the deletion of values
-      # that are in the sorted set. If it's a horreum object, the value is
-      # the identifier and not a serialized version of the object. So either
-      # the value exists in the sorted set or it doesn't -- we don't need to
-      # raise an error if it's not found.
-      dbclient.zrem dbkey, serialize_value(value, strict_values: false)
+      dbclient.zrem dbkey, serialize_value(value)
     end
     alias remove remove_element # deprecated
 

data/lib/familia/data_type/types/stringkey.rb

@@ -6,6 +6,28 @@ module Familia
   class StringKey < DataType
     def init; end
 
+    # StringKey uses raw string serialization (not JSON) because Redis string
+    # operations like INCR, DECR, APPEND operate on raw values.
+    # This overrides the base JSON serialization from DataType.
+    def serialize_value(val)
+      Familia.trace :TOREDIS, nil, "#{val}<#{val.class}>" if Familia.debug?
+
+      # Handle Familia object references - extract identifier
+      if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+        return val.is_a?(Class) ? val.name : val.identifier
+      end
+
+      # StringKey uses raw string conversion for Redis compatibility
+      val.to_s
+    end
+
+    # StringKey returns raw values (not JSON parsed)
+    def deserialize_value(val)
+      return val if val.is_a?(Redis::Future)
+      return @opts[:default] if val.nil?
+      val
+    end
+
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def char_count

data/lib/familia/features/external_identifier.rb

@@ -176,6 +176,35 @@ module Familia
           # extid_lookup.remove_field(extid)
           nil
         end
+
+        # Check if a string matches the extid format for the Horreum class. The specific
+        # class is important b/c each one can have its own custom prefix, like `ext_`.
+        #
+        # The validator accepts a reasonable range of ID lengths (20-32 characters) to
+        # accommodate potential changes to the entropy or encoding while maintaining
+        # security. The current implementation generates exactly 25 base36 characters
+        # from 16 bytes (128 bits), but this flexibility allows for future adjustments
+        # without breaking validation.
+        #
+        # @param guess [String] The string to check
+        # @return [Boolean] true if the guess matches the extid format, false otherwise
+        def extid?(guess)
+          return false if guess.to_s.empty?
+
+          options = feature_options(:external_identifier)
+          format = options[:format] || 'ext_%{id}'
+
+          # Extract prefix and suffix from format
+          return false unless format.include?('%{id}')
+          prefix, suffix = format.split('%{id}', 2)
+
+          # Build regex pattern to match the extid format
+          # Accept 20-32 base36 characters to allow for entropy/encoding variations
+          # Current generation: 16 bytes -> base36 -> 25 chars (rjust with '0')
+          pattern = /\A#{Regexp.escape(prefix)}[0-9a-z]{20,32}#{Regexp.escape(suffix)}\z/i
+
+          !!(guess =~ pattern)
+        end
       end
 
       # Instance methods for external identifier management

data/lib/familia/features/object_identifier.rb

@@ -279,6 +279,53 @@ module Familia
           # objid_lookup.remove_field(objid)
           nil
         end
+
+        # Check if a string matches the objid format for the Horreum class. The specific
+        # class is important b/c each one can have its own type of objid generator.
+        #
+        # @param guess [String] The string to check
+        # @return [Boolean] true if the guess matches the objid format, false otherwise
+        def objid?(guess)
+          return false if guess.to_s.empty?
+
+          options = feature_options(:object_identifier)
+          generator = options[:generator] || DEFAULT_GENERATOR
+
+          case generator
+          when :uuid_v7, :uuid_v4
+            # UUID format: xxxxxxxx-xxxx-Vxxx-xxxx-xxxxxxxxxxxx (36 chars with hyphens)
+            # Validate structure and that all characters are valid hex digits
+            guess_str = guess.to_s
+            return false unless guess_str.length == 36
+            return false unless guess_str[8] == '-' && guess_str[13] == '-' && guess_str[18] == '-' && guess_str[23] == '-'
+
+            # Extract segments and validate each is valid hex
+            segments = guess_str.split('-')
+            return false unless segments.length == 5
+            return false unless segments[0] =~ /\A[0-9a-fA-F]{8}\z/  # 8 hex chars
+            return false unless segments[1] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars
+            return false unless segments[2] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars (includes version)
+            return false unless segments[3] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars
+            return false unless segments[4] =~ /\A[0-9a-fA-F]{12}\z/ # 12 hex chars
+
+            # Validate version character
+            version_char = guess_str[14]
+            if generator == :uuid_v7
+              version_char == '7'
+            else # generator == :uuid_v4
+              version_char == '4'
+            end
+          when :hex
+            # Hex format: pure hexadecimal without hyphens
+            !!(guess =~ /\A[0-9a-fA-F]+\z/)
+          when Proc
+            # Cannot determine format for custom Proc generators
+            Familia.warn "[objid?] Validation not supported for custom Proc generators on #{name}" if Familia.debug?
+            false
+          else
+            false
+          end
+        end
       end
 
       # Instance methods for object identifier management

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()
 ```