familia 2.0.0.pre21 → 2.0.0.pre22

data/try/unit/data_types/serialization_try.rb

@@ -0,0 +1,386 @@
+# try/unit/data_types/serialization_try.rb
+#
+# frozen_string_literal: true
+
+# Test coverage for DataType serialization/deserialization behavior
+# Issue #190: Unify DataType and Horreum serialization for type preservation
+
+require_relative '../../support/helpers/test_helpers'
+
+Familia.debug = false
+
+# Create test instances
+@bone = Bone.new('serialize_test_token')
+
+# ========================================
+# DataType Serialization Behavior (Issue #190)
+# Now uses JSON serialization for type preservation
+# ========================================
+
+## HashKey stores string values correctly
+@bone.props['string_field'] = 'hello'
+@bone.props['string_field']
+#=> 'hello'
+
+## HashKey stores integer with type preservation
+@bone.props['int_field'] = 42
+@bone.props['int_field']
+#=> 42
+
+## HashKey stores float with type preservation
+@bone.props['float_field'] = 3.14
+@bone.props['float_field']
+#=> 3.14
+
+## HashKey stores symbol as string (symbols serialize to strings in JSON)
+@bone.props['symbol_field'] = :active
+@bone.props['symbol_field']
+#=> 'active'
+
+## HashKey stores boolean true with type preservation
+@bone.props['bool_true'] = true
+@bone.props['bool_true']
+#=> true
+
+## HashKey stores boolean true as TrueClass
+@bone.props['bool_true'].class
+#=> TrueClass
+
+## HashKey stores boolean false with type preservation
+@bone.props['bool_false'] = false
+@bone.props['bool_false']
+#=> false
+
+## HashKey stores boolean false as FalseClass
+@bone.props['bool_false'].class
+#=> FalseClass
+
+## HashKey stores nil with type preservation
+@bone.props['nil_field'] = nil
+@bone.props['nil_field']
+#=> nil
+
+## HashKey stores hash with type preservation
+@bone.props['hash_field'] = { 'key' => 'value' }
+@bone.props['hash_field']
+#=> {'key'=>'value'}
+
+## HashKey stores array with type preservation
+@bone.props['array_field'] = [1, 2, 3]
+@bone.props['array_field']
+#=> [1, 2, 3]
+
+# ========================================
+# List Serialization Behavior
+# ========================================
+
+## List stores string values correctly
+@bone.owners.delete!
+@bone.owners.push('owner1')
+@bone.owners.first
+#=> 'owner1'
+
+## List stores integer with type preservation
+@bone.owners.delete!
+@bone.owners.push(123)
+@bone.owners.first
+#=> 123
+
+## List stores boolean with type preservation
+@bone.owners.delete!
+@bone.owners.push(true)
+@bone.owners.first
+#=> true
+
+## List stores nil with type preservation
+@bone.owners.delete!
+@bone.owners.push(nil)
+@bone.owners.first
+#=> nil
+
+# ========================================
+# Set Serialization Behavior
+# ========================================
+
+## Set stores string values correctly
+@bone.tags.delete!
+@bone.tags.add('tag1')
+@bone.tags.members.include?('tag1')
+#=> true
+
+## Set stores integer with type preservation
+@bone.tags.delete!
+@bone.tags.add(42)
+@bone.tags.members.include?(42)
+#=> true
+
+## Set stores boolean with type preservation
+@bone.tags.delete!
+@bone.tags.add(true)
+@bone.tags.members.include?(true)
+#=> true
+
+# ========================================
+# SortedSet Serialization Behavior
+# ========================================
+
+## SortedSet stores string values correctly
+@bone.metrics.delete!
+@bone.metrics.add('metric1', 1.0)
+@bone.metrics.members.include?('metric1')
+#=> true
+
+## SortedSet stores integer member with type preservation
+@bone.metrics.delete!
+@bone.metrics.add(999, 1.0)
+@bone.metrics.members.include?(999)
+#=> true
+
+## SortedSet stores boolean member with type preservation
+@bone.metrics.delete!
+@bone.metrics.add(true, 1.0)
+@bone.metrics.members.include?(true)
+#=> true
+
+# ========================================
+# Horreum Field Serialization (for comparison)
+# Uses JSON encoding - type preserved
+# ========================================
+
+## Horreum field stores string with JSON encoding
+@customer = Customer.new
+@customer.custid = 'serialization_test'
+@customer.role = 'admin'
+@customer.save
+loaded = Customer.find_by_id('serialization_test')
+loaded.role
+#=> 'admin'
+
+## Horreum field stores boolean true (JSON encoded)
+@customer.verified = true
+@customer.save
+@loaded_customer = Customer.find_by_id('serialization_test')
+@loaded_customer.verified
+#=> true
+
+## Horreum verified field is actually boolean, not string
+@loaded_customer.verified.class
+#=> TrueClass
+
+## Horreum field stores boolean false (JSON encoded)
+@customer.reset_requested = false
+@customer.save
+@loaded_customer2 = Customer.find_by_id('serialization_test')
+@loaded_customer2.reset_requested
+#=> false
+
+## Horreum reset_requested field is actually boolean, not string
+@loaded_customer2.reset_requested.class
+#=> FalseClass
+
+# ========================================
+# Type Round-Trip Comparison (Unified Behavior)
+# ========================================
+
+## Integer round-trip in HashKey now preserves type (Issue #190)
+@bone.props['roundtrip_int'] = 100
+retrieved = @bone.props['roundtrip_int']
+retrieved.class
+#=> Integer
+
+## Boolean round-trip in HashKey preserves type
+@bone.props['roundtrip_bool'] = true
+@bone.props['roundtrip_bool'].class
+#=> TrueClass
+
+## DataType and Horreum now use same JSON serialization
+@session = Session.new
+@session.sessid = 'roundtrip_test'
+# Both DataType and Horreum fields now preserve types consistently
+
+# ========================================
+# Horreum serialize_value Comprehensive Tests
+# (Issue #190: Document behavior for unification)
+# ========================================
+
+## Horreum serialize_value: string gets JSON encoded with quotes
+@customer.serialize_value('hello')
+#=> '"hello"'
+
+## Horreum serialize_value: empty string gets JSON encoded
+@customer.serialize_value('')
+#=> '""'
+
+## Horreum serialize_value: integer becomes JSON number (no quotes)
+@customer.serialize_value(42)
+#=> '42'
+
+## Horreum serialize_value: zero becomes JSON number
+@customer.serialize_value(0)
+#=> '0'
+
+## Horreum serialize_value: negative integer
+@customer.serialize_value(-99)
+#=> '-99'
+
+## Horreum serialize_value: float becomes JSON number
+@customer.serialize_value(3.14159)
+#=> '3.14159'
+
+## Horreum serialize_value: boolean true becomes JSON true
+@customer.serialize_value(true)
+#=> 'true'
+
+## Horreum serialize_value: boolean false becomes JSON false
+@customer.serialize_value(false)
+#=> 'false'
+
+## Horreum serialize_value: nil becomes JSON null
+@customer.serialize_value(nil)
+#=> 'null'
+
+## Horreum serialize_value: symbol becomes JSON string
+@customer.serialize_value(:active)
+#=> '"active"'
+
+## Horreum serialize_value: hash becomes JSON object
+@customer.serialize_value({ name: 'test', count: 5 })
+#=> '{"name":"test","count":5}'
+
+## Horreum serialize_value: array becomes JSON array
+@customer.serialize_value([1, 'two', true, nil])
+#=> '[1,"two",true,null]'
+
+## Horreum serialize_value: nested structures work
+@customer.serialize_value({ users: [{ id: 1 }, { id: 2 }] })
+#=> '{"users":[{"id":1},{"id":2}]}'
+
+# ========================================
+# Horreum deserialize_value Comprehensive Tests
+# ========================================
+
+## Horreum deserialize_value: JSON string becomes Ruby string
+@customer.deserialize_value('"hello"')
+#=> 'hello'
+
+## Horreum deserialize_value: JSON number becomes Ruby integer
+@customer.deserialize_value('42')
+#=> 42
+
+## Horreum deserialize_value: JSON number is actually Integer class
+@customer.deserialize_value('42').class
+#=> Integer
+
+## Horreum deserialize_value: JSON float becomes Ruby float
+@customer.deserialize_value('3.14159')
+#=> 3.14159
+
+## Horreum deserialize_value: JSON float is actually Float class
+@customer.deserialize_value('3.14159').class
+#=> Float
+
+## Horreum deserialize_value: JSON true becomes Ruby true
+@customer.deserialize_value('true')
+#=> true
+
+## Horreum deserialize_value: JSON true is TrueClass
+@customer.deserialize_value('true').class
+#=> TrueClass
+
+## Horreum deserialize_value: JSON false becomes Ruby false
+@customer.deserialize_value('false')
+#=> false
+
+## Horreum deserialize_value: JSON false is FalseClass
+@customer.deserialize_value('false').class
+#=> FalseClass
+
+## Horreum deserialize_value: JSON null becomes Ruby nil
+@customer.deserialize_value('null')
+#=> nil
+
+## Horreum deserialize_value: JSON object becomes Ruby hash
+@customer.deserialize_value('{"name":"test","count":5}')
+#=> {"name"=>"test", "count"=>5}
+
+## Horreum deserialize_value: JSON array becomes Ruby array
+@customer.deserialize_value('[1,"two",true,null]')
+#=> [1, "two", true, nil]
+
+## Horreum deserialize_value: nil input returns nil
+@customer.deserialize_value(nil)
+#=> nil
+
+## Horreum deserialize_value: empty string returns nil
+@customer.deserialize_value('')
+#=> nil
+
+## Horreum deserialize_value: plain unquoted string (legacy data) returns as-is
+# This handles data stored before JSON encoding was used
+@customer.deserialize_value('plain string without quotes')
+#=> 'plain string without quotes'
+
+# ========================================
+# Familia Object Serialization (shared behavior)
+# ========================================
+
+## Horreum serialize_value: string value gets JSON encoded
+# When storing a value from another Familia object's field
+@ref_customer = Customer.new('reference_test@example.com')
+@ref_customer.custid = 'reference_test@example.com'
+# Note: Horreum.serialize_value uses JsonSerializer.dump, which JSON-encodes
+# all values, including strings. This is different from DataType#serialize_value,
+# which has special handling for Familia objects.
+@customer.serialize_value(@ref_customer.custid)
+#=> '"reference_test@example.com"'
+
+# ========================================
+# Round-trip Type Preservation Tests
+# ========================================
+
+## Round-trip: integer preserves type through Horreum serialization
+serialized = @customer.serialize_value(42)
+@customer.deserialize_value(serialized)
+#=> 42
+
+## Round-trip: integer class preserved
+serialized = @customer.serialize_value(42)
+@customer.deserialize_value(serialized).class
+#=> Integer
+
+## Round-trip: boolean true preserves type
+serialized = @customer.serialize_value(true)
+@customer.deserialize_value(serialized)
+#=> true
+
+## Round-trip: boolean true class preserved
+serialized = @customer.serialize_value(true)
+@customer.deserialize_value(serialized).class
+#=> TrueClass
+
+## Round-trip: boolean false preserves type
+serialized = @customer.serialize_value(false)
+@customer.deserialize_value(serialized)
+#=> false
+
+## Round-trip: nil preserves type
+serialized = @customer.serialize_value(nil)
+@customer.deserialize_value(serialized)
+#=> nil
+
+## Round-trip: hash preserves structure
+serialized = @customer.serialize_value({ active: true, count: 10 })
+@customer.deserialize_value(serialized)
+#=> {"active"=>true, "count"=>10}
+
+## Round-trip: array preserves structure and types
+serialized = @customer.serialize_value([1, 'two', true, nil, 3.5])
+@customer.deserialize_value(serialized)
+#=> [1, "two", true, nil, 3.5]
+
+# Cleanup
+@bone.props.delete!
+@bone.owners.delete!
+@bone.tags.delete!
+@bone.metrics.delete!
+@customer.destroy! rescue nil

data/try/unit/horreum/destroy_related_fields_cleanup_try.rb

@@ -259,8 +259,9 @@ destroy_result = model.destroy!
 
 # Should result in success and also complete in a reasonable amount of
 # time (under 100ms for this test). I acknowledge this is flaky.
+# Note: 42 results = 40 related field DELs + 1 main object DEL + 1 instances ZREM
 [destroy_result.class, destroy_result.successful?, destroy_result.results.size]
-#=> [MultiResult, true, 41]
+#=> [MultiResult, true, 42]
 #=%> 100
 
 ## Verify transaction_fallback_integration_try.rb bug is fixed

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre21
+  version: 2.0.0.pre22
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -168,12 +168,6 @@ files:
 - bin/irb
 - bin/try
 - bin/tryouts
-- changelog.d/20251105_flexible_external_identifier_format.rst
-- changelog.d/20251107_112554_delano_179_participation_asymmetry.rst
-- changelog.d/20251107_213121_delano_fix_thread_safety_races_011CUumCP492Twxm4NLt2FvL.rst
-- changelog.d/20251107_fix_participates_in_symbol_resolution.rst
-- changelog.d/20251107_optimized_redis_exists_checks.rst
-- changelog.d/20251108_frozen_string_literal_pragma.rst
 - changelog.d/README.md
 - changelog.d/scriv.ini
 - docs/1106-participates_in-bidirectional-solution.md
@@ -328,6 +322,8 @@ files:
 - try/edge_cases/reserved_keywords_try.rb
 - try/edge_cases/string_coercion_try.rb
 - try/edge_cases/ttl_side_effects_try.rb
+- try/features/count_any_edge_cases_try.rb
+- try/features/count_any_methods_try.rb
 - try/features/encrypted_fields/aad_protection_try.rb
 - try/features/encrypted_fields/concealed_string_core_try.rb
 - try/features/encrypted_fields/context_isolation_try.rb
@@ -505,6 +501,7 @@ files:
 - try/unit/data_types/hash_try.rb
 - try/unit/data_types/list_try.rb
 - try/unit/data_types/lock_try.rb
+- try/unit/data_types/serialization_try.rb
 - try/unit/data_types/sorted_set_try.rb
 - try/unit/data_types/sorted_set_zadd_options_try.rb
 - try/unit/data_types/string_try.rb

data/changelog.d/20251105_flexible_external_identifier_format.rst

@@ -1,66 +0,0 @@
-.. Added
-.. -----
-
-.. Changed
-.. -------
-
-- **ExternalIdentifier Format Flexibility**: The `external_identifier` feature now supports customizable format templates via the `format` option. This allows you to control the entire format of generated external IDs, including the prefix, separator, and overall structure.
-
-  **Default format** (unchanged behavior):
-
-  .. code-block:: ruby
-
-     class User < Familia::Horreum
-       feature :external_identifier
-     end
-     user.extid  # => "ext_abc123def456ghi789"
-
-  **Custom format with different prefix**:
-
-  .. code-block:: ruby
-
-     class Customer < Familia::Horreum
-       feature :external_identifier, format: 'cust_%{id}'
-     end
-     customer.extid  # => "cust_abc123def456ghi789"
-
-  **Custom format with different separator**:
-
-  .. code-block:: ruby
-
-     class APIKey < Familia::Horreum
-       feature :external_identifier, format: 'api-%{id}'
-     end
-     key.extid  # => "api-abc123def456ghi789"
-
-  **Custom format without traditional prefix**:
-
-  .. code-block:: ruby
-
-     class Resource < Familia::Horreum
-       feature :external_identifier, format: 'v2/%{id}'
-     end
-     resource.extid  # => "v2/abc123def456ghi789"
-
-  The `format` option accepts a Ruby format string with the `%{id}` placeholder for the generated identifier. The default format is `'ext_%{id}'`. This provides complete flexibility for various ID formatting needs including different prefixes, separators (underscore, hyphen, slash), URL paths, or no prefix at all.
-
-.. Deprecated
-.. ----------
-
-.. Removed
-.. -------
-
-.. Fixed
-.. -----
-
-.. Security
-.. --------
-
-.. Documentation
-.. -------------
-
-.. AI Assistance
-.. -------------
-
-- **Design Review**: Claude Code provided analysis of the current implementation and recommended several idiomatic Ruby approaches for format flexibility, ultimately suggesting the format template pattern using Ruby's native string formatting.
-- **Implementation**: Claude Code implemented the format template feature including code changes, test cases, and documentation updates.

data/changelog.d/20251107_112554_delano_179_participation_asymmetry.rst

@@ -1,44 +0,0 @@
-.. A new scriv changelog fragment.
-..
-.. Uncomment the section that is right (remove the leading dots).
-.. For top level release notes, leave all the headers commented out.
-..
-Added
------
-
-- Bidirectional reverse collection methods for ``participates_in`` with ``_instances`` suffix (e.g., ``user.project_team_instances``, ``user.project_team_ids``). Supports union behavior for multiple collections and custom naming via ``as:`` parameter. Closes #179.
-
-.. Changed
-.. -------
-..
-.. - A bullet item for the Changed category.
-..
-.. Deprecated
-.. ----------
-..
-.. - A bullet item for the Deprecated category.
-..
-.. Removed
-.. -------
-..
-.. - A bullet item for the Removed category.
-..
-.. Fixed
-.. -----
-..
-.. - A bullet item for the Fixed category.
-..
-.. Security
-.. --------
-..
-.. - A bullet item for the Security category.
-..
-.. Documentation
-.. -------------
-..
-.. - A bullet item for the Documentation category.
-..
-AI Assistance
--------------
-
-- Claude Opus 4 assisted with implementation of bidirectional participation relationships using ``_instances`` suffix pattern. Pivoted from initial dry-inflector pluralization approach based on feedback.

data/changelog.d/20251107_213121_delano_fix_thread_safety_races_011CUumCP492Twxm4NLt2FvL.rst

@@ -1,20 +0,0 @@
-.. Fixed mutex race conditions in thread safety implementation
-..
-
-Fixed
------
-
-- Fixed critical race condition in mutex initialization for connection chain lazy loading. The mutex itself was being lazily initialized with ``||=``, which is not atomic and could result in multiple threads creating different mutex instances, defeating synchronization. Changed to eager initialization via ``Connection.included`` hook. (`lib/familia/horreum/connection.rb`)
-
-- Fixed critical race condition in mutex initialization for logger lazy loading. Similar to connection chain issue, the logger mutex was lazily initialized with ``||=``. Changed to eager initialization at module definition time. (`lib/familia/logging.rb`)
-
-- Fixed logger assignment atomicity issue where ``Familia.logger=`` set ``DatabaseLogger.logger`` outside the mutex synchronization block, potentially causing ``Familia.logger`` and ``DatabaseLogger.logger`` to be temporarily out of sync during concurrent access. Moved ``DatabaseLogger.logger`` assignment inside the synchronization block. (`lib/familia/logging.rb`)
-
-- Added explicit return statement to ``Familia.logger`` method for robustness against future refactoring. (`lib/familia/logging.rb`)
-
-AI Assistance
--------------
-
-- Code review analysis to identify critical race conditions in mutex initialization
-- Implementation of proper eager mutex initialization patterns
-- Test file updates to reflect new initialization approach

data/changelog.d/20251107_fix_participates_in_symbol_resolution.rst

@@ -1,91 +0,0 @@
-.. Added
-.. -----
-
-.. Changed
-.. -------
-
-.. Deprecated
-.. ----------
-
-.. Removed
-.. -------
-
-.. Fixed
-.. -----
-
-- **Participation Relationships with Symbol/String Target Classes**: Fixed four bugs that occurred when calling `participates_in` with a Symbol or String target class instead of a Class object.
-
-  **Bug 1 - NoMethodError during relationship definition**:
-
-  The error was: ``private method 'member_by_config_name' called for module Familia``.
-
-  **Background**: The `participates_in` method supports flexible target class specifications:
-
-  .. code-block:: ruby
-
-     class Domain < Familia::Horreum
-       # All three forms should work:
-       participates_in Customer, :domains           # Class object (always worked)
-       participates_in :Customer, :domains          # Symbol (was broken)
-       participates_in 'Customer', :domains         # String (was broken)
-     end
-
-  **Root Cause**: The method had redundant class resolution code that directly called the private `Familia.member_by_config_name` method instead of using the public `Familia.resolve_class` API.
-
-  **Solution**: Removed the redundant resolution code and now uses the already-resolved class from the public API, simplifying the implementation and fixing the visibility issue.
-
-  **Bug 2 - NoMethodError in current_participations**:
-
-  When calling `current_participations` on objects that used Symbol/String target classes, it would fail with ``undefined method 'familia_name' for Symbol``.
-
-  **Root Cause**: The `current_participations` method was calling `.familia_name` on `config.target_class`, which stores the original Symbol/String value passed to `participates_in`.
-
-  **Solution**: Use the resolved `target_class` variable instead of the stored config value. The resolved class is already available from the `Familia.resolve_class` call earlier in the method.
-
-  **Bug 3 - NoMethodError in target_class_config_name**:
-
-  When calling `current_participations`, the internal `target_class_config_name` method would fail with ``undefined method 'config_name' for Symbol``.
-
-  **Root Cause**: The `ParticipationRelationship.target_class_config_name` method was calling `.config_name` directly on the stored `target_class` value, which could be a Symbol or String.
-
-  **Solution**: Resolve the target class before calling `config_name` by using `Familia.resolve_class(target_class)`, which handles all input types (Class, Symbol, String) correctly.
-
-  **Bug 4 - Confusing error when target class not loaded**:
-
-  When the target class hasn't been loaded yet (load order issue), the error was: ``undefined method 'method_defined?' for nil``.
-
-  **Root Cause**: When `Familia.resolve_class` returns `nil` (because the target class isn't registered in `Familia.members` yet), the code would pass `nil` to `TargetMethods::Builder.build`, which then failed with a confusing error message that didn't explain the actual problem.
-
-  **Solution**: Added explicit nil check after `resolve_class` with a detailed ArgumentError that:
-
-  - Clearly states which target class couldn't be resolved
-  - Lists the three most common causes (load order, typo, not inheriting from Horreum)
-  - Shows all currently registered Familia classes for debugging
-  - Provides a clear solution for fixing the load order
-
-  **Impact**: Projects using Symbol or String target classes in `participates_in` declarations will now work correctly throughout the entire lifecycle, including relationship definition, method generation, and participation queries. When there's a load order issue or typo, developers get a clear, actionable error message instead of a confusing nil error. This pattern is common when avoiding circular dependencies or when target classes are defined in different files.
-
-.. Security
-.. --------
-
-.. Documentation
-.. -------------
-
-.. AI Assistance
-.. -------------
-
-- **Root Cause Analysis**: Claude Code analyzed the error stack trace from the implementing project and identified that a private method was being called as a public method from outside the Familia module.
-- **Fix Implementation**: Claude Code identified redundant class resolution code and simplified it to use the already-resolved class from the public API.
-- **Test Coverage**: Claude Code created comprehensive regression tests including:
-
-  - Feature-level tests for Symbol/String target class resolution in participation relationships
-  - Unit tests for the `Familia.resolve_class` public API
-  - Edge case coverage for case-insensitive resolution and modularized classes
-
-- **Second Bug Discovery**: During test execution, Claude Code discovered a related bug in `current_participations` that was also failing with Symbol/String target classes. The test coverage revealed that `.familia_name` was being called on the unresolved config value instead of the resolved class instance.
-
-- **Third Bug Discovery**: Further test execution revealed another Symbol/String bug in `target_class_config_name`, where `.config_name` was being called directly on Symbol/String values. This was fixed by resolving the class first using `Familia.resolve_class`.
-
-- **Test Coverage Refinement**: Claude Code identified and removed unrealistic test cases (all-uppercase, all-lowercase class names) that don't occur in real Ruby code and don't work with the `snake_case` method's design. Updated tests to focus on realistic naming conventions: PascalCase and snake_case, with clear documentation explaining why certain formats aren't supported.
-
-- **Fourth Bug Discovery**: After merging to main, the implementing project revealed a load order issue where `Familia.resolve_class` returned `nil`, causing a confusing "undefined method for nil" error. Claude Code added explicit error handling with a detailed, actionable error message that helps developers quickly identify and fix load order issues, typos, or inheritance problems.